.. m-unit-tests documentation master file, created by
   sphinx-quickstart on Fri Oct 31 14:20:36 2014.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Dynare's m-unit-tests module
============================

Contents:

.. toctree::
   :maxdepth: 2


.. function:: get_directory_description(basedir)

   Returns a list of ``*.m`` files in directory ``basedir`` and its
   subfolders. The input argument ``basedir`` is a string and the
   returned argument is cell of strings with \\(n\\) elements where
   each element is the relative address of a file. The default value
   for ``basedir``is the current directory.


.. function:: is_unit_test_available(fname)

   Returns ``true``  if unit tests  defined in matlab  routine ``fname``
   have  to be  run,  ``false`` otherwise.  The  mandatory input  argument
   ``fname`` is a  string. The returned argument is set  equal to ``true`` if
   and only if the file contains the following line:

        .. code-block:: matlab

           return % --*-- Unit tests --*--

   after the core part of the routine, or

        .. code-block:: matlab

           end % classdef --*-- Unit tests --*--

   at the end of the definition of a class.

.. function:: mtest(fname[, fpath])

   Extracts  unit  test   sections  from  matlab's  routine  ``fname``
   executes the tests and reports results.

   **INPUTS**
     - ``fname`` (*string*) Name of the Matlab routine where unit
       tests to be run are defined.
     - ``fpath`` (*string*) Path to the routine (optional).

   **OUTPUTS**
     - ``check`` (*integer*) Scalar equal to 0 if the test fails and 1
       otherwise.
     - ``info`` (*cell*) Describes the test results. Cell info has nn
       rows and five columns. Each row correponds to a unit test in
       fname, and the columns report the following informations:

       - Column 1 Name of the tested routine.
       - Column 2 Number of the unit test.
       - Column 3 Status of the unit test (0 if the unit test fails, 1 otherwise).
       - Column 4 Details about the failure (vector of 0 and 1).
       - Column 5 Elapsed time in seconds (cpu time).

   **REMARKS**
     1. If only one input argument is provided, ``fname`` must contain
        the full path to the routine.
     2. For each unit test, :func:`mtest` generates a matlab function
        saved in ``<fname>_test_x.m`` and runs the function. If the
        function does not return errors the file is erased, otherwise the
        file is kept on disk.

.. function:: dtest(fname[, tpath])

   Runs unit tests defined in ``fname``, by calling :func:`mtest`
   routine, and displays the results.

   **INPUTS**
     - ``fname`` (*string*) Name (with path) of the Matlab routine
       where unit tests to be run are defined.
     - ``tpath`` (*string*) Path to the folder where the test routines
       generated by :func:`mtest` should be temporarly saved
       (optional, default value is the current directory).

   **OUTPUTS**
     None

   **REMARKS**
     1. The full path to the tested routine must be provided in ``fname``.

.. function:: run_unit_tests(listoffiles)

   Runs unit tests defined in a collection of files.

   **INPUTS**
     - ``listoffiles`` (*cell of strings*) The list of m files (with
       path) where the unit tests are written. This cell, with
       \\(n\\) elements, is the output of :func:`get_directory_description` routine.

   **OUTPUTS**
     - ``report`` (*cell*) Results of the unit tests (\\(n\\) rows
       and five columns). Each row stores the second output argument
       of :func:`mtest` routine (info).
     - ``time`` (*double*) Current date and time as date vector (see
       matlab's documentation for the ``clock`` function).


.. function:: run_unit_tests_in_directory(dirname[, savereport[, printreport, sendreport])

   Runs all the unit tests defined in a directory (and subfolders).

   **INPUTS**
     - ``dirname`` (*string*) Path to the directory.
     - ``savereport`` (*logical*) Scalar equal to ``false`` or ``true``. If equal to ``true`` generated report is saved in a ``*.mat`` file.
     - ``printreport`` (*logical*) Scalar equal to ``false`` or ``true``. If equal to ``true`` generated report is printed on screen.
     - ``sendreport`` (*string*) Email adress. If not empty generated report is sent by email.

   **OUTPUTS**
     - ``report`` (*cell*) First output argument of :func:`run_unit_test routine`.

   **REMARKS**
     1. Git needs to be available on the system, and it is assumed that the content of ``dirname`` is versionned with Git.


.. function:: display_report(report)

   Displays detailed report for the testsuite.

   **INPUTS**
     - ``report`` (*cell*) Output of :func:`run_unit_tests_in_directory`.



Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
