.. _testing:

Testing Infrastructure
######################

Functional tests are implemented in each module in a function named ``CheckIntegrity``.
This function is called by the test infrastructure to check the integrity of the module and returns the string ``"ok"`` if and only if the test was successful.

The ``__init__.py`` must have a variable named ``_test`` listing all submodules to be tested so that the test infrastructure works as intended.

Some tests need to write data to disk or read data from the test data directory.
Two functions are available to help writing tests :

*  GetTestDataPath() : Returns the path of the test data directory (``from Muscat.TestData import GetTestDataPath`` )
*  TemporaryDirectory: A class to handle the creation of a directory to hold temporary data (``from Muscat.Helpers.IO.TemporaryDirectory import TemporaryDirectory``)

.. important::

   There are two ways of running tests, depending on your installation
   of Muscat:

   1. If you have installed Muscat from a package manager, you must use

      .. code-block:: bash

         python -m Muscat.Helpers.Check

      For more information about the options, use the command :

      .. code-block::

         python -m Muscat.Helpers.Tests -h


   2. If you have installed Muscat from source, you must use ``ctest``, for instance:

      .. code-block:: bash

         ctest --test-dir build --output-on-failure --parallel 16


.. note::
    Some test will fail on some configuration
    Some packages are not available on all the supported platforms and some classes must be used inside a specific environments (paraview for example)
    The current know issues are :

    -  Muscat.IO.Catalyst is intended to be used inside a python console in ParaView ([More about](https://www.paraview.org/Wiki/ParaView/Catalyst/Overview)).


Coverage
========

Coverage is an important part of the development process.
To activate the coverage during test use the ``-R coverage`` option:

.. code-block:: bash

   ctest --test-dir build --output-on-failure --parallel 16 -R coverage

A html is generated in ``build/htmlcov`` to explore the results.

If you want to ignore some part of the code in teh coeverare report, use the ``#pragma : no cover`` comment.
For correct platform dependent coverage you can use the following comment to disconnect coverage in some platform:

.. code-block::

    # only nt coverage
    # only posix coverage


Disabling Tests
===============

Some tests can be disabled using an environment variable.
A typical use case arises when a test relies on an external dependency that may not be available.

The feature relies on the definition of non-empty environment variables in the form : ``"XXXXX_NO_FAIL"``.

An example is available in the :py:func:`Muscat.Bridges.PyVistaBridge.CheckIntegrity` function.