browser-test-with-restart

name	browser-test-with-restart
description	Debug and verify web UI issues by opening pages in a real browser, checking for errors, applying code fixes, rebuilding, and re-testing. Restart the coc dev server ONLY when the user explicitly asks for a restart — otherwise stop and ask for confirmation before restarting. Use when the user asks to debug a web page, verify a UI fix in the browser, or test a localhost page after code changes.

Browser Test with Server Restart

Workflow for debugging SPA dashboard issues end-to-end: inspect the page in a real browser, fix code, rebuild, restart the server, and verify the fix.

Project context

• SPA source: packages/coc/src/server/spa/client/react/
• Client build: npm run build:client (in packages/coc/)
• Copy to dist: npm run build:copy-client (in packages/coc/)
• Server restart: POST http://localhost:4000/api/admin/restart
• Default port: 4000

Workflow

1. Open the page and capture initial state

Use the browser-use subagent to navigate to the URL:

• Take a screenshot
• Check the browser console for JavaScript errors (PAGE ERROR and CONSOLE ERROR events)
• Report what is visible and any errors found

Example subagent prompt:

Navigate to <URL> and take a screenshot.
Report:
1. What you see on the page (describe the screenshot)
2. Any JavaScript errors in the browser console
3. The full URL in the address bar

2. Diagnose from browser evidence

• Blank page / crash → JS error in console; stack trace points to the broken component
• Wrong content rendered → routing or conditional rendering mismatch
• Missing data → API call failure, missing props, or race condition
• Layout broken → CSS classes or responsive breakpoints

3. Apply the code fix

Fix the source files under packages/coc/src/server/spa/client/react/.

4. Rebuild and restart

cd packages/coc
npm run build:client
npm run build:copy-client

⚠️ Only restart the server when the user has explicitly asked for it. Restarting is disruptive (it interrupts in-flight work and other sessions sharing the server). Never restart automatically as part of this workflow. If the user has not explicitly requested a restart, stop here, report that a restart is needed, and ask the user to confirm before proceeding.

Once the user has explicitly confirmed, restart the server and wait for it to come back:

curl -s -X POST http://localhost:4000/api/admin/restart
sleep 10

Verify the server is up by hitting any lightweight endpoint:

curl -s http://localhost:4000/api/queue

5. Verify the fix in the browser

Use the browser-use subagent again to revisit the same URL:

• Take a screenshot
• Confirm zero JavaScript errors in the console
• Describe what the page now shows

Compare before/after to confirm the fix.

6. Iterate if needed

If the browser still shows issues, capture the new errors and loop back to step 2.

Tips

• Only restart the server when the user explicitly asks. A restart interrupts in-flight work and any other sessions sharing the server. If a restart is needed but the user hasn't asked for one, stop and request confirmation first.
• Always rebuild before restarting. The server serves the bundled SPA from dist/; a restart alone won't pick up source changes.
• Check console errors first. A blank page is almost always a JS crash — the error message and stack trace are the fastest path to the root cause.
• Clean up browser artifacts. The browser subagent may create screenshot files or helper scripts in the workspace. Remove them before committing.
• Test cold-load deep links. Navigate directly to the URL rather than clicking through the UI — deep-linked pages may have race conditions that only appear on initial load.