| name | headless-browser-test |
| description | Run headless browser smoke and E2E tests for a web service. Use when verifying rendered web UI, checking browser errors, creating Playwright-style scenarios, collecting screenshots, or testing a deployed or local service through Chromium. |
Headless Browser Test
Use the scripts first. Keep prompts short; let them enforce browser setup,
artifacts, trace capture, and report shape.
The target URL is an input to this skill, never something it guesses or
rewrites. Resolve a URL that is reachable from wherever the browser process
runs, prove it is reachable, then test it.
Default Flow
- Resolve the target URL from the user, the deploy report, service docs, or
the local dev server output.
- Prove the URL is reachable from the same environment that will run the
browser:
curl -fsS <url> >/dev/null
- Run a smoke test:
node .codex/skills/headless-browser-test/scripts/run-headless-browser-test.mjs --url <url>
- For real E2E, write a small JSON scenario and run it with
--spec.
- If the user asks for durable repository tests, generate a Playwright template
and fill only the marked TODOs:
sh .codex/skills/headless-browser-test/scripts/write-playwright-e2e-template.sh test/e2e
Load Only What You Need
references/environment.md: runtime requirements, missing Chromium or
Playwright handling, and choosing a reachable URL.references/scenario-authoring.md: scenario JSON format, stable locator
contract, and fill-in templates for common tests.references/operation.md: testing a deployed service, artifact paths, failure
triage, and final-answer requirements.
Hard Rules
- Resolve the browser and Playwright from the environment. If the runtime
provides them globally, point
HEADLESS_BROWSER_EXECUTABLE and
HEADLESS_BROWSER_PLAYWRIGHT_ROOT at them rather than adding project
dependencies for one-off browser evidence.
- A missing browser in a container image is an image problem. Fix the image;
do not add a workspace dependency to work around it.
- When the browser runs somewhere other than the host that published the port,
pass the address that resolves from the browser's side. Note that a page
served from
localhost is a secure origin and one served from another
hostname is not, so APIs such as Web Crypto can behave differently — choose
the URL deliberately and record which one was tested.
- Test rendered behavior a user can see or operate. Do not assert
implementation details.
- Prefer role/name, label, text, alt text, title, and test id locators. Use
CSS or XPath only when no stable user-facing or documented test hook exists.
- Keep tests isolated. Do not rely on execution order, shared browser storage,
or state left by a previous test.
- Avoid uncontrolled third-party pages and services. Mock or constrain them
when they affect the result.
- Prefer auto-waiting locator actions and web-first assertions over manual
sleeps or one-shot visibility checks.
- Capture evidence under
test/YYYYMMDD/<HHMMSS>_headless-browser-test/.
- Final answers must include pass/fail, the tested URL, the report path,
screenshots, and whether the run was smoke-only or scenario-based.
