Skip to content

docs: explain model fixture and snapshot workflow #1031

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
CAOShurong wants to merge 2 commits into
base: main
Choose a base branch
from
+27 −3
Open

docs: explain model fixture and snapshot workflow #1031

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
87b30a1
Document model fixture workflow
CAOShurong Aug 12, 2026
698c855
docs: clarify snapshot comparison
CAOShurong Aug 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 27 additions & 3 deletions tests/_data/snapshots/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,28 @@
# TEST FIXTURES
# Test fixtures

## RE-CREATION
## Model fixtures

Serialization and deserialization tests share BOM factories from
[`tests/_data/models.py`](../models.py). To cover a model change:

1. Add a descriptively named factory that starts with `get_bom_` and returns a
`Bom`. The function is discovered automatically; its name also becomes the
snapshot filename prefix.
2. Populate every field relevant to the change so the JSON and XML output
tests exercise the complete model. Name a fixture ending in `_invalid` only
when serialization is expected to fail.
3. Register a factory in `all_get_bom_funct_with_incomplete_deps` when its
dependency graph is intentionally incomplete. Otherwise, include the
complete dependency graph in the returned BOM.
4. Re-create the snapshots, review the changed files, then run the tests again
without snapshot re-creation enabled.

The output tests serialize each discovered model for the applicable schema
versions, validate the generated JSON and XML, and compare it with the stored
snapshots. The deserialization tests also use these fixtures for round-trip
coverage.

## Re-creation

Some assets here can be (re-)created automatically, by setting the env var `CDX_TEST_RECREATE_SNAPSHOTS=1`.
It might also help to set `PYTHONHASHSEED=0`!
Expand All @@ -10,4 +32,6 @@ As a shortcut just run:
CDX_TEST_RECREATE_SNAPSHOTS=1 poetry run tox -e py
```

The files will be written as is, which might not be human-readable. feel free to reformat the files manually.
Only commit snapshots that belong to the model change. Snapshot tests compare
the serialized text with the stored fixture using exact string equality, so do
not reformat snapshots manually.