agent-browser-verify

name	agent-browser-verify
description	Automated browser verification for dev servers. Triggers when a dev server starts to run a visual gut-check with agent-browser — verifies the page loads, checks for console errors, validates key UI elements, and reports pass/fail before continuing.
metadata	{"priority":2,"docs":["https://openai.com/index/introducing-codex/"],"pathPatterns":[],"bashPatterns":["\\bnext\\s+dev\\b","\\bnpm\\s+run\\s+dev\\b","\\bpnpm\\s+dev\\b","\\bbun\\s+run\\s+dev\\b","\\byarn\\s+dev\\b","\\bvite\\s*(dev)?\\b","\\bnuxt\\s+dev\\b","\\bvercel\\s+dev\\b"],"promptSignals":{"phrases":["check the page","check the browser","check the site","is the page working","is it loading","blank page","white screen","nothing showing","page is broken","screenshot the page","take a screenshot","check for errors","console errors","browser errors","page is stuck","page is hanging","page not loading","page frozen","spinner not stopping","page not responding","page won't load","page will not load","nothing renders","nothing rendered","ui is broken","screen is blank","screen is white","app won't load"],"allOf":["[Truncated]","[Truncated]","[Truncated]","[Truncated]","[Truncated]","[Truncated]","[Truncated]","[Truncated]","[Truncated]","[Truncated]","[Truncated]","[Truncated]","[Truncated]"],"anyOf":["page","browser","screen","rendering","visual","spinner","loading"],"minScore":6}}

Dev Server Verification with agent-browser

You MUST verify the dev server with agent-browser after starting it. Do not assume the page works just because the dev server process started. Many issues (blank pages, hydration errors, missing env vars, broken imports) are only visible in the browser. Run this verification before continuing with any other work:

Quick Verification Flow

# 1. Open the dev server
agent-browser open http://localhost:3000
agent-browser wait --load networkidle

# 2. Screenshot for visual check
agent-browser screenshot --annotate

# 3. Check for errors
agent-browser errors     # uncaught JavaScript exceptions
agent-browser console    # console log/warn/error messages

# 4. Snapshot interactive elements
agent-browser snapshot -i

Verification Checklist

Run each check and report results:

1. Page loads — agent-browser open succeeds without timeout
2. No blank page — snapshot shows meaningful content (not empty body)
3. No error overlay — no Next.js/Vite error overlay detected
4. Console errors — agent-browser errors reports no uncaught exceptions and agent-browser console shows no error-level messages
5. Key elements render — snapshot -i shows expected interactive elements
6. Navigation works — if multiple routes exist, verify at least the home route

Error Detection

# Check for framework error overlays
agent-browser eval 'document.querySelector("[data-nextjs-dialog], .vite-error-overlay, #webpack-dev-server-client-overlay") ? "ERROR_OVERLAY" : "OK"'

# Check page isn't blank
agent-browser eval 'document.body.innerText.trim().length > 0 ? "HAS_CONTENT" : "BLANK"'

On Failure

If verification fails:

1. Screenshot the error state: agent-browser screenshot error-state.png
2. Capture the error overlay text or console output
3. Close the browser: agent-browser close
4. Fix the issue in code
5. Re-run verification (max 2 retry cycles to avoid infinite loops)

Diagnosing a Hanging or Stuck Page

When the page appears stuck (spinner, blank content after load, frozen UI), the browser is only half the story. Correlate what you see in the browser with server-side evidence:

1. Capture Browser Evidence

# Screenshot the stuck state
agent-browser screenshot stuck-state.png

# Check for pending network requests (XHR/fetch that never resolved).
# Request tracking is off until the first `network requests` call, so arm it,
# reload, then list — a row printed without a trailing status code never resolved.
agent-browser network requests
agent-browser open http://localhost:3000
agent-browser network requests --type xhr,fetch

# Check console for errors or warnings
agent-browser errors
agent-browser console

# Look for fetch calls to workflow/API routes that are pending
agent-browser eval 'document.querySelector("[data-nextjs-dialog]") ? "ERROR_OVERLAY" : "OK"'

2. Check Server Logs

After capturing browser state, immediately check the backend:

# Stream Vercel runtime logs for the deployment
vercel logs --follow

# If using Workflow DevKit, check run status
npx workflow inspect runs
npx workflow inspect run <run_id>

# Check workflow health
npx workflow health

3. Correlate Browser + Server

Browser Shows	Server Shows	Likely Issue
Spinner / loading forever	No recent function invocations	API route not being called — check fetch URL in client code
Spinner / loading forever	Function started but no step logs	Workflow step is stuck — add console.log at step entry/exit
Blank page, no errors	Build succeeded, no runtime errors	Hydration issue or missing data — check SSR vs client rendering
Network request pending	504 Gateway Timeout in logs	Function timeout — increase maxDuration or optimize step
Console: "Failed to fetch"	OIDC/credential error in logs	Missing vercel env pull — run vercel link && vercel env pull
Error overlay visible	Stack trace in runtime logs	Read the server error — it usually has more detail than the client

4. Fix and Re-verify

After fixing the issue:

# Re-open and verify the fix
agent-browser open http://localhost:3000
agent-browser wait --load networkidle
agent-browser screenshot after-fix.png
agent-browser eval 'document.body.innerText.trim().length > 0 ? "HAS_CONTENT" : "BLANK"'
agent-browser close

On Success

agent-browser close

Report: "Dev server verified — page loads, no errors detected, key UI elements render correctly."

Suggest Verification After Implementation

When you finish building or implementing a feature (wrote code, created routes, set up a project), briefly let the user know they can ask you to verify everything works with a browser check. One sentence is enough. Don't force it if only a small fix or question was involved.