browser-automation

# Browser Automation Prove rendered behavior in a real browser and report pass, fail, or blocked with evidence. Keep automation temporary unless the user asks for permanent tests. ## Runtime Use the cheapest runtime that proves the claim: 1. Browser tools exposed in the current session. See [`references/platform-browser-tools.md`](references/platform-browser-tools.md). 2. The project's configured browser runner. Infer the package manager from the lockfile; do not invent a runner. 3. The bundled Playwright scripts in this skill's `scripts/` directory. Read [`references/playwright.md`](references/playwright.md) for setup, the script skeleton, helpers, and custom headers. 4. None available: report blocked and name the missing tool or package. ## Rules - Target: reuse a reachable dev server; start one only when its command is known. Ask when no server or several servers are found. - Data: use seeded users, fixed dates, reset state, and mocked external services. Credentials, production data, and destructive actions need explicit user approval. - Locators: role, label, text, or test id first; CSS last. - Waiting: wait on observable state such as a selector, URL, network response, or accessibility snapshot. Never add fixed sleeps. For SPA or HTMX pages, assert the DOM after swaps and client-side route changes. - Headless: when the platform exposes no visible browser (Pi, CI, most CLIs), use headless screenshots plus a manifest as visual evidence. Use headed mode only when the user can see the browser. - Files: write generated scripts and artifacts to `/tmp/playwright-*`. Write to the project only when the user asked for permanent tests, and never write into the skill directory. - Failures: fix the app or tests only when that is in scope. After two failed scoped attempts, save evidence, quote the failing line or UI state, and stop. - Permanent tests: done when the relevant build/test/lint checks pass on what you changed, or you name each check that did not run and why. ## Bundled Playwright scripts Run them by absolute path from the caller's working directory, where `<skill-dir>` is the directory that contains this `SKILL.md`. Prefer the screenshot scripts over custom batch scripts: ```bash node <skill-dir>/scripts/screenshot-url.js --url <url> --selector <ready-selector> \ --out /tmp/playwright-page.png --json node <skill-dir>/scripts/screenshot-sequence.js --url-template '<url/{n}>' --from 1 --to 10 \ --selector <ready-selector> --out-dir /tmp/playwright-shots --json node <skill-dir>/scripts/run.js --json /tmp/playwright-check.js ``` - Manifests record URL, title, screenshot path, viewport, console errors, network failures, and HTTP responses with status >=400. - `run.js` keeps the caller's working directory and writes its status logs to stderr. Pass `--json` or `--quiet` whenever stdout must carry only the script's JSON: without them, a first-run Playwright install also writes to stdout. Playwright globals such as `chromium` and `helpers` stay available when the script also uses `require("fs")` or `require("path")`. ## Platform additions No target-specific additions. ## Output ```markdown ## Browser Automation Result Target: <page, feature, or flow> Runtime: <built-in browser | project runner | bundled Playwright | blocked> Actions: <commands or browser actions> Result: <pass | fail | blocked> Evidence: <screenshot, manifest, or trace paths, or the key observation> Next fix: <only when failing or blocked> ``` Report blocked, not pass, when the check did not run.