IMPORTANT - Path Resolution: Determine the skill directory from where this SKILL.md was loaded. Replace $SKILL_DIR with that path in all commands below.

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

CRITICAL WORKFLOW

Follow these steps in order for every request:

1. Detect dev servers (localhost testing — run this first, always):

cd $SKILL_DIR && node -e "require('./lib/helpers').detectDevServers().then(s => console.log(JSON.stringify(s)))"

• 1 server found → use it automatically, inform user
• Multiple found → ask user which one
• None found → ask for URL or offer to start dev server

2. Write script to /tmp — never write to skill directory or user's project:

/tmp/playwright-test-<task>.js

3. Execute via run.js:

cd $SKILL_DIR && node run.js /tmp/playwright-test-<task>.js

Script Template

Every script must follow this structure:

const { chromium } = require('playwright');
const TARGET_URL = 'http://localhost:3001'; // detected or user-provided

(async () => {
  const browser = await chromium.launch({ headless: false });
  const page = await browser.newPage();
  try {
    // automation here
  } catch (e) {
    console.error('Error:', e.message);
  } finally {
    await browser.close();
  }
})();

Inline Execution

For quick one-off tasks, skip writing a file:

cd $SKILL_DIR && node run.js "
await page.goto('http://localhost:3001');
await page.screenshot({ path: '/tmp/shot.png', fullPage: true });
console.log('Done');
"

Use inline for: screenshots, element checks, page title. Use files for: multi-step flows, responsive tests, anything user might re-run.

Setup

cd $SKILL_DIR && npm run setup

Only needed once. Installs Playwright and Chromium.

Available Helpers

const helpers = require('./lib/helpers');

await helpers.detectDevServers()              // scan common ports — use FIRST
await helpers.safeClick(page, selector)       // click with retry
await helpers.safeType(page, sel, text)       // type with clear
await helpers.takeScreenshot(page, name)      // timestamped screenshot to /tmp
await helpers.handleCookieBanner(page)        // dismiss common accept banners
await helpers.extractTableData(page, sel)     // table → { headers, rows }
await helpers.createContext(browser)          // context with env headers merged
await helpers.authenticate(page, creds)       // fill + submit login form
await helpers.retryWithBackoff(fn)            // exponential backoff wrapper
await helpers.waitForPageReady(page)          // smart wait: networkidle + selector

Custom Headers

Identify automated traffic or pass auth tokens globally:

# Single header
PW_HEADER_NAME=X-Automated-By PW_HEADER_VALUE=playwright-skill \
  cd $SKILL_DIR && node run.js /tmp/script.js

# Multiple headers (JSON)
PW_EXTRA_HEADERS='{"X-Automated-By":"playwright-skill","X-Debug":"true"}' \
  cd $SKILL_DIR && node run.js /tmp/script.js

Headers apply automatically when using helpers.createContext(browser). For raw Playwright API, use the injected getContextOptionsWithHeaders(options).

Rules

• Visible browser — always headless: false unless user explicitly says "headless" or "background"
• Parameterize URLs — put URL in TARGET_URL constant at top of every script
• Wait strategies — use waitForURL, waitForSelector, waitForLoadState, never fixed waitForTimeout
• Error handling — always wrap in try/catch, close browser in finally block

Troubleshooting

# Playwright not installed
cd $SKILL_DIR && npm run setup

# Module not found — always run via run.js, never node directly on script
cd $SKILL_DIR && node run.js /tmp/script.js

# Element not found — add explicit wait
await page.waitForSelector('.target', { timeout: 10000 })

# Browser doesn't open — check headless: false and display availability

For advanced patterns (network interception, visual regression, auth sessions, CI/CD): see API_REFERENCE.md