Browser Automation
Use a real browser only when rendered behavior matters: UI state, navigation,
forms, auth, screenshots, recordings, accessibility, visual checks, or
end-to-end flows.
Keep automation temporary unless the user asks for permanent tests. Do not use a
browser for plain HTTP API checks or pure logic tests.
Runtime Selection
- Prefer a platform built-in browser tool when available in the active tool
list. See
references/platform-browser-tools.md.
- Use the project's configured browser runner when it exists.
- Use
playwright-skill only as the bundled fallback/runtime reference.
- If no runtime is available, report blocked with the missing tool/package.
Use the cheapest runtime that proves the claim.
Workflow
- Define the goal: explore, validate, screenshot, record, debug, or test.
- Read needed local context: start scripts, browser config, routes, fixtures,
seed/reset docs, and auth notes.
- Detect or start the dev server. Reuse a reachable server.
- Use deterministic data: seeded users, fixed dates, stable IDs, reset state,
and mocked external services.
- Drive with semantic targets first: role, label, text, test id; CSS last.
- Capture artifacts needed to support the result: screenshot, trace, console
errors, network failures, accessibility snapshot, manifest, or report.
- Prefer screenshot/manifest evidence for visual checks in headless harnesses.
- Report pass, fail, or blocked. Do not imply success if the check did not run.
Playwright Fallback
Use Playwright when no built-in browser tool exists, the project already uses
Playwright, or a repeatable script/test is the best artifact.
If using the bundled helper, load playwright-skill for exact setup and
invocation. Use its turnkey screenshot helpers before writing custom batch
scripts:
node scripts/screenshot-url.js --url <url> --selector <ready-selector> --json
node scripts/screenshot-sequence.js --url-template '<url/{n}>' --from 1 --to 10 --json
Do not write generated files into the helper directory or project unless
creating permanent tests was requested.
Script and Test Rules
- Write temporary scripts to
/tmp/playwright-<name>.js or
/tmp/playwright-<name>.spec.ts when using the Playwright fallback.
- Never use fixed sleep delays.
- Wait or assert on visible state, URL, selector, network state, or
accessibility snapshot.
- Prefer headed mode only when the platform exposes a usable visible browser.
In Pi or other headless harnesses, use headless screenshots plus manifests as
visual evidence.
- Keep credentials, production data, and destructive actions out of browser
automation unless the user explicitly approves.
Failure Handling
- No target URL: detect a local dev server; ask if none is found.
- Multiple reachable servers: ask which target to use.
- Missing auth or fixture data: ask for safe test credentials or report blocked.
- Runtime unavailable: report the missing tool/package and required enablement.
- Fix or re-run only when fixing is in scope.
- Failure after two scoped attempts: save evidence, quote the failing line or UI
state, and stop.
Output Contract
## Browser Automation Result
Target: <page, feature, or flow>
Runtime: <built-in browser | project runner | playwright-skill | blocked>
Actions: <commands or browser action summary>
Result: <pass | fail | blocked>
Evidence: <screenshot/trace/output path or key observation>
Next Fix: <only when failing or blocked>
1---2description: 'Browser automation for rendered UI exploration, validation, screenshots,3 recordings, and end-to-end flows. Use when a task needs an actual browser or rendered4 DOM: inspect UI state, click/fill forms, debug frontend behavior, capture evidence,5 verify a feature, or run/generate browser tests. NOT for API checks or pure logic6 tests where curl, unit tests, or JSDOM is cheaper.'7name: browser-automation8metadata:9 source: https://skillmd.com/skills/alexei-led/browser-automation10---1112# Browser Automation1314Use a real browser only when rendered behavior matters: UI state, navigation,15forms, auth, screenshots, recordings, accessibility, visual checks, or16end-to-end flows.1718Keep automation temporary unless the user asks for permanent tests. Do not use a19browser for plain HTTP API checks or pure logic tests.2021## Runtime Selection22231. Prefer a platform built-in browser tool when available in the active tool24 list. See [`references/platform-browser-tools.md`](references/platform-browser-tools.md).252. Use the project's configured browser runner when it exists.263. Use `playwright-skill` only as the bundled fallback/runtime reference.274. If no runtime is available, report blocked with the missing tool/package.2829Use the cheapest runtime that proves the claim.3031## Workflow32331. Define the goal: explore, validate, screenshot, record, debug, or test.342. Read needed local context: start scripts, browser config, routes, fixtures,35 seed/reset docs, and auth notes.363. Detect or start the dev server. Reuse a reachable server.374. Use deterministic data: seeded users, fixed dates, stable IDs, reset state,38 and mocked external services.395. Drive with semantic targets first: role, label, text, test id; CSS last.406. Capture artifacts needed to support the result: screenshot, trace, console41 errors, network failures, accessibility snapshot, manifest, or report.427. Prefer screenshot/manifest evidence for visual checks in headless harnesses.438. Report pass, fail, or blocked. Do not imply success if the check did not run.4445## Playwright Fallback4647Use Playwright when no built-in browser tool exists, the project already uses48Playwright, or a repeatable script/test is the best artifact.4950If using the bundled helper, load `playwright-skill` for exact setup and51invocation. Use its turnkey screenshot helpers before writing custom batch52scripts:5354```bash55node scripts/screenshot-url.js --url <url> --selector <ready-selector> --json56node scripts/screenshot-sequence.js --url-template '<url/{n}>' --from 1 --to 10 --json57```5859Do not write generated files into the helper directory or project unless60creating permanent tests was requested.6162## Script and Test Rules6364- Write temporary scripts to `/tmp/playwright-<name>.js` or65 `/tmp/playwright-<name>.spec.ts` when using the Playwright fallback.66- Never use fixed sleep delays.67- Wait or assert on visible state, URL, selector, network state, or68 accessibility snapshot.69- Prefer headed mode only when the platform exposes a usable visible browser.70 In Pi or other headless harnesses, use headless screenshots plus manifests as71 visual evidence.72- Keep credentials, production data, and destructive actions out of browser73 automation unless the user explicitly approves.7475## Failure Handling7677- No target URL: detect a local dev server; ask if none is found.78- Multiple reachable servers: ask which target to use.79- Missing auth or fixture data: ask for safe test credentials or report blocked.80- Runtime unavailable: report the missing tool/package and required enablement.81- Fix or re-run only when fixing is in scope.82- Failure after two scoped attempts: save evidence, quote the failing line or UI83 state, and stop.8485## Output Contract8687```markdown88## Browser Automation Result8990Target: <page, feature, or flow>91Runtime: <built-in browser | project runner | playwright-skill | blocked>92Actions: <commands or browser action summary>93Result: <pass | fail | blocked>94Evidence: <screenshot/trace/output path or key observation>95Next Fix: <only when failing or blocked>96```