Agent-Skills.md

Agent Skills: Playwright Browser Automation

>-

UncategorizedID: cleanexpo/nodejs-starter-v1/playwright-browser

Repository

cleanexpo/nodejs-starter-v1
CleanExpoLicense: MIT
1

Install this agent skill to your local

pnpm dlx add-skill https://github.com/CleanExpo/NodeJS-Starter-V1/tree/HEAD/.skills/custom/playwright-browser

Skill Files

Browse the full folder contents for playwright-browser.

Download Skill

Loading file tree…

.skills/custom/playwright-browser/SKILL.md

Skill Metadata

Name
playwright-browser
Description
">-"

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

  1. Headless by default — use --headed only when debugging
  2. Screenshot at each step — capture visual evidence for review
  3. Parallel sessions — leverage Playwright's built-in parallelism
  4. Persistent profiles — reuse auth state across test runs
  5. 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)