Chrome DevTools MCP - UI Testing Skill

Auto-activation Triggers

English

• "test UI", "test the UI", "UI test"
• "open browser", "launch browser"
• "take screenshot", "capture screenshot"
• "check console errors", "any console errors"
• "test in browser", "verify in browser"

中文

• "測試 UI"、"UI 測試"、"測試畫面"
• "開瀏覽器"、"啟動瀏覽器"
• "截圖"、"擷取畫面"
• "檢查錯誤"、"有沒有錯誤"、"console 錯誤"
• "瀏覽器測試"、"在瀏覽器驗證"

Auto-trigger Scenarios

• User completed a feature and needs visual verification
• User asks to verify a UI change
• User wants to debug a visual issue

Prerequisites

Ensure Chrome DevTools MCP is configured in Claude Code:

claude mcp add chrome-devtools -- npx -y chrome-devtools-mcp@latest

Or with options:

# Headless mode (no UI)
claude mcp add chrome-devtools -- npx -y chrome-devtools-mcp@latest --headless

# Isolated session (clean browser state)
claude mcp add chrome-devtools -- npx -y chrome-devtools-mcp@latest --isolated

Available MCP Tools (26 total)

Navigation & Pages

Tool	Description
mcp__chrome-devtools__new_page	Open new page with URL
mcp__chrome-devtools__navigate_page	Navigate to URL, back, forward, reload
mcp__chrome-devtools__list_pages	List all open pages
mcp__chrome-devtools__select_page	Select page by index
mcp__chrome-devtools__close_page	Close page by index
mcp__chrome-devtools__wait_for	Wait for text to appear

Input & Interaction

Tool	Description
mcp__chrome-devtools__click	Click element by uid
mcp__chrome-devtools__fill	Fill input/textarea/select
mcp__chrome-devtools__fill_form	Fill multiple form elements
mcp__chrome-devtools__hover	Hover over element
mcp__chrome-devtools__drag	Drag element to another
mcp__chrome-devtools__press_key	Press key or combination
mcp__chrome-devtools__handle_dialog	Accept/dismiss browser dialogs
mcp__chrome-devtools__upload_file	Upload file through input

Debugging & Inspection

Tool	Description
mcp__chrome-devtools__take_snapshot	Get page A11y tree with UIDs
mcp__chrome-devtools__take_screenshot	Capture page/element screenshot
mcp__chrome-devtools__evaluate_script	Run JavaScript in page
mcp__chrome-devtools__list_console_messages	List console messages
mcp__chrome-devtools__get_console_message	Get specific console message

Network

Tool	Description
mcp__chrome-devtools__list_network_requests	List network requests
mcp__chrome-devtools__get_network_request	Get request details

Performance

Tool	Description
mcp__chrome-devtools__performance_start_trace	Start performance trace
mcp__chrome-devtools__performance_stop_trace	Stop trace recording
mcp__chrome-devtools__performance_analyze_insight	Analyze performance insights

Emulation

Tool	Description
mcp__chrome-devtools__emulate	Emulate network/CPU throttling
mcp__chrome-devtools__resize_page	Resize viewport

Common UI Testing Patterns

1. Basic Page Verification

1. take_snapshot → Get page structure with element UIDs
2. take_screenshot → Visual verification
3. list_console_messages → Check for errors

2. Form Testing Flow

1. new_page → Open target URL
2. take_snapshot → Get form element UIDs
3. fill_form → Fill all form fields
4. click → Submit button
5. wait_for → Wait for success message
6. take_screenshot → Capture result

3. Interactive Component Testing

1. take_snapshot → Get element UIDs
2. click → Trigger component action
3. take_snapshot → Verify state change
4. list_console_messages → Check for errors

4. Responsive Design Testing

1. resize_page → Set mobile viewport (375x667)
2. take_screenshot → Mobile view
3. resize_page → Set tablet viewport (768x1024)
4. take_screenshot → Tablet view
5. resize_page → Set desktop viewport (1920x1080)
6. take_screenshot → Desktop view

5. Performance Audit

1. performance_start_trace → Begin recording
2. navigate_page → Load page
3. performance_stop_trace → End recording
4. performance_analyze_insight → Get CWV scores

6. Network Request Verification

1. navigate_page → Load page
2. list_network_requests → See all requests
3. get_network_request → Check specific API response

Workflow: Post-Feature UI Verification

When you complete a feature that requires UI testing:

Step 1: Start Browser

Use: mcp__chrome-devtools__new_page
URL: http://localhost:{PORT}/path-to-feature

Common ports:
- Next.js: 3000 or custom (this project: 1408)
- Vite: 5173
- Angular: 4200

Step 2: Take Snapshot (ALWAYS do this first)

Use: mcp__chrome-devtools__take_snapshot
This returns element UIDs needed for interactions

Step 3: Interact with Elements

Use element UIDs from snapshot to:
- click buttons
- fill forms
- hover for tooltips

Step 4: Verify Results

- take_screenshot for visual verification
- list_console_messages for error checking
- take_snapshot for DOM state verification

Error Handling

Navigation Timeout

If navigate_page times out:

1. Check if dev server is running
2. Use new_page instead of navigate_page
3. Increase timeout: timeout: 30000

Element Not Found

If click/fill fails:

1. Re-run take_snapshot to get latest UIDs
2. Verify element is within viewport
3. Use wait_for to wait for element to appear

Page Not Loading

If page fails to load:

1. Verify URL is correct
2. Check dev server logs
3. Try navigate_page with type: "reload"

Tips

1. Always take_snapshot first - You need element UIDs before interacting
2. Prefer snapshot over screenshot - Faster and provides actionable data
3. Check console after interactions - Catch runtime errors early
4. Use wait_for after navigation - Ensure page is loaded before interacting
5. Filter network requests - Use resourceTypes to focus on API calls
6. Re-snapshot after interactions - UIDs may change after DOM updates

Quick Reference

# Open dev server and test
mcp__chrome-devtools__new_page → http://localhost:{PORT}

# Get page structure
mcp__chrome-devtools__take_snapshot

# Interact (use UID from snapshot)
mcp__chrome-devtools__click → uid: "abc123"
mcp__chrome-devtools__fill → uid: "input1", value: "test"

# Verify
mcp__chrome-devtools__take_screenshot
mcp__chrome-devtools__list_console_messages → types: ["error", "warn"]

Complete Example: Testing a Login Form

Complete login form testing workflow:

Step 1: Open login page
────────────────────
mcp__chrome-devtools__new_page
  url: "http://localhost:3000/login"

Step 2: Get page structure
────────────────────
mcp__chrome-devtools__take_snapshot

Output:
  uid=1_10 textbox "Email"
  uid=1_15 textbox "Password"
  uid=1_20 button "Sign In"

Step 3: Fill form
────────────────────
mcp__chrome-devtools__fill_form
  elements: [
    { uid: "1_10", value: "test@example.com" },
    { uid: "1_15", value: "password123" }
  ]

Step 4: Click login
────────────────────
mcp__chrome-devtools__click
  uid: "1_20"

Step 5: Wait for result
────────────────────
mcp__chrome-devtools__wait_for
  text: "Welcome"
  timeout: 5000

Step 6: Verify
────────────────────
mcp__chrome-devtools__take_screenshot  → Verify UI is correct
mcp__chrome-devtools__list_console_messages → Check for errors
  types: ["error", "warn"]

Step 7: Check API requests (optional)
────────────────────
mcp__chrome-devtools__list_network_requests
  resourceTypes: ["fetch", "xhr"]

Responsive Testing Example

Test responsive design across breakpoints:

# Mobile (iPhone SE)
mcp__chrome-devtools__resize_page → width: 375, height: 667
mcp__chrome-devtools__take_screenshot

# Tablet (iPad)
mcp__chrome-devtools__resize_page → width: 768, height: 1024
mcp__chrome-devtools__take_screenshot

# Desktop
mcp__chrome-devtools__resize_page → width: 1920, height: 1080
mcp__chrome-devtools__take_screenshot