kumaran-is 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
- NEVER use
browser_get_state({ include_screenshot: true })— generates 126K+ tokens. Useplaywright-cli screenshotinstead. - Always close sessions — run
playwright-cli close-allwhen done. - Check network + console after every critical action — form submissions, navigation, button clicks.
- Screenshots as proof — required for APPROVED verdicts in reality-checker.
- Console errors = NEEDS WORK — any unhandled console error is an automatic failure.
- 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
- Determine which tool — See "When to Use Which Tool" above
- Load reference files — Read detailed docs for the tool you're using
- For inspection/scripted tasks — Use playwright-cli Bash
- For goal-driven tasks — Use Browser-Use MCP
- For combined testing — playwright-cli monitors (network/console), Browser-Use acts
- Verify results — Check both user perspective and technical perspective
- Report findings — Present both perspectives
- Clean up —
playwright-cli close-all