==============
Testing |TOOL|
==============

|TOOL| comes with a testing suite to ensure the correctness and reliability of
the implemented features.
Automated unittests and functional tests are provided in the ``test/unittest``
and ``test/functional`` folders respectively.
In addition to them, |TOOL| provides some example scripts in the
``tutorials`` folder; they illustrate practical use-cases and workflows
to show how they are managed in |TOOL|. See section :ref:`tutorials` for a
detailed explanation of the provided cases.

Unittest Test Suite
-------------------

Unittests are intended to verify the public interface of |TOOL|, i.e. all the
public methods of the available classes, as well as the functions.
Since the tested functionalities relies on the *GEOM* module of *SALOME*, all
the tests must be run within *SALOME* itself.

The ``run_tests.py`` Python script provides the command to automatically run
all the test cases in the ``test/unittest`` folder.
This script must be run from the root folder of |TOOL| within a *SALOME*
instance. The following command, run in a terminal, executes all the unittests
in the *SALOME* GUI:

.. code-block:: bash

   salome test/unittest/run_tests.py

These tests can also be run in GUI-less mode with the following command in a
terminal:

.. code-block:: bash

   salome shell test/unittest/run_tests.py

In the latter case, the log of the tests will be printed in the current bash
console. In the former case, all *stdout* output is redirected to the *SALOME*
Python console.

Functional Tests
----------------

The functional tests are intended to verify that the functionalities implemented
in the different classes of |TOOL| work together correctly to replicate the
intended geometry layout and produce the expected output file, i.e. successive
runs of the same script must always generate the same *TDT*-format file.
Pre-prepared *TDT* files are shipped with the corresponding Python scripts.
These files have been tested in *DRAGON5* to ensure that the geometry layout
they represent can be tracked by the *SALT* module and provide physically
acceptable results.
The content of each output file, generated by running the functional tests, is
compared with the corresponding reference to ensure that it is always the same.

The ``run_tests.py`` Python script provides the command to automatically run
all the functional test cases in the ``test/functional`` folder.
This script must be run from the root folder of |TOOL| without needing to
explicitely run *SALOME*; this is performed *under the hood* by running a
*SALOME* shell instance for each test.
The following command runs all the functional tests from the terminal:

.. code-block:: bash

   python test/functional/run_tests.py

The functional tests consists of seven cases that models:

    - a lattice made by a single cartesian cell;
    - a lattice made by a single hexagonal cell;
    - a full cartesian lattice;
    - a full hexagonal lattice;
    - a cartesian lattice with an eighth symmetry;
    - a hexagonal lattice with a sixth symmetry;
    - a hexagonal lattice with a twelfth symmetry.