
=================
Testing Capytaine
=================

Running the test suite with Pytest
----------------------------------

To check that the installed packaged is working fine, you can run the test suite with `Pytest`_.
If Pytest is not already installed, it can be done with e.g.::

    pip install pytest

Then run the following command from the root of Capytaine repository to test the code::

    python -m pytest

Note that some tests are skipped if the required optional dependencies are not
installed, hence it is advisable to install all of Capytaine optional
dependencies (see :doc:`../user_manual/installation`) to fully test
the code.

Some useful features of Pytest include:

- stopping at the first failure::

   python -m pytest --maxfail=1

- running all test starting with the ones that failed in the previous run::

   python -m pytest --failed-first

.. _`Pytest`: https://docs.pytest.org/


Testing in isolated environments
--------------------------------

The ``Justfile`` contains recipes to run the test suite as well as some of the example code from
the cookbook (``docs/user_manual/examples/`` directory) in isolated environements using ``UV``.

The ``test_in_*_reference_env`` recipes is used to test the current source code
in an environment with fixed versions of Capytaine's dependencies.
This is meant to test changes in Capytaine without interferences from possible
changes in dependencies.
Two environments are predefined for this test, one is older and meant to be
used with the oldest version of Python supported by Capytaine (Python 3.8 at
the time of writing), while the other is more recent and is meant to be used
with a recent version of Python (Python 3.12 at the time of writing).
Their lockfiles can be found in the ``pytest/envs/`` directory.

You can run them locally with::

    just test_in_py38_reference_env
    just test_in_py312_reference_env

assuming you have UV installed.

These recipes are the main part of the
``.github/workflows/test_new_commits.yaml`` Github Actions workflow that is run
at each new commit and pull request.

Alternatively, the recipe ``test_in_latest_env`` and
``editable_build_and_test_in_latest_env`` uses the latest dependencies
available on PyPI to test Capytaine, respectively by installing it as a normal
package or by installing it in development mode as described above on this
page.

You can run them locally with::

    just test_in_latest_env
    just editable_build_and_test_in_latest_env

They are the main part of the
``.github/workflows/test_with_latest_dependencies.yaml`` Github Actions workflow
that is run twice a month on the main branch of the Github repository.

Finally the session ``test_in_nightly_env`` fetches yet-unreleased
versions of Capytaine dependencies and run the same tests. It is mostly meant
to anticipate breaking changes in the dependencies, such as the Numpy 1 to
Numpy 2 transition.


Testing the Fortran core
------------------------

The core Fortran routine of Capytaine located at
``capytaine/green_functions/libDelhommeau/`` includes some example meant to
demonstrate its usage on its own outside of Capytaine.
See ``capytaine/green_functions/libDelhommeau/Makefile`` for details.
The good compilation of this standalone Fortran code should be tested regularly.
It is done in CI for each new commit in ``.github/workflows/test_new_commits.yaml``.


While testing new developments in the Fortran core it is also useful to test
the compilation of Capytaine's Fortran core AND its Python binding, but without
the full Capytaine test suite.
This can be done with Capytaine's main ``Justfile`` as::

   just test_fortran_compilation


Sanity checks with Pre-commit
-----------------------------

Capytaine repository includes a config file for `pre-commit`_.
It is meant to catch common mistakes before creating a new commit.
While not as important as the functional tests described above, it is
recommended to install pre-commit and set it up in Capytaine repository while
developping Capytaine.

.. _`pre-commit`: https://pre-commit.com/


Testing in CI with Github Actions
---------------------------------

The directory ``.github/workflows/`` contains the definition of the Github
Actions that are run to test Capytaine in CI.
The workflows ``test_new_commits.yaml`` and
``test_with_latest_dependencies.yaml`` are mostly thin wrapper around the Just
recipes described above.
The former is run on each new commit, while the latter is run periodically.
Follow the instructions in the section above to run them locally.
Both only run on Linux, testing other platforms is only done with the
``build_wheel.yaml`` workflow described below.

The workflow ``build_docs.yaml`` builds the documentation and push it to
`<https://capytaine.org/master/>`_, whenever a commit modifies the sources in the
``docs/`` directory.

The workflow ``build_wheels.yaml`` builds the wheels (precompiled packages) for
all supported platform that are distributed on PyPI.
It is run when a new version is released.
It is also run periodically to check that the current main branch of Capytaine
can be built and run without issue on all platforms.
