Playwright MCP Guide

Rules and usage for Microsoft Playwright MCP server.

Table of Contents

Core

• •MUST-NOT-FORGET
• •Configuration
• •Available Tools

Workflows

• •Common Workflows
• •Advanced Workflows - Cookie popups, scrolling, expanding items, full page screenshots

Reference

• •Element Selection
• •Authentication - Persistent profiles, storage state, extension mode
• •Troubleshooting - Common issues, flaky tests
• •Setup - Installation

Intent Lookup

User wants to...

• •Research a topic / read articles → Navigate, dismiss cookie popup, scroll for lazy content, screenshot
• •Find a product / compare prices → Navigate, search, extract data with browser_evaluate
• •Fill out a form / submit application → Use browser_fill for fields, browser_click for submit
• •Download file / attachment → First find links with Section 5, then click to download
• •Log into a site → Fill credentials, submit; use PLAYWRIGHT_AUTHENTICATION.md to stay logged in
• •Do a bank transfer / pay bills → Requires persistent profile for auth; use browser_snapshot before each action
• •Check email / download attachments → Navigate to webmail, expand messages, click attachment links
• •Archive a webpage → See PLAYWRIGHT_ADVANCED_WORKFLOWS.md for full page screenshot workflow
• •Interact with dynamic content → Scroll to load lazy content, expand collapsed sections, then proceed

UI testing...

• •Verify page loads correctly → Navigate, browser_snapshot, check expected elements present
• •Test form validation → Submit empty/invalid data, check error messages appear
• •Test navigation flow → Click through menus, verify correct pages load
• •Test responsive layout → Resize browser, screenshot at different widths
• •Test button states → Hover, click, verify visual/functional changes
• •Test modal dialogs → Trigger modal, interact, close, verify dismissed
• •Test error states → Force errors (bad URL, timeout), verify error handling
• •Test accessibility → Use browser_snapshot (accessibility tree), check refs have labels
• •Compare before/after → Screenshot before change, screenshot after, compare
• •Test login/logout → Full auth flow, verify session state

Technical tasks...

• •Handle cookie popup → PLAYWRIGHT_ADVANCED_WORKFLOWS.md#1-close-cookie-popups
• •Run custom JavaScript → browser_evaluate(expression: "...")
• •Debug failures → PLAYWRIGHT_TROUBLESHOOTING.md

MUST-NOT-FORGET

• •Use accessibility tree (not screenshots) for element selection
• •Reference elements via ref=e5 format from browser_snapshot
• •Always call browser_snapshot before clicking to get current refs
• •Use browser_close when done to free resources
• •For logged-in sessions: Use persistent user profile or storage state

Configuration

Repository: https://github.com/microsoft/playwright-mcp Package: @playwright/mcp

Basic (isolated session):

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

Persistent profile (remembers logins):

{
  "args": ["@playwright/mcp@latest", "--user-data-dir", "[USER_PROFILE_PATH]/.ms-playwright-mcp-profile"]
}

Headless: Add "--headless" to args.

Timeouts: Add "--timeout-action", "10000", "--timeout-navigation", "120000" for slow pages.

Available Tools

Navigation

• •browser_navigate - browser_navigate(url: "https://example.com")

Element Interaction

• •browser_snapshot - Get accessibility tree with element refs
• •browser_click - browser_click(element: "Button", ref: "e12")
• •browser_type - browser_type(element: "Input", ref: "e8", text: "query")
• •browser_fill - browser_fill(element: "Email", ref: "e3", value: "user@example.com")
• •browser_select - browser_select(element: "Country", ref: "e15", values: ["USA"])
• •browser_hover - browser_hover(element: "Menu", ref: "e5")
• •browser_drag - Drag and drop between elements
• •browser_press_key - browser_press_key(key: "Enter") or browser_press_key(key: "Control+A")

Inspection

• •browser_screenshot - browser_screenshot() or browser_screenshot(fullPage: true)
• •browser_console_messages - Get console logs
• •browser_evaluate - browser_evaluate(expression: "document.title")

Timing

• •browser_wait_for - browser_wait_for(time: 2) wait seconds, or browser_wait_for(text: "Loading") wait for text

Session

• •browser_close - Close browser and free resources

Common Workflows

Navigate and Click

1. browser_navigate(url: "https://example.com")
2. browser_snapshot()
3. browser_click(element: "Login button", ref: "e12")

Fill Form

1. browser_snapshot()
2. browser_fill(element: "Username", ref: "e3", value: "user@example.com")
3. browser_fill(element: "Password", ref: "e5", value: "password123")
4. browser_click(element: "Submit", ref: "e8")

Wait for Content

After navigation or click, call browser_snapshot() to verify page loaded and get updated refs.

Full Page Screenshot

browser_screenshot(fullPage: true)

For cookie popups, lazy-load scrolling, and expanding collapsed items, see PLAYWRIGHT_ADVANCED_WORKFLOWS.md.

Element Selection

Using Refs from Snapshot

1. •Call browser_snapshot() to get current page structure
2. •Find element in returned accessibility tree
3. •Use the ref value in subsequent commands

Example snapshot output:

- banner [ref=e3]:
    - link "Home" [ref=e5] [cursor=pointer]
    - navigation [ref=e12]:
        - link "Docs" [ref=e13]

Selector Priority

When refs unavailable, use stable selectors:

1. •[data-testid="submit"] - Best
2. •getByRole('button', { name: 'Save' }) - Semantic
3. •getByText('Sign in') - User-facing
4. •input[name="email"] - HTML attributes
5. •Avoid: .btn-primary, #submit - Classes/IDs change

Requirements

• •Node.js 18+ with npx in PATH
• •Chrome/Chromium for headed mode

See SETUP.md for installation details.