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/2] 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/2] docs: clarify snapshot comparison

Describe the exact string comparison used by SnapshotMixin without implying a raw byte comparison.

Assisted-by: OpenAI Codex <noreply@openai.com>
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.