majiayu000 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
MANDATORY FLAGS:
--user-data-dir=/tmp/chrome-debug-profile- Remote debugging REQUIRES a non-default profile--remote-debugging-port=9222- Standard CDP port
NOTE: Headless mode (--headless=new) has known issues. Use GUI browser instead.
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":
- Ask user to run
/mcpto reconnect - Wait for confirmation
- Retry
Troubleshooting
| Symptom | Fix |
|---|---|
| "requires non-default data directory" | Add --user-data-dir=/tmp/chrome-debug-profile |
| "Not connected" from MCP | User runs /mcp to reconnect |
ERR_CONNECTION_REFUSED |
Start dev server with --host 0.0.0.0 |
| Chrome won't start | pkill -f "chrome.*remote-debugging" |
| Stale UIDs | Take fresh snapshot |
MCP Tools Quick Reference
Navigation
| Tool | Purpose |
|---|---|
list_pages |
List open tabs |
select_page |
Switch active tab |
new_page |
Open new tab |
navigate_page |
Navigate URL |
close_page |
Close tab |
Inspection
| Tool | Purpose |
|---|---|
take_snapshot |
Get DOM with UIDs |
take_screenshot |
Capture visual |
list_console_messages |
Get console logs |
list_network_requests |
Get network activity |
Interaction
| Tool | Purpose |
|---|---|
click |
Click element |
fill |
Enter text |
hover |
Hover element |
press_key |
Keyboard input |
Pre-Flight Checklist
- Chrome started with
--user-data-dirflag -
curl http://127.0.0.1:9222/json/versionreturns JSON - Dev server started with
--host 0.0.0.0 - MCP chrome-devtools connected
Common Mistakes
- Missing
--user-data-dir→ Remote debugging fails - Multiple Chrome instances → Port conflicts
- Multiple dev servers → Port conflicts
- Not waiting for services → Connection fails
- Not checking MCP status → Tools fail silently
Known Failures (WSL Environment)
Problem: Chrome Starts But MCP Tools Fail
Symptoms:
curl http://127.0.0.1:9222/json/versionreturns 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:
Acknowledge the failure immediately:
Chrome DevTools automation failed. You can restart manually.Do NOT:
- Keep retrying indefinitely
- Spawn more background processes
- Pretend it might work next time
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 stop attempting browser automation.