unittest.rst

Unit Tests
==========
Unit tests should be based on `unittest`_,
while `doctest`_ is not recommended for limited usage.
In the end, `pytest`_ is used to perform the unittests.
And `coverage`_ is used to assess the unit test coverage.

Introduction to ``unittest``
----------------------------
Here we show an example of an example unit test on ``csst_proto.top_level_interface.flip_image``

.. literalinclude:: ../../tests/test_flip_image.py
   :linenos:
   :language: python



Run Unit Tests
--------------

To run unit tests

.. code-block:: bash

    pytest --import-mode=importlib

To run unit tests with coverage

.. code-block:: bash

    coverage run -m pytest --import-mode=importlib

To display the coverage report

.. code-block:: bash

    coverage report

To generate the coverage report in html format

.. code-block:: bash

    coverage html

.. _unittest: https://docs.python.org/3.9/library/unittest.html
.. _doctest: https://docs.python.org/3.9/library/doctest.html
.. _pytest: https://docs.pytest.org/en/7.1.x
.. _coverage: https://coverage.readthedocs.io/en/6.5.0/


Conventions
-----------
Before write his own unit test scripts, a developer should have a glance at
the conventions on how `pytest`_ discovers unit tests (e.g, `test_*.py` or `*_test.py` files).

For more information, click `here`_.

.. _here: https://docs.pytest.org/en/7.1.x/explanation/goodpractices.html#test-discovery


Data access
-----------
For the Main Survey, i.e., the multi-band imaging (MBI) and the slit-less spectra (SLS)
developers might use two kinds of data to run their unit tests.

Auxiliary data (data used for your unit test ONLY)
   It should be put in ``/nfsdata/users/csstpipeline/L1Pipeline/unittests/<your_project_name>/``
   You can obtain this path from the environment in your unit test scirpts,

   .. code-block:: python

      import os
      os.getenv("AUX_DIR")


Simulation data (officially released simulation data)
   It should be accessed with the ``csst_common.data_manager.CsstMsDataManager``.
   The ``CsstMsDataManager.quickstart`` provides an interface to initialize
   an instance. See the next chapter for more details.

   Here we show an example which initializes the ``CsstMsDataManager`` with the 100th exposure of ``C5.2``
   simulation to perform a unit test for the project ``csst_ms_sls_instrument``.

   .. code-block:: python

        import os
        import unittest
        from csst_common.data_manager import CsstMsDataManager
        from csst_ms_sls_instrument.top_level_interface import sls_instrument_pipeline


        aux_dir = os.getenv("AUX_DIR")
        out_dir = os.path.join(aux_dir, "csst_ms_sls_instrument")


        class TestCsstMsSlsInstrument(unittest.TestCase):
            def setUp(self) -> None:
                self.dm = CsstMsDataManager.quickstart(ver_sim="C5.2", datatype="sls", dir_l1=out_dir, exposure_id=100)

            def test_instrument(self):
                test_detector = 1
                # for l0 image path:
                self.dm.l0_detector(test_detector)
                # for l1 image path:
                self.dm.l1_detector(detector=test_detector, post="flt.fits")
                self.dm.l1_file(name="merged.fits", comment="This is a merged image.")
                self.assertTrue(os.path.exists(self.dm.l0_detector(test_detector)))



For developers on other instruments (CPIC, THZ, MCI and IFS),
unit tests might be performed in their local environments.