---
schema_version: 1
revision: "22ce5d34dbcb5a78"
id: "foundations-browser-proof-field-guide"
title: "Browser Proof Field Guide"
---

# Browser Proof Field Guide

> 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](https://agent-browser.dev/)

## 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

```text
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:**

- browser-proof.md
- screenshot
- console/network summary
- typecheck/test log

### 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

- [Codex in-app browser](https://developers.openai.com/codex/app/browser)
- [Codex Chrome extension](https://developers.openai.com/codex/app/chrome-extension)
- [agent-browser](https://github.com/vercel-labs/agent-browser)
- [Playwright screenshots](https://playwright.dev/docs/screenshots)
- [Playwright Trace Viewer](https://playwright.dev/docs/trace-viewer)
- [Chrome DevTools Console](https://developer.chrome.com/docs/devtools/console/log)

## Related principles

- [Explore software through perspectives and runtime QA](/topics/foundations-perspective-qa-and-testing/)
- [Verify fixes with deterministic evidence and narrow boundaries](/topics/foundations-deterministic-verification-and-boundaries/)
- [Preserve contracts and state machines while code changes](/topics/foundations-contracts-state-machines-and-code/)

## Original references

- [Agent foundations: Explore software through perspectives and runtime QA (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-05.html)
- [Agent foundations: Verify fixes with deterministic evidence and narrow boundaries (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-08.html)
- [Agent foundations: Preserve contracts and state machines while code changes (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-11.html)
