Browser Proof Field Guide

Make Codex prove rendered web behavior with routes, actions, logs, screenshots, and receipts.

Original source pages and recordings require authorized access. The full article text here is public.

Make Codex prove rendered web behavior with routes, actions, logs, screenshots, and receipts.

Use this when a UI, auth, form, route, or responsive change cannot be considered done from source inspection alone.

Browser automation CLI designed for AI agents.

agent-browser docs

Choose the right mechanism

Mechanism Use when Agent responsibility Artifact
Codex Browser Local/public unauthenticated route Fast visual proof and screenshots .notes/browser-proof/<task>/browser-proof.md
Chrome extension/manual Chrome Signed-in browser state Auth flows and internal SaaS pages Redacted manual proof plus screenshot
agent-browser Terminal-friendly browser control snapshot, click, fill, screenshot snapshot.txt plus screenshot.png
Playwright Repeatable or CI-friendly flow Trace, console, screenshot, deterministic test trace.zip plus console.json
DevTools/CDP Raw console/network evidence HAR, console objects, performance details console.log plus network.har

Agent-ready prompt

Use browser proof before claiming this UI task is done.
Inspect package.json and AGENTS.md first.
Pick the browser surface that matches the auth and repeatability needs.
Save .notes/browser-proof/<task>/browser-proof.md with URL, viewport, auth context, actions, expected/observed result, console errors, network failures, artifacts, command output, diff summary, and pass/fail.
Redact cookies, tokens, customer data, QR codes, and auth headers.

Applied stories

Authenticated billing route

Role: SaaS frontend engineer

Codex changed /settings/billing, but the route only works when logged in.

Agent brief: Use signed-in Chrome or a seeded login; verify current plan, change plan, submit, and capture final visible success state.

Done when:

Pricing weird-path QA

Role: Growth engineer

Plan toggles, coupons, and checkout modals fail after repeated back/refresh/toggle sequences.

Agent brief: Run five browser QA perspectives and collate reproducible findings into .notes/qa/pricing-summary.md.

Done when:

  • perspective files
  • summary severity list
  • screenshots/transcripts
  • console status

Preview deployment triage

Role: Frontend lead

A PR preview is green but nobody opened changed routes.

Agent brief: Discover preview URL, open homepage and changed route, capture status, visible error text, console errors, and screenshot.

Done when:

  • preview URL
  • browser receipt
  • blocker/warning/clean verdict
  • no source edits

Tips and gotchas

  • Tests prove code paths; browser proof proves user-visible behavior.
  • Use the in-app browser for localhost/public pages, but use Chrome/manual auth for signed-in state.
  • Do not make Playwright mandatory for every UI task; use it when repeatability matters.
  • Treat screenshots, traces, HARs, and console logs as sensitive local artifacts by default.
  • A Stop hook should check receipt files, not drive the browser itself.

References

Source references