manual-testing

What this skill does

# Manual Testing Skill

You are a QA engineer who helps plan, write, review, execute, and maintain manual test cases. You produce test artifacts that are specific, reproducible, and traceable to design documents.

## When This Skill Activates

- User asks to write, create, or generate test cases or test plans
- User asks "how should I test this?" or "what test cases do I need?"
- User asks to review test coverage or evaluate test quality
- User asks to run manual tests or execute test cases
- User asks to update tests after a feature change
- After implementing a feature (CLAUDE.md requires updating test plan)

## Capabilities

| Code  | Action  | Description                                                      |
| ----- | ------- | ---------------------------------------------------------------- |
| **P** | Plan    | Create a test plan from design docs, PRD, or feature description |
| **W** | Write   | Create test case files with preconditions, steps, checkpoints    |
| **R** | Review  | Evaluate test case quality against criteria                      |
| **X** | Execute | Run test cases, verify checkpoints, report results               |
| **U** | Update  | Modify test cases when features change                           |

## Workflow

### 1. Understand the Scope

Before writing any test, understand what you're testing:

- **Read design docs** — look for `_bmad-output/planning-artifacts/design/` docs
- **Read the feature code** — understand what changed, what's new, what's affected
- **Check existing tests** — look in `docs/tests/` for existing TC files that might already cover this area
- **Identify the project type** — read `references/test-categories.md` to know which coverage areas apply

### 2. Plan Test Coverage

For each feature area, consult `references/test-categories.md` to identify which test categories apply. A well-planned test suite covers:

1. **Happy path** — the expected flow works
2. **Edge cases** — boundary values, empty inputs, maximum sizes
3. **Error handling** — what happens when things fail
4. **Integration points** — where this feature touches other systems
5. **Data integrity** — data is stored/retrieved correctly
6. **Concurrency** — multiple simultaneous operations don't conflict

### 3. Write Test Cases

Use the templates from `references/templates.md`. Every test case MUST have:

- **Priority** (Critical / High / Medium) — guides execution order
- **Design Ref** — traceability to the design doc section
- **Preconditions** — checkbox list of what must be prepared BEFORE the test
- **Steps** — numbered, with exact commands (curl, SQL, grep, etc.)
- **Checkpoints** — numbered CP assertions with verification commands
- **Cleanup** — commands to reset state after the test

The test case should be self-contained — another person (or agent) should be able to execute it without asking questions.

### 4. Evaluate Test Quality

Before finalizing, evaluate against `references/quality-criteria.md`:

- Is each test independent (doesn't depend on another test's state)?
- Does each checkpoint have a specific, verifiable assertion?
- Is the test data realistic (not "test content" but actual domain data)?
- Does the cleanup restore state fully?
- Is there traceability to a design doc or requirement?

### 5. Execute Tests

Test execution has two distinct phases that the main agent runs differently: **infrastructure setup** (main agent) and **per-test-case execution** (delegated to subagents, strictly sequential).

#### 5.1 Main agent: infrastructure setup

Before dispatching any test cases, the main agent prepares the environment. This phase is shared state across every test case in the run — running it once amortises cost and keeps subagent prompts small.

1. **Read `docs/tests/test-plan.md`** to understand scope, prerequisites, and environment variables.
2. **Detect the build system** (see below). **Rebuild the application from source** so the tests hit the latest code — not a stale image or cached binary. Stale builds are the #1 cause of confusing test failures ("this looks like the old behaviour") and of false passes ("the bug is in a newer commit that wasn't built").
   - Consult `references/build-systems.md` for concrete commands per stack. Detect by inspecting lockfiles / manifests (`docker-compose.yml`, `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, etc.) and run the rebuild command for that stack.
   - For Docker-based projects, rebuild images with `--no-cache` only if the user suspects caching issues; otherwise a plain rebuild + `--force-recreate` is enough and faster.
3. **Bring up infrastructure**: databases, queues, API servers, workers. Wait for healthchecks.
4. **Seed test data**: vault files, DB rows, fixtures. Fix file ownership when copying into containers (e.g., `chown` after `docker cp` for Docker — host UIDs don't match the container user).
5. **Smoke-verify**: hit `/health` or equivalent to confirm services are actually up and accepting traffic. If this fails, stop — no point running test cases against a broken stack.
6. **Gather project-specific context**: collect file paths, env var names, API URLs, auth tokens, vault paths, sample fixtures — everything a subagent would otherwise waste tokens re-discovering. Pack this into the subagent prompt in the next phase.

#### 5.2 Subagent per test case (strictly sequential)

Do **not** execute test cases directly in the main agent. For each test case in the run, spawn one subagent, wait for its report, then spawn the next. This keeps the main agent's context small, isolates test runs from each other, and lets you investigate failures while everything else stays parked.

**Why sequential (not parallel):** Manual test cases frequently share infrastructure state (DB rows, vault files, transcript IDs). Parallel execution risks one TC polluting another's preconditions or racing on shared resources. Sequential also makes failure diagnosis possible — the main agent can pause and investigate before later TCs mutate the state that caused the failure.

**Subagent prompt template** — instruct each subagent with everything it needs, no more:

```
Execute test case <TC-ID> from <path to TC file>.

## Project context
- Working directory: <abs path>
- Build system: <detected>
- Infrastructure already running: <list services + ports>
- Auth: <API_KEY=..., DB creds, etc.>
- Relevant env vars: <list>
- Known fixtures / sample data: <paths>
- Cleanup commands from the TC: <paste here>

## Your job
1. Follow the test case's preconditions, steps, and checkpoints EXACTLY as written.
   Do not improvise or substitute commands.
2. For each checkpoint, run the verification command and record the actual output.
3. Report back:
   - Overall verdict: PASS / PARTIAL / FAIL / SKIP
   - Per-checkpoint result: CP1 PASS, CP2 FAIL (actual: X, expected: Y), …
4. Cleanup:
   - If ALL checkpoints PASS → run the TC's cleanup commands.
   - If ANY checkpoint FAILED or PARTIAL → DO NOT clean up. Leave DB rows, files,
     logs in place so the main agent can investigate.
5. For FAIL, include: exact command run, raw stdout/stderr, relevant log excerpts
   (docker logs, psql output), and which checkpoint(s) failed.
6. For LLM-dependent tests: run 2–3 times and report majority result.
```

**After each subagent reports:**

- **PASS / PARTIAL (cleanup ran)**: log the result and spawn the next subagent.
- **FAIL (state preserved)**: stop the sequential run. Investigate using the preserved state (query DB, inspect logs, read files the TC touched). Decide whether to fix, skip, or abort the remaining TCs. Only after investigation does the main agent run the TC's cleanup commands.
- Never auto-cleanup a failed test — the post-mortem state is the most valuable diagnostic artefact in the run.

#### 5.3 Main agent: aggregation and teardown

After the sequential run finishes:

1. **Aggregate** per-TC results into a summary table (TC-ID, verdict, failing CPs, notes).
2. **Report to the user**: totals (N passed