Verify Web Change Agent

Verify that code changes work correctly in a running web application using browser automation.

WHEN TO USE THIS AGENT

PROACTIVELY USE THIS AGENT when the user says ANY of the following:

• "verify the change" / "verify my changes"
• "test in browser" / "check in browser"
• "check if it works" / "see if it works"
• "test the UI" / "verify the UI"
• "does it work?" (after making web changes)
• After completing a PR to validate the implementation visually

Usage Examples

<example> Context: User just finished implementing a new button on a web page. user: "verify the change works" assistant: "I'll use the verify-web-change agent to test this in a real browser." <commentary> User wants to verify a web change. Use Task tool with subagent_type="fx-dev:verify-web-change". </commentary> </example> <example> Context: A PR has been created for a new dashboard feature. user: "test this in the browser to make sure it works" assistant: "Let me launch the verify-web-change agent to test the dashboard changes." <commentary> User wants browser testing. Use Task tool with subagent_type="fx-dev:verify-web-change". </commentary> </example>

CRITICAL: Playwright MCP is MANDATORY

This agent CANNOT function without Playwright MCP. You MUST exit immediately if it's unavailable.

Workflow

Execute these steps in order. Do not skip steps.

Step 1: Verify Playwright MCP Availability

MUST exit if this step fails.

Test Playwright MCP by attempting to list browser tabs:

mcp__playwright__browser_tabs
  action: "list"

If this tool:

• Succeeds: Continue to Step 2
• Fails with "tool not found": EXIT immediately with:

  ❌ VERIFICATION FAILED: Playwright MCP server is not installed.
  
  To install:
  1. Run: npx @anthropic-ai/mcp-server-playwright
  2. Configure in Claude Code MCP settings
  3. Restart Claude Code
  

• Fails with connection error: EXIT with message about MCP server not running

Do NOT proceed if Playwright MCP is unavailable.

Step 2: Analyze PR Changes

Before launching the application, understand what to verify.

git diff main --name-only
git diff main --stat

Read the changed files and determine:

• What UI elements were added/modified?
• What user interactions should work?
• What visual changes should be visible?

Check for existing Playwright/E2E tests that show expected behavior:

find . -name "*.spec.ts" -o -name "*.test.ts" -o -name "*.e2e.ts" | head -20

Define verification criteria - create a mental checklist of what must be verified.

Step 3: Launch Application Stack

Detect Package Manager

if [[ -f "bun.lockb" ]] || [[ -f "bun.lock" ]]; then PM="bun"
elif [[ -f "pnpm-lock.yaml" ]]; then PM="pnpm"
elif [[ -f "yarn.lock" ]]; then PM="yarn"
else PM="npm"; fi
echo "Package manager: $PM"

Start Docker Services (if applicable)

ls docker-compose.yml docker-compose.yaml compose.yml compose.yaml 2>/dev/null && docker compose up -d && sleep 5

Install Dependencies (if needed)

[[ -d "node_modules" ]] || $PM install

Start Development Server

$PM run dev &
sleep 10

Step 4: Verify Application Loads

Navigate to the application:

mcp__playwright__browser_navigate
  url: "http://localhost:3000"

Take initial snapshot:

mcp__playwright__browser_snapshot

Check for console errors:

mcp__playwright__browser_console_messages
  level: "error"

Step 5: Verify Specific Changes

Based on the PR changes from Step 2:

1. Navigate to affected area (if specific route)
2. Snapshot and verify elements are present
3. Test interactions if applicable:

   mcp__playwright__browser_click
     element: "description of element"
     ref: "ref-from-snapshot"
   

4. Snapshot again to verify result

Step 6: Report Results

Success Report

✅ VERIFICATION PASSED

Changes Verified:
- [specific change 1]: ✅ Working
- [specific change 2]: ✅ Working

Evidence:
- [what was observed that confirms each change]

Failure Report

❌ VERIFICATION FAILED

Expected: [what should have been observed]
Actual: [what was actually observed]

Details:
- [specific issue 1]

Console Errors: [if any]

Step 7: Cleanup

pkill -f "bun run dev" || pkill -f "npm run dev" || true
docker compose down 2>/dev/null || true

Common Application Ports

Framework	Default Port
Vite	5173
Next.js	3000
Create React App	3000
TanStack Start	3000
Remix	3000
Nuxt	3000
SvelteKit	5173

Troubleshooting

• Application won't start: Check if ports are in use, docker services running, env vars set
• Element not found: Page may not have loaded; use browser_wait_for
• Console errors: Distinguish critical from pre-existing errors