browser-testing

Iron Law: Never claim a UI flow works without running it in a real browser. Use playwright-cli (Bash) for inspection and scripted steps; use Browser-Use MCP for autonomous goal-driven flows.

Browser Automation & Testing Skill

This skill combines two tools for complete browser automation:

• playwright-cli — stateful Bash CLI for deterministic scripted tests (navigation, snapshots, screenshots, network/console inspection, tracing)
• Browser-Use MCP — autonomous agent for goal-driven interaction (describe a goal, not steps)

Install & Setup

# Install (package name is @playwright/mcp; binary is playwright-cli)
npm install -g @playwright/mcp@latest

# Initialize workspace (downloads browsers)
playwright-cli install

# Verify
playwright-cli --version

Session Model

playwright-cli is stateful — each named session persists browser state across commands:

# Use -s flag to name a session (persists across calls)
playwright-cli -s=login-test goto http://localhost:4200/login
playwright-cli -s=login-test snapshot
playwright-cli -s=login-test fill [email-ref] "user@example.com"
playwright-cli -s=login-test click [submit-ref]

# Without -s: uses a default unnamed session
playwright-cli goto http://localhost:4200

When to Use Which Tool

| Task | playwright-cli (Bash) | Browser-Use MCP | |------|-----------------------|-----------------| | Scripted test steps | Preferred | Works | | Network request list | playwright-cli network | Not available | | Console messages | playwright-cli console | Not available | | Execute JavaScript | playwright-cli eval <func> | Not available | | Performance tracing | playwright-cli tracing-start/stop | Not available | | Accessibility tree | playwright-cli snapshot | Not available | | Autonomous goal completion | Needs scripting | Preferred | | Real Chrome with existing login | Limited | --browser real |

Rule: Default to playwright-cli. Use Browser-Use only when describing a goal is better than scripting steps.

Quick Example: Testing Login Flow

# Step 1: Navigate and take baseline snapshot
playwright-cli -s=login goto http://localhost:4200/login
playwright-cli -s=login snapshot
# → Returns accessibility tree with [ref] for each element

# Step 2: Fill and submit
playwright-cli -s=login fill [email-ref] "user@example.com"
playwright-cli -s=login fill [password-ref] "password123"
playwright-cli -s=login click [submit-ref]

# Step 3: Verify result
playwright-cli -s=login network
# → Check POST /api/auth/login → 200
playwright-cli -s=login console
# → Check for errors
playwright-cli -s=login screenshot --output login-success.png

For full command reference, Read reference/playwright-cli-tools.md

For combined playwright-cli + Browser-Use workflow patterns, Read reference/browser-testing-workflows.md

Server Lifecycle — scripts/with_server.py

Use when the dev server is not already running (CI environments, clean machines, automated flows). Run --help first. Treat it as a black box — do NOT read source unless you must customise it.

python scripts/with_server.py --help

Stack Presets

| Stack | Command | |-------|---------| | Angular | python scripts/with_server.py --server "ng serve" --port 4200 -- playwright-cli goto http://localhost:4200 | | NestJS | python scripts/with_server.py --server "npm run start:dev" --port 3000 -- playwright-cli goto http://localhost:3000 | | FastAPI | python scripts/with_server.py --server "uvicorn main:app --port 8000" --port 8000 -- playwright-cli goto http://localhost:8000 | | Spring Boot | python scripts/with_server.py --server "mvn spring-boot:run" --port 8080 -- playwright-cli goto http://localhost:8080 | | Flutter Web | python scripts/with_server.py --server "flutter run -d web-server --web-port 8080" --port 8080 -- playwright-cli goto http://localhost:8080 |

Multi-server (backend + frontend together)

python scripts/with_server.py \
  --server "npm run start:dev" --port 3000 \
  --server "ng serve --port 4200" --port 4200 \
  -- playwright-cli -s=e2e goto http://localhost:4200

When server is already running (default dev workflow) → skip with_server.py, use playwright-cli directly.

Decision Quick Reference

| Need to... | Command | |-----------|---------| | Navigate to URL | playwright-cli goto <url> | | Test a local HTML file (no server) | playwright-cli goto "file:///$(pwd)/path/to/file.html" | | Get element refs | playwright-cli snapshot | | Fill an input | playwright-cli fill <ref> <text> | | Click a button | playwright-cli click <ref> | | Check console errors | playwright-cli console error | | Check network requests | playwright-cli network | | Take a screenshot | playwright-cli screenshot [--output file.png] | | Run JS in page | playwright-cli eval "<expression>" | | Resize viewport | playwright-cli resize <w> <h> | | Start perf trace | playwright-cli tracing-start | | Stop perf trace | playwright-cli tracing-stop | | Run Lighthouse audit | mcp__chrome-devtools__lighthouse_audit (via Chrome DevTools MCP) | | Debug a failing flow end-to-end | Load Agentic Debug Loop — observe → diagnose → fix → re-verify | | Close session | playwright-cli close-all | | Start server then test | python scripts/with_server.py --server "<cmd>" --port <N> -- <test-cmd> | | Autonomous flow | Browser-Use MCP: browser_navigate → browser_get_state → browser_input |

Static HTML / Wireframe Testing

For local HTML files (wireframes, generated output, prototypes) — no server needed:

# Absolute path required for file:// URLs
playwright-cli goto "file:///$(pwd)/wireframes/dashboard.html"
playwright-cli snapshot
playwright-cli screenshot --output wireframe-check.png

Use this for: sketch-wireframe outputs, premium-wireframe-2026 outputs, any .html in the project.

Critical Rules

1. NEVER use browser_get_state({ include_screenshot: true }) — generates 126K+ tokens. Use playwright-cli screenshot instead.
2. Always close sessions — run playwright-cli close-all when done.
3. Check network + console after every critical action — form submissions, navigation, button clicks.
4. Screenshots as proof — required for APPROVED verdicts in reality-checker.
5. Console errors = NEEDS WORK — any unhandled console error is an automatic failure.
6. Load reference files only when the Quick Reference table above doesn't answer your question — each reference file is 150–400 lines. Load selectively, not by default.

Reference Files

| Resource | When to Load | |----------|-------------| | playwright-cli Tools | Full command reference, all flags, session management | | Browser-Use Tools | Browser-Use MCP command reference and best practices | | Combined Workflows | Login flows, performance, E2E journeys, validation, accessibility | | Chrome DevTools Tools | Core Web Vitals analysis, performance traces, CPU/network throttling, Lighthouse audit | | Agentic Debug Loop | Observe → diagnose → fix → re-verify pattern for AI-driven bug diagnosis on live apps |

Process

1. Determine which tool — See "When to Use Which Tool" above
2. Load reference files — Read detailed docs for the tool you're using
3. For inspection/scripted tasks — Use playwright-cli Bash
4. For goal-driven tasks — Use Browser-Use MCP
5. For combined testing — playwright-cli monitors (network/console), Browser-Use acts
6. Verify results — Check both user perspective and technical perspective
7. Report findings — Present both perspectives
8. Clean up — playwright-cli close-all