0002. Acceptance tests live in a consumer repository, over one cumulative fixture

Status

Accepted.

Context

Every defect this engine has had was an interaction, not a unit failure: a tag file that was computed correctly but never wired into the doxyfile that needed it; a Sphinx role that resolved at parse time against an index which did not exist yet; a doctree cache shared between two build stages that answered for work never redone. In each case every component was individually correct and the assembled documentation set was wrong — and in most of them the build exited 0 while producing a complete-looking docset with dead cross-references.

Unit tests over the engine’s Python modules cannot see that class of defect at all. Neither can a per-feature fixture that builds one document in isolation: the interaction only exists when two documents, two toolchains, and two build stages are present at once.

Decision

The engine’s primary test layer is an acceptance suite in a separate repository called which consumes zdocs exactly as a real project would — a Zephyr workspace with its own documents, its own registry, and its own vocabulary. It configures and builds with the same cmake commands a user runs, and asserts on what lands in deploy/. There are no mocks and no in-process Sphinx.

Consequences

• The suite is slow by unit-test standards — minutes, not seconds — because every test builds real documentation with real Sphinx and real Doxygen. That cost buys the only signal that matters for this engine, and it is why a second, fast unit layer was later added for the pure-Python parts (0003. The engine carries its own unit suite, in the engine repository).