even-better-playwright-mcp

Get compressed accessibility snapshot with ref IDs.

Returns: DOM tree with [ref=e1], [ref=e2] etc. Use refs with execute tool: await $('e1').click() Call again after navigation (refs become stale).

Options:

• compress: Enable smart compression (default: true) Reduces token usage by ~90% via list folding and wrapper removal.

• search: Search pattern (string or regex) to filter results with context

• showDiff: Show changes since last snapshot (useful for tracking page updates)

Capture page screenshot.

Options:

• ref: Screenshot specific element by ref (e.g., 'e5')

• fullPage: Capture entire scrollable area

• withLabels: Show Vimium-style ref labels on interactive elements

When withLabels is used, labels are color-coded by role:

• Yellow: links

• Orange: buttons

• Coral: text inputs

• Pink: checkboxes/radios

• Blue: images/videos

Execute Playwright code with these in scope:

• page - Current Playwright page

• context - Browser context, access all pages via context.pages()

• state - Persistent object across calls (e.g., state.myPage = await context.newPage())

• $('e5') - Shorthand for page.locator('aria-ref=e5')

• accessibilitySnapshot() - Get current page snapshot

• require - Load Node.js modules (path, url, crypto, buffer, util, assert, os, fs)

• Node.js globals: setTimeout, setInterval, fetch, URL, Buffer, crypto, etc.

Rules

• Multiple calls: Use multiple execute calls for complex logic - helps understand intermediate state and isolate failures

• Never close: Never call browser.close() or context.close(). Only close pages you created or if user asks

• No bringToFront: Never call unless user asks - it's disruptive and unnecessary

• Check state after actions: Always verify page state after clicking/submitting (see next section)

• Clean up listeners: Call page.removeAllListeners() at end to prevent leaks

• Wait for load: Use page.waitForLoadState('domcontentloaded') not page.waitForEvent('load') - waitForEvent times out if already loaded

• Avoid timeouts: Prefer proper waits over page.waitForTimeout() - there are better ways

Checking Page State

After any action (click, submit, navigate), verify what happened:

For visually complex pages (grids, galleries, dashboards), use screenshotWithAccessibilityLabels({ page }) instead.

Accessibility Snapshots

Example output:

Use aria-ref to interact - NO quotes around the ref value:

For pagination: (await accessibilitySnapshot()).split('\n').slice(0, 50).join('\n')

Choosing snapshot method:

• Use accessibilitySnapshot for simple pages, text search, token efficiency

• Use screenshotWithAccessibilityLabels for complex visual layouts, spatial position matters

Selector Best Practices

For unknown sites: use accessibilitySnapshot() with aria-ref For development (with source access), prefer:

1. [data-testid="submit"] - explicit test attributes

2. getByRole('button', { name: 'Save' }) - semantic

3. getByText('Sign in'), getByLabel('Email') - user-facing

4. input[name="email"] - semantic HTML

5. Avoid: classes/IDs that change frequently

If locator matches multiple elements (strict mode violation), use .first(), .last(), or .nth(n):

Working with Pages

Navigation

Common Patterns

Popups: const [popup] = await Promise.all([page.waitForEvent('popup'), page.click('a[target=_blank]')]); await popup.waitForLoadState(); Downloads: const [download] = await Promise.all([page.waitForEvent('download'), page.click('button.download')]); await download.saveAs('/tmp/' + download.suggestedFilename()); iFrames: const frame = page.frameLocator('#my-iframe'); await frame.locator('button').click(); Dialogs: page.on('dialog', async d => { await d.accept(); }); await page.click('button'); Load files: const fs = require('fs'); const content = fs.readFileSync('./data.txt', 'utf-8'); await page.locator('textarea').fill(content);

page.evaluate

Code inside page.evaluate() runs in the browser - use plain JavaScript only. console.log inside evaluate runs in browser, not visible here:

Utility Functions

• getLatestLogs({ page?, count?, search? }) - Get browser console logs

• getCleanHTML({ locator, search?, showDiffSinceLastCall?, includeStyles? }) - Get cleaned HTML

• waitForPageLoad({ page, timeout? }) - Smart load detection (ignores analytics/ads)

• getCDPSession() - Get CDP session for raw Chrome DevTools Protocol commands

• getLocatorStringForElement(locator) - Get stable selector from ephemeral aria-ref

• getReactSource({ locator }) - Get React component source location (dev mode only)

• getStylesForLocator({ locator, cdp }) - Inspect CSS styles (read styles-api resource first)

• createDebugger({ cdp }) - Set breakpoints, step through code (read debugger-api resource first)

• createEditor({ cdp }) - View/edit page scripts and CSS (read editor-api resource first)

• screenshotWithAccessibilityLabels({ page }) - Screenshot with Vimium-style visual labels (yellow=links, orange=buttons, coral=inputs)

Network Interception

For scraping/reverse-engineering APIs, intercept network instead of scrolling DOM:

Then trigger actions and analyze: console.log('Captured', state.responses.length, 'API calls'); Clean up when done: page.removeAllListeners('request'); page.removeAllListeners('response');

IMPORTANT: After navigation, refs are stale - call snapshot tool again.

Search current snapshot with regex.

Requires: Call snapshot first. Returns: Matching lines with refs.

Options:

• pattern: Regex pattern to search for

• ignoreCase: Case-insensitive matching (default: false)

• lineLimit: Max lines to return (default: 100)

Use this to find specific elements in large pages without re-reading the entire snapshot.

Get captured network requests from the browser. Automatically starts capturing when first called. Use includeStatic:true to include images/CSS/fonts. Returns recent requests with status, timing, and response previews.