================= 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 ``_, 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.