flakewatch-browser-agent

MCP browser investigation agent for Flakewatch.

When screenshot-only analysis isn't enough, this package gives Claude access to a live browser via the Chrome DevTools MCP server. The agent can navigate pages, click buttons, hover elements, inspect the DOM, and take screenshots to investigate test failures interactively.

When to use this

Most test failures can be diagnosed from screenshots and error messages alone (screenshot mode). The browser agent is useful for failures that involve:

• Hidden elements -- dropdown menus, modals, tooltips that only appear after interaction
• Overlapping elements -- z-index issues where an overlay blocks clicks
• Async loading -- content that appears after a delay
• Multi-step flows -- sequences that require clicking through several states

Usage

Used automatically when you run Flakewatch in full mode:

npx flakewatch analyze \
  --results-dir ./test-results \
  --mode full \
  --base-url http://localhost:3000

Requires the app to be running and accessible at the provided URL.

How it works

1. Spawns a headless Chrome instance via the Chrome DevTools MCP server
2. Gives Claude a set of browser tools (navigate, click, hover, fill, screenshot, DOM snapshot, etc.)
3. Claude investigates each failure in an agentic loop -- navigating to the page, trying interactions, inspecting elements
4. Produces a verdict with evidence from the live investigation

License

MIT