playwright-skill

Write and execute focused Playwright scripts for the user's request. Prefer the skill's executor and helpers, but use the full Playwright API when needed.

This skill can be installed in several locations, so resolve its directory first. Set SKILL_DIR to the directory containing this SKILL.md file, then run the commands below as written:

export SKILL_DIR=<absolute path of the directory containing this SKILL.md>
export TMP_DIR="$(node -p 'require("node:os").tmpdir()')"

If shell state does not persist between commands, substitute the literal paths for $SKILL_DIR and $TMP_DIR in each command instead.

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

1. For localhost work, detect running servers before writing a URL:

   Copy

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

   Use the only result automatically. Ask which URL to use when there are multiple results. Ask for a URL or offer to start a server when none exist.

2. Write reusable scripts to $TMP_DIR/playwright-test-*.js unless the user asks to save them in the project. Use PW_SCRIPT_DIR to preserve scripts.

3. Use a visible browser by default. Use headless: true only when requested or when the environment has no display.

4. Put the target URL in a constant or environment variable.

5. Run scripts with node "$SKILL_DIR/run.js" <script.js>.

6. Report actions, failures, and artifact paths. Do not claim success without checking the resulting page.

Run once:

cd "$SKILL_DIR" && npm run setup

This installs Playwright and Chromium. Use cd "$SKILL_DIR" && npm run install-all-browsers when Firefox or WebKit is required.

const os = require('node:os');
const path = require('node:path');
const { chromium } = require('playwright');

const targetUrl = process.env.TARGET_URL || 'http://localhost:3000';
const artifactDir = process.env.PW_ARTIFACT_DIR || os.tmpdir();

(async () => {
  const browser = await chromium.launch({ headless: false });
  try {
    const page = await browser.newPage();
    await page.goto(targetUrl);
    console.log('Page loaded:', await page.title());
    await page.screenshot({ path: path.join(artifactDir, 'page.png'), fullPage: true });
  } finally {
    await browser.close();
  }
})();

Run it:

node "$SKILL_DIR/run.js" "$TMP_DIR/playwright-test-page.js"

For short one-off tasks, use inline execution:

node "$SKILL_DIR/run.js" -e "const browser = await chromium.launch({headless: false}); try { const page = await browser.newPage(); await page.goto('https://example.com'); console.log(await page.title()); } finally { await browser.close(); }"

The -e process exits as soon as the snippet settles, so close the browser inside the snippet.

Prefer locators that describe what a user sees, in this order:

1. page.getByRole() with an accessible name
2. page.getByLabel() for form controls
3. page.getByText() for visible content
4. page.getByTestId() when the application provides a test contract

Actions auto-wait for actionability. Use web-first assertions or a locator's waitFor() instead of waitForSelector(), fixed sleeps, or networkidle.

await page.getByLabel('Email').fill('test@example.com');
await page.getByRole('button', { name: 'Sign in' }).click();
await page.waitForURL('**/dashboard');
await page.getByRole('heading', { name: 'Dashboard' }).waitFor();

const helpers = require(`${process.env.PW_SKILL_DIR}/lib/helpers`);

const servers = await helpers.detectDevServers();
const browser = await helpers.launchBrowser('chromium');
const context = await helpers.createContext(browser);
const page = await context.newPage();
await helpers.handleCookieBanner(page);
await helpers.takeScreenshot(page, 'result');

Available helpers are detectDevServers, getExtraHeadersFromEnv, launchBrowser, createContext, handleCookieBanner, and takeScreenshot. Use Playwright locators and assertions directly for actions, waits, extraction, authentication, tables, and retries.

• PW_BROWSER: chromium, firefox, or webkit for launchBrowser().
• PW_CHANNEL: installed browser channel such as chrome or msedge.
• PW_EXECUTABLE_PATH: explicit browser executable path.
• PW_HEADLESS: true or false; visible mode is the default.
• SLOW_MO: action delay in milliseconds.
• PW_HEADER_NAME and PW_HEADER_VALUE: one extra HTTP header.
• PW_EXTRA_HEADERS: JSON object of extra HTTP headers.
• PW_SCRIPT_DIR: directory for preserving file-based scripts.
• PW_ARTIFACT_DIR: directory for helper-generated screenshots.

See API_REFERENCE.md for network interception, API mocking, authentication state, video, visual checks, device emulation, and CI patterns.