Claude Code and Playwright for Browser QA: A Setup

To run browser QA with Claude Code, add Playwright as an MCP server with claude mcp add playwright npx @playwright/mcp@latest, or install Playwright CLI with skills, then ask Claude to open your local app and walk a user flow. Use Claude in Chrome when you need your real logged-in browser. Setup details checked 31 October 2026.

The stack at a glance

Requirements: Node.js 18 or newer for both Playwright packages, Claude Code installed, and your app running locally.

What this stack is good for

Browser QA with an agent is strongest at exploratory checks. You describe a flow in words, the agent drives a real browser, and it reports what it saw: console errors, failed network calls, broken layouts at a given width. It is also useful for turning a manual checklist into a repeatable script.

It is weaker as a replacement for a proper test suite. An agent run is not deterministic, costs tokens each time, and can miss a regression on one run and catch it on the next. The best use is a pair: let the agent explore and write the tests, then run the written tests in CI without the agent.

Option A: Playwright MCP

This is the quickest to set up. One command adds the server for the current project:

claude mcp add playwright npx @playwright/mcp@latest

To pass options, use the double-dash form that Claude Code's docs describe for stdio servers:

claude mcp add --transport stdio playwright -- npx @playwright/mcp@latest --headless --isolated

Run /mcp inside Claude Code to confirm it is connected. Our Playwright MCP page has install lines for other agents.

The tools you get

The README lists tools such as browser_navigate, browser_click, browser_type, browser_fill_form, browser_snapshot, browser_take_screenshot, browser_console_messages, browser_network_requests, browser_resize, browser_handle_dialog, browser_file_upload, browser_tabs and browser_wait_for. Some are opt-in: configuration, network routing, and capability groups switched on with --caps (vision, pdf, devtools).

The snapshot tool matters most. By default the agent works from the page's accessibility tree, a text outline of the page, not from pixels. The README says a screenshot cannot be used to act; the agent must use a snapshot for actions. That makes runs cheaper and more reliable than vision-based clicking.

Options worth knowing

The README also warns that a persistent profile can only be used by one browser instance at a time, so concurrent clients sharing a workspace conflict. Use --isolated for parallel runs.

Option B: Playwright CLI with skills

The Playwright team now steers coding agents elsewhere. The first lines of the MCP README say: "If you are using a coding agent, you might benefit from using the CLI+SKILLS instead." The reason given is token cost: CLI calls avoid loading large tool schemas and verbose accessibility trees into the model context. The MCP route stays relevant "for specialized agentic loops that benefit from persistent state, rich introspection, and iterative reasoning over page structure, such as exploratory automation, self-healing tests, or long-running autonomous workflows".

Setup:

npm install -g @playwright/cli@latest
playwright-cli --help
playwright-cli install --skills

The skills install makes Claude Code use the locally installed skills. You can also skip the skills and tell the agent to read playwright-cli --help. The README's demo asks the agent to test the TodoMVC page and take screenshots for passing and failing scenarios. You can also run commands by hand, for example playwright-cli open https://demo.playwright.dev/todomvc/ --headed.

For background on why skills save context, see skills vs MCP and agent skills.

Option C: Claude in Chrome

When the page you need to test sits behind a login you do not want to script, use your real browser. Claude Code's docs describe the integration with the Claude in Chrome extension:

claude --chrome

Then ask in plain language, as in the docs' example: open localhost:3000, submit the form with invalid data and check that the error messages appear. The browser runs in a visible window, shares your login state, and pauses when it meets a login page or CAPTCHA.

What the docs list for testing: reading console errors and DOM state, design verification against a mock, form validation and user-flow checks, and recording a GIF of an interaction.

The conditions matter:

• Chrome or Edge, with the extension at version 1.0.36 or later; other Chromium browsers are detected
• A direct Anthropic plan: Pro, Max, Ultra, Team or Enterprise
• Sign in with /login; an API key or a long-lived token keeps Chrome integration off
• Not supported in WSL, and not available through Amazon Bedrock, Google Cloud's Agent Platform or Microsoft Foundry
• Run /chrome to check status, reconnect and choose a browser

Enabling Chrome by default increases context use because the browser tools are always loaded, per the docs. Turn it on per session unless you test every day.

Which option when

Add a QA subagent

Long browser sessions fill the context with page snapshots. A subagent keeps them out of your main conversation. In Claude Code, create a file such as .claude/agents/browser-qa.md that describes the role, limits the tools, and tells it what to report. A sketch:

---
name: browser-qa
description: Runs browser checks against the local app and reports findings. Use after UI changes.
---
You test the app at http://localhost:3000 in a browser.
- Walk the flow you are given, step by step.
- At widths 1440, 768 and 390, check for layout breakage.
- Report console errors and failed network requests.
- Never submit forms against real payment or email services.
- Finish with a short list: passed, failed, unsure.

Check the current subagent file format in the Claude Code docs before copying; the front matter fields can change. See subagents, how to write a subagent and the browser QA recipe. The debugger subagent pairs well with it.

Put the checklist in CLAUDE.md

Tell Claude what "done" means for UI work. A short block does more than a clever prompt:

## Browser QA
- Start the dev server with `npm run dev` (port 3000) before testing.
- After any UI change, check the page at 1440, 768 and 390 pixels wide.
- Check the browser console; any error fails the check.
- Test the keyboard path: Tab reaches every control, Enter activates it.
- Use test accounts only. Never use real customer data.

Keep it short. See write a good CLAUDE.md and the CLAUDE.md starter template.

A first run

1. Start your dev server.
2. Add the server: claude mcp add playwright npx @playwright/mcp@latest --headless (or install the CLI).
3. Ask: "Open http://localhost:3000/signup, submit the empty form, and tell me which validation messages appear. Check the console."
4. Ask for a second pass at 390 pixels with browser_resize.
5. Ask Claude to write a Playwright test for the flow it just walked, and run that test yourself.
6. Commit the test. The next run does not need the agent.

Step five is the one that pays back. The agent's exploration becomes a permanent, free-to-run check.

Safety and cost

• Untrusted pages. Page text can contain instructions aimed at the agent. Test your own app and known pages, not the open web, and review anything the agent wants to do outside the flow.
• Real accounts. Use seed users on a local or staging database. The --isolated flag stops a profile persisting; with Claude in Chrome the agent shares your logins, so keep sensitive tabs closed.
• Permissions. Claude Code asks before browser actions in Claude in Chrome. Keep the prompts on for sites you have not allowed.
• Secrets. Do not paste real passwords into prompts. Use environment variables or a storage-state file with test cookies.
• Tokens. Snapshots are large. Use the CLI route, a subagent, or --mobile pages to cut usage.
• Production. Never point write-capable tests at production.

Troubleshooting

• The server does not appear. Run /mcp to see its status. Check that node --version reports 18 or newer, since npx needs it.
• The browser will not start. Playwright may need its browser binaries. The README covers Docker and headless setups, including a --no-sandbox option for containers.
• Two sessions fight over a profile. The README says a persistent profile serves one browser at a time. Add --isolated for the second client.
• Claude in Chrome says "Browser extension is not connected". The docs list causes: the extension is signed in to a different account or organization than Claude Code, or a network rule blocks bridge.claudeusercontent.com. Run /chrome and reconnect.
• A dialog blocks everything. JavaScript alerts stop browser events. Dismiss the dialog by hand, or have the agent use browser_handle_dialog.
• Runs are slow and costly. Move to the CLI route, shrink the page with --mobile, or ask for targeted checks rather than "test everything".

Other agents, same idea

The same Playwright setup works elsewhere. The Playwright README has install steps for Codex, Copilot, Gemini CLI, Cursor and others. See Cursor vs Claude Code if you are choosing, or the Chrome DevTools MCP and Puppeteer MCP alternatives. For a wider set of tools see best MCP servers.

What to ask the agent to check

A vague "test the site" wastes tokens. These prompts give the agent a clear finish line.

• "Open /signup. Submit the form empty, then with a malformed email. List every validation message and whether it is visible at 390 pixels wide."
• "Walk the checkout from cart to confirmation. At each step report the page title, any console error and any failed network request."
• "Tab through the page with the keyboard only. Report any control you cannot reach or any focus state you cannot see."
• "Resize to 1440, 768 and 390. Describe any element that overlaps, overflows or disappears."
• "Compare the page to the design brief in docs/brief.md and list every difference."

Each prompt names a place, an action and what to report. That makes the result easy to review and easy to turn into a Playwright test afterwards.

Reading the agent's report critically

An agent report is a claim, not proof. Ask for evidence: a screenshot path, the console line, the network request number. If it says a flow passed, ask which assertion it checked. Run the committed test yourself before you trust it, and make sure the test fails when you deliberately break the page. A test that cannot fail is not a test.

Keeping runs cheap

Page snapshots and screenshots are the biggest token cost. Test one flow per session, close the session when the flow ends, use the CLI route for routine checks, and keep the subagent's report short. If a flow needs a login, save a test account's storage state once and reuse it rather than logging in on every run.

Our take

This is an editorial reading of vendor documentation, not a test we ran.

The most useful fact in the sources is the Playwright team's own advice: for coding agents, prefer the CLI with skills, because MCP tool schemas and accessibility trees cost context. We would start there, and keep Playwright MCP for exploratory sessions where the agent needs to reason about page structure. Claude in Chrome fills a different gap, the logged-in app, and it has a real list of conditions that rule it out for some people (no WSL, no cloud-provider access, direct plan required).

Treat the agent as a tester who writes down what it did. Every exploratory session should end with a committed Playwright test, so the next run is free and repeatable. And always check the viewport you were asked to check, since layout bugs are what agents find fastest.

Checklist

• Node.js 18 or newer installed
• Chose MCP, CLI with skills, or Claude in Chrome for this job
• Added the server or installed the CLI and confirmed with /mcp
• Wrote a browser QA block in CLAUDE.md
• Created a browser-qa subagent
• Ran the first flow at 1440, 768 and 390 pixels
• Turned the walked flow into a committed Playwright test
• Used test accounts only