# Test

> Generate test plan, test cases, test data fixtures, and Playwright E2E tests mapped to acceptance criteria.

- Skill: `cwijayasundara/test-4` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add cwijayasundara/test-4`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cwijayasundara/test-4/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: cwijayasundara (https://skillmd.com/u/cwijayasundara)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/cwijayasundara/test-4

---


# 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:
```json
[
  { "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:

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

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