/test - Web E2E Testing Agent Skill

/test - Web E2E Testing Agent

Prerequisites: Playwright MCP Setup

No npm install needed — Claude Code handles it automatically

Create .mcp.json in project root (not in .claude/ or subdirectories):

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

Restart Claude Code after adding/modifying .mcp.json
Verify MCP active: look for mcp__playwright__browser_* tools

CI Mode requirements (no MCP needed):

npm install -D @playwright/test
npx playwright install

CRITICAL: Mode Detection (Execute FIRST)

STEP 1: Parse for --ci flag
           │
    ┌──────┴──────┐
    ▼             ▼
Has --ci?     No --ci?
    │             │
    ▼             ▼
MODE = CI     STEP 2: Check for mcp__playwright__browser_* tools
              │
     ┌────────┴────────┐
     ▼                 ▼
Available?         NOT Available?
     │                 │
     ▼                 ▼
MODE = Interactive   Check Automation field
                     │
            ┌────────┴────────┐
            ▼                 ▼
      Automation: auto    Manual mode
            │                 │
            ▼                 ▼
      Fall back to CI     STOP — display
      Notify user         prereqs, do NOT
                          fall back or proceed

ABSOLUTE RULES:

No --ci + No Playwright MCP + Manual mode = STOP. Do not proceed. Do not fall back.
No --ci + No Playwright MCP + Auto mode = Fall back to CI silently. Notify user and continue.
No --ci + Playwright MCP available = Interactive mode ONLY. Never create test scripts.
--ci present = CI mode. Playwright MCP not required.

CRITICAL: Mode-Specific Rules

Interactive Mode — What NOT To Do

Do NOT create .ts, .js, or .spec test files
Do NOT create TEST_REPORT.md, TEST_SUMMARY.txt in project root
Do NOT create test-screenshots/ or similar folders in project root
Do NOT run npx playwright test
Do NOT spawn subagents to run headless tests
Use mcp__playwright__browser_* tools directly in conversation
Write final report ONLY to docs/testing/{task-name}.md

CI Mode — Allowed Actions

Create test scripts in tests/e2e/{task-name}/ (NOT project root)
Run npx playwright test for headless execution
Spawn subagents for parallel test execution
Write final report to docs/testing/{task-name}.md
Cleanup all temporary artifacts after tests
Ask user if they want to keep test scripts for CI pipeline

Workflow

Always execute Mode Detection FIRST.

Interactive Mode (Default)

/test {task-name}
       ↓
1. Read task document: ## Implementation Notes (primary), ## Acceptance Criteria (test cases)
2. Build test plan mapping each acceptance criterion to a Playwright action
3. Execute tests via mcp__playwright__browser_* tools directly
   ⚠️ DO NOT create test script files
4. Write report to docs/testing/{ID}-{task-name}.md using: docs/templates/test-report.md
5. Update TASKS.md
       ↓
Route on automation mode (see below)

CI Mode (`--ci` flag)

/test --ci {task-name}
       ↓
1. Read task document for requirements
2. Create test directory: tests/e2e/{task-name}/
3. Generate Playwright test script(s)
4. Run: npx playwright test
5. Capture results
6. Write report to docs/testing/{ID}-{task-name}.md using: docs/templates/test-report.md
7. Cleanup temporary artifacts (keep test scripts by default)
8. Update TASKS.md
       ↓
Route on automation mode (see below)

/test --ci --cleanup {task-name}
       ↓
Same as above, but ALSO deletes tests/e2e/{task-name}/

CI Mode: Directory Structure (CRITICAL)

project-root/
├── tests/
│   └── e2e/
│       └── {task-name}/           ← Test scripts go HERE (*.spec.ts)
│           ├── {task-name}.spec.ts
│           └── helpers.ts (if needed)
│
├── docs/
│   └── testing/
│       └── {task-name}.md         ← ONLY the final report goes HERE
│
└── (temporary — ALWAYS DELETE after tests)
    ├── TEST_REPORT.md, TEST_CASES.md, TEST_SUMMARY.txt
    ├── test_results.md, test_execution_summary.md
    ├── TEST_REPORT_INDEX.md, playwright_mcp_test_log.md
    ├── test-screenshots/, test-results/, playwright-report/

ONLY allowed in docs/testing/:

docs/testing/{task-name}.md (final test report, one per task)
docs/testing/README.md (if project has one)

CI Mode: Artifact Management

| Artifact | Location | --ci | --ci --cleanup | |----------|----------|--------|------------------| | Final test report | docs/testing/{task-name}.md | Keep | Keep | | Test scripts | tests/e2e/{task-name}/ | Keep | Delete | | TEST_CASES.md | anywhere | Delete | Delete | | test_results.md | anywhere | Delete | Delete | | test_execution_summary.md | anywhere | Delete | Delete | | TEST_REPORT_INDEX.md | anywhere | Delete | Delete | | playwright_mcp_test_log.md | anywhere | Delete | Delete | | TEST_SUMMARY.txt | anywhere | Delete | Delete | | test-screenshots/ | anywhere | Delete | Delete | | playwright-report/ | anywhere | Delete | Delete | | test-results/ | anywhere | Delete | Delete |

Cleanup commands (run at end of every CI test):

rm -f TEST_REPORT.md TEST_SUMMARY.txt TEST_CASES.md
rm -f test_results.md test_execution_summary.md TEST_REPORT_INDEX.md
rm -f playwright_mcp_test_log.md
rm -rf test-screenshots/ test-results/ playwright-report/
rm -f test-*.ts test-*.js *.spec.ts
rm -f docs/testing/TEST_CASES.md docs/testing/test_results.md
rm -f docs/testing/test_execution_summary.md docs/testing/TEST_REPORT_INDEX.md
rm -f docs/testing/playwright_mcp_test_log.md docs/testing/TEST_SUMMARY.txt
rm -f docs/testing/*.spec.ts

Pre-Testing Setup

Read task document in this priority order:

## Implementation Notes — how to access and test what was built (URL, credentials, setup)
## Acceptance Criteria — Given/When/Then scenarios to verify (your test cases)
If ## Implementation Notes missing, fall back to ## Requirements and ## File Changes

Do NOT scan the codebase or infer test scenarios.

Map each criterion to a Playwright action:

Given I am on `/auth/login`          → navigate to URL
When I submit valid credentials      → fill form + click submit
Then I am redirected to `/dashboard` → assert URL changed

Execute: happy path → error states → edge cases.

Testing with Playwright MCP

mcp__playwright__browser_navigate    - Go to URL
mcp__playwright__browser_snapshot    - Capture accessibility snapshot
mcp__playwright__browser_click       - Click elements
mcp__playwright__browser_type        - Type text
mcp__playwright__browser_fill_form   - Fill form fields
mcp__playwright__browser_take_screenshot - Capture screenshot
mcp__playwright__browser_console_messages - Check console
mcp__playwright__browser_network_requests - Check network
mcp__playwright__browser_wait_for    - Wait for conditions

Test execution pattern:

// 1. Navigate
mcp__playwright__browser_navigate({ url: "http://localhost:3000/path" })
// 2. Snapshot to understand structure
mcp__playwright__browser_snapshot()
// 3. Interact (use ref from snapshot)
mcp__playwright__browser_click({ ref: "button[Submit]", element: "Submit button" })
// 4. Verify
mcp__playwright__browser_snapshot()
// 5. Check errors
mcp__playwright__browser_console_messages({ level: "error" })

Responsive testing:

mcp__playwright__browser_resize({ width: 390, height: 844 }) // iPhone 14 Pro
mcp__playwright__browser_resize({ width: 768, height: 1024 }) // iPad

Write Test Report

Write report to docs/testing/{ID}-{task-name}.md using: docs/templates/test-report.md

Update TASKS.md

PASS: Move to "Approved" section with status "PASS - Awaiting approval"
FAIL: Keep in "Testing" with status "FAIL - See report"

Auto Mode Behavior

When task document has Automation: auto, this skill is a worker — output SIGNAL and exit. Do not spawn next skill.

On PASS

≡ SIGNAL
STAGE: test
STATUS: PASS
TASK: {ID}
SUMMARY: {N}/{N} acceptance criteria verified
REFERENCE: docs/testing/{ID}-{task-name}.md
≡ END

Manual mode: Run /clear then /document {ID}.

On FAIL

Write failure block to task document ## Implementation Notes:

### Test failure (attempt {N})
- **Failed criteria:** {list which acceptance criteria failed}
- **Root cause:** {specific observable failure — URL, element, response}
- **Files to check:** {files most likely involved}

≡ SIGNAL
STAGE: test
STATUS: FAIL
TASK: {ID}
SUMMARY: {N} criteria failed — details in test report
REFERENCE: docs/testing/{ID}-{task-name}.md
≡ END

Manual mode: Run /clear then /implement {ID} → /simplify {ID} → /test {ID}.

Manual Testing Guidance

For features that can't be fully automated, document in report:

| Test | Instructions | Expected Result | |------|--------------|-----------------| | Visual accuracy | Compare to design | Matches mockup | | Animation | Trigger X action | Smooth 60fps |

Manual mode handoff:

PASS: notify user, report at docs/testing/{ID}-{task-name}.md, next step /document {ID}
FAIL: notify user, report at docs/testing/{ID}-{task-name}.md, next step /implement {ID} then re-run /test {ID}

Agent Skills: /test - Web E2E Testing Agent

Install this agent skill to your local

Skill Files