Web Inspector MCP

Give LLMs visual superpowers to see, debug, and test any web page.

A Model Context Protocol (MCP) server that provides comprehensive web inspection and debugging capabilities. Built on Playwright, it enables AI assistants to deeply understand web page structure, debug element visibility issues, validate layouts, and inspect DOM in real browser environments.

Why Web Inspector MCP?

Modern web applications are complex. Elements are hidden, layouts break, selectors fail, and debugging feels like detective work. Web Inspector MCP gives your AI assistant the tools to:

• Understand any page structure - Progressive DOM inspection that drills through wrapper divs to find semantic elements
• Debug visibility issues - Detailed diagnostics showing exactly why clicks fail (clipped, covered, scrolled out of view)
• Trace layout constraints - Walk up the DOM tree to find where unexpected margins, width limits, and overflow clipping come from
• Validate layouts - Compare element positions to ensure consistent alignment and spacing
• Test selector reliability - See all matching elements with their visibility status before writing tests
• Inspect styles - Get computed CSS to understand why elements behave unexpectedly
• Find elements without IDs - Locate elements by text content when test IDs aren't available

Perfect For

• QA Engineers - Debug failing automated tests and understand why selectors break
• Frontend Developers - Investigate layout issues and CSS problems across browsers
• Test Automation - Build robust selectors and validate page structure before writing tests
• Accessibility Audits - Inspect ARIA roles, semantic HTML, and element visibility
• Web Scraping - Understand page structure and find the right selectors for data extraction

Installation

No manual installation required! Your AI coding assistant will automatically install the server via npx when configured.

If you prefer global installation for faster startup:

npm install -g mcp-web-inspector

---

AI Tool Setup

All configurations below use npx which automatically downloads and runs the latest version. Click to expand installation instructions for your AI tool:

Installation via CLI

# Add the server globally
codex mcp add web-inspector -- npx -y mcp-web-inspector

# Verify it was registered
codex mcp list

Manual Configuration

Codex stores MCP server definitions in ~/.codex/config.toml. Add (or create) an entry under the [mcp.servers] table:

[mcp.servers.web-inspector]
command = "npx"
args = ["-y", "mcp-web-inspector"]

Restart Codex CLI to make sure the new server is available in future sessions.

Installation via CLI

# Add MCP server using Claude Code CLI
claude mcp add web-inspector --scope user -- npx -y mcp-web-inspector

# Verify installation
claude mcp list

Manual Configuration

Edit ~/.config/claude/mcp.json (Linux/macOS) or %APPDATA%\Claude\mcp.json (Windows):

{
  "mcpServers": {
    "web-inspector": {
      "command": "npx",
      "args": ["-y", "mcp-web-inspector"]
    }
  }
}

After installation, restart Claude Code to load the server.

Configuration File Location

• MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Add to Configuration

{
  "mcpServers": {
    "web-inspector": {
      "command": "npx",
      "args": ["-y", "mcp-web-inspector"]
    }
  }
}

Restart Claude Desktop after saving the configuration.

Prerequisites

• VS Code version 1.101 or later
• GitHub Copilot extension installed

Installation via CLI

# VS Code Stable
code --add-mcp '{"name":"web-inspector","command":"npx","args":["-y","mcp-web-inspector"]}'

# VS Code Insiders
code-insiders --add-mcp '{"name":"web-inspector","command":"npx","args":["-y","mcp-web-inspector"]}'

Manual Configuration

1. Open VS Code Settings (JSON)
2. Add MCP server configuration to mcp.json:

{
  "servers": {
    "web-inspector": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-web-inspector"]
    }
  }
}

Enable MCP in VS Code

1. Open VS Code Settings (UI)
2. Search for "MCP"
3. Enable Chat > MCP option
4. MCP only works in Agent mode - switch to agent mode in the chat interface
5. Open the mcp.json file and click the "Start" button next to the server

First-Time Browser Setup

When you first use the server with npx, Playwright browsers will be automatically installed on first tool use if not already present. The installation happens once and browsers are stored in your home directory, shared across all projects.

If automatic installation doesn't work (firewall, permissions, etc.), you'll see clear instructions to run:

npx playwright install chromium firefox webkit

Then restart VS Code to use the server.

Note about Embedded Browser

GitHub Copilot and VS Code may have an embedded browser feature. If you experience conflicts or prefer using Web Inspector MCP for all web inspection tasks, you may want to disable the built-in browser:

1. Open VS Code Settings
2. Search for "browser preview" or "simple browser"
3. Disable relevant browser-related extensions if needed

Web Inspector MCP provides more powerful inspection capabilities than the embedded browser.

Configuration File Location

• MacOS/Linux: ~/.cursor/mcp.json or check Cursor's settings directory
• Windows: %APPDATA%\Cursor\mcp.json

Add to Configuration

{
  "mcpServers": {
    "web-inspector": {
      "command": "npx",
      "args": ["-y", "mcp-web-inspector"]
    }
  }
}

Steps

1. Open Cursor Settings (Cmd/Ctrl + ,)
2. Search for "MCP" settings
3. Edit the MCP configuration file
4. Add the web-inspector server configuration
5. Restart Cursor
6. Verify the server is available in the MCP panel

Configuration

Windsurf uses the same configuration format as Claude Desktop. You can literally copy your Claude Desktop config!

Configuration File: Check Windsurf's settings for the exact path (typically in app data directory)

{
  "mcpServers": {
    "web-inspector": {
      "command": "npx",
      "args": ["-y", "mcp-web-inspector"]
    }
  }
}

Steps

1. Open Windsurf settings
2. Navigate to MCP configuration
3. Add the web-inspector server
4. Restart Windsurf
5. Verify server availability in the tools panel

Windsurf handles MCP tools very well - configuration is straightforward!

Prerequisites

• VS Code with Cline extension installed
• Node.js installed on your system

Configuration

1. Open Cline's settings in VS Code
2. Locate the MCP configuration section
3. Add the server configuration:

{
  "mcpServers": {
    "web-inspector": {
      "command": "npx",
      "args": ["-y", "mcp-web-inspector"]
    }
  }
}

1. Restart VS Code or reload the Cline extension
2. The Web Inspector MCP tools will be available in Cline's tool panel

Most MCP-compatible tools use a similar configuration format. Look for:

1. MCP settings or configuration file
2. Server/Tools configuration section
3. Add the standard configuration:

{
  "mcpServers": {
    "web-inspector": {
      "command": "npx",
      "args": ["-y", "mcp-web-inspector"]
    }
  }
}

CLI-first assistants such as GitHub Copilot CLI, Copylot CLI, Continue CLI, and other emerging AI coders follow the same patterneither run their mcp add command with npx -y mcp-web-inspector or drop the snippet above into their MCP config file.

If your tool supports MCP but isn't listed here, consult its documentation for the exact configuration file location.

---

Command Line Options

Customize server behavior with command line flags:

• --no-save-session - Disable automatic session persistence (start with fresh browser state each time)
• --user-data-dir <path> - Custom directory for session data (default: ./.mcp-web-inspector)
• --headless - Run browser in headless mode by default (no visible window)
• --expose-sensitive-network-data - Loosen redaction for sensitive network headers (e.g., show truncated auth/cookie values). Disabled by default for safety.

Example usage:

{
  "mcpServers": {
    "web-inspector": {
      "command": "npx",
      "args": ["-y", "mcp-web-inspector", "--user-data-dir", "./my-sessions"]
    }
  }
}

Run in headless mode for automation/CI:

{
  "mcpServers": {
    "web-inspector": {
      "command": "npx",
      "args": ["-y", "mcp-web-inspector", "--headless"]
    }
  }
}

Combine multiple flags:

{
  "mcpServers": {
    "web-inspector": {
      "command": "npx",
      "args": ["-y", "mcp-web-inspector", "--headless", "--no-save-session", "--user-data-dir", "./.mcp-web-inspector"]
    }
  }
}

---

Session Persistence & Data Storage

By default, browser session data and screenshots are automatically saved and organized in ./.mcp-web-inspector/:

.mcp-web-inspector/
   user-data/       # Browser sessions (cookies, localStorage, sessionStorage)
   screenshots/     # Screenshot files

How It Works

• Session data persists across browser restarts
• Screenshots are saved to the screenshots directory
• Browser maintains logged-in state between sessions
• Works out of the box - just navigate and your data is saved

Benefits

• Test authenticated features without re-logging in each time
• Maintain shopping cart state across sessions
• Preserve user preferences and settings
• Debug logged-in user workflows efficiently

Disabling Session Persistence

If you prefer the browser to start fresh each time (no persistent state), use the --no-save-session flag:

Claude Code CLI:

claude mcp add web-inspector --scope user -- npx -y mcp-web-inspector --no-save-session

Claude Desktop / Windsurf / Cline:

{
  "mcpServers": {
    "web-inspector": {
      "command": "npx",
      "args": ["-y", "mcp-web-inspector", "--no-save-session"]
    }
  }
}

Cursor:

{
  "mcpServers": {
    "web-inspector": {
      "command": "npx",
      "args": ["-y", "mcp-web-inspector", "--no-save-session"],
      "env": {}
    }
  }
}

Clearing Data

To clear all saved data (sessions and screenshots):

rm -rf ./.mcp-web-inspector

To clear only sessions or screenshots:

rm -rf ./.mcp-web-inspector/user-data      # Clear sessions only
rm -rf ./.mcp-web-inspector/screenshots    # Clear screenshots only

Security Best Practices

** IMPORTANT**: Add .mcp-web-inspector/ to your .gitignore file to prevent committing:

• Browser session data (cookies, localStorage, sessionStorage)
• Saved screenshots (may contain sensitive information)
• Authentication tokens and credentials

Add to your .gitignore:

# MCP Web Inspector data
.mcp-web-inspector/

Why this matters:

• Session data contains cookies and authentication tokens
• Screenshots may capture sensitive user data
• Committing this data could leak credentials to your repository
• Session files can be large and bloat your git history

Best practices:

• Default is visible browser (headless: false) for interactive debugging
• Use headless: true explicitly for automation and CI/CD environments
• Clear session data after testing sensitive applications
• Use --no-save-session flag when testing on shared/public sites

---

Core Tools

Inspection

inspect_dom

PRIMARY INSPECTION TOOL - START HERE FOR LAYOUT DEBUGGING: Progressive DOM inspection that shows parent-child relationships, centering issues, spacing gaps, and scrollable containers. Skips wrapper divs and shows only semantic elements (header, nav, main, form, button, elements with test IDs, ARIA roles, etc.).

WORKFLOW: Call without selector for page overview, then drill down by calling with child's selector.

DETECTS: Scrollable containers (shows "scrollable 36px" when scrollHeight > clientHeight), parent-relative positioning, vertical/horizontal centering, sibling spacing gaps, layout patterns.

OUTPUT FORMAT:

[0] <button data-testid="menu">
    @ (16,8) 4040px                          Absolute viewport position (x,y) and size
    from edges: 16px 1144px 8px 8px       Distance from parent edges (8px = 8px means vertically centered)
    "Menu"
     visible,  interactive

[1] <div data-testid="title">
    @ (260,2) 13128px
    from edges: 244px 244px 2px 42px      Equal left/right (244px) = horizontally centered, unequal top/bottom = NOT vertically centered
    gap from [0]: 16px                       Spacing between siblings
    "Title"
     visible, 2 children

SYMBOLS: =visible, =hidden, =interactive, =horizontal edges, =vertical edges, =vertical scroll, =horizontal scroll
CENTERING: Equal left/right distances = horizontally centered, equal top/bottom = vertically centered
SCROLL DETECTION: Automatically detects scrollable containers and shows overflow amount (e.g., "scrollable 397px" means 397px of hidden content). No need to use evaluate() to compare scrollHeight/clientHeight.

RELATED TOOLS: For comparing TWO elements' alignment (not parent-child), use compare_element_alignment(). For box model (padding/margin), use measure_element().

More efficient than get_html() or evaluate() for structural analysis. Use BEFORE visual tools (screenshot) or evaluate(). Supports testid shortcuts.

• Parameters:

  • selector (string, optional): CSS selector, text selector, or testid shorthand to inspect. Omit for page overview (defaults to body). Use 'testid:login-form', '#main', etc.
  • includeHidden (boolean, optional): Include hidden elements in results (default: false)
  • maxChildren (number, optional): Maximum number of children to show (default: 20)
  • maxDepth (number, optional): Maximum depth to drill through non-semantic wrapper elements when looking for semantic children (default: 5). Increase for extremely deeply nested components, decrease to 1 to see only immediate children without drilling.

• Output Format:

  • Optional selection header when multiple matches (with chosen index).
  • For each listed element:
    • Indexed tag with best identifier (testid/ID/classes).
    • Position line: @ (x,y) widthheight px.
    • from edges: left/right/top/bottom distances; centering hints.
    • gap from [prev]: spacing between siblings when applicable.
    • Text snippet in quotes (trimmed).
    • Status: visible / hidden, interactive, N children.
    • Scrollable markers / with overflow amount when detected.

• Examples:

• inspect_dom({})

• inspect_dom({ selector: 'testid:menu' })

• inspect_dom({ selector: '#content', maxChildren: 10 })

• Example Output (inspect_dom({})):

[0] <header data-testid="site-header">
    @ (0,0) 128064px
    from edges: 0px 0px 0px 1216px
    "My App"
     visible, 3 children

[1] <main id="content">
    @ (0,64) 1280640px
    from edges: 0px 0px 64px 512px
    "Welcome back"
     visible, 5 children, scrollable  320px

• Example Output (inspect_dom({ selector: 'testid:menu' })):

[0] <button data-testid="menu">
    @ (16,8) 4040px
    from edges: 16px 1224px 8px 16px
    "Menu"
     visible,  interactive

inspect_ancestors

DEBUG LAYOUT CONSTRAINTS: Walk up the DOM tree to find where width constraints, margins, borders, and overflow clipping come from. Shows for each ancestor: position/size, width constraints (w, max-w, min-w), margins with directional arrows ( format), padding, display type, borders (directional if non-uniform), overflow (=hidden, =scroll), flexbox context (flex direction justify items gap), grid context (cols rows gap), position/z-index/transform when set. Automatically detects horizontal centering via auto margins and flags clipping points (). Essential for debugging unexpected centering, constrained width, or clipped content. Default: 10 ancestors (reaches in most React apps), max: 15. Use after inspect_dom() to understand parent layout constraints.

• Parameters:

  • selector (string, required): CSS selector or testid shorthand for the element to start from (e.g., 'testid:header', '#main')
  • limit (number, optional): Maximum number of ancestors to traverse (default: 10, max: 15). Increase for deeply nested component frameworks.

• Output Format:

  • Header showing selected element index when selector matched multiple.
  • For each ancestor (starting from target):
    • [i] | testid:... or classes
    • @ (x,y) widthheight px
    • Inline summary: w, display (if not block), m/p, max-w, min-w
    • Flexbox/Grid context when present (direction, gap, grid templates)
    • Margin breakdown with arrows () and centering diagnostics
    • Border details when set (directional if non-uniform)
    • Overflow state: hidden, / scroll + overflow amount
    • Extra: position/z-index/transform when non-default
    • Diagnostics: CLIPPING POINT / SCROLLABLE CONTAINER / WIDTH CONSTRAINT

• Examples:

• inspect_ancestors({ selector: 'testid:submit-button' })

• inspect_ancestors({ selector: '#content', limit: 15 })

• Example Output (inspect_ancestors({ selector: 'testid:submit-button' })):

Selected: testid:submit-button (1 of 2 matches)

Ancestor Chain:

[0] <button> | testid:submit-button
    @ (860,540) 120x40px | w:120px display:inline-block
    margin: 0px 0px 0px 0px
    border: 1px solid rgb(0, 122, 255)
     none

[1] <div> | form-actions
    @ (800,520) 240x80px | w:240px display:flex m:0px p:16px gap:8px
    flex: row, justify:center, align:center, gap:8px
    margin: auto auto  Horizontally centered (likely margin:0 auto)
    border: none
    overflow:  hidden
     CLIPPING POINT - May clip overflowing children

[2] <form> | #login-form
    @ (640,200) 560x480px | w:560px max-w:600px
    position:relative
     WIDTH CONSTRAINT

compare_element_alignment

COMPARE TWO ELEMENTS: Get comprehensive alignment and dimension comparison in one call. Shows edge alignment (top, left, right, bottom), center alignment (horizontal, vertical), and dimensions (width, height). Perfect for debugging 'are these headers aligned?' or 'do these panels match?'. Returns all alignment info with / symbols and pixel differences. For parent-child centering, use inspect_dom() instead (automatically shows if children are centered in parent). More efficient than evaluate() with manual getBoundingClientRect() calculations.

• Parameters:

  • selector1 (string, required): CSS selector, text selector, or testid shorthand for the first element (e.g., 'testid:main-header', '#header')
  • selector2 (string, required): CSS selector, text selector, or testid shorthand for the second element (e.g., 'testid:chat-header', '#secondary-header')

• Output Format:

  • Optional warnings when a selector matched multiple elements (uses first visible; suggests adding unique data-testid).
  • Header: Alignment: vs
  • Two lines with each element's position and size: @ (x,y) wh px
  • Edges block: Top/Left/Right/Bottom with / and diffs
  • Centers block: Horizontal/Vertical center alignment with / and diffs
  • Dimensions block: Width/Height same or different with / and diffs
  • Optional hint to run inspect_ancestors(...) when large misalignment detected

• Examples:

• compare_element_alignment({ selector1: 'testid:header-title', selector2: 'testid:subtitle' })

• compare_element_alignment({ selector1: '#left-panel', selector2: '#right-panel' })

• Example Output (compare_element_alignment({ selector1: '#left-panel', selector2: '#right-panel' })):

Alignment: <div #left-panel> vs <div #right-panel>
  #left-panel: @ (80,120) 320600px
  #right-panel: @ (440,120) 320600px

Edges:
  Top:     aligned (both @ 120px)
  Left:    not aligned (80px vs 440px, diff: 360px)
  Right:   not aligned (400px vs 760px, diff: 360px)
  Bottom:  aligned (both @ 720px)

Centers:
  Horizontal:  not aligned (240px vs 600px, diff: 360px)
  Vertical:    aligned (both @ 420px)

Dimensions:
  Width:   same (320px)
  Height:  same (600px)

get_computed_styles

INSPECT CSS PROPERTIES: Get computed CSS values for specific properties (display, position, width, etc.). Use when you need raw CSS values or specific properties not shown by measure_element(). Returns styles grouped by category (Layout, Visibility, Spacing, Typography). For box model visualization (padding/margin), use measure_element() instead.

• Parameters:

  • selector (string, required): CSS selector, text selector, or testid shorthand (e.g., 'testid:submit-button', '#main')
  • properties (string, optional): Comma-separated list of CSS properties to retrieve (e.g., 'display,width,color'). If not specified, returns common layout properties: display, position, width, height, opacity, visibility, z-index, overflow, margin, padding, font-size, font-weight, color, background-color

• Output Format:

  • Optional selection header when multiple elements matched.
  • Header: 'Computed Styles: <tag id/class/testid>'
  • One or more sections: Layout, Visibility, Spacing, Typography, Other
  • Each section lists 'property: value' lines for requested properties

• Examples:

• get_computed_styles({ selector: 'testid:login-form' })

• get_computed_styles({ selector: '#hero', properties: 'display,width,color' })

• Example Output (get_computed_styles({ selector: 'testid:login-form' })):

 Found 2 elements matching "testid:login-form", using element 1 (first visible)
 Tip: Consider adding a unique data-testid attribute for more reliable selection.
   Primary fix: add data-testid and target it (e.g., testid:submit).
   Workaround: use '>> nth=<index>' only when you can't add test IDs.

Computed Styles: <form data-testid="login-form">

Layout:
  display: block
  position: static
  width: 560px
  height: 480px

Visibility:
  opacity: 1
  visibility: visible
  z-index: auto
  overflow: visible

Spacing:
  margin: 0px
  padding: 24px

Typography:
  font-size: 16px
  font-weight: 400
  color: rgb(33, 37, 41)

check_visibility

Check if an element is visible to the user. CRITICAL for debugging click/interaction failures. Returns detailed visibility information including viewport intersection, clipping by overflow:hidden, and whether element needs scrolling. Supports testid shortcuts (e.g., 'testid:submit-button').

• Parameters:

  • selector (string, required): CSS selector, text selector, or testid shorthand (e.g., 'testid:login-button', '#submit', 'text=Click here')

• Output Format:

  • Header: Visibility: <tag id/class/testid>
  • Status line: visible/ hidden, / in viewport with % visible
  • CSS: opacity, display, visibility
  • Optional interactability issues: disabled, readonly, aria-disabled, pointer-events:none
  • Optional Issues block: clipped by parent overflow, covered by element (with descriptor and ~coverage%), needs scroll
  • Optional Suggestions: scroll_to_element, modal/overlay hint, interaction state note
  • Optional tip to run inspect_ancestors when clipping is detected

• Examples:

• check_visibility({ selector: 'testid:submit' })

• check_visibility({ selector: '#login button' })

• Example Output (check_visibility({ selector: 'testid:submit' })):

Visibility: <button data-testid="submit">

 visible,  in viewport
opacity: 1, display: inline-block, visibility: visible

• Example Output (check_visibility({ selector: '#hero-cta' })):

Visibility: <a #hero-cta>

 hidden,  not in viewport (45% visible)
opacity: 1, display: block, visibility: visible

Issues:
   covered by another element (~60% covered)
    Covering: <div .modal-backdrop> (z-index: 9999)
   needs scroll to bring into view

 Call scroll_to_element before clicking
 Element may be behind modal, overlay, or fixed header

query_selector

Test a selector and return detailed information about all matched elements. Essential for selector debugging and finding the right element to interact with. Returns compact text format with element tag, position, text content, visibility status, and interaction capability. Shows why elements are hidden (display:none, opacity:0, zero size). Supports testid shortcuts (e.g., 'testid:submit-button'). Use limit parameter to control how many matches to show (default: 10). NEW: Use onlyVisible parameter to filter results (true=visible only, false=hidden only, undefined=all).

• Parameters:

  • selector (string, required): CSS selector, text selector, or testid shorthand to test (e.g., 'button.submit', 'testid:login-form', 'text=Sign In')
  • limit (number, optional): Maximum number of elements to return detailed info for (default: 10, recommended max: 50)
  • onlyVisible (boolean, optional): Filter results by visibility: true = show only visible elements, false = show only hidden elements, undefined/not specified = show all elements (default: undefined)
  • showAttributes (string, optional): Comma-separated list of HTML attributes to display for each element (e.g., 'id,name,aria-label,href,type'). If not specified, attributes are not shown.

• Output Format:

  • Header showing total matches (and filtered visible/hidden counts if requested).
  • For each match (up to limit):
    • Index with element tag and identifier (testid/id/class).
    • Position line: @ (x,y) widthxheight px.
    • Optional trimmed text content in quotes.
    • Optional listed attributes if requested.
    • Status line: visible or hidden with reason (display:none, opacity:0, zero size); interactive when applicable.
  • Footer with how many are shown vs omitted and a tip to increase limit.

• Examples:

• query_selector({ selector: 'a', limit: 3 })

• query_selector({ selector: 'testid:submit', onlyVisible: true, showAttributes: 'href,aria-label' })

• Example Output (query_selector({ selector: 'a', limit: 2 })):

Found 5 elements matching "a":

[0] <a #home-link>
    @ (16,12) 80x20px
    "Home"
    href: "/"
     visible,  interactive

[1] <a class="nav-item">
    @ (104,12) 120x20px
    "Products"
     visible,  interactive

Showing 2 of 5 matches (3 omitted)
Use limit parameter to show more: { selector: "a", limit: 5 }

get_test_ids

Discover all test identifiers on the page (data-testid, data-test, data-cy, etc.). Returns a compact text list grouped by attribute type. Essential for test-driven workflows and understanding what elements can be reliably selected. Use the returned test IDs with selector shortcuts like 'testid:submit-button'.

• Parameters:

  • attributes (string, optional): Comma-separated list of test ID attributes to search for (default: 'data-testid,data-test,data-cy')
  • showAll (boolean, optional): If true, display all test IDs without truncation. If false (default), shows first 8 test IDs per attribute with a summary for longer lists.

• Output Format:

  • 'Found N test IDs' header or 'Found 0 test IDs' with tips
  • For each attribute group: attribute name with count and a compact comma-separated list (or truncated with '... and X more')
  • Optional duplicate warnings: attribute:value appears N times
  • Suggestion block with best practices and usage tip for selector shortcuts

• Examples:

• get_test_ids({})

• get_test_ids({ showAll: true })

• get_test_ids({ attributes: 'data-testid,data-cy' })

• Example Output (get_test_ids({})):

Found 5 test IDs:

data-testid (3):
  submit, email-input, password-input

data-cy (2):
  navbar, footer

 Tip: Use these test IDs with selector shortcuts:
   testid:submit  [data-testid="submit"]

• Example Output (get_test_ids({ showAll: false })):

Found 14 test IDs:

data-testid (12):
  submit, email-input, password-input, remember-me, login-form, link-register, link-forgot, header-title,
  ... and 4 more
   Use showAll: true to see all 12 test IDs

data-cy (2):
  navbar, footer

measure_element

MEASUREMENT TOOL - DEBUG SPACING ISSUES: See padding, margin, border, and dimension measurements in visual box model format. Use when elements have unexpected spacing or size. Returns compact visual representation showing content padding border margin with directional arrows (24px for top margin, etc.). Also provides raw dimensions useful for scroll detection (clientHeight vs content height). For parent-child centering issues, use inspect_dom() first (shows if child is centered in parent). For comparing alignment between two elements, use compare_element_alignment(). For quick scroll detection, use inspect_dom() instead (shows 'scrollable '). More readable than get_computed_styles() or evaluate() for box model debugging.

• Parameters:

  • selector (string, required): CSS selector or testid shorthand (e.g., 'testid:submit', '#login-button')

• Output Format:

  • Header: Element: <tag id/class/testid>
  • Position/size line: @ (x,y) widthxheight px
  • Box Model section: Content size, Padding (with directional arrows), Border (with arrows or shorthand), Margin (with arrows)
  • Total Space line: totalWidthxtotalHeight px (with margin)
  • Optional suggestion to run inspect_ancestors when unusual spacing detected

• Examples:

• measure_element({ selector: 'testid:card' })

• measure_element({ selector: '#hero' })

• Example Output (measure_element({ selector: 'testid:card' })):

Element: <div data-testid="card">
@ (240,320) 360x240px

Box Model:
  Content: 328x208px
  Padding: 16px 16px 8px 8px
  Border:  none
  Margin:  0px 24px 0px 0px

Total Space: 360x264px (with margin)

find_by_text

Find elements by their text content. Essential for finding elements without good selectors, especially in poorly structured DOM. Returns elements with position, visibility, and interaction state. Supports exact match, case-sensitive search, and NEW: regex pattern matching for advanced text searching (e.g., '/\d+ items?/' to find elements with numbers).

• Parameters:

  • text (string, required): Text to search for in elements. If regex=true, this can be a regex pattern in /pattern/flags format (e.g., '/\d+/i' for case-insensitive numbers) or a raw pattern string.
  • exact (boolean, optional): Whether to match text exactly (default: false, allows partial matches). Ignored if regex=true.
  • caseSensitive (boolean, optional): Whether search should be case-sensitive (default: false). Ignored if regex=true (use regex flags instead).
  • regex (boolean, optional): Whether to treat 'text' as a regex pattern (default: false). If true, supports /pattern/flags format or raw pattern. Examples: '/sign.*/i' (case-insensitive), '/\d+ items?/' (numbers + optional 's').
  • limit (number, optional): Maximum number of elements to return (default: 10)

• Output Format:

  • Header showing 'No elements found ...' or 'Found N elements ...'
  • Up to limit results, each with:
    • <tag id/class/testid ...> line with key attributes
    • Position line: @ (x,y) widthxheight px
    • Trimmed text content (if any)
    • Visibility and interactability status
  • Footer shows how many are displayed vs omitted and how to increase limit

• Examples:

• find_by_text({ text: 'Sign in' })

• find_by_text({ text: '/^Next \d+$/', regex: true })

• find_by_text({ text: 'Delete', exact: true, caseSensitive: true })

• Example Output (find_by_text({ text: 'Sign in' })):

Found 3 elements containing "Sign in":

[0] <button data-testid="primary-cta">
    @ (640,420) 120x40px
    "Sign in"
     visible

[1] <a class="link" href="/signin">
    @ (600,480) 68x20px
    "Sign in"
     visible,  interactive

[2] <div class="menu-item">
    @ (40,360) 200x24px
    "Sign in"
     hidden

Showing all 3 matches

element_exists

Quick check if an element exists on the page. Ultra-lightweight alternative to query_selector_all when you only need existence confirmation. Returns simple exists/not found status. Most common check before attempting interaction. Supports testid shortcuts.

• Parameters:

  • selector (string, required): CSS selector, text selector, or testid shorthand (e.g., 'testid:submit-button', '#main')

• Output Format:

  • Returns one line:
    • exists: <ta