Playwright Support Runtime

Support-only helper for browser-automation. Provides Playwright primitives: dev-server detection, a script runner (scripts/run.js), screenshot CLIs, and helper utilities (scripts/lib/helpers.js).

Do not treat this as the user-facing browser skill. Load it only when browser-automation chooses the bundled Playwright helper as the runtime/reference.

Critical workflow

1. Run from this skill directory — the directory containing this SKILL.md. If the loaded skill path is different from ~/.pi/agent/skills, use that loaded path.

2. Detect dev servers first for localhost testing:

   node scripts/run.js --json "console.log(JSON.stringify(await helpers.detectDevServers()))"
   

   One server → use it. Multiple → ask which. None → ask for a URL.

3. Use /tmp/playwright-* for generated scripts and artifacts unless the user asked for permanent tests. Never write generated scripts or artifacts into scripts/, the skill directory, or the user's project.

4. Prefer headless screenshots in Pi/headless harnesses. Use headed mode only when the platform exposes a usable visible browser.

5. Parameterize target URLs at the top of generated scripts as TARGET_URL.

Running scripts

node scripts/run.js --quiet /tmp/playwright-test-<name>.js
node scripts/run.js --json "console.log(JSON.stringify({ ok: !!chromium }))"

run.js preserves the caller working directory, auto-wraps code for await, uses the caller project's Playwright dependency first, then a pinned package in $XDG_CACHE_HOME/cc-thingz/playwright/1.57.0 (default ~/.cache). It installs the fallback package with npm outside the plugin directory. Runner logs go to stderr; script stdout stays clean for JSON. Browser binaries require separate setup.

chromium, firefox, webkit, devices, helpers, and getContextOptionsWithHeaders(opts) are exposed as globals for all scripts. Scripts may still use normal imports such as require("fs"), require("path"), or require("playwright").

Turnkey screenshots

For one page:

node scripts/screenshot-url.js \
  --url http://localhost:3030/1?clicks=20 \
  --selector .slidev-page \
  --out /tmp/playwright-slide-01.png \
  --manifest /tmp/playwright-slide-01.json \
  --json

For a sequence:

node scripts/screenshot-sequence.js \
  --url-template 'http://localhost:3030/{n}?clicks=20' \
  --from 1 \
  --to 17 \
  --selector .slidev-page \
  --out-dir /tmp/playwright-slidev \
  --manifest /tmp/playwright-slidev/manifest.json \
  --json

The manifest includes URL, title, screenshot path, viewport, console errors, network failures, and HTTP responses with status >=400.

Helpers

Open scripts/lib/helpers.js when you need helper signatures. Key helpers: launchBrowser, createContext, waitForStablePage, waitForPageReady, safeClick, safeType, takeScreenshot, authenticate, and detectDevServers.

Use helpers.waitForStablePage(page, { selector, animationFrames }) before SPA screenshots when networkidle is not enough.

Custom HTTP headers

Set env vars before invoking run.js or screenshot helpers to inject extra headers into every request:

# single header
PW_HEADER_NAME=X-Automated-By PW_HEADER_VALUE=playwright-skill \
  node scripts/run.js /tmp/script.js

# multiple
PW_EXTRA_HEADERS='{"X-Automated-By":"playwright-skill","X-Debug":"true"}' \
  node scripts/run.js /tmp/script.js

Headers apply automatically when scripts use helpers.createContext(browser). For raw browser.newContext(...), wrap options with getContextOptionsWithHeaders(...).

Output

URL: <target URL>
Actions: <actions run>
Artifacts: <paths or none>
Failures: <failures or none>

Base success claims on script output or artifacts, not on command completion alone.

Failure handling

• run.js not found: run from the directory containing this SKILL.md, or use the absolute loaded skill path.
• Dev server not detected: ask the user for the URL rather than assuming localhost:3000.
• Script syntax error: quote the failing line, state the cause, rewrite the offending section — do not re-run the broken script.
• Missing Playwright package or browser: follow references/setup.md. A package import alone does not prove browser launch is available.
• Keep Chromium sandboxing enabled. Set PLAYWRIGHT_SKILL_NO_SANDBOX=1 only when the execution environment requires it and the trust boundary permits it.

References

• references/setup.md — project runtime, pinned cache, and explicit browser installation.
• references/api.md — runtime-only patterns and links to official Playwright API docs. Open it when a helper doesn't cover the needed action (custom locators, waits, network interception, or auth patterns).