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 ../user_manual/installation.rst) 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

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.

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.