Test plans and sections#

A test plan describes behaviors and scenarios to verify. The current executable catalog is a directory of .snag.md test definitions, grouped by directory and optional section.md configuration. It is not a separate manifest.

Reusable definitions#

A test definition has a section-local optional explicit ID (filename fallback) and a free-form Markdown body. Authoring recommends prerequisites, checkbox steps and expected outcomes. Those instructions are reusable across attempts. A test result records what happened when they were executed; it must not rewrite the original definition to fit the observation.

Hierarchical sections#

Directories create sections even without a section file. A section can add instructions, metadata, executor defaults, evidence requirements, destination settings and lifecycle hooks. Tests start in deterministic filename traversal order; numeric order has no precedence.

Instructions append root-to-leaf with explicit replacement. Tags accumulate case-insensitively with explicit removal; components and levels remain descriptive sets. Explicit test executor values override section defaults. Destination provider/project settings inherit together; a child destination replaces that pair. These are routing hints, not credentials or live provider access.

Execution revisions#

The parser fingerprints the resolved execution contract, including the free-form body, authored checklist, optional prerequisites/expectations, inherited instructions/settings and declared hooks. Metadata used only for discovery/selection does not change that revision. An explicit retry must match it; changing instructions while reusing old attempts would otherwise hide which contract was tested.

The revision fingerprint is compatibility metadata, not a cryptographic authenticity claim. A project's hook implementation still needs its own change discipline.

Inspect the sample catalog, write a first definition, and consult format/reference for inheritance and validation rules.