playwright-verification

majiayu000 的头像作者 majiayu000

使用 Playwright MCP 和 Claude Code CLI 进行自动功能验证。在验证 UI 功能、运行验收测试、检查功能完成状态或验证 features.json 验证步骤时使用。与代理开发工作流程集成以进行进度跟踪。

📖 中文导读:使用 Playwright MCP 和 Claude Code CLI 进行自动功能验证。在验证 UI 功能、运行验收测试、检查功能完成状态或验证 features.json 验证步骤时使用。与代理开发工作流程集成以进行进度跟踪。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: playwright-verification description: Automated feature verification using Playwright MCP and Claude Code CLI. Use when verifying UI features, running acceptance tests, checking feature completion status, or validating features.json verification steps. Integrates with agentic-development workflow for progress tracking.

Playwright Verification Skill

Automated browser-based verification of features.json using Microsoft's Playwright MCP server and Claude Code CLI.

Quick Start

# In Claude Code CLI
claude
> /project:verify p6-sound-list      # Verify single feature
> /project:verify-all                 # Verify all incomplete features

Prerequisites

# One-time setup
npm install -D @playwright/test
npx playwright install chromium

# Add MCP to Claude Code (per-project)
claude mcp add playwright -- npx @playwright/mcp@latest --headless

Core Concepts

Verification Flow

features.json           Claude Code              Playwright MCP
     │                      │                         │
     │  verification: [     │                         │
     │    "Click X",        │  Parse steps            │
     │    "Panel opens"     │────────────────────────>│
     │  ]                   │                         │
     │                      │  browser_click("X")     │
     │                      │────────────────────────>│
     │                      │                         │ Execute
     │                      │  browser_snapshot()     │
     │                      │<────────────────────────│
     │                      │                         │
     │  passes: true        │  Update JSON            │
     │<─────────────────────│                         │

Verification Step Patterns

Map plain English verification steps to Playwright MCP actions:

Step Pattern Playwright Action Example
"Click X button/toggle" browser_click "Click Sound Browser toggle"
"Panel opens/closes" browser_snapshot + assert "Panel opens showing categories"
"X visible/shown" browser_snapshot + find element "Search input visible"
"X hidden/not visible" browser_snapshot + assert absent "Panel closes on click-away"
"Typing X filters Y" browser_type + browser_snapshot "Typing filters samples"
"Persists via localStorage" browser_evaluate "Theme persists via localStorage"
"Shortcut X does Y" browser_press_key + verify "Escape stops all audio"
"Works when X not focused" browser_click outside + action "Works when REPL not focused"
"Double-click X" browser_click with count:2 "Double-click inserts name"

Feature Dependencies

Features with dependencies are skipped if dependencies haven't passed:

{
  "id": "p6-sound-search",
  "dependencies": ["p6-sound-list"],  // Must pass first
  "passes": false
}

Verification order respects dependency graph automatically.

Commands Reference

/project:verify

Verify a single feature by ID.

Usage:

/project:verify p6-sound-list

Process:

  1. Read feature from features.json
  2. Check dependencies (skip if not met)
  3. Navigate to localhost:5173
  4. Execute each verification step
  5. Report pass/fail per step
  6. Update features.json if ALL pass

Output:

=== Verifying: p6-sound-list ===
✓ Click Sound Browser toggle button
✓ Panel opens showing sample categories
✓ Each category expands to show sample names
✗ Sample count displayed per category
✓ Panel closes on toggle or click-away

Result: 4/5 passed - FAIL

/project:verify-all

Verify all incomplete features in current phase.

Usage:

/project:verify-all

Process:

  1. Read currentPhase from features.json meta
  2. Filter: phase === currentPhase AND passes === false
  3. Sort by dependency order
  4. Run verification on each
  5. Generate summary report
  6. Update claude-progress.txt

Output:

=== Phase 6 Verification Summary ===

Passing: 3/16
├── p6-sound-list ✓
├── p6-shortcut-halt ✓
└── p6-hud-fps ✓

Failed: 1/16
└── p6-sound-search ✗ (step 3)

Skipped: 2/16 (dependencies not met)
├── p6-sound-preview
└── p6-sound-insert

Next priority: p6-sound-search

Playwright MCP Tools

Available tools when Playwright MCP is connected:

Tool Purpose
browser_navigate Go to URL
browser_click Click element by name/role
browser_type Type into focused element
browser_press_key Press keyboard key
browser_snapshot Get accessibility tree
browser_evaluate Run JavaScript in page
browser_scroll Scroll page/element
browser_wait Wait for condition

Accessibility Tree

Playwright MCP uses accessibility tree, not screenshots. Element identification via:

  • Role: button, textbox, heading, etc.
  • Name: visible text or aria-label
  • State: checked, expanded, disabled

Example snapshot fragment:

- button "Sound Browser" [ref=btn1]
- region "Sound Panel" [ref=panel1]
  - heading "Drums"
  - list
    - listitem "bd" [ref=item1]
    - listitem "sd" [ref=item2]

File Structure

basilisk-av/
├── .claude/
│   ├── settings.json          # MCP config
│   └── commands/
│       ├── verify.md          # Single feature command
│       └── verify-all.md      # Batch command
├── features.json              # Feature definitions
├── claude-progress.txt        # Session tracking
└── init.sh                    # Dev startup

features.json Schema

{
  "meta": {
    "project": "basilisk-av",
    "currentPhase": 6,
    "lastUpdated": "2025-12-12"
  },
  "features": [
    {
      "id": "p6-feature-name",
      "phase": 6,
      "category": "category-name",
      "description": "What it does",
      "priority": "high|medium|low",
      "dependencies": ["p6-other-feature"],
      "verification": [
        "Step 1 in plain English",
        "Step 2 in plain English"
      ],
      "passes": false
    }
  ]
}

Rules:

  • Only modify passes field during verification
  • Never edit verification steps mid-session
  • Dependencies must use exact feature IDs

Debugging

Headed Mode (Watch Browser)

# Remove headless flag
claude mcp remove playwright
claude mcp add playwright -- npx @playwright/mcp@latest

# Now browser window visible during verification

Check MCP Connection

claude
> /mcp
# Should list: playwright

Manual Snapshot

claude
> Use playwright to navigate to localhost:5173 and take a snapshot

Common Issues

Issue Solution
MCP not found claude mcp add playwright -- npx @playwright/mcp@latest
Browser won't launch npx playwright install chromium
Element not found Check accessibility tree with browser_snapshot
Timeout Increase wait, check dev server running
WSL display issues Use --headless or set DISPLAY=:0

Integration with Agentic Development

This skill extends the agentic-development workflow:

  1. Session Start: init.sh shows feature status
  2. Development: Implement feature code
  3. Verification: /project:verify <id> runs automated checks
  4. Progress: claude-progress.txt updated automatically
  5. Handoff: Clean state for next session

Workflow Example

# Start session
./init.sh

# Check what to work on
# → Shows: "Next incomplete: p6-sound-list"

# Implement feature...

# Verify implementation
claude
> /project:verify p6-sound-list

# If passing, move to next
> /project:verify p6-sound-search

# End session - progress auto-tracked

Writing Good Verification Steps

Do

  • Use specific, observable actions: "Click Sound Browser button"
  • Reference visible UI text: "Panel shows 'No results' message"
  • One assertion per step: "Search input visible at top"
  • Include edge cases: "Works when REPL not focused"

Don't

  • Vague steps: "It should work"
  • Multiple assertions: "Panel opens and shows categories and count"
  • Implementation details: "useState updates correctly"
  • Non-observable: "Performance is good"

Examples

Good:

"verification": [
  "Click Sound Browser toggle button",
  "Panel opens showing sample categories",
  "Click 'Drums' category header",
  "Category expands showing sample names",
  "Click toggle button again",
  "Panel closes"
]

Bad:

"verification": [
  "Sound browser works",
  "Categories load from Strudel API and render in React state",
  "UX is intuitive"
]

CI Integration (Future)

# .github/workflows/verify.yml
name: Feature Verification
on: [push]
jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npx playwright install chromium
      - run: npm run dev &
      - run: sleep 5
      - run: |
          # Run verification via Playwright test file
          npx playwright test verify.spec.ts

References