| name | test |
| description | Generate test plan, test cases, test data fixtures, and Playwright E2E tests mapped to acceptance criteria. |
| argument-hint | [--plan-only | --e2e-only] |
| context | fork |
| agent | generator |
Test Skill — Test Plan, Cases, Fixtures, and Playwright E2E
Usage
/test
/test --plan-only
/test --e2e-only
/test — generate all test artefacts: plan, cases, fixtures, and E2E tests./test --plan-only — generate test plan, test cases, and test data fixtures (everything in specs/test_artefacts/). Stop before writing Playwright files. Does NOT require source code — only needs stories from /spec./test --e2e-only — skip plan/cases, go straight to Playwright E2E generation. Use when plan already exists and source code has been built.
Prerequisites
For --plan-only (test planning phase — runs parallel with /design):
specs/stories/ — user stories with acceptance criteria (one file per story).project-manifest.json — for service configuration context.
For full run or --e2e-only (Playwright generation — runs after /auto):
specs/stories/ — user stories with acceptance criteria.backend/ and/or frontend/ — source code that the E2E tests will target.project-manifest.json — for base URLs and service port configuration.specs/test_artefacts/ — test plan, cases, and fixtures (generated by --plan-only).
If required prerequisites are missing, stop and report what is absent.
Steps
Step 1 — Read Patterns
Read .claude/skills/code-gen/SKILL.md for quality principles (typing, error handling, test structure), plus .claude/skills/code-gen/references/test-strategy.md for the test-layer model and boundary checklist.
Read .claude/skills/evaluate/SKILL.md for the contract verification approach used by the evaluator.
Read .claude/skills/evaluate/references/playwright-patterns.md for all selector, assertion, and waiting rules — it is the single source of truth (shared with /evaluate). Read .claude/skills/code-gen/references/test-playwright.md secondarily, for config and file-structure patterns only.
Step 2 — Read Acceptance Criteria
Read every story file in specs/stories/. For each story, extract:
- Story ID and title
- Acceptance criteria (AC) — each criterion becomes one or more test cases.
- Edge cases and error paths documented in the story.
Every test case generated must trace to a specific AC. Record the mapping explicitly.
Step 3 — Spawn the generator (test-authoring)
Spawn the generator agent with the full context: story files, source code structure, and the patterns read in Step 1. Point it at .claude/skills/test/references/test-authoring.md for the test-plan / test-case / Playwright-E2E / fixture authoring guidance.
The agent operates in the forked context. It must not modify source code.
Step 4 — Generate Test Artefacts (specs/test_artefacts/)
Create specs/test_artefacts/ if it does not exist.
specs/test_artefacts/test-plan.md
- Scope: what is being tested and what is explicitly out of scope.
- Test levels: unit, integration, E2E.
- Environment assumptions: base URLs, test DB, seed state.
- Pass/fail criteria for the sprint.
specs/test_artefacts/test-cases.md
- One section per story.
- Each test case: ID, AC reference, preconditions, steps, expected result.
- Cover success paths, error paths, and boundary conditions.
specs/test_artefacts/test-data/
- One fixture file per domain entity (e.g.,
orders.json, users.json).
- Data must be domain-representative: real-looking emails, valid UUIDs, plausible amounts.
- Never use
"foo", 123, or "test" as stand-in values.
- In
--plan-only mode, fixtures are schema-free: /design runs in parallel, so specs/design/api-contracts.md may not exist yet. Derive field names from story acceptance criteria, and reconcile fixtures against api-contracts.md in Step 5 (or when /build Phase 4 begins) — field-name drift between fixtures and contracts is expected until then and must be resolved before any Playwright file uses them.
specs/test_artefacts/test-traces.json — the trace spine: one entry per test case, each tracing to the acceptance-criterion id(s) it verifies:
[
{ "id": "TC-1", "text": "register returns 201 on valid input", "traces": ["E1-S1-AC1"] },
{ "id": "TC-2", "text": "register rejects duplicate email with 409", "traces": ["E1-S1-AC2"] }
]
Every test case must trace to at least one {story}-AC{n} id from specs/stories/story-traces.json. A test case tracing to no AC tests behavior nobody asked for; an AC with no test case is an untested requirement.
Step 4.5 — Grounding Gate [HARD BLOCK — when specs/stories/story-traces.json exists]
Build the AC index (the acceptance criteria are the upstream this layer must cover) and run the deterministic check:
node -e "const fs=require('fs');const s=JSON.parse(fs.readFileSync('specs/stories/story-traces.json'));fs.writeFileSync('specs/test_artefacts/ac-index.json',JSON.stringify(s.flatMap(x=>(x.acs||[]).map(id=>({id})))))"
node .claude/scripts/trace-check.js \
--required specs/test_artefacts/ac-index.json \
--downstream specs/test_artefacts/test-traces.json \
--layer test \
--out specs/reviews/test-grounding.json
specs/reviews/test-grounding.json is a hard gate: any net_new (test case tracing to no AC) or dropped (AC with no test case — an untested requirement) blocks. Resolve before reporting the plan. (Skip when story-traces.json does not exist.)
If --plan-only: STOP HERE. Steps 4–4.5 (plan + cases + fixtures + trace spine + grounding gate) are the complete deliverable for the planning phase. Do not proceed to Playwright generation — source code does not exist yet. Report the generated artifacts and exit.
Step 5 — Generate Playwright E2E Tests (e2e/)
Create e2e/ at the project root if it does not exist.
For each story, generate a Playwright test file named {story-id}.spec.ts.
Selector and assertion rules are single-sourced in .claude/skills/evaluate/references/playwright-patterns.md (the canonical Playwright reference, shared with /evaluate). The rules below summarize it — defer to that file if they differ.
Rules for Playwright tests:
- Use
getByRole, getByLabel, getByText — never CSS selectors or XPath.
- No
waitForTimeout. Use expect(locator).toBeVisible() with retry.
- Each
test() block maps to exactly one acceptance criterion. The test name must reference the AC.
- Import fixtures from
specs/test_artefacts/test-data/.
- Follow Arrange → Act → Assert structure.
Step 6 — Copy Playwright Config
Copy the config template:
cp .claude/templates/playwright.config.template.ts playwright.config.ts
Fill in the baseURL values from project-manifest.json. Configure webServer entries for each service that needs to be running during tests.
Step 7 — Install Playwright
npx playwright install --with-deps chromium
Step 8 — Verify
npx playwright test
All tests must pass on the first run against the target environment. A failing test that was written incorrectly is not acceptable — fix the test before reporting results.
Output
| Path | Purpose |
|---|
specs/test_artefacts/test-plan.md | Sprint test plan |
specs/test_artefacts/test-cases.md | Full test case inventory mapped to ACs |
specs/test_artefacts/test-data/ | JSON fixture files per domain entity |
specs/test_artefacts/test-traces.json | Trace spine: each test case → AC id(s) |
specs/reviews/test-grounding.json | (when story-traces exists) deterministic AC-coverage verdict |
e2e/{story-id}.spec.ts | Playwright tests per story |
playwright.config.ts | Playwright configuration |
Gotchas
- Test cases not mapped to acceptance criteria. Every test case must cite its AC. Unmapped tests are noise.
- CSS selectors instead of
getByRole. CSS selectors break on refactors. Use ARIA-based selectors exclusively.
- Flaky waits.
waitForTimeout is banned. Network or animation delays must be handled with expect(...).toBeVisible() or waitForResponse.
- Missing test data fixtures. Tests that generate random data inline produce unrepeatable results. Always use fixture files.
- Testing implementation details. Test behavior through the public interface, not internal state.
- Skipping error paths. Every documented error path in the AC must have a test.
