Chrome DevTools Testing Skill

Purpose

Automate testing of web applications using Chrome DevTools Protocol (CDP) with GUI Chrome browser.

Standard Setup

Step 1: Start Chrome (GUI Browser)

/usr/bin/google-chrome \
  --remote-debugging-port=9222 \
  --user-data-dir=/tmp/chrome-debug-profile \
  --no-first-run \
  --no-default-browser-check \
  "about:blank" &

sleep 3
curl -s http://127.0.0.1:9222/json/version

REQUIRED FLAGS:

• --user-data-dir=/tmp/chrome-debug-profile - Remote debugging REQUIRES a non-default profile
• --remote-debugging-port=9222 - Standard CDP port

RECOMMENDED: GUI mode (--headless=new has known issues). Always use GUI browser with flags specified.

Step 2: Start Dev Server

pnpm exec vite --host 0.0.0.0

Step 3: Navigate and Test

navigate_page(url: "http://localhost:PORT", type: "url")
take_snapshot()

Complete Workflow

Clean Start

# Kill existing Chrome sessions
pkill -f "chrome.*remote-debugging" || true

# Kill process on dev port if needed
fuser -k 3000/tcp || true

Start Services

# 1. Start Chrome (GUI)
/usr/bin/google-chrome \
  --remote-debugging-port=9222 \
  --user-data-dir=/tmp/chrome-debug-profile \
  --no-first-run \
  --no-default-browser-check \
  "about:blank" &

sleep 3
curl -s http://127.0.0.1:9222/json/version

# 2. Start dev server
cd /path/to/app
pnpm exec vite --host 0.0.0.0 &

sleep 5

MCP Connection

If chrome-devtools MCP shows "Not connected":

1. Ask user to run /mcp to reconnect
2. Wait for confirmation
3. Retry

Troubleshooting

MCP Tools Quick Reference

Navigation

Inspection

Interaction

Understanding UIDs

What is a UID?

Every DOM element in a page snapshot receives a unique identifier (UID). UIDs are used to reference specific elements for interaction (click, fill, hover).

When UIDs become stale:

• After page navigation
• After DOM mutations (elements added/removed/reordered)
• After JavaScript dynamically modifies the page
• After timeout waiting for elements

Best practice: Always run take_snapshot() before attempting interactions. This refreshes UIDs to match current page state.

Example workflow:

1. navigate_page(url: "http://localhost:3000")
2. take_snapshot()                          # Get fresh UIDs
3. click(uid: "button-123")                 # Use UID from snapshot
4. take_snapshot()                          # Refresh after action
5. fill(uid: "input-456", text: "search")   # Use new UID

Pre-Flight Checklist

• Chrome started with --user-data-dir flag
• curl http://127.0.0.1:9222/json/version returns JSON
• Dev server started with --host 0.0.0.0
• MCP chrome-devtools connected

Best Practices

1. Always include --user-data-dir → Remote debugging REQUIRES --user-data-dir=/tmp/chrome-debug-profile to function properly
2. Always refresh UIDs → Run take_snapshot() after every navigation or DOM change to ensure element identifiers match current state
3. Always clean Chrome instances → Use lsof -ti:9222 | xargs kill -9 to clean up conflicting port 9222 instances
4. Always clean dev servers → Use fuser -k 3000/tcp before starting new server to prevent port conflicts
5. Always wait for services → Execute sleep 3-5 after starting Chrome/server to ensure connection readiness
6. Always verify MCP status → Have user run /mcp to reconnect if tools fail silently
7. Always use GUI mode → Use GUI browser with --user-data-dir for reliable display and MCP connection
8. Always use --host 0.0.0.0 → Required for Docker/remote access to ensure dev server reachability

Chrome Version Compatibility

Supported versions: Chrome 90+ (CDP Protocol v1.3+)

Check version:

/usr/bin/google-chrome --version

Known issues by version:

• Chrome < 90 → CDP protocol too old, tools may not work
• Chrome 90-100 → Stable, most common
• Chrome 101+ → Supports newer CDP features, recommended
• Chromium (headless) → Use GUI Chrome instead. GUI Chrome provides best CDP support

If version is too old:

# Option 1: Update Chrome
sudo apt-get update && sudo apt-get install google-chrome-stable

# Option 2: Use different installation
/snap/bin/chromium --version
/snap/bin/chromium --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug &

Known Failures (WSL Environment)

Problem: Chrome Starts But MCP Tools Fail

Symptoms:

• curl http://127.0.0.1:9222/json/version returns valid JSON
• MCP chrome-devtools tools return "Not connected"
• Chrome window never appears visually for user
• Multiple background processes accumulate

Root Cause: In WSL2 environments, Chrome may technically start with debugging enabled but fail to establish proper GUI display or MCP connection. The CDP endpoint responds to curl but the MCP integration cannot connect.

What To Do:

1. Acknowledge the failure immediately:

   Chrome DevTools automation failed. You can restart manually.
   

2. Instead:

   • Stop retries immediately
   • Kill all background processes
   • Acknowledge the failure and suggest manual verification

3. Tell user to verify manually:

   • Open Chrome on Windows side
   • Navigate to http://localhost:PORT
   • Check browser console for errors

When This Happens

If MCP tools fail after Chrome appears to start:

Chrome DevTools automation failed.
HTTP verification shows servers are responding.
Please verify manually in your browser:
- http://localhost:3000 (main app)
- http://localhost:5173 (dev server)

Then continue with manual verification only.