# Author a Markdown test plan

Create a directory for your catalog. Put each scenario in its own Markdown file; use directories and optional `section.md` files to group shared setup and guidance. Keep expectations specific enough for a worker to decide what it observed.

## Write one test

Save this as `profile/save.snag.md` in your project's catalog:

```markdown
---
id: profile-save-roundtrip
title: Saved profile name survives navigation
executor: browser
tags: [smoke]
components: [profile]
levels: [acceptance]
---

## Prerequisites

A disposable host is running at the agreed URL in fixed mode.

## Steps

- [ ] Open Profile, enter Morgan Lee, and save.
- [ ] Visit Overview, then return to Profile.
- [ ] Read the saved display name.

## Expected outcomes

The name is Morgan Lee after returning, and the confirmation agrees.
```

Use an optional section-local ID; the filename provides a fallback. Free prose is valid; unknown frontmatter is retained without executable authority. Prefer checkbox steps when authoring a checklist. Supported executors are browser, api and cli. [Format reference](../reference/test-definition-format.md) describes optional fields.

## Share guidance through sections

Put common fixture guidance, executor defaults, evidence requirements and hooks in `section.md`. A root section is the only location for run hooks. Section hooks establish shared resources once; per-test hooks handle each isolated attempt. Avoid using once-per-section login as if it authenticated new browser contexts.

Metadata such as tags is inherited for selection. Do not encode credentials in definitions, destinations or report text. Name environment inputs and resolve secrets in trusted host code.

## Validate before execution

```sh
node tooling/testing/plan.mts inspect --catalog <project>/tests
```

Inspection reports selection metadata, alternatives and unselectable gaps. Use `parseCatalog` or `resolveCatalogTest` through the public API for explicit semantic authoring checks; execution validates only reached tests. Check inheritance by reading parent sections together with the leaf. The [sample catalog](../../examples/test-plan.md) shows realistic hierarchy and intentional failures.

Change scenario IDs only when identity changes. Execution-affecting changes produce a new revision and cannot silently retry old attempts. [Selection and execution](select-and-run-tests.md) explains the next step.

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.