Claude-Code-Workflow/.claude/skills/team-frontend-debug/specs/debug-tools.md

Chrome DevTools MCP Usage Patterns

Reference for debug tool usage across all roles. Reproducer and Verifier are primary consumers.

1. Navigation & Page Control

Navigate to URL

mcp__chrome-devtools__navigate_page({ type: "url", url: "http://localhost:3000/page" })

Wait for Page Load

mcp__chrome-devtools__wait_for({ text: ["Expected Text"], timeout: 10000 })

Reload Page

mcp__chrome-devtools__navigate_page({ type: "reload" })

List Open Pages

mcp__chrome-devtools__list_pages()

Select Page

mcp__chrome-devtools__select_page({ pageId: 0 })

2. User Interaction Simulation

Click Element

// First take snapshot to find uid
mcp__chrome-devtools__take_snapshot()
// Then click by uid
mcp__chrome-devtools__click({ uid: "<uid-from-snapshot>" })

Fill Input

mcp__chrome-devtools__fill({ uid: "<uid>", value: "input text" })

Fill Multiple Fields

mcp__chrome-devtools__fill_form({
  elements: [
    { uid: "<uid1>", value: "value1" },
    { uid: "<uid2>", value: "value2" }
  ]
})

Hover Element

mcp__chrome-devtools__hover({ uid: "<uid>" })

Press Key

mcp__chrome-devtools__press_key({ key: "Enter" })
mcp__chrome-devtools__press_key({ key: "Control+A" })

Type Text

mcp__chrome-devtools__type_text({ text: "typed content", submitKey: "Enter" })

3. Evidence Collection

Screenshot

// Full viewport
mcp__chrome-devtools__take_screenshot({ filePath: "<session>/evidence/screenshot.png" })

// Full page
mcp__chrome-devtools__take_screenshot({ filePath: "<path>", fullPage: true })

// Specific element
mcp__chrome-devtools__take_screenshot({ uid: "<uid>", filePath: "<path>" })

DOM/A11y Snapshot

// Standard snapshot
mcp__chrome-devtools__take_snapshot()

// Verbose (all a11y info)
mcp__chrome-devtools__take_snapshot({ verbose: true })

// Save to file
mcp__chrome-devtools__take_snapshot({ filePath: "<session>/evidence/snapshot.txt" })

Console Messages

// All messages
mcp__chrome-devtools__list_console_messages()

// Errors and warnings only
mcp__chrome-devtools__list_console_messages({ types: ["error", "warn"] })

// Get specific message detail
mcp__chrome-devtools__get_console_message({ msgid: 5 })

Network Requests

// All requests
mcp__chrome-devtools__list_network_requests()

// XHR/Fetch only (API calls)
mcp__chrome-devtools__list_network_requests({ resourceTypes: ["xhr", "fetch"] })

// Get request detail (headers, body, response)
mcp__chrome-devtools__get_network_request({ reqid: 3 })

// Save response to file
mcp__chrome-devtools__get_network_request({ reqid: 3, responseFilePath: "<path>" })

Performance Trace

// Start trace (auto-reload and auto-stop)
mcp__chrome-devtools__performance_start_trace({ reload: true, autoStop: true })

// Start manual trace
mcp__chrome-devtools__performance_start_trace({ reload: false, autoStop: false })

// Stop and save
mcp__chrome-devtools__performance_stop_trace({ filePath: "<session>/evidence/trace.json" })

4. Script Execution

Evaluate JavaScript

// Get page title
mcp__chrome-devtools__evaluate_script({ function: "() => document.title" })

// Get element state
mcp__chrome-devtools__evaluate_script({
  function: "(el) => ({ text: el.innerText, classes: el.className })",
  args: ["<uid>"]
})

// Check React state (if applicable)
mcp__chrome-devtools__evaluate_script({
  function: "() => { const fiber = document.querySelector('#root')._reactRootContainer; return fiber ? 'React detected' : 'No React'; }"
})

// Get computed styles
mcp__chrome-devtools__evaluate_script({
  function: "(el) => JSON.stringify(window.getComputedStyle(el))",
  args: ["<uid>"]
})

5. Common Debug Patterns

Pattern: Reproduce Click Bug

1. navigate_page → target URL
2. wait_for → page loaded
3. take_snapshot → find target element uid
4. take_screenshot → before state
5. list_console_messages → baseline errors
6. click → target element
7. wait_for → expected result (or timeout)
8. take_screenshot → after state
9. list_console_messages → new errors
10. list_network_requests → triggered requests

Pattern: Debug API Error

1. navigate_page → target URL
2. wait_for → page loaded
3. take_snapshot → find trigger element
4. click/fill → trigger API call
5. list_network_requests → find the API request
6. get_network_request → inspect headers, body, response
7. list_console_messages → check for error handling

Pattern: Debug Performance Issue

1. navigate_page → target URL (set URL first)
2. performance_start_trace → start recording with reload
3. (auto-stop after page loads)
4. Read trace results → identify long tasks, bottlenecks

Pattern: Debug Visual/CSS Issue

1. navigate_page → target URL
2. take_screenshot → capture current visual state
3. take_snapshot({ verbose: true }) → full a11y tree with styles
4. evaluate_script → get computed styles of problematic element
5. Compare expected vs actual styles

6. Error Handling

Error	Meaning	Resolution
"No page selected"	No browser tab active	list_pages → select_page
"Element not found"	uid is stale	take_snapshot → get new uid
"Navigation timeout"	Page didn't load	Check URL, retry with longer timeout
"Evaluation failed"	JS error in script	Check script syntax, page context
"No trace recording"	stop_trace without start	Ensure start_trace was called first