🎭 Playwright CLI (Web Automation)
Priority: P1 (HIGH)
[!IMPORTANT] Tier 0 (Infrastructure): Browser process management, named sessions, network/console logs. Tier 1 (Core Interactions): Clicks, fills, and navigation (
openvsgoto). Tier 2 (Verification): Snapshot-based assertions and auth state persistence.
🔌 Activation
Triggers: playwright-cli, playwright mcp, browser_snapshot, browser automation, web verify, snapshot, auth-state.json.
🪜 Driver Ladder
sh scripts/preflight.sh— exit 0 found, 2 missing, 1 broken.PLAYWRIGHT_CLI_BINoverrides lookup.playwright-cli -s={ID}— default when preflight passes and a shell exists.- Playwright MCP (
browser_navigate→browser_snapshot→browser_console_messages→browser_take_screenshot→browser_close), launched--isolated --headless --output-dir .playwright-cli/{ID}. Use when CLI missing or runtime has no shell (Antigravity, Copilot).--extensionopt-in only: not a security boundary. - Neither: ask for exported screenshots + console log; label
human-provided. - Nothing exported: return
BLOCKED (driver: playwright), continue other lanes.
One driver per session. Full table: driver-ladder.
🛠 Core Workflow
| Step | Command | Purpose |
|---|---|---|
| 1 | playwright-cli -s={ID} open <url> | Start named session. (Mandatory -s=). |
| 2 | playwright-cli -s={ID} snapshot --aria | Aria Snapshot: YAML-like view for LLM reasoning (Best for assertions). |
| 3 | playwright-cli -s={ID} console | Check for JS errors/warnings. |
| 4 | playwright-cli -s={ID} screenshot | Visual evidence. Use --mask <ref> for dynamic content. |
| 5 | playwright-cli -s={ID} close | MANDATORY Cleanup. |
For a sticky header that appears after scrolling, scroll until the header is visible, use hover on the header (or its stable role/reference) to establish the visible state, then capture the screenshot. Keep the named session open until the evidence is captured.
📁 Evidence
.playwright-cli/{ID}/ (MCP: same dir via --output-dir). Files: <AC|step>-<before|after>.png, <AC|step>-<before|after>.aria.txt, console.txt; trace.zip only on a FAIL needing replay. Walkthrough records driver: + evidence_dir:. Relative paths only; CLI refuses writes outside cwd.
💡 Agent-Native Optimization
- Aria-First: Use
snapshot --ariaas primary way to "see" page. Filters noise. - Robust Locators: Prefer Role-based references (e.g.
button[name="Submit"]) over fragile CSS classes. - Visual Stability: evaluated
document.body.style.animation = 'none'to freeze animations before capture.
🚫 Anti-Patterns (Zero-Tolerance)
- Unnamed Sessions: Never omit
-s=. Bare commands collide across concurrent runs. - Double Open: Use
openfor first run;gotofor mid-session navigation. - Unmasked Snapshots: Mask clocks/random IDs before comparison to avoid false positives.
- Orphaned Processes: Always
closesession, even on failure.
✅ Evaluation Criteria
- Cleanup Rate: 100% session closure.
- Assertion Quality: 90% of assertions use
snapshotrather than pixels. - Auth Persistence: Successful re-use of
state-loadfor multi-step flows.
🔗 References
- Web Visual Testing: common-web-visual-testing — Methodology for what to verify.
- Driver Ladder: driver-ladder — CLI ↔ MCP equivalence, launch flags, degradation rules.
- Setup: setup — install, MCP registration snippet, security, alternatives not adopted.
- Anti-Patterns Rationale: anti-patterns-rationale — Why these rules exist.
Canonical response anchors
When this skill applies, preserve the following domain terminology or equivalent concrete examples in the answer when relevant:
- 🎭 Playwright CLI (Web Automation)
Remediation anchors
- Remediation anchors: hover, screenshot
