visual-validate

Visual Validate

Drive a real browser via MCP to verify a UI change works as intended. Auto-detects which browser MCP is available (chrome-devtools preferred, playwright fallback). Screenshots, interactions, and console capture confirm the change is real — not just type-checked.

MCP Auto-Detection

Prefer chrome-devtools MCP tools (mcp__chrome-devtools__*); fall back to playwright (mcp__playwright__*) if absent. If neither is available, STOP and tell the user to install one. State the detected MCP at the start: "Using chrome-devtools MCP for visual validation."

Workflow

Phase 1 — Setup

1. Confirm the dev server URL with the user (default to http://localhost:3000 if a Next.js/Vite project is detected; otherwise ask).
2. If the dev server is not running, ask the user to start it. Do NOT start it automatically — port collisions are easy and dev servers are user state.
3. Open the page via the detected MCP:
   • chrome-devtools: new_page → navigate_page
   • playwright: equivalent navigate tool

Phase 2 — Capture baseline (before)

1. Take a "before" screenshot of the relevant page/component. Save reference to it.
2. Capture the initial console state.
3. If the user provides a specific element or component to focus on, take an element-scoped screenshot via DOM snapshot.

Phase 3 — Exercise the change

1. Ask the user what interactions to validate (e.g., "click the toggle", "submit form with X data", "resize to mobile width").
2. Execute interactions via MCP:
   • chrome-devtools: click, fill, hover, press_key, resize_page
   • playwright: equivalent tools
3. Wait for any animations / network requests to settle (wait_for or equivalent).

Phase 4 — Capture after

1. Take "after" screenshot(s).
2. Capture console messages and any new network errors via list_console_messages and list_network_requests.
3. Run accessibility audit on the final state via lighthouse_audit (chrome-devtools) if available.

Phase 5 — Report

1. Present findings in this structure:

## Visual Validation — <feature>

**MCP**: chrome-devtools (or playwright)
**URL**: <url>
**Interactions exercised**: <list>

### Screenshots
- Before: <path or reference>
- After: <path or reference>

### Console
- Errors: <count> — <summary>
- Warnings: <count>

### Network
- Failed requests: <count>
- Slow requests (>1s): <count>

### Accessibility (if lighthouse_audit ran)
- Score: <n>
- Critical issues: <list>

### Verdict
- PASS: change works as intended, no new console errors, no a11y regressions
- FAIL: console errors / a11y regressions / unexpected visual changes — list each issue with screenshot reference

Rules

• Never modify files during validation; this is read-only browser interaction
• Always close the browser page at the end (close_page) to free resources
• Capture console messages even on PASS — silent regressions surface in console first

Error Handling

• No MCP available → STOP with installation hint (chrome-devtools or playwright MCP server setup)
• Dev server unreachable → ask user to confirm URL and start the server
• Navigation timeout (>30s) → report and stop; likely a build error or wrong URL
• MCP tool errors mid-flow → report which step failed, attempt cleanup (close_page), stop

Choosing chrome-devtools vs playwright

• chrome-devtools: DevTools-specific features — lighthouse audit, network throttling, performance profiling, memory snapshots.
• playwright: cross-browser testing (Firefox, Safari/WebKit) or an existing Playwright setup.