Summary
The documentation library publishes 2 cross-language engineering practice
guides carrying 15 fenced examples, of which roughly 8 are executable or
otherwise machine-checkable. None of them is currently executed by any test.
An example that is never run is an assertion nobody checks, and these
documents are vendored into repositories across the estate, so a wrong example
propagates.
This issue asks for behavioural tests covering every example in this batch.
Why now
A review of these guides found footnote references pointing at unrelated
sources, which no automated check would catch.
Scope
What is being asked
Follow the tested-correctness contract the documentation style
guide
now specifies:
- Precede every fenced example with a marker comment carrying a stable
identifier, written <!-- tested-example: <identifier> -->.
- Load the examples from the published document with a shared loader, so the
tests exercise the shipped text rather than a copied fixture. The loader must
fail on an unmarked fence, an unterminated fence, a missing identifier, or a
duplicate identifier.
- Share that loader between the integration tests and the behaviour-driven
scenarios, so a documented example becomes a contract the implementation must
satisfy.
For this batch the natural harness is compiling or running the few executable
examples, and asserting that the Markdown templates the style guide publishes
still satisfy the repository's own Markdown gate.
Out of scope
Illustrative blocks that are not executable, such as directory trees, terminal
transcripts and utility-name listings, still need a marker so the loader can
prove no fence was missed, but their test may assert shape rather than execute
them. Roughly 7 of the 15 blocks in this batch fall into that category.
Acceptance
- Every fenced block in each listed document carries a unique marker.
- The loader fails the build on an unmarked, unterminated or duplicated fence.
- Each executable example is executed, and its documented outcome asserted.
- The suite runs in the repository's existing gate sequence.
Introduced by #140.
Summary
The documentation library publishes 2 cross-language engineering practice
guides carrying 15 fenced examples, of which roughly 8 are executable or
otherwise machine-checkable. None of them is currently executed by any test.
An example that is never run is an assertion nobody checks, and these
documents are vendored into repositories across the estate, so a wrong example
propagates.
This issue asks for behavioural tests covering every example in this batch.
Why now
A review of these guides found footnote references pointing at unrelated
sources, which no automated check would catch.
Scope
What is being asked
Follow the tested-correctness contract the documentation style
guide
now specifies:
identifier, written
<!-- tested-example: <identifier> -->.tests exercise the shipped text rather than a copied fixture. The loader must
fail on an unmarked fence, an unterminated fence, a missing identifier, or a
duplicate identifier.
scenarios, so a documented example becomes a contract the implementation must
satisfy.
For this batch the natural harness is compiling or running the few executable
examples, and asserting that the Markdown templates the style guide publishes
still satisfy the repository's own Markdown gate.
Out of scope
Illustrative blocks that are not executable, such as directory trees, terminal
transcripts and utility-name listings, still need a marker so the loader can
prove no fence was missed, but their test may assert shape rather than execute
them. Roughly 7 of the 15 blocks in this batch fall into that category.
Acceptance
Introduced by #140.