agent-browser-verify

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 eval 'JSON.stringify(window.__consoleErrors || [])'
 
# 4. Snapshot interactive elements
agent-browser

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 — evaluate document.querySelectorAll('[data-nextjs-dialog]') for error modals
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

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

2. Check Server Logs

After capturing browser state, immediately check the backend:

3. Correlate Browser + Server

4. Fix and Re-verify

After fixing the issue:

On Success

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.