diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3ff8908f64..e9f0fc4cce 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -159,3 +159,21 @@ You must commit the generated files as well as part of your PR. The `*_extender` files under `docs/reference/cli` are meant as extensions of the autogenerated documentation. Those are meant to be updated manually. + +## Python test snapshots + +Snapshots can be included in Python tests using `inline-snapshot`, following the pattern in +https://github.com/prefix-dev/pixi/blob/main/tests/integration_python/test_import.py. + +1. To add a new snapshot, you first write `assert value == snapshot()`, where `value` is the +string you are testing. +2. You can then run your tests with `pixi run test-specific-test your_test_name`. The test should +error (this is expected), but also create a snapshot inline (inside the parentheses which follow +`snapshot`), unless the test fails for another reason before hitting the `snapshot()` line. +If the test fails for another reason, fix that reason and run the tests again. +3. Running tests in the future will prompt you whenever actual values do not match the snapshots. +If you want to fix all snapshots and review the diff afterwards, you can use `pixi run snapshot-update your_test_name`. +4. You may wish to redact parts of snapshots. This will be necessary when values are dependent on +the machine running the tests, e.g. manifests created with `pixi init`. This can be done using +`dirty-equals`: see documentation at https://15r10nk.github.io/inline-snapshot/0.23/eq_snapshot/#dirty-equals +and examples in https://github.com/prefix-dev/pixi/blob/main/tests/integration_python/test_import.py.