.. _running-tests:

*************
Running tests
*************

In TARDIS, we focus primarily on unit tests. These tests check the outputs of individual functions, ensuring that each component behaves as expected.

Unit tests run quickly and are executed after every suggested change to TARDIS, allowing for immediate feedback and maintaining code quality.

All of them are based on the excellent ``astropy-setup-helpers`` package and
`pytest <https://docs.pytest.org/en/latest/>`_.

Running the Unit Tests
======================

This is very straightforward to run on your own machine. For very simple unit
tests, you can run this with:

.. code-block:: shell

    > pytest tardis

Running Regression Data Tests
============================


.. note::
    We have migrated from ``tardis-refdata`` to ``tardis-regression-data``.


Running the more advanced unit tests requires TARDIS Regression data that can be
downloaded from the `tardis-regression-data <https://github.com/tardis-sn/tardis-regression-data>`_ repository.
The regression data contains data in different formats (npy, hdf5, csv etc.) which is used by the testing pipeline to verify the accuracy of the codebase.
`Git LFS <https://www.atlassian.com/git/tutorials/git-lfs>`_ is used to download and track the files in the tardis-regression-data repository.


.. code-block:: shell

    > GIT_LFS_SKIP_SMUDGE=1 git clone https://github.com/tardis-sn/tardis-regression-data.git
    > cd tardis-regression-data
    > git lfs fetch && git lfs checkout

.. note::
    ``GIT_LFS_SKIP_SMUDGE=1`` defers downloading large files until the explicit ``git lfs fetch`` command, which provides better visibility into download progress and allows you to monitor which files are being retrieved.


The ``tardis-regression-data`` repository should be located outside of the main ``tardis`` repository, rather than being nested within it.
Finally, the tests can be run using the following command

.. code-block:: shell

    > pytest tardis --tardis-regression-data=/path/to/tardis-regression-data/

Or, to run tests for a particular file or directory

.. code-block:: shell

    > pytest tardis/path/to/test_file_or_directory --tardis-regression-data=/path/to/tardis-regression-data/


.. note::
    In some cases you might have to update the regression data. The steps to update the regression data are outlined in the :ref:`update regression-data`.

.. note::
    The `tests workflow <https://github.com/tardis-sn/tardis/blob/master/.github/workflows/tests.yml>`_ runs on 
    `pull requests <https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request>`_ and on 
    `push <https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#push>`_ events.
    To prevent leaking LFS quota, tests have been disabled on forks.
    If, by any chance, you need to run tests on your fork, make sure to run the tests workflow on master branch first.
    The LFS cache generated in the master branch should be available in all child branches. 
    You can check if cache was generated by looking in the ``Setup LFS`` step of the workflow run. 
    Cache can also be found under the "Management" Section under "Actions" tab.


For instructions to update regression data, please see :ref:`update regression-data`.