# Playwright Harness > Drive a real browser with Playwright on any OS and gate on what you observe: write a script, launch Chromium (headless by default; a shared headed window when a human must watch or drive), drive the page, and assert on screenshots plus collected page errors. The operational trunk for browser work; specializations layer on top. Use for ANY web task: "drive the UI headlessly", "smoke-test a screen", "screenshot a component or canvas", "reproduce a console error", "fill and submit a form", "test a login flow", "check responsive layout", "find broken links", "open a browser I can watch/drive", or "automate a browser flow". Open references/interactions.md and references/flows.md for the element vocabulary and multi-step recipes; switch to playwright-camera-mask-testing for a camera or person feed, or playwright-gif-capture for an animated GIF. Validated on Linux/WSL (headless, ANGLE GPU path for WebGL) and macOS (headless + interactive headed mode). - Skill: `simiancraft/playwright-harness` (Agent Skill, multi-file: 5 files) - Install (CLI): `npx skillmds@latest add simiancraft/playwright-harness` - Raw SKILL.md: https://api.skillmd.com/api/skills/simiancraft/playwright-harness/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - Author: simiancraft (https://skillmd.com/u/simiancraft) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/simiancraft/playwright-harness --- # Playwright Harness Project-agnostic kernel for driving a browser and asserting on it; the operational trunk the rest of the suite hangs off. ## Map of the suite This skill is the trunk: what to install, plus the run-and-assert pattern. Everything else hangs off it. ``` playwright-harness/ <- you are here: prerequisites + run pattern + assert loop ├── references/ │ ├── interactions.md address elements: locators, actions, waits, assertions │ └── flows.md recipes: login, forms, responsive, link-checking, network stubbing ├── scripts/ │ ├── keeper.mjs interactive headed mode: long-lived shared browser + CDP │ └── observe.mjs interactive headed mode: attach, report URL/errors, screenshot └── specializations (separate, discoverable skills; read this one first): ├── playwright-camera-mask-testing a real person through getUserMedia; assert segmentation/mask by vision └── playwright-gif-capture an animated GIF of a page, canvas, or WebGL animation ``` `references/` is this skill's own depth, loaded by reading the file. The specializations are separate, discoverable skills; open one when its input (a camera feed, a GIF) is what you need. > **Runtime/package manager.** Examples use plain `node` + `npm`; substitute your > own runner (`bun`, `pnpm`, `yarn`) wherever they appear. Playwright itself is > unaffected. ## Prerequisites (install once) - **Node 18+** and a package manager. - **Playwright + a browser binary.** Playwright ships no browser by default: ```bash npm i -D playwright # or add to the project that already has it npx playwright install chromium ``` - **Headless system libraries (Linux/WSL only).** A fresh box is missing the shared libs Chromium needs (`libnss3`, `libatk`, `libgbm`, …); the symptom is a launch error listing `error while loading shared libraries`. Install them once: ```bash npx playwright install-deps chromium # needs sudo; or your distro's equivalent packages ``` **macOS needs none of this** — the downloaded Chromium runs as-is, headless or headed. There is no `install-deps` step and no GPU shim to configure; a headed launch opens a normal window on the desktop. - Some specializations need extra binaries (e.g. `ffmpeg` for video/GIF encode); each declares its own in a "Prerequisites" block. ## The run pattern 1. **Write the script into a dedicated scratch dir**, never into the skill or the project: `/tmp/pw-/run.mjs`, with any output alongside it (`/tmp/pw-/shot.png`). A per-task dir stops parallel runs from colliding on a shared filename. Parameterize the URL as `const TARGET_URL = process.env.TARGET_URL || ''` so it is never hardcoded. 2. **Make `playwright` resolvable from the script's own directory.** ESM resolves a bare import from the SCRIPT's location upward; cwd is irrelevant, so running a `/tmp` script from inside a project that has playwright does NOT work. Symlink an existing install into the scratch dir (do not reuse a shared `/tmp/node_modules`; it collides with other `/tmp` installs and then the import silently fails to resolve): ```bash mkdir -p /tmp/pw- ln -sfn /path/to/an-install/node_modules /tmp/pw-/node_modules # an install that has playwright node /tmp/pw-/run.mjs ``` No install handy? `cd /tmp/pw- && npm i playwright` right there. Confirm it resolves before relying on it: from the scratch dir, `node -e "import('playwright').then(() => console.log('resolves'))"`. 3. **Default to headless.** It is faster and gives clean, chrome-free screenshots. Use `headless: false` only when a human must watch or drive — see "Interactive headed mode" below. (On a display-less box — CI, WSL without WSLg — headed launches fail outright; headless is not just the default there, it is the only mode.) ```js // /tmp/pw-task/run.mjs import { chromium } from 'playwright'; const TARGET_URL = process.env.TARGET_URL || 'http://localhost:8080/'; const browser = await chromium.launch({ headless: true }); const page = await browser.newPage({ viewport: { width: 1280, height: 720 } }); const errors = []; page.on('pageerror', (e) => errors.push(`pageerror: ${e.message}`)); page.on('console', (m) => m.type() === 'error' && errors.push(`console: ${m.text()}`)); await page.goto(TARGET_URL, { waitUntil: 'load' }); await page.locator('#root').screenshot({ path: '/tmp/pw-task/shot.png' }); // element-cropped; use page.screenshot() for the full page await browser.close(); console.log(errors.length ? `ERRORS:\n${errors.join('\n')}` : 'no page errors'); ``` ## Interactive headed mode (shared browser, human + agent) When a human must watch the agent drive — or type URLs and act while the agent observes — one browser is shared between them instead of scripting a headless one-shot. Two scripts in `scripts/` implement it; copy them into the scratch dir (they follow the same resolution rule as any run-pattern script): - **`keeper.mjs`** — launched as a **background process**, it opens a headed Chromium with a persistent profile (`./profile` beside the script, so logins survive relaunches) and exposes CDP on `:9222` (`CDP_PORT` to override). The human gets a real window with an address bar; the process lives until the window closes. - **`observe.mjs`** — run on demand, it attaches over CDP, reports the active tab's URL and title, and screenshots it for vision assertion. Its `browser.close()` only detaches the CDP connection; the headed window stays up. Driving works the same way: any ad-hoc script that starts with `chromium.connectOverCDP('http://127.0.0.1:9222')` can locate elements, click, and fill in the shared window using the ordinary vocabulary from `references/interactions.md`. Two caveats learned the hard way: - **The keeper dies with its parent.** If the shell/session that spawned it exits, the window vanishes. Check the CDP port (`lsof -nP -iTCP:9222`) before assuming the browser is still up; relaunching is idempotent thanks to the persistent profile. - **Screenshots of a headed window include its real viewport**, sized by the human's window, not a scripted `viewport:` — assert on element crops, not pixel-exact page dimensions. ## Assert on what you observe - **Gate on page errors.** Collect `pageerror` + `console` errors (filter favicon/DevTools noise), and treat a non-empty list as a failure. - **Then Read the screenshot** (vision); that is the half only your eyes can do. Crop with `locator.screenshot()` so the assertion is about the thing under test, not the whole page. - **Wait on conditions, not the clock:** `waitForSelector`, `waitForURL`, `waitForLoadState`, or a page-exposed signal, beats a fixed `waitForTimeout`. ## Interactions and flows The element vocabulary and the multi-step recipes live in the two references above. They exist to reach observable states worth gating on, not to be a general automation toolkit; a new recipe earns its place by ending on something you assert, not just an action it performs. ## WebGL / GPU caveat (headless, any OS; fix shown is Linux/WSLg) Default headless Chromium renders WebGL via **SwiftShader** on every platform, which silently **no-ops heavy GPU work**: a canvas-heavy page or a generative shader renders black/empty with GPU time ~0, no error. A headed launch (macOS or a Linux desktop) always has the real GPU, so interactive headed mode sidesteps this entirely. If a canvas is empty headless but works in a real browser, relaunch reaching the real GPU — under WSLg, via ANGLE: ```js chromium.launch({ headless: true, args: ['--use-gl=angle', '--use-angle=gl', '--ignore-gpu-blocklist'] }); ``` Confirm you got a real GPU, not SwiftShader, via the renderer string: ```js await page.evaluate(() => { const g = document.createElement('canvas').getContext('webgl2'); const x = g.getExtension('WEBGL_debug_renderer_info'); return x ? g.getParameter(x.UNMASKED_RENDERER_WEBGL) : 'no-debug-renderer-info'; }); ``` Read the string case-insensitively for the software markers `SwiftShader` and `llvmpipe`: if either is present you are on the no-op software path. The leading `ANGLE (` proves nothing on its own; the software path can arrive wrapped, e.g. `ANGLE (Google, Vulkan ... SwiftShader driver)`. A real GPU names an actual adapter, e.g. `ANGLE (Intel..., D3D12 (Intel(R) UHD Graphics 770), ...)`. Let any shader/animation settle a second or two after first paint (PSO compile) before capturing, or early frames stutter. ## Serving an exported static site To test a production build, serve it and point `TARGET_URL` at it. If the app deploys under a sub-path (project Pages sites), serve it under that sub-path; root-served local runs hide absolute-path 404s (`/_app/...`, `/static/...`) that only bite in production: ```bash mkdir -p /tmp/site && ln -sfn "$(pwd)/dist" /tmp/site/ python3 -m http.server 8091 -d /tmp/site # test http://localhost:8091// ``` `python3 -m http.server PORT -d DIR` serves any static directory (a single loose fixture works the same way). It is static-only and cannot answer an app's live endpoints (`/api/...`); for those, point `TARGET_URL` at the running dev server, or stub the endpoints with the network-stubbing recipe in `references/flows.md`. ## Scope - **CAN validate:** page loads and routing, UI wiring and flows, element presence, console/page-error cleanliness, visual state by vision, the real deployed site (point `TARGET_URL` at it; no install needed). - **CANNOT validate:** real frame-rate/perf (headless timing is not device timing), true input-device fidelity, or Firefox/WebKit capability differences unless you launch those browsers explicitly. ## The specialization contract A sibling skill (mapped above) says "Read playwright-harness first" and adds only its delta: its inputs and its assertion. It does not re-document the run pattern, the assert loop, or the GPU caveat. A new reference follows the same rule: it states its patterns and points back here for execution.