Test

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:

# Flatten every story's acceptance-criterion ids into the upstream index
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

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.