IMPORTANT - Path Resolution: This skill can be installed in different locations (plugin system, manual installation, global, or project-specific). Before executing any commands, determine the skill directory based on where you loaded this SKILL.md file, and use that path in all commands below. Replace $SKILL_DIR with the actual discovered path.

Common installation paths:

• Plugin system: ~/.claude/plugins/marketplaces/playwright-skill/skills/playwright-skill
• Manual global: ~/.claude/skills/playwright-skill
• Project-specific: <project>/.claude/skills/playwright-skill

Playwright Browser Automation

General-purpose browser automation skill. I'll write custom Playwright code for any automation task you request and execute it via the universal executor.

CRITICAL WORKFLOW - Follow these steps in order:

1. Auto-detect dev servers - For localhost testing, ALWAYS run server detection FIRST:

   terminalCopy

   Loading...
   • If 1 server found: Use it automatically, inform user
   • If multiple servers found: Ask user which one to test
   • If no servers found: Ask for URL or offer to help start dev server

2. Write scripts to /tmp - NEVER write test files to skill directory; always use /tmp/playwright-test-*.js

3. Use visible browser by default - Always use headless: false unless user specifically requests headless mode

4. Parameterize URLs - Always make URLs configurable via environment variable or constant at top of script

How It Works

1. You describe what you want to test/automate
2. I auto-detect running dev servers (or ask for URL if testing external site)
3. I write custom Playwright code in /tmp/playwright-test-*.js (won't clutter your project)
4. I execute it via: cd $SKILL_DIR && node run.js /tmp/playwright-test-*.js
5. Results displayed in real-time, browser window visible for debugging
6. Test files auto-cleaned from /tmp by your OS

Setup (First Time)

This installs Playwright and Chromium browser. Only needed once.

Execution Pattern

Step 1: Detect dev servers (for localhost testing)

Step 2: Write test script to /tmp with URL parameter

Step 3: Execute from skill directory

Common Patterns

Test a Page (Multiple Viewports)

Test Login Flow

Fill and Submit Form

Check for Broken Links

Take Screenshot with Error Handling

Test Responsive Design

Inline Execution (Simple Tasks)

For quick one-off tasks, you can execute code inline without creating files:

When to use inline vs files:

• Inline: Quick one-off tasks (screenshot, check if element exists, get page title)
• Files: Complex tests, responsive design checks, anything user might want to re-run

Available Helpers

Optional utility functions in lib/helpers.js:

See lib/helpers.js for full list.

Custom HTTP Headers

Configure custom headers for all HTTP requests via environment variables. Useful for:

• Identifying automated traffic to your backend
• Getting LLM-optimized responses (e.g., plain text errors instead of styled HTML)
• Adding authentication tokens globally

Configuration

Single header (common case):

Multiple headers (JSON format):

How It Works

Headers are automatically applied when using helpers.createContext():

For scripts using raw Playwright API, use the injected getContextOptionsWithHeaders():

Advanced Usage

For comprehensive Playwright API documentation, see API_REFERENCE.md:

• Selectors & Locators best practices
• Network interception & API mocking
• Authentication & session management
• Visual regression testing
• Mobile device emulation
• Performance testing
• Debugging techniques
• CI/CD integration

Tips

• CRITICAL: Detect servers FIRST - Always run detectDevServers() before writing test code for localhost testing
• Custom headers - Use PW_HEADER_NAME/PW_HEADER_VALUE env vars to identify automated traffic to your backend
• Use /tmp for test files - Write to /tmp/playwright-test-*.js, never to skill directory or user's project
• Parameterize URLs - Put detected/provided URL in a TARGET_URL constant at the top of every script
• DEFAULT: Visible browser - Always use headless: false unless user explicitly asks for headless mode
• Headless mode - Only use headless: true when user specifically requests "headless" or "background" execution
• Slow down: Use slowMo: 100 to make actions visible and easier to follow
• Wait strategies: Use waitForURL, waitForSelector, waitForLoadState instead of fixed timeouts
• Error handling: Always use try-catch for robust automation
• Console output: Use console.log() to track progress and show what's happening

Troubleshooting

Playwright not installed:

Module not found: Ensure running from skill directory via run.js wrapper

Browser doesn't open: Check headless: false and ensure display available

Element not found: Add wait: await page.waitForSelector('.element', { timeout: 10000 })

Example Usage

Notes

• Each automation is custom-written for your specific request
• Not limited to pre-built scripts - any browser task possible
• Auto-detects running dev servers to eliminate hardcoded URLs
• Test scripts written to /tmp for automatic cleanup (no clutter)
• Code executes reliably with proper module resolution via run.js
• Progressive disclosure - API_REFERENCE.md loaded only when advanced features needed