browser-interaction

Browser automation via MCP tools (chrome-devtools or playwright).

Prerequisites

Load browser MCP tools before any interaction:

ToolSearch query: "+chrome-devtools list pages snapshot navigate screenshot"

If chrome-devtools unavailable, fall back to playwright:

ToolSearch query: "+playwright browser snapshot navigate"

Tool Mapping

| Action | Chrome DevTools | Playwright | |--------|-----------------|------------| | List pages | list_pages | browser_tabs | | Navigate | navigate_page | browser_navigate | | Click | click | browser_click | | Fill | fill | browser_type | | Screenshot | take_screenshot | browser_take_screenshot | | Snapshot | take_snapshot | browser_snapshot | | Wait | wait_for | browser_wait_for |

RULE 0: Fresh Snapshot Before Interaction

Every browser interaction follows this loop:

Navigate → Fresh Snapshot → Interact (using uid) → Verify
         ↑                                        │
         └────────────────────────────────────────┘

Element refs (uid="1_5") regenerate per snapshot. Old refs match DIFFERENT elements after navigation.

# WRONG: uid reused after navigation
take_snapshot()            # uid="1_42" → Save button
navigate_page(url="/foo")
click(uid="1_42")          # uid "1_42" may now match an unrelated element

# RIGHT: fresh snapshot after every navigation
navigate_page(url="/foo")
take_snapshot()            # fresh uids
click(uid=<new>)

Navigate:

mcp__chrome-devtools__navigate_page(type: "url", url: "http://localhost:8080/wp-admin/", timeout: 30000)

Snapshot → Interact:

mcp__chrome-devtools__take_snapshot()
mcp__chrome-devtools__click(uid: "1_42", includeSnapshot: true)
mcp__chrome-devtools__fill(uid: "1_15", value: "test@example.com")

Verify (see RULE 1 for screenshot selection):

mcp__chrome-devtools__take_screenshot(uid: "3_272")

RULE 1: Token-Efficient Interaction

Choose the cheapest tool for your goal:

| Goal | Tool | Typical tokens | |------|------|----------------| | Interact (click/fill/read) | Snapshot | ~50-500 (simple pages) | | Visual check (layout/styling) | Screenshot with uid | ~300-1,300 | | Full page context (last resort) | Screenshot (no uid) | ~1,500-1,900 |

Target elements, not full viewport. Use the uid parameter on take_screenshot to capture only the relevant section. On WP admin pages, target <main> to skip the sidebar (~250 nav elements).

Warning: On heavy-navigation pages (WP admin, WooCommerce), snapshots can exceed screenshot costs because the a11y tree includes every sidebar/toolbar link. Prefer element-targeted screenshots for visual checks on these pages.

Image token cost = (width × height) / 750. Format, compression, and color depth have zero effect.

Capability Patterns

Common capabilities composed from the base tools. Each follows RULE 0 (fresh snapshot before interaction).

| Capability | Reach for when... | |---|---| | Viewport / device emulation | Walking breakpoints | | Theme switching | Verifying every theme in scope | | Network throttling | Exercising loading states | | Request blocking | Exercising error states | | Accessibility scan | Auditing per surface against the WCAG bar | | Keyboard navigation | Verifying every affordance reachable and operable by keyboard | | Scroll | Verifying behavior at scrollY > 0 (sticky, chrome falling off, infinite-scroll triggers) | | Focus tracking | Verifying focus return after modal close, dropdown collapse, async completion | | Multi-perspective sign-in | Evaluating role-distinct or visibility-distinct experiences | | Console + network log inspection | Surfacing findings the visible UI doesn't show |

Viewport / device emulation

| Tool | Call | |---|---| | Chrome DevTools | emulate({ width, height, deviceScaleFactor, isMobile, hasTouch }) for full emulation; resize_page({ width, height }) for plain resize | | Playwright | browser_resize({ width, height }) |

Emulation also sets user-agent and touch-event behavior; resize only changes dimensions. Use emulation for mobile testing where touch/UA matter; resize for desktop sizing. Verify with a fresh snapshot.

Common breakpoints: 375 / 768 / 1280 / 1920 (mobile / tablet / desktop / wide).

Theme switching

Three patterns, in order of preference:

1. UI toggle — click the product's theme button. Most authentic; tests the actual user path.
2. Class injection — evaluate_script / browser_evaluate toggling a class on <html> or <body>:

   document.documentElement.classList.toggle('dark')
   

3. prefers-color-scheme emulation (Chrome DevTools only): emulate({ prefersColorScheme: 'dark' }).

Pick the pattern that matches how the product implements theming. Verify the switch took effect by querying getComputedStyle(document.body).backgroundColor (or another theme-keyed property) via evaluate_script / browser_evaluate, or by a fresh snapshot showing the changed theme.

Network throttling

Three approaches, in order of fidelity:

1. Chrome DevTools emulate with network conditions (if your build exposes them) — check parameter schema; Slow-3G ≈ 400 ms latency, 400 kbps down/up.
2. CDP via evaluate_script — Network.emulateNetworkConditions through the debugger (requires chrome.debugger permission in the inspected context).
3. Fetch wrapper with artificial delay (universal fallback, works under either MCP):

   (() => {
     const DELAY_MS = 2000;
     const orig = window.fetch;
     window.fetch = (...args) => new Promise(r =>
       setTimeout(() => orig(...args).then(r), DELAY_MS));
   })()
   

   Run via evaluate_script / browser_evaluate. Less authentic (latency only, no bandwidth simulation) but reliable.

Request blocking

To force error states for a specific endpoint, install a fetch override in the page context:

(() => {
  const orig = window.fetch;
  window.fetch = (url, opts) =>
    url.toString().includes('TARGET_URL')
      ? Promise.resolve(new Response('{"error":"forced"}', { status: 500 }))
      : orig(url, opts);
})()

Run via evaluate_script (Chrome DevTools) or browser_evaluate (Playwright). For XHR-based requests, override XMLHttpRequest.prototype.open similarly. Replace TARGET_URL with the substring identifying the endpoint to block.

Accessibility scan

take_snapshot / browser_snapshot returns the a11y tree as part of the snapshot — basic audit surface. For deeper audits:

• Lighthouse (Chrome DevTools): lighthouse_audit includes accessibility scoring.
• axe-core (either tool): inject the script via evaluate_script / browser_evaluate and read axe.run()'s violations report.

When flagging, cite the specific WCAG success criterion (e.g., 1.4.3 Contrast (Minimum), 2.1.1 Keyboard).

Keyboard navigation

| Action | Chrome DevTools | Playwright | |---|---|---| | Single key | press_key({ key: 'Tab' }) | browser_press_key({ key: 'Tab' }) | | Modifier + key | Pass shift / alt / ctrl / meta per the tool's schema | Same |

Common sequences (extend the principle: each affordance type implies a key set the user expects to work — match to the widget's ARIA role when in doubt):

• Lists / menus: Arrow keys + Enter + Escape.
• Forms: Tab / Shift+Tab + Enter.
• Modals: Escape closes; Tab cycles within (focus trap should hold).
• Custom widgets (tablist, combobox, tree, slider, etc.): Per the WAI-ARIA Authoring Practices for that role.

After each keypress, fresh snapshot or evaluate_script querying document.activeElement to verify focus moved as expected.

Scroll

Scroll programmatically:

window.scrollTo({ top: 0, behavior: 'instant' })           // top
window.scrollTo({ top: document.body.scrollHeight })       // bottom
document.querySelector(selector).scrollIntoView()           // specific element

After each scroll, fresh snapshot or element-targeted screenshot to capture state at the new position. Use this to verify sticky elements stay stuck, headers don't disappear, infinite-scroll triggers fire, and chrome doesn't fall off the viewport at scrollY > 0.

Focus tracking

Query the currently-focused element:

() => `${document.activeElement?.tagName}#${document.activeElement?.id}.${[...document.activeElement?.classList || []].join('.')}`

Run via evaluate_script / browser_evaluate. Use after dismissals (modal close, dropdown collapse, async completion) to verify focus returned somewhere sensible. Focus left on <body> after a dismissal is typically a regression.

Multi-perspective sign-in

Each MCP instance holds its own session cookies. To switch perspectives:

1. Sign out via UI, or clear cookies via evaluate_script:

   document.cookie.split(';').forEach(c => {
     document.cookie = c.replace(/^ +/, '').replace(/=.*/, '=;expires=' + new Date(0).toUTCString() + ';path=/');
   })
   

2. Navigate to the sign-in surface.
3. Fill + submit credentials for the next perspective.
4. Verify the signed-in state changed (different identity in chrome, different sidebar entries, different visibility on shared resources).

For dev-mode magic-link flows that return the verification URL inline, check list_network_requests / browser_network_requests if the auto-redirect doesn't trigger; manually navigate to the verification URL.

Console + network log inspection

| Concern | Chrome DevTools | Playwright | |---|---|---| | Console messages | list_console_messages → get_console_message(idx) for detail | browser_console_messages | | Network requests | list_network_requests → get_network_request(idx) for detail | browser_network_requests → browser_network_request |

After any meaningful interaction, query both. Console errors and 4xx/5xx network responses are findings the visible UI may not surface. Read every entry — not just the one prompted by your question.

Error Recovery

| Error | Recovery | |-------|----------| | "browser is already running" | Kill stuck browser (see Reference below) | | "Ref not found" / "No node with given id" | Fresh snapshot, get new uid, retry | | Network timeout | Wait 2s, retry (max 3 attempts) |

Reference

Chrome DevTools Profile Locations

chrome-devtools-mcp stores browser profiles at:

| Mode | Profile path | pkill pattern | |------|-------------|---------------| | Default | $HOME/.cache/chrome-devtools-mcp/chrome-profile | chrome-devtools-mcp/chrome-profile | | --isolated | OS temp dir, e.g. /var/folders/.../puppeteer_dev_chrome_profile-XXXXXX | puppeteer_dev_chrome_profile |

The profile persists across runs unless --isolated is used. A killed Chrome process leaves a SingletonLock file in the profile dir that blocks the next launch.

Killing a Stuck Browser

When chrome-devtools-mcp reports "browser is already running":

# 1. Try isolated profile first (temp dir) — kills ALL isolated instances
pkill -f 'puppeteer_dev_chrome_profile'

# 2. If that didn't match, try default persistent profile
pkill -f 'chrome-devtools-mcp/chrome-profile'
rm -f "$HOME/.cache/chrome-devtools-mcp/chrome-profile/SingletonLock"

Wait 2 seconds after killing before retrying.

Note: With --isolated, each session gets a unique temp dir (e.g. puppeteer_dev_chrome_profile-RGjl4g). The pkill pattern above kills all isolated instances. There is no reliable way to target a specific one without tracing PIDs through the process tree.