playwright-verification
使用 Playwright MCP 和 Claude Code CLI 进行自动功能验证。在验证 UI 功能、运行验收测试、检查功能完成状态或验证 features.json 验证步骤时使用。与代理开发工作流程集成以进行进度跟踪。
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:
- Read feature from features.json
- Check dependencies (skip if not met)
- Navigate to localhost:5173
- Execute each verification step
- Report pass/fail per step
- 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:
- Read currentPhase from features.json meta
- Filter: phase === currentPhase AND passes === false
- Sort by dependency order
- Run verification on each
- Generate summary report
- 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
passesfield 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:
- Session Start:
init.shshows feature status - Development: Implement feature code
- Verification:
/project:verify <id>runs automated checks - Progress:
claude-progress.txtupdated automatically - 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