qa

name	qa
description	AI-driven browser testing against feature specs. Default mode reads spec REQs and autonomously tests in a real browser via Playwright MCP. Also supports running existing Playwright test files, visual regression, and accessibility audits.
allowed-tools	Bash, Read, Glob, Grep, Agent
model	sonnet

/qa — Browser Quality Assurance

AI-driven browser testing. The default mode reads your feature spec and autonomously drives a real browser to verify every REQ — clicking, typing, navigating like an actual user.

Usage

/qa [feature]            # Spec-driven AI browser testing (default, thorough)
/qa --quick [feature]    # Spec-driven fast smoke test (primary flow only)
/qa --spec [feature]     # Explicit spec-driven testing
/qa --e2e [feature]      # Run existing Playwright test files
/qa --visual [feature]   # Visual regression (screenshot comparison)
/qa --a11y [feature]     # Accessibility audit (axe-core)
/qa --all [feature]      # Run all modes
/qa [test-path]          # Run specific test file (treated as --e2e)

Routing

Parse $ARGUMENTS to determine mode:

• --quick: Spec-driven Mode with SCOPE: commit (fast smoke test — primary flow only)
• --e2e: Jump to E2E Mode
• --visual: Jump to Visual/A11y Mode with MODE: visual
• --a11y: Jump to Visual/A11y Mode with MODE: a11y
• --all: Run Spec-driven → E2E → Visual → A11y sequentially
• --spec or no flag (default): Jump to Spec-driven Mode with SCOPE: branch (thorough)
• If argument looks like a file path (contains .spec. or .test. or /): Treat as --e2e with that path

---

Spec-driven Mode (default)

1. Resolve feature name

• Parse feature name from $ARGUMENTS (e.g., /qa checkout-coupon)
• If no feature name: read spec/STATE.md for the active feature
• If still no feature: list available features from spec/feature/ and ask user

2. Verify spec exists

spec/feature/[name]/spec.md must exist

If not found:

No spec found for feature "[name]".
Run /spec [name] first to create a feature spec, or use /qa --e2e to run existing test files.

→ STOP

3. Verify dev server

Check if a dev server is already running on common ports:

curl -s -o /dev/null -w "%{http_code}" http://localhost:3000 2>/dev/null | grep -q 200 && echo "http://localhost:3000" && exit 0
curl -s -o /dev/null -w "%{http_code}" http://localhost:3001 2>/dev/null | grep -q 200 && echo "http://localhost:3001" && exit 0
curl -s -o /dev/null -w "%{http_code}" http://localhost:5173 2>/dev/null | grep -q 200 && echo "http://localhost:5173" && exit 0
echo "NOT_RUNNING"

If not running → ask the user:

Dev server is not running. Please start it in a separate terminal:
  npm run dev
Then re-run /qa.

→ STOP — do not start the dev server automatically. Background processes are unreliable and leave orphan servers.

Record the BASE_URL that responded (e.g., http://localhost:3000).

4. Spawn browser-tester agent

[HANDOFF]
TO: browser-tester (sonnet)
TASK: Autonomous spec-based browser testing for feature "[feature-name]"
MODE: spec-driven
SCOPE: [branch (default) | commit (--quick)]
BASE_URL: [detected dev server URL]
DONE-WHEN:
  - Every REQ from spec.md has PASS/FAIL/SKIP with failure classification
  - Console errors checked after each navigation
  - Structured report with per-REQ results, evidence, and failure taxonomy
  - Adversarial edge cases tested (depth depends on SCOPE)
MUST-NOT:
  - Modify any file
  - Spend more than 4 attempts on any single REQ
  - Retry without new evidence (fresh snapshot, different approach)
READS:
  - spec/feature/[feature-name]/spec.md
  - spec/feature/[feature-name]/design.md
[/HANDOFF]

5. Collect and output final report

Receive the browser-tester report and output:

# QA Report: [feature-name]
Date: YYYY-MM-DD | Mode: spec-driven

## Spec Compliance
| REQ | Description | Status | Classification | Signals | Evidence |
|-----|------------|--------|---------------|---------|----------|
| REQ-001 | ... | PASS | — | 2/2 | ... |
| REQ-002 | ... | FAIL | APP_BUG | 0/2 | ... |

## Adversarial Findings
| ID | Test | Result | Detail |
|----|------|--------|--------|
| ADV-001 | ... | ... | ... |

## Console Errors
[Any errors captured]

## Summary
- REQs: N tested, N passed, N failed, N skipped
- Adversarial: N tested, N issues found

6. Integration with checkpoint flow

If the active feature spec has checkpoint:human-verify:

• After all REQs pass → trigger checkpoint for human browser verification
• After any REQ fails → do NOT trigger checkpoint — report failures first

---

E2E Mode (--e2e)

Run existing Playwright test files.

1. Verify Playwright installed

npx playwright --version 2>/dev/null || echo "NOT_INSTALLED"

If not installed:

Playwright is not installed. To set up:
  npm install -D @playwright/test
  npx playwright install

→ STOP

2. Verify dev server (same as spec-driven mode)

3. Run tests

npx playwright test --reporter=list $ARGUMENTS

If $ARGUMENTS is a specific test path:

npx playwright test [test-path] --reporter=list

4. Report results

# QA Report: E2E
Date: YYYY-MM-DD | Mode: e2e

## Results
- Tests run: N
- Passed: N
- Failed: N
- Skipped: N

## Failures (if any)
| Test | Error | File |
|------|-------|------|
| ... | ... | ... |

---

Visual/A11y Mode

Visual Regression (--visual)

Spawn browser-tester agent:

[HANDOFF]
TO: browser-tester (sonnet)
TASK: Visual regression testing for feature "[feature-name]"
MODE: visual
READS:
  - spec/feature/[feature-name]/design.md
[/HANDOFF]

Accessibility Audit (--a11y)

Option A — If @axe-core/playwright is installed and tests exist:

npx playwright test --grep "a11y\|accessibility" --reporter=list

Option B — Spawn browser-tester agent:

[HANDOFF]
TO: browser-tester (sonnet)
TASK: Accessibility audit for feature "[feature-name]"
MODE: a11y
READS:
  - spec/feature/[feature-name]/design.md
[/HANDOFF]

---

Hard constraints

• Never modify source code — only test and report
• If Playwright is not installed, do not attempt to install without user confirmation
• Always report actual test output, not assumptions
• Do not start dev servers automatically — ask the user to start one if not running