Playwright Browser Automation

Headless browser automation using Playwright CLI and MCP tools for E2E testing, UI verification, screenshots, and web scraping.

When to Apply

Positive Triggers

E2E test execution (test:e2e, playwright test)
UI screenshot capture for review or regression
Web scraping / content extraction
Form submission testing
Visual regression testing
Lighthouse / performance auditing via browser
Multi-page workflow validation

Negative Triggers (Do NOT Apply)

Unit tests (use Vitest/Pytest)
API-only tests (use httpx/fetch)
Personal browser sessions (use claude-browser skill)
Static code analysis

Core Principles

Headless by default — use --headed only when debugging
Screenshot at each step — capture visual evidence for review
Parallel sessions — leverage Playwright's built-in parallelism
Persistent profiles — reuse auth state across test runs
CI-safe — all operations must work in headless CI environments

MCP Playwright Tools

These tools are available via the mcp__playwright__* namespace:

Tool	Purpose
`browser_navigate`	Navigate to URL
`browser_click`	Click element by selector or text
`browser_fill_form`	Fill form fields
`browser_take_screenshot`	Capture page screenshot
`browser_snapshot`	Get accessibility tree snapshot
`browser_evaluate`	Execute JavaScript in page context
`browser_press_key`	Simulate keyboard input
`browser_type`	Type text into focused element
`browser_select_option`	Select dropdown option
`browser_wait_for`	Wait for element/condition
`browser_network_requests`	Inspect network activity
`browser_console_messages`	Read console output
`browser_hover`	Hover over element
`browser_drag`	Drag and drop
`browser_handle_dialog`	Accept/dismiss dialogs
`browser_file_upload`	Upload files
`browser_tabs`	Manage browser tabs
`browser_navigate_back`	Go back
`browser_resize`	Resize viewport
`browser_close`	Close browser
`browser_install`	Install browser binaries
`browser_run_code`	Run Playwright code snippet

Usage Pattern

1. Load tools: ToolSearch "playwright"
2. Navigate: browser_navigate to target URL
3. Interact: browser_click, browser_fill_form, browser_type
4. Capture: browser_take_screenshot at each significant step
5. Verify: browser_snapshot for accessibility tree, browser_evaluate for assertions
6. Clean up: browser_close when done

CLI Playwright Commands

# Install browsers
npx playwright install chromium

# Run all E2E tests
npx playwright test

# Run specific test file
npx playwright test tests/e2e/login.spec.ts

# Run with headed browser (debugging)
npx playwright test --headed

# Generate test from user interaction
npx playwright codegen http://localhost:3000

# Show HTML report
npx playwright show-report

# Run with specific project/browser
npx playwright test --project=chromium

Screenshot Workflow

Naming Convention

{step-number}-{description}.png

Examples: 01-login-page.png, 02-form-filled.png, 03-dashboard-loaded.png

Storage

ai-review/screenshots/     # Automated review screenshots
test-results/              # Playwright test artifacts
playwright-report/         # HTML report with traces

Capture Strategy

Before action: Capture initial state
After action: Capture result state
On failure: Automatic screenshot (Playwright default)
Full page: Use fullPage: true for long pages

Session Management

Auth State Reuse

// Save auth state after login
await page.context().storageState({ path: 'auth-state.json' });

// Reuse in subsequent tests
const context = await browser.newContext({
  storageState: 'auth-state.json'
});

Persistent Contexts

For multi-step workflows that span multiple tool calls, maintain browser context between operations. Close explicitly when done.

Parallel Execution

Playwright supports parallel test execution natively:

# Run tests in parallel (default)
npx playwright test --workers=4

# Run serially (debugging)
npx playwright test --workers=1

For MCP tool usage, open multiple browser tabs for parallel story validation.

Project Integration

File	Purpose
`apps/web/playwright.config.ts`	Playwright configuration
`apps/web/tests/e2e/`	E2E test directory
`apps/web/package.json`	`test:e2e` script

Anti-Patterns

Running headed browsers in CI — always use headless
Hardcoding selectors — prefer data-testid or accessible roles
Ignoring timeouts — set explicit timeouts per action
Skipping screenshots — always capture evidence for review
Using page.waitForTimeout() — prefer page.waitForSelector() or browser_wait_for

Pre-Merge Checklist

All E2E tests pass in headless mode
Screenshots captured for new UI flows
Auth state properly managed (no credential leaks)
Network requests validated (no unexpected external calls)
Console errors checked (no uncaught exceptions)
Viewport tested at standard breakpoints (mobile, tablet, desktop)

playwright-browser