manual-testing

Files (5)

• SKILL.md
• build-systems.md · references/
• quality-criteria.md · references/
• templates.md · references/
• test-categories.md · references/

SKILL.md (first lines)

# 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

### 0. Harness Gate — can the agent drive and observe this product like a human?

**Run this before scoping, before writing a single scenario.** A manual test is only as good as the executor's ability to operate the product and see the result independently. An agent that cannot click the button and cannot look at the screen will write assertions it can never run, and the suite is scrap.

Answer two questions about the **agent**, not about the system:

| | Question | If NO |
| --- | --- | --- |
| **Control** | Can the agent drive the product the way the user does — click, type, open menus, switch windows or profiles? | The suite is human-only. Say so, or get the harness. |
| **Observation** | Can the agent see the real result independently of what the product reports about itself — real pixels, real stored bytes, the real file? | Assertions collapse to the product's self-report. Get the harness. |

Both must be YES before authoring. **State the answers explicitly in your first reply** — a capability listed as an assumption after the deliverable is the gate not run.

If either is NO: **stop and recommend the harness setup to the user.** Name the capability gap, name the tool that closes it, and say what it unlocks. Do not write the suite and hope; do not silently downgrade to a suite only a human can execute.

**Recommended harness by product type:**

| Product | Recommend | Why |
| --- | --- | --- |
| Native desktop app (Windows/macOS/Linux) | `cua-driver` | Drives real windows, menus, and dialogs; captures real window pixels — the only way to see what the user sees |
| Web application | `playwright-cli` | Drives the page and reads the DOM, network, and console |
| **Chrome extension** | `playwright-cli` **and** `cua-driver` | Needs both: Playwright for page/DOM and browser-internal state (`chrome.storage`, service worker), cua-driver for the parts Playwright cannot reach — the extension popup, the toolbar, and native browser chrome |
| Headless service / CLI / API | Shell + the service's own clients | No GUI to drive; observation is files, exit codes, DB rows, logs |
| Mobile app | Platform driver (Appium/XCUITest/Espresso) | Same reasoning as desktop |

Reason from the two capabilities, not from the table — a product not listed still needs both answered. When the product **is** the automation surface (an MCP server, a bridge, a driver), its own output is a claim under test; observation must come from outside it.

**Verify the harness before trusting it**, e.g. `cua-driver status` returns an interactive session, or a probe screenshot of the real window is captured and read. A harness assumed present is the same defect as a capability assumed.

### 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** — find the project's suite before writing anything new. In this repo that is `tests/uat/` (`test-plan.md`, `testcases/TC-*.md`); other projects may use `docs/tests/` or `test/manual/`. Read the plan's format contract and match it — a test case in the wrong house format is rework.
- **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

**Match the suite's existing format first.** Read the test plan's format contract before writing. Two structures are in common use; `references/templates.md` has both.

| Structure | Shape | Use when |
| --- | --- | --- |
| **Given/When/Then** | One scenario holds its own setup, actions, and assertions | Default for new suites. A reader never has to map "step 3" onto "CP5", and a renumbered step can't orphan an assertion. |
| **Steps + Checkpoints** | Numbered steps, then numbered `CP1..CPn` | Only when the suite already uses it. Don't mix the two in one suite. |

Either way, every test case MUST have:

- **Priority** (Critical / High / Medium) — guides execution order
- **Design Ref** — traceability to the design doc section
- **Preconditions** — what must be prepared BEFORE the test (file-level, shared by every scenario)
- **The sequence and its assertions** — exact commands, exact expected values
- **Cleanup** — commands to reset state after the test

**Markdown hard breaks are required in Given/When/Then files.** Consecutive `**Given**` / `**When**` / `**Then**` / `**And**` lines with no trailing whitespace render as **one run-on paragraph** — the assertions become unreadable. End each such line with two spaces. Verify before you hand the file over:

```bash
# every GWT line must end in two spaces; prints the offenders
grep -n '^\*\*\(Given\|When\|Then\|And\)\*\*' TC-*.md | grep -v '  $'
```

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 the suite's test plan** (`tests/uat/test-plan.md` in this repo) for scope, prerequisites, environment variables, and the run-folder convention.

From bmad-labs/skills, MIT.

More from bmad-labs/skills