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:

---
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 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#

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 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 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.