Running the Python test suite and checking ROOT file hashes.

Python bindings are exercised through pytest, in addition to the doc-example snippets used by Python Bindings.

Running the tests

First configure and build the Python bindings, then load the generated environment as described in Python Bindings. Enable the optional components needed by the tests you want to run.

A number of unit tests based on the pytest library are shipped with the repository, under $REPO_ROOT/Python/Core/tests, Python/Fatras/tests, and Python/Examples/tests. They cover the public API of the Python bindings, and a set of tests also execute the standalone example scripts under Examples/Scripts/Python/.

To run these tests, pytest and a few other dependencies need to be installed:

pip install -r Python/Examples/tests/requirements.txt

You can then simply run pytest from the repository root.

Remarks: It is strongly recommended to use a virtual environment for this purpose! For example, run
python -m venv venv

source venv/bin/activate

to create a local virtual environment, and then run the pip command above.

Markers

Tests are grouped by optional dependency using pytest markers: csv, obj, root, json, slow, edm4hep, odd, hepmc3, and pypi. pypi marks the subset that only exercises what the PyPI wheel actually provides (see Python Bindings) — this is what cibuildwheel runs as the wheel smoke test. Run one marker's subset with:

pytest -m odd

ROOT file hash regression checks

In a number of cases, the python based test suite will run hash based regression tests against ROOT files that are written by the test workloads. These tests use a custom hash algorithm written in python, which hashes each individual entry of each TTree found in a file. These entry hashes are then sorted, concatenated and hashed again for the final output. This procedure ensures that if the ROOT file content changes, the hash changes, while also giving the same hash when the events stored in the file are reordered.

The tests are implemented by looking up a reference hash from a central data file $REPO_ROOT/Python/Examples/tests/root_file_hashes.txt that looks like

test_ckf_tracks_example_full_seeding__performance_seeding_trees.root: 938bcc9b9425b12c620f5d0efa2c592817dfe92a18c309e97aa9d87412918620
test_ckf_tracks_example_full_seeding__trackstates_ckf.root: 2faceafd4a521ff4030557301723e29c3d870edad052965eb644b824b57e2146
test_ckf_tracks_example_truth_estimate__performance_seeding_trees.root: 5c0cf9e84af64e6814ab1ddf4cbaf4be6008ad8b2371b5b0241085b19d0fc52c
test_ckf_tracks_example_truth_estimate__performance_seeding_trees.root: 5c0cf9e84af64e6814ab1ddf4cbaf4be6008ad8b2371b5b0241085b19d0fc52c
test_ckf_tracks_example_truth_estimate__trackstates_ckf.root: ac4485c09a68fca3d056cb8d9adb81695e68d822629e48c71fd2b6d2bbd31f88

where the left side before the : indicates the test in which the check is performed and the name of the ROOT file that is checked. The right side is the reference hash.

Note: The file from which reference hashes are loaded can be changed by setting the environment variable ROOT_HASH_FILE to the desired file.

These checks have two purposes:

Detect regressions in the algorithms: if an algorithm produces different output, the test will catch it. This also means that if algorithmic changes are made that intentionally change the output, the reference hashes also have to be updated.

Warning: Please make sure to check the contents of a changed file are correct/reasonable before updating the reference hash!

Detect potential reproducibility issues. Tests that run with multiple threads should produce the same output every run, event ordering aside. If a test workload has a thread-reproducibility issue, the output hash should also change.

Running the hash checks locally and how to update the reference hashes

By default, the hash checks are not executed when the pytest command is run. To enable them, you need to set the environment variable ROOT_HASH_CHECKS needs to be set to ON, for example like:

ROOT_HASH_CHECKS=ON pytest

If any hash mismatches are observed, the corresponding tests will fail, and pytest will print a summary at the end that looks like

------------------------------------------- RootHashAssertionErrors -----------------------------------------------------
The ROOT files produced by tests have changed since the last recorded reference.
This can be be expected if e.g. the underlying algorithm changed, or it can be a test failure symptom.
Please manually check the output files listed below and make sure that their content is correct.
If it is, you can update the test reference file Python/Examples/tests/root_file_hashes.txt with the new hashes below.
 
test_seeding__estimatedparams.root: 8bbc97cb3d4777c61dd0b483a1c8268fc8411ad182c35bc731e5ed222450deca
test_material_recording__geant4_material_tracks.root: 019ce62ce378efa5c02a94768039686ed3cdfbd60c115c1f0cab2cbc53def57b
test_material_mapping__material-maps_tracks.root: c03215e8b53733a3a7d7a0a5f9aec5bf2df20e8e40cc0492a8fa22400491d216
test_material_mapping__propagation-material.root: a15a5c1e92fc3b848efb232eea1d40c422ee3a1d9ef1f7140294415621a04ce5
test_ckf_tracks_example_full_seeding__tracksummary_ckf.root: 9e4d14169f20961be38d0305853a7cf7eeea4a647f0c94a48aada22c3c2c7a51
test_ckf_tracks_example_truth_estimate__tracksummary_ckf.root: 3d56b26788163852e2c1f7288920f60a505bd14deeabb6f9189b680fcd90bfc5
test_ckf_tracks_example_truth_smeared__tracksummary_ckf.root: ca2ce4069d2a2388c3d3c826dec8bea9f9d1e622239a20f8b985784d6c546c6e
=========================================== short test summary info =====================================================
FAILED Python/Examples/tests/test_examples.py::test_seeding
FAILED Python/Examples/tests/test_examples.py::test_material_recording
FAILED Python/Examples/tests/test_examples.py::test_material_mapping
FAILED Python/Examples/tests/test_examples.py::test_ckf_tracks_example_full_seeding
FAILED Python/Examples/tests/test_examples.py::test_ckf_tracks_example_truth_estimate
FAILED Python/Examples/tests/test_examples.py::test_ckf_tracks_example_truth_smeared
================================== 6 failed, 183 passed in 199.82s (0:03:19) ============================================

Here, we see that 7 hash checks have failed. The error output conveniently has the same format as the reference hashes found in root_file_hashes.txt. To update the reference hashes, simply replace the corresponding entries in root_file_hashes.txt with the output from the pytest run.

Note: CI runs the ROOT hash checks. However, we have observed the hashes to change between different machines. This is believed to be due to differences in math libraries producing slightly different outputs. As a consequence, locally obtained file hashes might cause CI failures, as the CI hashes are different.

For local testing, it is therefore advisable to use ROOT_HASH_FILE to use a different file for the reference hashes and populated it with known-good reference hashes from the main branch, before testing your developments.

To make the CI succeed if it obtains different hashes than you get locally: make sure that the output is correct, and then update the central root_file_hashes.txt with the hashes reported in the failed CI job.