Developer notes

Testing

The booz_xform package includes both C++ and python tests, including unit and regression tests, and continuous integration.

C++ tests

Unit tests of the C++ code are handled using the doctest header-only library. A copy of the library in externalPackages/doctest is used. Source code for the C++ tests is located in the tests directory. Whenever booz_xform is compiled, a unitTests executable is compiled containing the C++ tests. To access this executable, you should compile the code manually (i.e. outside of pip) using cd build; cmake ..; make -j, which will create the unitTests executable in the build directory.

Python tests

The python tests require the packages scipy and matplotlib, which the core part of booz_xform does not require.

Python tests are based on the standard unittest python module, and can also be run with pytest. Source code for the python tests is located in the tests directory. The python tests will use the installed version of the booz_xform python package, not necessarily a shared library compiled manually in the build directory. To run the python tests, call

pytest

from the repository home directory. You can also run a single file with pytest tests/test_regression.py, or execute individual *.py test files directly. pip install ".[test]" installs pytest along with the other packages the tests need.

The python regression tests make use of files in the tests/test_files directory.

Continuous integration

The C++ and python tests are automatically run after every commit to the repository. This automation is handled by GitHub Actions, and controlled by the script .github/workflows/ci.yml. To view the results of the continuous integration runs, you can click on the “Actions” link from the GitHub repository page, or you can directly visit https://github.com/hiddenSymmetries/booz_xform/actions.

Versions and releases

The version number is declared in exactly one place, [project] version in pyproject.toml. Everything else – the wheel and sdist metadata that PyPI displays, booz_xform.__version__, the version compiled into the C++ code and recorded in boozmn_*.nc output files, the version shown in this documentation, and the git tag – is derived from it. tests/test_version.py and the check-version job in .github/workflows/release.yml both fail if those derivations ever disagree.

Releases are cut by tagging with tbump and publishing a GitHub release, which triggers .github/workflows/release.yml. That workflow builds binary wheels for Linux and macOS with cibuildwheel, smoke-tests each one, and uploads them together with the source distribution to PyPI. The full procedure is documented for maintainers in dev/RELEASING.md in the repository.