CycloneDX / CycloneDX/cyclonedx-python-lib
docs: explain model fixture and snapshot workflow
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 117
- Forks
- 67
- Avg merge
- 8d 2h
- Merged PRs (30d)
- 2
Description
Description
The contributor documentation links to tests/_data/snapshots/README.md, but that file currently explains only how to regenerate snapshots. It does not explain how BOM model factories in tests/_data/models.py are discovered or how they feed the JSON, XML, and round-trip tests.
This gap came up in the maintainer guidance on #914: https://github.com/CycloneDX/cyclonedx-python-lib/pull/914#issuecomment-3562249425. The maintainer explicitly welcomed a dedicated documentation pull request.
Proposed documentation
Document the existing workflow without changing test behavior:
get_bom_*factory discovery and snapshot naming;_invalidfixtures;- registration of deliberately incomplete dependency graphs;
- regenerating snapshots, reviewing only the intended files, and rerunning tests with snapshot recreation disabled.
Acceptance
- The documented paths and collector names match the current default branch.
- The shared JSON/XML output and deserialization fixture tests pass.
- The full test suite remains green.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with tests/_data/snapshots/README.md and compare its current guidance with tests/_data/models.py and the shared JSON/XML output and deserialization fixture tests. Document the existing factory discovery, snapshot naming, _invalid fixtures, incomplete dependency graphs, and regeneration review workflow; done means the paths and collector names match the default branch and the specified tests and full suite pass with recreation disabled.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation, testing
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 74/100