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:

bash

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

Or with options:

bash

# 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

code

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

code

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

code

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

code

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

code

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

code

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

code

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)

code

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

Step 3: Interact with Elements

code

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

Step 4: Verify Results

code

- 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:

•Check if dev server is running
•Use new_page instead of navigate_page
•Increase timeout: timeout: 30000

Element Not Found

If click/fill fails:

•Re-run take_snapshot to get latest UIDs
•Verify element is within viewport
•Use wait_for to wait for element to appear

Page Not Loading

If page fails to load:

•Verify URL is correct
•Check dev server logs
•Try navigate_page with type: "reload"

Tips

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

Quick Reference

code

# 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:

code

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:

code

# 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