agentsclimarketplace

Playwright harness

Skill simiancraft/simiancraft-skills/skills/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).From its SKILL.md

Install
npx -y skills add simiancraft/simiancraft-skills --skill playwright-harness

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 6 stars6 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

11.0 KB, as published. Nobody here has run it

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:
    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:
    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-<task>/run.mjs, with any output alongside it (/tmp/pw-<task>/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 || '<default>' 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):
    mkdir -p /tmp/pw-<task>
    ln -sfn /path/to/an-install/node_modules /tmp/pw-<task>/node_modules  # an install that has playwright
    node /tmp/pw-<task>/run.mjs
    
    No install handy? cd /tmp/pw-<task> && 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.)
// /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:

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:

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:

mkdir -p /tmp/site && ln -sfn "$(pwd)/dist" /tmp/site/<base-path>
python3 -m http.server 8091 -d /tmp/site   # test http://localhost:8091/<base-path>/

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.

What ships with it: 2 files

8.6 KB alongside SKILL.md

references/

Gives 0 of the 12 instructions most design frontend skills give

Counted across 1,179 of the 2,086 authors here whose files we hold, read 2026-09-06

  • Commit to a bold aesthetic directionin 31 of 1179, across 24 files
  • Prefer component composition over inheritancein 28 of 1179, across 14 files
  • Animate only transform and opacity propertiesin 27 of 1179, across 22 files
  • Memoize expensive computations with useMemoin 26 of 1179, across 13 files
  • Use semantic HTML elementsin 24 of 1179, across 23 files
  • Virtualize long lists for performancein 21 of 1179, across 10 files
  • Use CSS variables for design tokensin 20 of 1179, across 14 files
  • Implement loading, empty, and error statesin 20 of 1179
  • Lazy load heavy components with Suspensein 19 of 1179, across 8 files
  • Respect prefers-reduced-motion media queriesin 18 of 1179, across 10 files
  • Prioritize CSS-only animations for HTMLin 18 of 1179, across 16 files
  • Use compound components for related UI elementsin 18 of 1179, across 7 files

Said here and by no other author read

  • write scripts into a dedicated scratch directory
  • parameterize the target URL using an environment variable
  • symlink an existing playwright install into the scratch directory
  • default to headless mode for faster execution
  • use interactive headed mode when human observation is required
  • collect page and console errors to gate test success

Grouped from the skills themselves: near-identical wordings counted once, and counted by distinct author, so one author publishing three of these counts once.

Keep looking

Skills are one crate of 611,919. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.