playwright-skill

name	playwright-skill
description	Complete browser automation with Playwright. Auto-detects dev servers, writes clean test scripts to /tmp. Test pages, fill forms, take screenshots, check responsive design, validate UX, test login flows, check links, automate any browser task. Use when user wants to test websites, automate browser interactions, validate web functionality, or perform any browser-based testing.

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

Common installation paths:

• Plugin system: ~/.claude/plugins/marketplaces/playwright-skill/skills/playwright-skill
• Manual global: ~/.cursor/skills/playwright-skill
• Project-specific (codex): .cursor/skills/playwright-skill
• Project-specific: <project>/.cursor/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 .cursor/skills/playwright-skill && 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 .cursor/skills/playwright-skill && 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 .cursor/skills/playwright-skill && 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 .cursor/skills/playwright-skill && 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 .cursor/skills/playwright-skill && node run.js /tmp/script.js

# Multiple headers (JSON)
PW_EXTRA_HEADERS='{"X-Automated-By":"playwright-skill","X-Debug":"true"}' \
  cd .cursor/skills/playwright-skill && 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 .cursor/skills/playwright-skill && npm run setup

# Module not found — always run via run.js, never node directly on script
cd .cursor/skills/playwright-skill && 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