Scenario corpus

A curated set of self-contained examples that show one mcptest concept at a time. Read them top to bottom for a tour, or jump to the one that matches what you are trying to do today. Scenarios 8 through 16 run against the hosted test server, so they need no local server and no setup.

#	Scenario	What it teaches
1	First test	The minimal stdio test against a placeholder server.
2	Performance budget	Lock in latency and token budgets per step.
3	Snapshot tests	Snapshot matcher with automatic cassette normalization.
4	Compliance baseline	Suppress known-failing rules while hardening incrementally.
5	CI quality gate	Three-stage CI pattern (pre-commit, PR, build).
6	URL target staging	URL target with bearer-token env, readiness probe, tenancy headers.
7	LLM-judge matcher	The `llm-judge` matcher with a `--max-cost` cap.
8	Catch schema drift	`mcptest diff` against the prior catalog to flag breaking changes.
9	Scan for attacks	`mcptest security` over a deliberately poisoned catalog.
10	Grade against the spec	Compliance grading, and what a failing run looks like.
11	Test behind OAuth	A token-gated endpoint, by bearer token or OAuth.
12	Multi-server suites	One suite across two servers, plus the cross-server trust boundary.
13	Tool overload	Tool selection when the catalog is crowded with decoys.
14	Rate-limit backoff	How the runner handles an HTTP 429 with `Retry-After`.
15	Migration doctor	Catch a legacy error code and plan the spec migration.
16	Record and replay	Record a session once, replay it offline in CI.
17	Model matrix	Fan one agent test across a `models:` list and read the grid.

Each scenario file:

Opens with a one-paragraph framing.
Shows the YAML test file inline.
Shows the matching CI workflow snippet when applicable.
Documents the expected output.
Cross-links to the conceptual docs.

If you want the full YAML reference, read docs/yaml-reference.md. If you want end-to-end CI patterns, read docs/guides/ci-integration.md.