playwright-mcp

Playwright MCP Browser Automation

You are an expert at using the Playwright MCP server for live browser interaction. This skill teaches you to navigate pages, inspect elements, fill forms, and debug web UIs through direct browser control.

Critical: These Are Direct Tool Calls

MCP tools are direct tool calls — exactly like Read, Grep, or Bash. They are NOT CLI commands.

CORRECT — call the tool directly:

Tool: mcp__playwright__browser_navigate
Parameters: { "url": "http://localhost:3010" }

WRONG — do NOT shell out:

Bash: claude mcp call playwright browser_navigate ...  # This does not work

All Playwright MCP tools use the mcp__playwright__ prefix.

Critical: Always Snapshot Before Interacting

browser_snapshot returns an accessibility tree with ref values for every interactive element. You must snapshot before clicking, typing, or hovering — the ref values are required for all interaction tools.

Critical: Output Size Awareness

Prefer browser_snapshot over browser_take_screenshot for understanding page structure. Screenshots are for visual verification only.

Workflow 1: Navigate & Inspect

Trigger: User says "open this page", "what's on the page?", "inspect the UI", "check the layout"

Steps

1. Navigate to the page:

   browser_navigate({ url: "http://localhost:3010/home/team-slug/settings" })
   

2. Get page structure (always do this before interacting):

   browser_snapshot → accessibility tree with ref values for all elements
   

3. Analyze the snapshot: Identify interactive elements (buttons, links, inputs) by their ref values. Report page structure to user.

Decision: Snapshot vs Screenshot

Workflow 2: Form Interaction

Trigger: User says "fill out the form", "submit the login", "type in the field", "select an option"

Steps

1. Snapshot to find form fields:

   browser_snapshot → identify input refs and their labels
   

2. Fill fields (choose based on complexity):

   • Single field: browser_type({ ref: "input-ref", text: "value" })
   • Multiple fields: browser_fill_form({ fields: [{ ref: "ref1", value: "val1" }, { ref: "ref2", value: "val2" }] })
   • Dropdown: browser_select_option({ ref: "select-ref", values: ["option-value"] })

3. Submit the form:

   browser_click({ ref: "submit-button-ref" })
   

4. Verify result:

   browser_snapshot → check for success message, error states, or navigation
   

Key Patterns

• browser_fill_form is faster than multiple browser_type calls for multi-field forms
• Use browser_press_key({ key: "Enter" }) as alternative to clicking submit
• After submission, wait if needed: browser_wait_for({ text: "Success" }) then snapshot

Workflow 3: Debug Investigation

Trigger: User says "debug the page", "check for errors", "what API calls are happening?", "why isn't it working?"

Steps

1. Navigate to the problematic page:

   browser_navigate({ url: "..." })
   

2. Run these in parallel (they are independent):

   browser_console_messages → JavaScript errors, warnings, logs
   browser_network_requests → API calls, failed requests, status codes
   

3. Snapshot the page:

   browser_snapshot → current UI state, error messages, loading states
   

4. Investigate further:

   browser_evaluate({ expression: "document.querySelectorAll('.error').length" }) → run custom JS
   

Workflow 4: Multi-Step Navigation

Trigger: User says "go through the flow", "test the signup process", "walk through the wizard"

Steps

1. Navigate to starting page:

   browser_navigate({ url: "..." })
   

2. For each step:

   browser_snapshot → find the next action
   browser_click({ ref: "..." }) or browser_type({ ref: "...", text: "..." })
   browser_wait_for({ text: "expected content" }) → if page loads async
   

3. Handle dialogs if they appear:

   browser_handle_dialog({ accept: true }) → confirm/alert/prompt
   

4. Go back if needed:

   browser_navigate_back
   

Tool Reference

Navigation

Inspection

Interaction

Advanced

Troubleshooting

"No browser running" or Connection Errors

The Playwright MCP server manages its own browser instance. If tools fail:

1. Try browser_install to ensure the browser binary is available
2. Try browser_navigate to a simple URL — this may initialize the browser

Elements Not Found After Navigation

Pages with async content may not have rendered yet:

1. Use browser_wait_for({ text: "expected content" }) before snapshot
2. Use browser_wait_for({ timeout: 2000 }) for time-based waiting

Proxied or Internal Domains

The MCP browser cannot reach proxied or internal domains that require network tunnels. Use http://127.0.0.1:54321 directly for local Supabase.

Snapshot Returns Very Large Output

Complex pages produce large accessibility trees. If output is too large:

1. Navigate to a specific sub-page rather than the full app
2. Use browser_evaluate to query specific elements instead