Test and section format#
The catalog is a directory of Markdown sources. Discover .snag.md tests with free-form Markdown bodies. Prerequisites, checkbox steps and expected outcomes are recommended authoring structure; supporting Markdown is ignored. section.md configures its directory's section; directories without one still create sections.
Test fields#
| Field | Meaning |
|---|---|
id | Optional section-local ID; filename fallback |
title | Human-readable title; falls back to a body H1 or the stable ID |
executor | browser, api, or cli; can inherit a section default |
order | Legacy metadata; filenames determine start order |
tags, components, levels | String-list selection/descriptive metadata, merged as sets |
instructions | Additional inherited guidance |
destination | Provider/project pair; replaces the inherited pair when explicit |
evidence | Per-executor screenshot/video/diagnostic/recording/file policy |
hooks | Per-test beforeEach/afterEach declarations |
Unknown frontmatter is preserved without executable authority. Recognized settings validate when a selected test is reached. Unknowable selection metadata is reported as unselectable; invalid reached definitions are recorded/skipped while independent tests continue. Authoring guide provides a minimal complete definition.
Section fields and hooks#
Sections can supply title, order, executor defaults and shared settings. The body contributes inherited instructions. Root section.md alone can declare beforeRun/afterRun. Sections declare beforeSection/afterSection; per-test hooks inherit through section layers.
Hook items require a unique ID and exactly one function name or instruction. onFailure is block by default or stop. Layer controls support disable, items, and replace; their precise composition is shown in canonical lifecycle guidance.
Resolution and revisions#
Instructions append root-to-leaf, with instructions: {replace: true, items: [...]} for replacement. Tags accumulate case-insensitively with tags: {remove: [...], items: [...]} for removal. Explicit executor settings override defaults. Evidence merges per executor/kind; default requirements and inherited overrides apply to the resolved test contract. Tests start in deterministic filename traversal order.
Execution revisions fingerprint instructions, expectations, executor, evidence and declared hooks; descriptive/selection metadata does not change execution compatibility. Explicit retry requires matching revisions. This is not a cryptographic trust guarantee or a snapshot of hook implementation code.
For exact examples, read canonical test format, section configuration, and the sample catalog. Inspect command reports selection metadata, alternatives and unselectable gaps; semantic validation is lazy.
References use catalog-id:section/local-id; root tests use catalog-id:local-id. Filename-ordered duplicate suffixes skip occupied authored IDs. Artifacts retain original source paths and resolved definitions. Rename existing test files from .md to .snag.md deliberately and start a new run after identity/revision changes; this is not a general artifact migration policy.