From 87b30a12085a83960d5ba56801f0701d317e163c Mon Sep 17 00:00:00 2001 From: Shurong Cao <170531907+CAOShurong@users.noreply.github.com> Date: Thu, 13 Aug 2026 02:17:18 +0800 Subject: [PATCH 1/3] Document model fixture workflow Signed-off-by: Shurong Cao <170531907+CAOShurong@users.noreply.github.com> --- tests/_data/snapshots/README.md | 29 ++++++++++++++++++++++++++--- 1 file changed, 26 insertions(+), 3 deletions(-) diff --git a/tests/_data/snapshots/README.md b/tests/_data/snapshots/README.md index f97432444..96501b253 100644 --- a/tests/_data/snapshots/README.md +++ b/tests/_data/snapshots/README.md @@ -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`! @@ -10,4 +32,5 @@ 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. Since snapshots are +compared byte-for-byte, do not reformat them manually. From 698c85526eb80625391e9123f04897ccfc0d7a96 Mon Sep 17 00:00:00 2001 From: Shurong Cao <170531907+CAOShurong@users.noreply.github.com> Date: Thu, 13 Aug 2026 16:03:53 +0800 Subject: [PATCH 2/3] docs: clarify snapshot comparison Describe the exact string comparison used by SnapshotMixin without implying a raw byte comparison. Assisted-by: OpenAI Codex Signed-off-by: Shurong Cao <170531907+CAOShurong@users.noreply.github.com> --- tests/_data/snapshots/README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/tests/_data/snapshots/README.md b/tests/_data/snapshots/README.md index 96501b253..6ef8f6eb1 100644 --- a/tests/_data/snapshots/README.md +++ b/tests/_data/snapshots/README.md @@ -32,5 +32,6 @@ As a shortcut just run: CDX_TEST_RECREATE_SNAPSHOTS=1 poetry run tox -e py ``` -Only commit snapshots that belong to the model change. Since snapshots are -compared byte-for-byte, do not reformat them 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. From 92919fe13a7f329940ee232ef3338a69c306406c Mon Sep 17 00:00:00 2001 From: Shurong Cao <170531907+CAOShurong@users.noreply.github.com> Date: Wed, 9 Sep 2026 22:51:19 +0800 Subject: [PATCH 3/3] docs: document schema version filtering for model fixtures Signed-off-by: Shurong Cao <170531907+CAOShurong@users.noreply.github.com> --- tests/_data/snapshots/README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/tests/_data/snapshots/README.md b/tests/_data/snapshots/README.md index 6ef8f6eb1..9f9f25b15 100644 --- a/tests/_data/snapshots/README.md +++ b/tests/_data/snapshots/README.md @@ -16,6 +16,9 @@ Serialization and deserialization tests share BOM factories from 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. +5. For version-specific fixtures, prefix the name with the target schema version + tag (e.g. `get_bom_v1_5_*`). The test runner uses `is_valid_for_schema_version()` + to ensure such models are only evaluated against applicable schema versions. The output tests serialize each discovered model for the applicable schema versions, validate the generated JSON and XML, and compare it with the stored