Skip to content

Test every example in the cross-language engineering practice guides (15 examples) #149

Description

@leynos

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

Document Examples Languages
documentation-style-guide.md 9 markdown 4, none 2, rust 2, mermaid 1
complexity-antipatterns-and-refactoring-strategies.md 6 cpp 2, python 2, java 2

What is being asked

Follow the tested-correctness contract the documentation style
guide

now specifies:

  1. Precede every fenced example with a marker comment carrying a stable
    identifier, written <!-- tested-example: <identifier> -->.
  2. 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.
  3. 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.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions