Chrome Devtools

Chrome DevTools MCP Skill

Complete Chrome browser automation and debugging using the Chrome DevTools Protocol. This skill provides access to all Chrome DevTools capabilities for web development, testing, and debugging tasks.

Capabilities

1. Navigate & Automate - Control browser navigation, tabs, and page interactions 2. Interact with Pages - Click, type, drag, fill forms, upload files 3. Debug & Inspect - View console logs, network requests, execute scripts 4. Performance Analysis - Record traces and get performance insights 5. Emulation - Test different devices, network conditions, viewports 6. Visual Testing - Take screenshots and DOM snapshots

Quick Reference

For detailed instructions on each operation, see:

• NAVIGATION.md - Page navigation, tabs, waiting
• INTERACTION.md - Clicking, typing, forms, uploads
• DEBUGGING.md - Console logs, network requests, script execution
• PERFORMANCE.md - Performance tracing and analysis
• EMULATION.md - Device and network emulation
• VISUAL.md - Screenshots and DOM snapshots

Common Workflows

Web Testing Workflow

1. Navigate to page with navigate_page 2. Interact with elements using click, fill, press_key 3. Verify results with take_screenshot or list_console_messages 4. Check network activity with list_network_requests

Performance Analysis Workflow

1. Start trace with performance_start_trace 2. Navigate or interact with page 3. Stop trace with performance_stop_trace 4. Get insights with performance_analyze_insight

Debugging Workflow

1. Navigate to problematic page 2. Check console with list_console_messages 3. Inspect network with list_network_requests 4. Execute diagnostic scripts with evaluate_script 5. Take screenshots for visual confirmation

Form Testing Workflow

1. Navigate to form page 2. Fill individual fields with fill or use fill_form for bulk entry 3. Upload files if needed with upload_file 4. Submit and verify with screenshots/console

Tool Categories Overview

Input Automation (8 tools)

• click - Click on elements
• drag - Drag and drop operations
• fill - Enter text in fields
• fill_form - Fill multiple form fields
• handle_dialog - Manage alerts/dialogs
• hover - Hover over elements
• press_key - Keyboard input
• upload_file - File upload handling

Navigation (6 tools)

• navigate_page - Go to URLs
• new_page - Create new tabs
• close_page - Close tabs
• list_pages - View open tabs
• select_page - Switch tabs
• wait_for - Wait for conditions

Emulation (2 tools)

• emulate - Device/condition simulation
• resize_page - Viewport sizing

Performance (3 tools)

• performance_start_trace - Begin recording
• performance_stop_trace - End recording
• performance_analyze_insight - Get recommendations

Network (2 tools)

• list_network_requests - View all requests
• get_network_request - Get request details

Debugging (5 tools)

• evaluate_script - Run JavaScript
• take_screenshot - Capture visuals
• take_snapshot - Capture DOM
• list_console_messages - View console
• get_console_message - Get specific message

Critical Instructions

REQUIRED: Before using ANY Chrome DevTools tools, you MUST load the relevant reference file(s) using the Read tool. These references contain essential operational instructions that are NOT included in this overview.

When the user asks to work with Chrome DevTools:

1. Identify the operation they want to perform (navigate, debug, test, analyze) 2. MANDATORY: Load the relevant reference file(s) using the Read tool BEFORE executing any tools:

• Navigation tasks → Read references/NAVIGATION.md FIRST
• Interaction tasks → Read references/INTERACTION.md FIRST
• Debugging tasks → Read references/DEBUGGING.md FIRST
• Performance tasks → Read references/PERFORMANCE.md FIRST
• Emulation tasks → Read references/EMULATION.md FIRST
• Visual testing tasks → Read references/VISUAL.md FIRST

3. Execute the appropriate MCP tool commands following the patterns from the loaded reference 4. Report results clearly with screenshots or data as appropriate 5. Chain operations when needed (e.g., navigate → interact → verify)

DO NOT attempt to use Chrome DevTools tools without first loading and reading the relevant reference documentation.

Best Practices

• Always wait appropriately - Use wait_for to ensure page readiness
• Handle errors gracefully - Check console messages and network errors
• Take screenshots - Visual confirmation is valuable for debugging
• Chain operations logically - Navigate before interacting, start trace before actions
• Clean up - Close pages when done to free resources
• Use selectors carefully - Ensure element selectors are specific and reliable

Examples

Take a screenshot of a website

User: "Take a screenshot of example.com"
Me: Uses navigate_page → wait_for → take_screenshot

Test form submission

User: "Fill out the login form on staging.example.com"
Me: Uses navigate_page → fill_form → click → list_console_messages

Analyze page performance

User: "Check the performance of our homepage"
Me: Uses performance_start_trace → navigate_page → performance_stop_trace → performance_analyze_insight

Debug network issues

User: "Why is the API call failing on /dashboard?"
Me: Uses navigate_page → list_network_requests → get_network_request (for failed request)

Test mobile viewport

User: "How does the site look on iPhone 13?"
Me: Uses emulate (iPhone 13) → navigate_page → take_screenshot

Configuration

The Chrome DevTools MCP server should be configured in Claude Code's MCP settings:

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["chrome-devtools-mcp@latest"]
    }
  }
}

Optional configuration flags:

• --headless false - Show browser window
• --categoryEmulation - Enable emulation tools
• --categoryPerformance - Enable performance tools
• --categoryNetwork - Enable network tools

Chrome DevTools MCP Skill

A comprehensive skill for controlling and inspecting Chrome browser using the Chrome DevTools Protocol through the chrome-devtools-mcp npm package.

Overview

This skill provides complete browser automation and debugging capabilities through Chrome DevTools, enabling:

• Page navigation and tab management
• Element interaction (clicks, typing, forms)
• Console and network debugging
• Performance analysis and tracing
• Device and network emulation
• Screenshots and DOM snapshots

Installation

Ensure the chrome-devtools-mcp package is configured in your Claude Code MCP settings:

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["chrome-devtools-mcp@latest"]
    }
  }
}

Optional Configuration

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": [
        "chrome-devtools-mcp@latest",
        "--headless=false",
        "--categoryEmulation",
        "--categoryPerformance",
        "--categoryNetwork"
      ]
    }
  }
}

Configuration flags:

• --headless=false - Show browser window (default: true)
• --categoryEmulation - Enable device/network emulation tools
• --categoryPerformance - Enable performance tracing tools
• --categoryNetwork - Enable network debugging tools
• --channel=stable|beta|dev|canary - Chrome channel to use
• --isolated - Use isolated browser profile

Skill Structure

chrome-devtools/
├── SKILL.md                      # Main skill definition
├── README.md                     # This file
└── references/
    ├── NAVIGATION.md             # Page navigation and tab management
    ├── INTERACTION.md            # Element interaction (clicks, forms, etc.)
    ├── DEBUGGING.md              # Console logs and network debugging
    ├── PERFORMANCE.md            # Performance tracing and analysis
    ├── EMULATION.md              # Device and network emulation
    └── VISUAL.md                 # Screenshots and DOM snapshots

Tool Categories

Navigation (6 tools)

• navigate_page - Go to URLs
• new_page - Create new tabs
• close_page - Close tabs
• list_pages - View open tabs
• select_page - Switch tabs
• wait_for - Wait for conditions

Interaction (8 tools)

• click - Click elements
• fill - Enter text
• fill_form - Fill multiple fields
• press_key - Keyboard input
• hover - Hover over elements
• drag - Drag and drop
• upload_file - Upload files
• handle_dialog - Manage alerts/dialogs

Debugging (5 tools)

• list_console_messages - View console logs
• get_console_message - Get specific log
• list_network_requests - View network requests
• get_network_request - Get request details
• evaluate_script - Execute JavaScript

Performance (3 tools)

• performance_start_trace - Begin recording
• performance_stop_trace - End recording
• performance_analyze_insight - Get recommendations

Emulation (2 tools)

• emulate - Device/network simulation
• resize_page - Viewport sizing

Visual (2 tools)

• take_screenshot - Capture screenshots
• take_snapshot - Capture DOM state

Usage Examples

Take a Screenshot

User: "Take a screenshot of example.com"

Agent workflow:
1. Reads references/NAVIGATION.md and references/VISUAL.md
2. Uses navigate_page to go to example.com
3. Uses wait_for to ensure page is loaded
4. Uses take_screenshot to capture the page

Debug Network Issues

User: "Check why the API call is failing on /dashboard"

Agent workflow:
1. Reads references/NAVIGATION.md and references/DEBUGGING.md
2. Uses navigate_page to go to /dashboard
3. Uses wait_for to ensure page loads
4. Uses list_network_requests to see all requests
5. Uses get_network_request to inspect failed request
6. Reports findings with error details

Test Mobile Layout

User: "How does the site look on iPhone 13?"

Agent workflow:
1. Reads references/EMULATION.md, references/NAVIGATION.md, and references/VISUAL.md
2. Uses emulate to set iPhone 13 device
3. Uses navigate_page to load the site
4. Uses wait_for to ensure content loads
5. Uses take_screenshot to capture mobile view

Analyze Performance

User: "Check the performance of our homepage"

Agent workflow:
1. Reads references/PERFORMANCE.md
2. Uses performance_start_trace with the URL
3. Uses wait_for to ensure page loads
4. Uses performance_stop_trace to end recording
5. Uses performance_analyze_insight to get recommendations
6. Reports Core Web Vitals and optimization suggestions

Fill and Submit Form

User: "Fill out the contact form on example.com/contact"

Agent workflow:
1. Reads references/NAVIGATION.md and references/INTERACTION.md
2. Uses navigate_page to go to /contact
3. Uses wait_for to ensure form loads
4. Uses fill_form to populate all fields
5. Uses click to submit the form
6. Uses take_screenshot to verify submission

Reference Loading

CRITICAL: The skill requires loading appropriate reference files before using any tools. The SKILL.md file contains mandatory instructions to load references using the Read tool before executing operations.

Each reference file contains:

• Detailed tool parameters and examples
• Common workflows and patterns
• Best practices
• Troubleshooting guides

Common Workflows

Web Testing

navigate → wait → interact → verify → screenshot

Performance Analysis

start_trace → navigate → wait → stop_trace → analyze

Debugging

navigate → check_console → check_network → execute_diagnostics

Responsive Design Testing

for each device:
  emulate → navigate → wait → screenshot → compare

Best Practices

1. Always wait after navigation - Use wait_for to ensure readiness 2. Use specific selectors - Avoid ambiguous element selectors 3. Handle errors gracefully - Check console and network for issues 4. Take screenshots - Visual confirmation is valuable 5. Chain operations logically - Navigate → interact → verify 6. Clean up resources - Close pages when done 7. Test multiple conditions - Different devices, networks, states 8. Load references first - Always read relevant reference files

Related Skills

• github - Manage GitHub issues (can create issues from test failures)
• review - Code review (can review test automation code)

Resources

• Chrome DevTools MCP GitHub
• Chrome DevTools MCP npm
• Chrome DevTools Protocol
• Chrome for Developers Blog

Troubleshooting

MCP server not connecting:

• Verify chrome-devtools-mcp is in your MCP config
• Check if Chrome is installed
• Try running npx chrome-devtools-mcp@latest --help

Browser not opening:

• Check --headless flag setting
• Verify Chrome executable path
• Check for permission issues

Tools not working:

• Ensure correct category flags are enabled
• Check MCP server logs
• Verify tool names match MCP definitions

Performance issues:

• Close unused tabs with close_page
• Use headless mode for faster execution
• Limit trace duration for performance tests

Version

Skill created for chrome-devtools-mcp@latest (as of January 2025)

For the latest features and updates, check the npm package page.

Chrome DevTools Debugging Reference

Access console logs, inspect network requests, execute JavaScript, and gather debugging information.

Available Tools

list_console_messages

Retrieve all console messages (logs, warnings, errors) from the page.

Parameters:

• pageId (optional): Specific page to get console messages from
• types (optional): Filter by message type (["log", "warn", "error", "info"])

Example:

Get all console messages:
mcp__chrome-devtools__list_console_messages

Get only errors:
mcp__chrome-devtools__list_console_messages
  types: ["error"]

Get warnings and errors:
mcp__chrome-devtools__list_console_messages
  types: ["warn", "error"]

Get from specific page:
mcp__chrome-devtools__list_console_messages
  pageId: page-123

Returns: Array of console message objects with:

• type: Message type (log, warn, error, info)
• text: Message content
• timestamp: When the message occurred
• source: Where it came from
• stackTrace: Stack trace for errors

Common use cases:

• Checking for JavaScript errors
• Verifying debug output
• Monitoring warnings
• Debugging application flow
• Catching exceptions

---

get_console_message

Retrieve a specific console message by ID or index.

Parameters:

• messageId (required): The ID or index of the message
• pageId (optional): Specific page

Example:

Get specific message:
mcp__chrome-devtools__get_console_message
  messageId: msg-123

Get message from specific page:
mcp__chrome-devtools__get_console_message
  messageId: msg-456
  pageId: page-123

Returns: Detailed message object with:

• Full message text
• Stack trace (if error)
• Source location
• Arguments/parameters

Common use cases:

• Getting detailed error information
• Examining specific log entries
• Debugging specific console output

---

list_network_requests

View all network requests made by the page.

Parameters:

• pageId (optional): Specific page to get requests from
• filter (optional): Filter by URL pattern, method, or status

Example:

Get all requests:
mcp__chrome-devtools__list_network_requests

Get API requests only:
mcp__chrome-devtools__list_network_requests
  filter: "/api/"

Get failed requests:
mcp__chrome-devtools__list_network_requests
  filter: "status:4xx,5xx"

Get from specific page:
mcp__chrome-devtools__list_network_requests
  pageId: page-123

Returns: Array of network request objects with:

• requestId: Unique identifier
• url: Request URL
• method: HTTP method (GET, POST, etc.)
• status: Response status code
• statusText: Status message
• type: Resource type (xhr, fetch, script, stylesheet, image, etc.)
• timing: Performance timing data
• size: Response size

Common use cases:

• Debugging API calls
• Finding failed requests
• Analyzing network performance
• Verifying request/response data
• Tracking resource loading

---

get_network_request

Get detailed information about a specific network request.

Parameters:

• requestId (required): The ID of the request
• pageId (optional): Specific page

Example:

Get request details:
mcp__chrome-devtools__get_network_request
  requestId: req-123

Get from specific page:
mcp__chrome-devtools__get_network_request
  requestId: req-456
  pageId: page-123

Returns: Detailed request object with:

• Full request headers
• Request payload/body
• Response headers
• Response body
• Timing breakdown
• Cookies
• Security details

Common use cases:

• Inspecting request headers
• Viewing request/response payloads
• Debugging authentication issues
• Analyzing timing/performance
• Checking cookies and security

---

evaluate_script

Execute JavaScript code in the page context.

Parameters:

• script (required): JavaScript code to execute
• returnByValue (optional): Whether to return the result value
• pageId (optional): Specific page to execute on

Example:

Get page title:
mcp__chrome-devtools__evaluate_script
  script: "document.title"
  returnByValue: true

Execute function:
mcp__chrome-devtools__evaluate_script
  script: |
    function getFormData() {
      const form = document.querySelector('#myForm');
      return new FormData(form);
    }
    getFormData();
  returnByValue: true

Modify DOM:
mcp__chrome-devtools__evaluate_script
  script: |
    document.querySelector('#status').textContent = 'Ready';

Get computed styles:
mcp__chrome-devtools__evaluate_script
  script: |
    const el = document.querySelector('#target');
    window.getComputedStyle(el).backgroundColor;
  returnByValue: true

Check for errors:
mcp__chrome-devtools__evaluate_script
  script: |
    window.hasErrors = typeof window.onerror !== 'undefined';
    window.hasErrors;
  returnByValue: true

Common use cases:

• Querying DOM state
• Extracting data from the page
• Testing JavaScript functions
• Modifying page state
• Running diagnostic scripts
• Checking global variables

---

Debugging Workflows

Error Investigation Workflow

1. Check for console errors:
   mcp__chrome-devtools__list_console_messages
     types: ["error"]

2. Get detailed error info:
   mcp__chrome-devtools__get_console_message
     messageId: <error-id>

3. Check related network failures:
   mcp__chrome-devtools__list_network_requests
     filter: "status:4xx,5xx"

4. Execute diagnostic script:
   mcp__chrome-devtools__evaluate_script
     script: "console.log('Current state:', appState)"

API Debugging Workflow

1. Navigate to page:
   mcp__chrome-devtools__navigate_page
     url: https://app.example.com

2. Trigger API call (interact with page)

3. List all API requests:
   mcp__chrome-devtools__list_network_requests
     filter: "/api/"

4. Inspect failed request:
   mcp__chrome-devtools__get_network_request
     requestId: req-123

5. Verify request payload and headers

Performance Debugging Workflow

1. Start fresh navigation:
   mcp__chrome-devtools__navigate_page
     url: https://example.com

2. Wait for page load:
   mcp__chrome-devtools__wait_for
     condition: networkidle

3. Get all network requests:
   mcp__chrome-devtools__list_network_requests

4. Identify slow requests (sort by timing)

5. Get details of slow request:
   mcp__chrome-devtools__get_network_request
     requestId: slow-req-id

6. Analyze timing breakdown

State Inspection Workflow

1. Navigate to page:
   mcp__chrome-devtools__navigate_page
     url: https://app.example.com

2. Interact with application

3. Query application state:
   mcp__chrome-devtools__evaluate_script
     script: |
       JSON.stringify({
         user: window.currentUser,
         route: window.location.pathname,
         errors: window.errors || []
       })
     returnByValue: true

4. Check console for issues:
   mcp__chrome-devtools__list_console_messages

Form Validation Debugging

1. Fill form with test data:
   mcp__chrome-devtools__fill_form
     fields: {...}

2. Submit form:
   mcp__chrome-devtools__click
     selector: "button[type='submit']"

3. Check console for validation errors:
   mcp__chrome-devtools__list_console_messages
     types: ["error", "warn"]

4. Inspect form state:
   mcp__chrome-devtools__evaluate_script
     script: |
       const form = document.querySelector('form');
       ({
         isValid: form.checkValidity(),
         errors: [...form.querySelectorAll(':invalid')]
           .map(el => el.name)
       })
     returnByValue: true

---

Best Practices

1. Check console early and often - Errors appear as soon as they occur 2. Filter console messages - Focus on errors/warnings when debugging 3. Use evaluate_script for queries - Better than trying to parse HTML 4. Inspect network for API issues - Don't guess at network problems 5. Return values when executing scripts - Set returnByValue: true 6. Combine debugging tools - Console + network + scripts = complete picture 7. Clear console between tests - Navigate away to reset console state 8. Use try-catch in scripts - Handle potential errors in evaluated code

---

Common Patterns

Error Detection Pattern

list_console_messages(types: ["error"]) →
if errors exist → get_console_message → investigate

API Verification Pattern

trigger action → list_network_requests(filter: "/api/") →
verify status codes → get_network_request(failed) → debug

State Inspection Pattern

evaluate_script(query state) →
parse result →
verify expectations

Comprehensive Debug Pattern

check console → check network → execute diagnostic scripts →
take screenshot → report findings

---

Script Patterns

Query DOM Elements

// Find elements
document.querySelectorAll('.class-name').length

// Check visibility
document.querySelector('#element').offsetParent !== null

// Get text content
document.querySelector('#target').textContent

// Check attributes
document.querySelector('input').value

Extract Data

// Get all links
[...document.querySelectorAll('a')].map(a => ({
  href: a.href,
  text: a.textContent
}))

// Get form data
Object.fromEntries(new FormData(document.querySelector('form')))

// Get table data
[...document.querySelectorAll('table tr')].map(row =>
  [...row.querySelectorAll('td')].map(cell => cell.textContent)
)

Check Application State

// Global state
window.appState || window.__STATE__ || {}

// React DevTools
window.__REACT_DEVTOOLS_GLOBAL_HOOK__

// Vue DevTools
window.__VUE_DEVTOOLS_GLOBAL_HOOK__

// Check for errors
window.hasOwnProperty('onerror')

Performance Checks

// Check resource timing
performance.getEntriesByType('resource')
  .filter(r => r.duration > 1000)

// Check navigation timing
performance.getEntriesByType('navigation')[0]

// Memory usage (if available)
performance.memory

---

Network Request Filtering

By URL pattern:

filter: "/api/users"       // Contains this path
filter: "api"              // Contains "api"
filter: "*.jpg"            // Images

By status:

filter: "status:200"       // Successful
filter: "status:4xx"       // Client errors
filter: "status:5xx"       // Server errors
filter: "status:4xx,5xx"   // All errors

By method:

filter: "method:POST"
filter: "method:GET"
filter: "method:PUT,DELETE"

By type:

filter: "type:xhr"         // AJAX requests
filter: "type:fetch"       // Fetch API
filter: "type:script"      // JavaScript files
filter: "type:stylesheet"  // CSS files

---

Troubleshooting

No console messages:

• Check if page has actually loaded
• Verify console is not being cleared by page
• Try navigating again to reset state

Can't see network requests:

• Ensure requests happened after opening DevTools
• Try navigating to page with fresh start
• Check if requests are being filtered out

Script evaluation fails:

• Check for syntax errors in script
• Verify page context is correct
• Try simpler script first to test
• Use try-catch in script

Network request details incomplete:

• Some requests may not have response bodies
• Cached resources may have limited info
• CORS may block some details

State queries return unexpected results:

• Verify timing - state may change after query
• Check if application uses different state storage
• Try multiple approaches to access state

Chrome DevTools Emulation Reference

Simulate different devices, network conditions, CPU throttling, and viewport sizes to test responsive designs and performance under various constraints.

Available Tools

emulate

Simulate different device types, network conditions, and user agents.

Parameters:

• device (optional): Device preset name (e.g., "iPhone 13", "iPad Pro", "Galaxy S21")
• network (optional): Network condition preset ("offline", "slow-3g", "fast-3g", "4g")
• userAgent (optional): Custom user agent string
• viewport (optional): Viewport dimensions object {width, height, deviceScaleFactor, isMobile}
• geolocation (optional): GPS coordinates {latitude, longitude, accuracy}
• cpuThrottling (optional): CPU throttling multiplier (e.g., 4 = 4x slowdown)
• pageId (optional): Specific page to apply emulation to

Example:

Emulate iPhone 13:
mcp__chrome-devtools__emulate
  device: "iPhone 13"

Emulate slow network:
mcp__chrome-devtools__emulate
  network: "slow-3g"

Emulate custom device:
mcp__chrome-devtools__emulate
  viewport: {
    width: 375,
    height: 667,
    deviceScaleFactor: 2,
    isMobile: true
  }

Emulate slow CPU (4x slowdown):
mcp__chrome-devtools__emulate
  cpuThrottling: 4

Emulate location:
mcp__chrome-devtools__emulate
  geolocation: {
    latitude: 37.7749,
    longitude: -122.4194,
    accuracy: 100
  }

Combine emulations:
mcp__chrome-devtools__emulate
  device: "iPhone 13"
  network: "fast-3g"
  cpuThrottling: 2

Custom user agent:
mcp__chrome-devtools__emulate
  userAgent: "Mozilla/5.0 (custom bot)"

Device Presets:

• Mobile: "iPhone 13", "iPhone 13 Pro Max", "iPhone SE", "Pixel 5", "Pixel 7", "Galaxy S21", "Galaxy S20 Ultra"
• Tablet: "iPad", "iPad Pro 11", "iPad Pro 12.9", "Galaxy Tab S8"
• Desktop: "Laptop with touch", "Laptop with HiDPI", "Desktop 1080p", "Desktop 4K"

Network Presets:

• offline - No connectivity
• slow-3g - Slow 3G (400ms RTT, 400kbps down, 400kbps up)
• fast-3g - Fast 3G (150ms RTT, 1.6Mbps down, 750kbps up)
• 4g - 4G (50ms RTT, 4Mbps down, 3Mbps up)
• wifi - WiFi (10ms RTT, 30Mbps down, 15Mbps up)
• custom - Define custom latency/throughput

CPU Throttling:

• 1 - No throttling (default)
• 2 - 2x slowdown
• 4 - 4x slowdown (common for low-end mobile)
• 6 - 6x slowdown (very slow devices)

Common use cases:

• Testing mobile responsiveness
• Simulating slow networks
• Testing on low-end devices
• Geolocation-based features
• User agent detection
• Touch interface testing

---

resize_page

Adjust viewport dimensions without full device emulation.

Parameters:

• width (required): Viewport width in pixels
• height (required): Viewport height in pixels
• deviceScaleFactor (optional): Pixel density (default: 1)
• pageId (optional): Specific page to resize

Example:

Standard mobile size:
mcp__chrome-devtools__resize_page
  width: 375
  height: 667

Tablet size:
mcp__chrome-devtools__resize_page
  width: 768
  height: 1024

Desktop size:
mcp__chrome-devtools__resize_page
  width: 1920
  height: 1080

With retina density:
mcp__chrome-devtools__resize_page
  width: 375
  height: 667
  deviceScaleFactor: 2

Specific page:
mcp__chrome-devtools__resize_page
  width: 1024
  height: 768
  pageId: page-123

Common viewport sizes:

• Mobile portrait: 375x667, 360x640, 414x896
• Mobile landscape: 667x375, 896x414, 812x375
• Tablet portrait: 768x1024, 834x1194, 1024x1366
• Tablet landscape: 1024x768, 1194x834, 1366x1024
• Desktop: 1366x768, 1920x1080, 2560x1440

Common use cases:

• Testing responsive breakpoints
• Verifying layout at specific sizes
• Screenshot at exact dimensions
• Testing media queries
• Checking overflow behavior

---

Emulation Workflows

Mobile Testing Workflow

1. Emulate mobile device:
   mcp__chrome-devtools__emulate
     device: "iPhone 13"

2. Navigate to page:
   mcp__chrome-devtools__navigate_page
     url: https://example.com

3. Wait for load:
   mcp__chrome-devtools__wait_for
     condition: networkidle

4. Take screenshot:
   mcp__chrome-devtools__take_screenshot

5. Test interactions:
   mcp__chrome-devtools__click
     selector: "#mobile-menu"

Network Performance Testing

1. Set slow network:
   mcp__chrome-devtools__emulate
     network: "slow-3g"

2. Start performance trace:
   mcp__chrome-devtools__performance_start_trace
     url: https://example.com

3. Wait for load:
   mcp__chrome-devtools__wait_for
     condition: networkidle

4. Stop trace:
   mcp__chrome-devtools__performance_stop_trace

5. Analyze:
   mcp__chrome-devtools__performance_analyze_insight
     focus: "loading"

Responsive Design Testing

1. Test mobile:
   - resize_page(375, 667)
   - navigate, wait, screenshot

2. Test tablet:
   - resize_page(768, 1024)
   - navigate, wait, screenshot

3. Test desktop:
   - resize_page(1920, 1080)
   - navigate, wait, screenshot

4. Compare screenshots

Low-End Device Simulation

1. Emulate slow device:
   mcp__chrome-devtools__emulate
     device: "Pixel 5"
     network: "fast-3g"
     cpuThrottling: 4

2. Start trace:
   mcp__chrome-devtools__performance_start_trace
     url: https://app.example.com

3. Wait and interact:
   - wait_for(networkidle)
   - click, fill form, etc.

4. Stop trace:
   mcp__chrome-devtools__performance_stop_trace

5. Analyze interaction performance:
   mcp__chrome-devtools__performance_analyze_insight
     focus: "interaction"

Geolocation Testing

1. Set location (San Francisco):
   mcp__chrome-devtools__emulate
     geolocation: {
       latitude: 37.7749,
       longitude: -122.4194,
       accuracy: 100
     }

2. Navigate to location-aware page:
   mcp__chrome-devtools__navigate_page
     url: https://example.com/map

3. Verify location detection:
   mcp__chrome-devtools__evaluate_script
     script: |
       navigator.geolocation.getCurrentPosition(
         pos => pos.coords
       )
     returnByValue: true

Offline Testing

1. Set offline mode:
   mcp__chrome-devtools__emulate
     network: "offline"

2. Navigate (will fail):
   mcp__chrome-devtools__navigate_page
     url: https://example.com

3. Check error handling:
   mcp__chrome-devtools__list_console_messages
     types: ["error"]

4. Take screenshot of offline page

5. Go back online:
   mcp__chrome-devtools__emulate
     network: "wifi"

6. Verify recovery

---

Best Practices

1. Test multiple devices - Don't rely on single device emulation 2. Combine CPU and network throttling - Real-world conditions vary 3. Test both orientations - Portrait and landscape 4. Verify touch targets - Ensure clickable areas are large enough (44x44px min) 5. Test with slow networks - Don't assume fast connections 6. Check geolocation permissions - Handle denied permissions 7. Test offline scenarios - Verify graceful degradation 8. Use realistic user agents - Some sites serve different content 9. Test at common breakpoints - 375px, 768px, 1024px, 1920px 10. Verify device pixel ratio - Test retina and standard displays

---

Common Patterns

Multi-Device Testing Pattern

for device in ["iPhone 13", "iPad Pro", "Desktop 1080p"]:
  emulate(device) → navigate → screenshot → verify

Network Condition Testing Pattern

for network in ["slow-3g", "fast-3g", "4g"]:
  emulate(network) → start_trace → load page →
  stop_trace → analyze → record metrics

Breakpoint Testing Pattern

for width in [375, 768, 1024, 1920]:
  resize_page(width, height) → navigate →
  screenshot → verify layout

Progressive Enhancement Pattern

emulate(offline) → verify basic functionality →
emulate(slow-3g) → verify enhanced features →
emulate(wifi) → verify full experience

---

Responsive Breakpoints

Common CSS Breakpoints

/* Mobile */
@media (max-width: 767px) { }

/* Tablet */
@media (min-width: 768px) and (max-width: 1023px) { }

/* Desktop */
@media (min-width: 1024px) { }

/* Large Desktop */
@media (min-width: 1920px) { }

Test at These Widths

• 320px - Small mobile (iPhone SE)
• 375px - Standard mobile (iPhone 13)
• 414px - Large mobile (iPhone 13 Pro Max)
• 768px - Tablet portrait (iPad)
• 1024px - Tablet landscape / small laptop
• 1366px - Common laptop
• 1920px - Full HD desktop

---

Device Specifications

Popular Mobile Devices

iPhone 13:

• Viewport: 390x844
• DPR: 3
• User agent: iOS 15

iPhone 13 Pro Max:

• Viewport: 428x926
• DPR: 3
• User agent: iOS 15

iPhone SE:

• Viewport: 375x667
• DPR: 2
• User agent: iOS 15

Pixel 5:

• Viewport: 393x851
• DPR: 2.75
• User agent: Android 11

Galaxy S21:

• Viewport: 360x800
• DPR: 3
• User agent: Android 11

Tablets

iPad:

• Viewport: 768x1024 (portrait)
• DPR: 2
• User agent: iPadOS 15

iPad Pro 11:

• Viewport: 834x1194 (portrait)
• DPR: 2
• User agent: iPadOS 15

iPad Pro 12.9:

• Viewport: 1024x1366 (portrait)
• DPR: 2
• User agent: iPadOS 15

---

Network Conditions Details

Offline

• Use case: Testing offline functionality, service workers
• RTT: N/A
• Download: 0 kbps
• Upload: 0 kbps

Slow 3G

• Use case: Poor mobile coverage, developing regions
• RTT: 400ms
• Download: 400 kbps (50 KB/s)
• Upload: 400 kbps (50 KB/s)

Fast 3G

• Use case: Average mobile connection
• RTT: 150ms
• Download: 1.6 Mbps (200 KB/s)
• Upload: 750 kbps (94 KB/s)

4G

• Use case: Good mobile connection
• RTT: 50ms
• Download: 4 Mbps (500 KB/s)
• Upload: 3 Mbps (375 KB/s)

WiFi

• Use case: Typical home/office WiFi
• RTT: 10ms
• Download: 30 Mbps (3.75 MB/s)
• Upload: 15 Mbps (1.88 MB/s)

---

CPU Throttling Guide

1x (No Throttling)

• Desktop computers
• High-end laptops
• Flagship phones (recent year)

2x Throttling

• Mid-range laptops
• Older desktops
• Previous-gen flagship phones

4x Throttling

• Low-end laptops
• Budget phones
• Older devices (3+ years)
• Common testing baseline

6x Throttling

• Very old devices
• Budget phones (entry-level)
• Extreme testing scenario

---

Troubleshooting

Emulation doesn't seem to work:

• Verify emulation was set before navigation
• Check if site detects server-side (can't be emulated)
• Try refreshing page after setting emulation
• Ensure pageId is correct if specified

Network throttling not visible:

• Throttling applies to new requests only
• Clear cache to force new requests
• Verify using list_network_requests to check timing
• Check if site uses service worker (may cache)

Device emulation doesn't match real device:

• Browser emulation is approximate
• Test on real device for final verification
• Some features (GPU, sensors) can't be fully emulated
• JavaScript performance differs from real hardware

Geolocation not working:

• Check if page requests permission
• Verify geolocation API is used correctly
• Some sites may require HTTPS for geolocation
• Check browser console for permission errors

Touch events not working:

• Ensure device emulation sets isMobile: true
• Some sites detect touch differently
• Try actual device for touch-specific features
• Check if site uses pointer events vs touch events

Chrome DevTools Interaction Reference

Interact with page elements through clicks, keyboard input, form filling, drag operations, and file uploads.

Available Tools

click

Click on page elements.

Parameters:

• selector (required): CSS selector for the element to click
• button (optional): Which mouse button ("left", "right", "middle")
• clickCount (optional): Number of clicks (1, 2 for double-click)
• pageId (optional): Specific page to operate on

Example:

Single click:
mcp__chrome-devtools__click
  selector: "#submit-button"

Double click:
mcp__chrome-devtools__click
  selector: ".editable-field"
  clickCount: 2

Right click:
mcp__chrome-devtools__click
  selector: "#context-menu-trigger"
  button: right

Click on specific page:
mcp__chrome-devtools__click
  selector: "button[type='submit']"
  pageId: page-123

Common use cases:

• Submitting forms
• Opening dropdowns
• Triggering navigation
• Activating buttons
• Opening context menus

---

fill

Enter text into form fields.

Parameters:

• selector (required): CSS selector for the input field
• value (required): Text to enter
• pageId (optional): Specific page to operate on

Example:

Fill text input:
mcp__chrome-devtools__fill
  selector: "#username"
  value: "testuser@example.com"

Fill password:
mcp__chrome-devtools__fill
  selector: "input[type='password']"
  value: "SecurePass123"

Fill textarea:
mcp__chrome-devtools__fill
  selector: "#comment-box"
  value: "This is my feedback..."

Common use cases:

• Entering form data
• Filling login credentials
• Entering search queries
• Populating text areas

---

fill_form

Fill multiple form fields at once.

Parameters:

• fields (required): Object mapping selectors to values
• pageId (optional): Specific page to operate on

Example:

Fill entire login form:
mcp__chrome-devtools__fill_form
  fields: {
    "#username": "user@example.com",
    "#password": "SecurePass123",
    "#remember-me": "true"
  }

Fill registration form:
mcp__chrome-devtools__fill_form
  fields: {
    "input[name='firstName']": "John",
    "input[name='lastName']": "Doe",
    "input[name='email']": "john@example.com",
    "select[name='country']": "USA"
  }

Common use cases:

• Completing multi-field forms efficiently
• Registration flows
• Checkout processes
• Settings/preferences forms

---

press_key

Simulate keyboard input.

Parameters:

• key (required): Key to press (e.g., "Enter", "Tab", "Escape", "a", "ArrowDown")
• modifiers (optional): Array of modifier keys (["Control"], ["Shift"], ["Meta"])
• pageId (optional): Specific page to operate on

Example:

Press Enter:
mcp__chrome-devtools__press_key
  key: Enter

Press Tab:
mcp__chrome-devtools__press_key
  key: Tab

Ctrl+A (select all):
mcp__chrome-devtools__press_key
  key: a
  modifiers: ["Control"]

Cmd+V (paste on Mac):
mcp__chrome-devtools__press_key
  key: v
  modifiers: ["Meta"]

Arrow navigation:
mcp__chrome-devtools__press_key
  key: ArrowDown

Common key names:

• Special: Enter, Tab, Escape, Backspace, Delete
• Arrows: ArrowUp, ArrowDown, ArrowLeft, ArrowRight
• Modifiers: Control, Shift, Alt, Meta (Cmd on Mac)
• Function: F1 through F12
• Letters/numbers: Use the character directly

Common use cases:

• Submitting forms (Enter)
• Navigating fields (Tab)
• Keyboard shortcuts
• Dismissing dialogs (Escape)
• Dropdown navigation (Arrow keys)

---

hover

Move the mouse cursor over elements.

Parameters:

• selector (required): CSS selector for the element to hover over
• pageId (optional): Specific page to operate on

Example:

Hover over menu item:
mcp__chrome-devtools__hover
  selector: "#dropdown-trigger"

Hover to reveal tooltip:
mcp__chrome-devtools__hover
  selector: ".info-icon"

Hover over navigation:
mcp__chrome-devtools__hover
  selector: "nav .menu-item"

Common use cases:

• Revealing dropdowns
• Triggering tooltips
• Activating hover effects
• Testing interactive states
• Revealing hidden menus

---

drag

Perform drag and drop operations.

Parameters:

• sourceSelector (required): Element to drag from
• targetSelector (required): Element to drag to
• pageId (optional): Specific page to operate on

Example:

Drag file to upload zone:
mcp__chrome-devtools__drag
  sourceSelector: "#file-item"
  targetSelector: "#drop-zone"

Reorder list items:
mcp__chrome-devtools__drag
  sourceSelector: ".list-item:nth-child(1)"
  targetSelector: ".list-item:nth-child(3)"

Drag to trash:
mcp__chrome-devtools__drag
  sourceSelector: "#document-123"
  targetSelector: "#trash-bin"

Common use cases:

• File uploads via drag-drop
• Reordering lists
• Kanban board operations
• Interactive games/puzzles
• Visual editors

---

upload_file

Handle file upload inputs.

Parameters:

• selector (required): CSS selector for file input
• filePath (required): Absolute path to file to upload
• pageId (optional): Specific page to operate on

Example:

Upload single file:
mcp__chrome-devtools__upload_file
  selector: "input[type='file']"
  filePath: "/Users/john/documents/report.pdf"

Upload to specific input:
mcp__chrome-devtools__upload_file
  selector: "#profile-picture"
  filePath: "/Users/john/pictures/avatar.jpg"

Common use cases:

• Uploading documents
• Changing profile pictures
• Attaching files to forms
• Bulk file uploads
• Image uploads

---

handle_dialog

Respond to browser dialogs (alerts, confirms, prompts).

Parameters:

• action (required): "accept" or "dismiss"
• promptText (optional): Text to enter in prompt dialogs
• pageId (optional): Specific page to operate on

Example:

Accept alert:
mcp__chrome-devtools__handle_dialog
  action: accept

Dismiss confirmation:
mcp__chrome-devtools__handle_dialog
  action: dismiss

Respond to prompt:
mcp__chrome-devtools__handle_dialog
  action: accept
  promptText: "My response"

Common use cases:

• Accepting confirmations
• Dismissing alerts
• Responding to prompts
• Handling before-unload dialogs

---

Interaction Workflows

Form Submission Workflow

1. Fill form fields:
   mcp__chrome-devtools__fill_form
     fields: {
       "#email": "user@example.com",
       "#password": "pass123"
     }

2. Submit form:
   mcp__chrome-devtools__click
     selector: "button[type='submit']"

3. Wait for navigation/response:
   mcp__chrome-devtools__wait_for
     condition: networkidle

4. Verify success:
   mcp__chrome-devtools__take_screenshot

Search Workflow

1. Focus search field:
   mcp__chrome-devtools__click
     selector: "#search-input"

2. Enter search term:
   mcp__chrome-devtools__fill
     selector: "#search-input"
     value: "test query"

3. Submit search:
   mcp__chrome-devtools__press_key
     key: Enter

4. Wait for results:
   mcp__chrome-devtools__wait_for
     condition: ".search-results"

Dropdown Navigation Workflow

1. Hover over menu:
   mcp__chrome-devtools__hover
     selector: "#main-menu"

2. Wait for dropdown:
   mcp__chrome-devtools__wait_for
     condition: "#dropdown-menu"

3. Click submenu item:
   mcp__chrome-devtools__click
     selector: "#dropdown-menu a[href='/settings']"

File Upload Workflow

1. Navigate to upload page:
   mcp__chrome-devtools__navigate_page
     url: https://example.com/upload

2. Upload file:
   mcp__chrome-devtools__upload_file
     selector: "input[type='file']"
     filePath: "/path/to/file.pdf"

3. Wait for upload processing:
   mcp__chrome-devtools__wait_for
     condition: ".upload-success"

4. Verify upload:
   mcp__chrome-devtools__take_screenshot

Keyboard Navigation Workflow

1. Press Tab to navigate:
   mcp__chrome-devtools__press_key
     key: Tab

2. Select option with Enter:
   mcp__chrome-devtools__press_key
     key: Enter

3. Navigate dropdown with arrows:
   mcp__chrome-devtools__press_key
     key: ArrowDown

---

Best Practices

1. Wait before interacting - Ensure elements are ready before clicking/filling 2. Use specific selectors - Avoid ambiguous selectors that match multiple elements 3. Verify element visibility - Elements must be visible and clickable 4. Handle dynamic content - Wait for AJAX/dynamic content to load 5. Use fill_form for efficiency - Batch form fills instead of multiple fill calls 6. Clear fields before filling - Some fields may have default values 7. Handle dialogs promptly - Dialogs can block other operations 8. Test selectors first - Verify selectors match expected elements

---

Common Patterns

Safe Click Pattern

wait_for(selector) → click(selector) → wait_for(result)

Form Fill Pattern

fill_form → click(submit) → wait_for(networkidle) → verify

Keyboard Shortcut Pattern

press_key(key, modifiers) → wait_for(result)

Hover-Click Pattern

hover(trigger) → wait_for(menu) → click(item)

---

Selector Tips

Good selectors:

• #unique-id - IDs are best (unique)
• [data-testid='submit'] - Test IDs are reliable
• button[type='submit'] - Specific attributes
• .form-group input[name='email'] - Scoped selectors

Avoid:

• .btn - Too generic
• div:nth-child(5) - Fragile to DOM changes
• body > div > div > span - Overly specific path
• Relying on text content (use data attributes instead)

---

Troubleshooting

Element not found:

• Verify selector is correct
• Wait for element to appear in DOM
• Check if element is in iframe
• Use list_console_messages for JS errors

Click doesn't work:

• Ensure element is visible and clickable
• Check for overlaying elements
• Wait for page to be fully loaded
• Try scrolling element into view first

Fill doesn't work:

• Verify input is not disabled
• Check for readonly attribute
• Ensure field accepts text input
• Try clicking field first to focus

Upload fails:

• Verify file path is absolute and correct
• Check file exists and is readable
• Ensure selector targets file input
• Verify input accepts the file type

Dialog not handled:

• Set up handler before triggering action
• Check if dialog actually appears
• Verify action type (accept vs dismiss)
• Test with simple alert first

Chrome DevTools Navigation Reference

Control browser navigation, manage tabs, and handle page lifecycle events.

Available Tools

navigate_page

Navigate the browser to a specific URL.

Parameters:

• url (required): The URL to navigate to
• pageId (optional): Specific page/tab ID to navigate

Example:

Navigate to homepage:
mcp__chrome-devtools__navigate_page
  url: https://example.com

Navigate specific tab:
mcp__chrome-devtools__navigate_page
  url: https://example.com/login
  pageId: page-123

Common use cases:

• Opening websites for testing
• Navigating to specific app routes
• Refreshing pages (navigate to current URL)

---

new_page

Create a new browser tab.

Parameters:

• url (optional): URL to open in the new tab

Example:

Create blank tab:
mcp__chrome-devtools__new_page

Create tab with URL:
mcp__chrome-devtools__new_page
  url: https://example.com

Common use cases:

• Opening multiple pages for comparison
• Isolating test scenarios
• Parallel page operations

---

close_page

Close a browser tab.

Parameters:

• pageId (required): The ID of the page/tab to close

Example:

Close specific tab:
mcp__chrome-devtools__close_page
  pageId: page-123

Common use cases:

• Cleaning up after tests
• Managing browser resources
• Closing completed workflows

---

list_pages

List all open browser tabs/pages.

Parameters: None

Example:

Get all open pages:
mcp__chrome-devtools__list_pages

Returns: Array of page objects with:

• pageId: Unique identifier
• url: Current URL
• title: Page title

Common use cases:

• Finding specific tabs
• Checking what's open
• Getting page IDs for other operations

---

select_page

Switch focus to a specific tab.

Parameters:

• pageId (required): The ID of the page/tab to select

Example:

Switch to specific tab:
mcp__chrome-devtools__select_page
  pageId: page-123

Common use cases:

• Switching between test scenarios
• Focusing on specific page for operations
• Multi-tab workflows

---

wait_for

Wait for specific conditions before proceeding.

Parameters:

• condition (required): What to wait for (e.g., "networkidle", "load", selector)
• timeout (optional): Max wait time in milliseconds
• pageId (optional): Specific page to wait on

Example:

Wait for page load:
mcp__chrome-devtools__wait_for
  condition: load

Wait for network idle:
mcp__chrome-devtools__wait_for
  condition: networkidle

Wait for element:
mcp__chrome-devtools__wait_for
  condition: "#login-button"
  timeout: 5000

Wait for specific page:
mcp__chrome-devtools__wait_for
  condition: load
  pageId: page-123

Condition types:

• load - Wait for page load event
• networkidle - Wait until network is idle
• domcontentloaded - Wait for DOM ready
• CSS selector - Wait for element to appear

Common use cases:

• Ensuring page readiness before interaction
• Waiting for dynamic content
• Synchronizing test steps
• Handling slow-loading pages

---

Navigation Workflows

Basic Page Navigation

1. Navigate to URL:
   mcp__chrome-devtools__navigate_page
     url: https://example.com

2. Wait for page ready:
   mcp__chrome-devtools__wait_for
     condition: networkidle

3. Proceed with operations...

Multi-Tab Workflow

1. List current tabs:
   mcp__chrome-devtools__list_pages

2. Create new tab:
   mcp__chrome-devtools__new_page
     url: https://example.com/page2

3. Switch between tabs:
   mcp__chrome-devtools__select_page
     pageId: page-123

4. Close when done:
   mcp__chrome-devtools__close_page
     pageId: page-123

Progressive Web App Navigation

1. Navigate to app:
   mcp__chrome-devtools__navigate_page
     url: https://app.example.com

2. Wait for app shell:
   mcp__chrome-devtools__wait_for
     condition: "#app-root"

3. Wait for data load:
   mcp__chrome-devtools__wait_for
     condition: networkidle

4. Proceed with testing...

Handling Slow Pages

1. Navigate with explicit wait:
   mcp__chrome-devtools__navigate_page
     url: https://slow-site.example.com

2. Wait with timeout:
   mcp__chrome-devtools__wait_for
     condition: load
     timeout: 30000

3. Verify loaded:
   mcp__chrome-devtools__list_console_messages
   (check for errors)

---

Best Practices

1. Always wait after navigation - Use wait_for to ensure page readiness 2. Use networkidle for SPAs - Single-page apps need network idle, not just load 3. Handle timeouts gracefully - Set appropriate timeout values 4. Clean up tabs - Close pages when done to free resources 5. Check console after navigation - Verify no critical errors 6. Use specific selectors for waiting - Wait for actual content, not just load event

---

Common Patterns

Safe Navigation Pattern

navigate_page → wait_for(networkidle) → verify success

Tab Management Pattern

list_pages → identify target → select_page → operate → close_page

Refresh Pattern

Get current URL → navigate_page(same URL) → wait_for

Multi-Step Navigation Pattern

navigate_page(URL1) → wait_for → interact →
navigate_page(URL2) → wait_for → verify

---

Troubleshooting

Page won't load:

• Increase timeout in wait_for
• Check network connectivity
• Verify URL is accessible
• Check console for errors

Wait times out:

• Use more specific wait conditions
• Check if element selector is correct
• Try networkidle instead of specific selector
• Verify page actually loads the expected content

Can't find page ID:

• Use list_pages to get current page IDs
• Ensure page wasn't closed
• Check if new_page succeeded

Navigation doesn't complete:

• Check for redirects
• Verify no JavaScript errors blocking load
• Try waiting for specific element instead of load event

Chrome DevTools Performance Reference

Record and analyze performance traces to identify bottlenecks, measure page load times, and get actionable optimization insights.

Available Tools

performance_start_trace

Begin recording a performance trace.

Parameters:

• url (optional): URL to navigate to and trace (starts fresh trace)
• categories (optional): Trace categories to capture (default: all relevant)
• pageId (optional): Specific page to trace

Example:

Start trace on current page:
mcp__chrome-devtools__performance_start_trace

Start trace with navigation:
mcp__chrome-devtools__performance_start_trace
  url: https://example.com

Start trace with specific categories:
mcp__chrome-devtools__performance_start_trace
  categories: ["loading", "scripting", "rendering"]

Start trace on specific page:
mcp__chrome-devtools__performance_start_trace
  pageId: page-123

Trace categories:

• loading - Page and resource loading
• scripting - JavaScript execution
• rendering - Layout, paint, composite
• painting - Paint operations
• gpu - GPU activity
• network - Network activity
• devtools.timeline - Full timeline
• v8.execute - Detailed V8 execution

Common use cases:

• Measuring page load performance
• Profiling user interactions
• Finding rendering bottlenecks
• Analyzing JavaScript execution
• Identifying layout thrashing

---

performance_stop_trace

Stop the current performance trace and save the data.

Parameters:

• pageId (optional): Specific page to stop trace on

Example:

Stop current trace:
mcp__chrome-devtools__performance_stop_trace

Stop trace on specific page:
mcp__chrome-devtools__performance_stop_trace
  pageId: page-123

Returns: Trace data including:

• Timeline events
• Frame metrics
• Network timing
• JavaScript execution
• Rendering metrics
• Memory usage

Common use cases:

• Completing trace after page load
• Finishing trace after user interaction
• Capturing specific time window

---

performance_analyze_insight

Analyze a completed trace and get actionable performance recommendations.

Parameters:

• traceData (optional): Trace data to analyze (uses last trace if not provided)
• focus (optional): What to focus on ("loading", "interaction", "rendering", "all")

Example:

Analyze last trace:
mcp__chrome-devtools__performance_analyze_insight

Analyze with focus on loading:
mcp__chrome-devtools__performance_analyze_insight
  focus: "loading"

Analyze interaction performance:
mcp__chrome-devtools__performance_analyze_insight
  focus: "interaction"

Analyze rendering performance:
mcp__chrome-devtools__performance_analyze_insight
  focus: "rendering"

Returns: Performance insights including:

• Metrics: Core Web Vitals (LCP, FID, CLS), TTI, FCP, etc.
• Issues: Specific problems found (long tasks, layout shifts, etc.)
• Recommendations: Actionable fixes with priority
• Opportunities: Potential optimizations with estimated impact
• Resource breakdown: Time spent by category

Focus areas:

• loading - Initial page load, resource timing, FCP, LCP
• interaction - Responsiveness, FID, long tasks, blocking time
• rendering - Paint, layout, CLS, reflows
• all - Comprehensive analysis

Common use cases:

• Getting optimization priorities
• Understanding performance bottlenecks
• Finding Core Web Vitals issues
• Identifying render-blocking resources
• Discovering long tasks

---

Performance Workflows

Basic Performance Analysis

1. Start tracing:
   mcp__chrome-devtools__performance_start_trace
     url: https://example.com

2. Wait for page load:
   mcp__chrome-devtools__wait_for
     condition: networkidle

3. Stop tracing:
   mcp__chrome-devtools__performance_stop_trace

4. Get insights:
   mcp__chrome-devtools__performance_analyze_insight

Interaction Performance Testing

1. Navigate to page:
   mcp__chrome-devtools__navigate_page
     url: https://app.example.com

2. Wait for ready:
   mcp__chrome-devtools__wait_for
     condition: networkidle

3. Start trace:
   mcp__chrome-devtools__performance_start_trace

4. Perform interaction:
   mcp__chrome-devtools__click
     selector: "#heavy-operation-button"

5. Wait for completion:
   mcp__chrome-devtools__wait_for
     condition: "#result"

6. Stop trace:
   mcp__chrome-devtools__performance_stop_trace

7. Analyze interaction performance:
   mcp__chrome-devtools__performance_analyze_insight
     focus: "interaction"

Page Load Optimization

1. Start trace with URL:
   mcp__chrome-devtools__performance_start_trace
     url: https://example.com

2. Wait for load:
   mcp__chrome-devtools__wait_for
     condition: networkidle

3. Stop trace:
   mcp__chrome-devtools__performance_stop_trace

4. Get loading insights:
   mcp__chrome-devtools__performance_analyze_insight
     focus: "loading"

5. Implement recommendations

6. Re-test to measure improvement

Rendering Performance Analysis

1. Navigate to page:
   mcp__chrome-devtools__navigate_page
     url: https://app.example.com

2. Start trace:
   mcp__chrome-devtools__performance_start_trace

3. Trigger animation/scroll:
   mcp__chrome-devtools__evaluate_script
     script: "window.scrollTo(0, document.body.scrollHeight)"

4. Wait a bit:
   mcp__chrome-devtools__wait_for
     condition: networkidle

5. Stop trace:
   mcp__chrome-devtools__performance_stop_trace

6. Analyze rendering:
   mcp__chrome-devtools__performance_analyze_insight
     focus: "rendering"

Before/After Comparison

1. Baseline test:
   - Start trace with URL
   - Wait for complete load
   - Stop trace
   - Analyze and save results

2. Make optimizations

3. Comparison test:
   - Start trace with URL
   - Wait for complete load
   - Stop trace
   - Analyze and compare metrics

---

Performance Metrics

Core Web Vitals

LCP (Largest Contentful Paint):

• Good: < 2.5s
• Needs improvement: 2.5s - 4.0s
• Poor: > 4.0s
• Measures: Loading performance

FID (First Input Delay):

• Good: < 100ms
• Needs improvement: 100ms - 300ms
• Poor: > 300ms
• Measures: Interactivity

CLS (Cumulative Layout Shift):

• Good: < 0.1
• Needs improvement: 0.1 - 0.25
• Poor: > 0.25
• Measures: Visual stability

Other Important Metrics

FCP (First Contentful Paint):

• Good: < 1.8s
• Measures: When first content appears

TTI (Time to Interactive):

• Good: < 3.8s
• Measures: When page becomes fully interactive

TBT (Total Blocking Time):

• Good: < 200ms
• Measures: Sum of long task blocking time

Speed Index:

• Good: < 3.4s
• Measures: How quickly content is visually displayed

---

Best Practices

1. Test with realistic conditions - Use network/CPU throttling 2. Multiple test runs - Performance varies, test 3-5 times 3. Test on real devices - Mobile performance often differs 4. Focus on user journey - Trace critical user paths 5. Set performance budgets - Define acceptable metric targets 6. Test after changes - Verify optimizations work 7. Use appropriate focus - Target specific performance aspects 8. Clear cache between tests - Test first-time visitor experience

---

Common Patterns

Complete Performance Audit Pattern

start_trace(url) → wait(networkidle) → stop_trace →
analyze_insight(all) → review recommendations

Interaction Testing Pattern

navigate → wait → start_trace →
interact → wait → stop_trace →
analyze_insight(interaction)

Optimization Verification Pattern

baseline test → analyze → implement fixes →
new test → compare metrics → verify improvement

---

Trace Categories Explained

loading:

• Resource loading events
• Parse HTML/CSS
• Network requests
• Cache hits/misses

scripting:

• JavaScript execution
• Function calls
• Garbage collection
• V8 compilation

rendering:

• Layout calculations
• Paint operations
• Compositing
• Layer creation

painting:

• Paint rectangles
• Rasterization
• GPU upload

network:

• Request/response timing
• Connection setup
• Data transfer

---

Performance Issues & Solutions

Long Tasks (> 50ms)

Problem: JavaScript blocking main thread Solutions:

• Code splitting
• Web Workers
• Async/defer scripts
• Reduce JavaScript payload

Layout Thrashing

Problem: Forced synchronous layouts Solutions:

• Batch DOM reads/writes
• Use requestAnimationFrame
• Avoid layout-triggering properties in loops

Large Largest Contentful Paint

Problem: Critical resources load slowly Solutions:

• Optimize images
• Preload critical resources
• Remove render-blocking resources
• Use CDN

High Cumulative Layout Shift

Problem: Elements shifting during load Solutions:

• Set image dimensions
• Reserve space for ads/embeds
• Avoid inserting content above existing content
• Use transform for animations

Slow First Input Delay

Problem: Page not responsive to input Solutions:

• Break up long tasks
• Defer non-critical JavaScript
• Use web workers
• Optimize event handlers

---

Reading Trace Results

Timeline Events

• Frame: Visual frame rendered
• Task: Main thread work
• Animation: Animation frame
• Event: User input event
• Paint: Paint operation
• Layout: Layout calculation
• Compile: JavaScript compilation
• Evaluate: JavaScript execution

Performance Markers

• FCP: First paint with content
• LCP: Largest element painted
• TTI: Page becomes interactive
• Long Task: Task > 50ms

Resource Types

• Document: HTML page
• Script: JavaScript files
• Stylesheet: CSS files
• Image: Images
• Font: Web fonts
• XHR/Fetch: API requests

---

Troubleshooting

Trace doesn't capture expected events:

• Ensure correct categories are enabled
• Check if trace duration was long enough
• Verify page actually performed the action

Metrics seem inaccurate:

• Run multiple tests for consistency
• Check network conditions
• Verify page loaded completely
• Clear cache if testing fresh load

Analysis shows no issues but page feels slow:

• Test on slower devices/networks
• Check for issues not covered by metrics
• Test different user flows
• Monitor real user metrics (RUM)

Can't reproduce performance issue:

• Check if issue is device/network specific
• Test with different browser profiles
• Clear cache and cookies
• Check for race conditions

Chrome DevTools Visual Testing Reference

Capture screenshots and DOM snapshots for visual verification, regression testing, and documentation.

Available Tools

take_screenshot

Capture a visual screenshot of the current page.

Parameters:

• fullPage (optional): Capture entire scrollable page (default: false)
• selector (optional): Capture only specific element
• clipArea (optional): Capture specific rectangle {x, y, width, height}
• omitBackground (optional): Transparent background (default: false)
• quality (optional): JPEG quality 0-100 (default: 80)
• format (optional): Image format ("png" or "jpeg", default: "png")
• pageId (optional): Specific page to capture

Example:

Capture viewport:
mcp__chrome-devtools__take_screenshot

Capture full page:
mcp__chrome-devtools__take_screenshot
  fullPage: true

Capture specific element:
mcp__chrome-devtools__take_screenshot
  selector: "#main-content"

Capture specific area:
mcp__chrome-devtools__take_screenshot
  clipArea: {
    x: 0,
    y: 0,
    width: 800,
    height: 600
  }

High quality JPEG:
mcp__chrome-devtools__take_screenshot
  format: "jpeg"
  quality: 95

Transparent background:
mcp__chrome-devtools__take_screenshot
  selector: ".logo"
  omitBackground: true

Specific page:
mcp__chrome-devtools__take_screenshot
  fullPage: true
  pageId: page-123

Returns:

• Base64-encoded image data
• Image dimensions
• Format information

Common use cases:

• Visual regression testing
• Documenting UI states
• Capturing error states
• Creating thumbnails
• Generating reports
• Verifying responsive layouts
• Recording test results

---

take_snapshot

Capture a DOM snapshot (HTML structure and state).

Parameters:

• selector (optional): Capture DOM for specific element
• depth (optional): How many levels deep to capture (default: all)
• includeStyles (optional): Include computed styles (default: false)
• includeEventListeners (optional): Include event listener info (default: false)
• pageId (optional): Specific page to snapshot

Example:

Capture full DOM:
mcp__chrome-devtools__take_snapshot

Capture specific element:
mcp__chrome-devtools__take_snapshot
  selector: "#app"

Shallow snapshot:
mcp__chrome-devtools__take_snapshot
  selector: ".container"
  depth: 2

Include computed styles:
mcp__chrome-devtools__take_snapshot
  selector: "#styled-component"
  includeStyles: true

Include event listeners:
mcp__chrome-devtools__take_snapshot
  selector: "#interactive-form"
  includeEventListeners: true

Complete snapshot:
mcp__chrome-devtools__take_snapshot
  includeStyles: true
  includeEventListeners: true

Returns:

• DOM tree structure
• Element attributes
• Text content
• Computed styles (if requested)
• Event listeners (if requested)

Common use cases:

• Debugging DOM issues
• Analyzing element structure
• Comparing DOM states
• Documenting element hierarchy
• Verifying dynamic content
• Checking accessibility tree
• Debugging event handlers

---

Visual Testing Workflows

Basic Screenshot Workflow

1. Navigate to page:
   mcp__chrome-devtools__navigate_page
     url: https://example.com

2. Wait for content:
   mcp__chrome-devtools__wait_for
     condition: networkidle

3. Take screenshot:
   mcp__chrome-devtools__take_screenshot
     fullPage: true

4. Save/compare screenshot

Element-Specific Screenshot

1. Navigate and wait:
   navigate → wait

2. Capture specific element:
   mcp__chrome-devtools__take_screenshot
     selector: "#product-card"

3. Use for component testing

Responsive Visual Testing

1. For each viewport size:
   mcp__chrome-devtools__resize_page
     width: <width>
     height: <height>

2. Navigate:
   mcp__chrome-devtools__navigate_page
     url: https://example.com

3. Wait:
   mcp__chrome-devtools__wait_for
     condition: networkidle

4. Screenshot:
   mcp__chrome-devtools__take_screenshot

5. Compare across sizes

Mobile Device Screenshots

1. Emulate device:
   mcp__chrome-devtools__emulate
     device: "iPhone 13"

2. Navigate:
   mcp__chrome-devtools__navigate_page
     url: https://example.com

3. Wait:
   mcp__chrome-devtools__wait_for
     condition: networkidle

4. Screenshot:
   mcp__chrome-devtools__take_screenshot

5. Repeat for other devices

Error State Capture

1. Navigate to page:
   navigate → wait

2. Trigger error:
   mcp__chrome-devtools__click
     selector: "#trigger-error"

3. Wait for error display:
   mcp__chrome-devtools__wait_for
     condition: ".error-message"

4. Capture error:
   mcp__chrome-devtools__take_screenshot

5. Capture error logs:
   mcp__chrome-devtools__list_console_messages
     types: ["error"]

Form State Capture

1. Navigate to form:
   navigate → wait

2. Fill form:
   mcp__chrome-devtools__fill_form
     fields: {...}

3. Take filled state screenshot:
   mcp__chrome-devtools__take_screenshot
     selector: "form"

4. Submit:
   mcp__chrome-devtools__click
     selector: "button[type='submit']"

5. Take success/error screenshot:
   mcp__chrome-devtools__take_screenshot

DOM Comparison Workflow

1. Navigate to page:
   navigate → wait

2. Capture initial DOM:
   mcp__chrome-devtools__take_snapshot
     selector: "#dynamic-content"

3. Perform action:
   mcp__chrome-devtools__click
     selector: "#load-more"

4. Wait for update:
   wait_for(condition)

5. Capture updated DOM:
   mcp__chrome-devtools__take_snapshot
     selector: "#dynamic-content"

6. Compare snapshots

Interactive State Documentation

1. Capture default state:
   take_screenshot(selector: "#component")

2. Trigger hover state:
   mcp__chrome-devtools__hover
     selector: "#component"

3. Capture hover state:
   take_screenshot(selector: "#component")

4. Trigger active state:
   click → screenshot

5. Document all states

---

Best Practices

1. Wait before screenshots - Ensure content is fully loaded 2. Use fullPage for layout testing - Captures entire scroll area 3. Use selector for components - Focus on specific UI elements 4. Consistent viewport sizes - For comparison screenshots 5. Clear backgrounds - Use omitBackground for logos/icons 6. High quality for documentation - Use quality: 95+ for JPEGs 7. PNG for UI elements - Better for text and sharp edges 8. JPEG for photos - Smaller file size 9. Wait after interactions - Animations need to complete 10. Capture error states - Document failure scenarios

---

Common Patterns

Visual Regression Testing Pattern

baseline: screenshot → save
test: screenshot → compare with baseline → report differences

Multi-State Component Pattern

for state in [default, hover, active, disabled]:
  set state → screenshot → document

Responsive Screenshots Pattern

for size in breakpoints:
  resize → navigate → wait → screenshot → save

Before/After Pattern

screenshot(before) → make changes → screenshot(after) → compare

---

Screenshot Configuration

Format Selection

PNG (default):

• Lossless compression
• Best for: UI elements, text, diagrams
• Supports transparency
• Larger file size

JPEG:

• Lossy compression
• Best for: Photos, complex images
• Smaller file size
• No transparency
• Use quality: 80-95

Quality Settings

Low (60-70):

• Very small files
• Visible compression artifacts
• Use for: Previews, thumbnails

Medium (80-85):

• Good balance
• Minimal artifacts
• Use for: Most screenshots

High (90-95):

• Excellent quality
• Larger files
• Use for: Documentation, archival

Maximum (100):

• No compression loss
• Very large files
• Use for: Critical comparisons

---

Capture Strategies

Full Page Capture

Best for:
- Landing pages
- Marketing pages
- Documentation
- Portfolio sites

Considerations:
- Large file sizes
- Long render time
- May miss lazy-loaded content

Viewport Capture

Best for:
- Above-fold content
- Quick previews
- Fast testing
- Consistent sizing

Considerations:
- Misses below-fold content
- Faster rendering
- Smaller files

Element Capture

Best for:
- Component testing
- Specific UI elements
- Focused comparisons
- Documentation

Considerations:
- Requires stable selectors
- May need scroll-into-view
- Precise targeting

Clipped Area Capture

Best for:
- Specific regions
- Cropped screenshots
- Exact dimensions
- Banner/header images

Considerations:
- Exact pixel coordinates needed
- Absolute positioning
- No auto-sizing

---

DOM Snapshot Use Cases

Debugging Dynamic Content

Capture before/after DOM states to identify:
- Elements added/removed
- Attribute changes
- Class modifications
- Structure changes

Event Listener Debugging

Include event listeners to:
- Find duplicate listeners
- Identify missing handlers
- Debug event propagation
- Document interactions

Style Debugging

Include computed styles to:
- Check CSS application
- Debug specificity issues
- Verify responsive styles
- Document visual states

Accessibility Analysis

Use DOM snapshots to:
- Verify ARIA attributes
- Check semantic HTML
- Validate keyboard navigation
- Document focus order

---

Troubleshooting

Screenshot is blank:

• Wait for page load (use wait_for)
• Check if content is hidden
• Verify page navigation completed
• Check console for errors

Element not captured:

• Verify selector is correct
• Ensure element is visible
• Check if element needs scroll
• Wait for dynamic content

Screenshot cut off:

• Use fullPage: true for full capture
• Check viewport height
• Verify page scroll height
• Wait for lazy-loaded content

Colors look different:

• Check browser color profile
• Verify CSS is loaded
• Check for theme/dark mode
• Compare formats (PNG vs JPEG)

Large file sizes:

• Use JPEG with quality: 80
• Reduce capture area
• Optimize image dimensions
• Use selector instead of fullPage

Snapshot missing content:

• Increase depth parameter
• Wait for dynamic content
• Check shadow DOM elements
• Verify iframe content

Transparent areas not working:

• Use PNG format
• Set omitBackground: true
• Verify background is actually transparent
• Check parent container backgrounds