Parser fixtures

Parser fixtures must exercise real structural problems without turning the repository into a redistributed standard corpus.

Preferred order

1. Project-authored synthetic DocBook.
2. Tiny attributed excerpt only when a synthetic structure would not test the relevant behavior faithfully.
3. Local official-artifact integration test for broad or release-level verification.

Synthetic fixtures

Place authored fixtures under:

tests/fixtures_synthetic/

A good fixture:

• contains the smallest document structure that reaches the parser branch;
• uses invented labels or clearly synthetic values;
• includes stable xml:id anchors;
• preserves realistic table or variable-list shape;
• covers one primary behavior;
• includes malformed or ambiguous variants in separate focused cases;
• is understandable without opening the official standard.

Use the same fixture to test parser output, import behavior, public response, and warnings when that creates an end-to-end regression.

Minimal attributed excerpts

Use:

tests/fixtures_minimal_attributed/

only when a small real excerpt is necessary.

For every excerpt:

• keep it narrowly bounded;
• retain required attribution;
• document the source part, edition, section/table/anchor, and reason for use;
• avoid adjacent unrelated rows or prose;
• do not aggregate excerpts into broad coverage;
• review the repository’s notices and fixture policy.

Do not commit

• full official DocBook parts;
• official PDFs or HTML;
• target databases;
• generated full parsed JSON;
• generated SQLite knowledge bases;
• full-text or vector indexes;
• bulk SR template, context-group, or coded-concept data.

Use a local ignored cache for official integration.

Test parser uncertainty

A fixture should make unsupported structure visible. Assert:

• a warning is emitted;
• the warning identifies the part or source location;
• counts contribute to build metrics;
• unresolved include or cross-reference rows remain observable;
• the public resolver does not invent the missing relationship.

Update expected outputs deliberately

When a parser change modifies snapshots or golden responses:

1. inspect the semantic difference;
2. confirm references and ordering;
3. confirm classification and confidence still fit;
4. update the focused expected output;
5. run the full offline suite;
6. run official integration when the change touches real-source variability.

Do not regenerate every snapshot without reviewing the diff.

Promote to an official-edition test

A behavior belongs in local official integration when it depends on:

• a structure too broad to reproduce safely;
• cross-part target databases or links;
• current-release directory behavior;
• edition-specific table variation;
• release-readiness counts or representative named rows.

The test must locate source material from the user’s local cache rather than adding it to the repository.