# 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](../guides/author-test-plans.md) 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](../../../integration/agent-testing.md#lifecycle-hooks).

## 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](../../../integration/agent-testing.md#test-definition), [section configuration](../../../integration/agent-testing.md#optional-section-configuration), and [the sample catalog](../../examples/test-plan.md). [Inspect command](runner-commands.md) 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.