Skip to main content

Published

Claude Code + Playwright: 3 Ways to Set It Up (2026)

Short answer

There are three ways to use Claude Code with Playwright. Add the Playwright MCP server with claude mcp add playwright npx @playwright/mcp@latest so Claude can drive a real browser. Run npx playwright init-agents --loop=claude to install the planner, generator and healer agents. Or skip both and ask Claude Code to write .spec.ts files that you run with npx playwright test. Most teams end up combining them.

Last updated: 2026-11-09

How do I use Claude Code with Playwright?​

Claude Code can work with Playwright in three different ways, and they solve different problems.

RouteWhat you installBest for
Playwright MCPOne claude mcp add commandLetting Claude look at the running app, reproduce a bug, or explore a feature
Playwright Test Agentsnpx playwright init-agents --loop=claudeA plan, generate and repair loop that produces test files
Plain test filesOnly @playwright/testHaving Claude write and run tests the same way it edits any other code

None of them replaces the others. The MCP server is how Claude sees the page. The agents are a ready-made workflow on top of it. Plain test files are what you end up keeping and running in CI.

Route 1: How do I add Playwright MCP to Claude Code?​

Run this in your terminal:

claude mcp add playwright npx @playwright/mcp@latest

The Playwright docs say the server is available in your next Claude Code session. Node.js 18 or newer is required. Claude Code stores the server in local scope by default, which means it loads only in the project where you added it and stays private to you. To share it with your team, add --scope project or put the entry under mcpServers in a .mcp.json file at the project root and commit it.

Flags for the server go after a double dash, so Claude Code does not read them as its own options. For example, to run headless with an in-memory profile:

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

To check the connection, run claude mcp list or claude mcp get playwright in your shell, or /mcp inside a session. Then try a prompt such as "open http://localhost:3000, sign up with a new email, and tell me what the dashboard shows". If Claude opens a browser and reports back, the tools are wired up.

For the full flag list, the accessibility-snapshot design, and when the Playwright CLI is the better choice, see Playwright MCP: what it is, setup, and where it fits.

Route 2: What are Playwright Test Agents and how do I use them with Claude Code?​

Playwright ships three agents: a planner, a generator and a healer. According to the Playwright docs, the planner explores the app and produces a Markdown test plan, the generator turns that plan into Playwright test files, and the healer runs the suite and repairs failing tests. You can use them on their own or chain them.

Install the definitions for Claude Code from your project root:

npx playwright init-agents --loop=claude

The docs recommend regenerating these definitions whenever you update Playwright, so they pick up new tools and instructions. The command also accepts vscode, codex and opencode as loop values.

The workflow then runs in three prompts:

  1. Plan: Ask the planner for a scenario, such as "generate a plan for guest checkout". Give it a seed test, which is a normal Playwright test that sets up the environment, including global setup, fixtures and hooks. The planner writes a Markdown plan into a specs/ folder.
  2. Generate: Point the generator at the plan. It performs the scenarios live to verify selectors and assertions, then writes test files under tests/.
  3. Heal: When a test fails, give the healer the test name. It replays the failing steps, inspects the current UI, proposes a patch such as a locator update or a wait adjustment, and re-runs until the test passes or its guardrails stop it. The docs say the output is either a passing test or a skipped test if the healer believes the functionality is broken.

Read what the healer changes. A test that gets skipped or loosened until it passes is not the same as a test that still checks the behavior you care about.

Route 3: Can Claude Code just write the tests without MCP?​

Yes, and for many teams this is the daily workflow. Install Playwright in the usual way and ask Claude Code to write a test the way you would ask it to write any function:

npm init playwright@latest

Then a prompt like this works well:

Write a Playwright test for the login flow in app/login. Use getByRole and
getByLabel locators. Seed the user through the API in a fixture, not through
the UI. Run it with npx playwright test and fix any failures.

Claude Code can run the command itself, read the failure output, and edit the file. Two habits make this route much more reliable:

  • Tell it how to log in once: have a setup project save a storage state and reuse it, so each test does not repeat the sign-in flow.
  • Give it the trace when something fails: Playwright can record a trace.zip on the first retry, and a failing CI run is much easier for an agent to debug with the trace than with a one-line timeout. See Playwright Trace Viewer: how to record, open and read a trace.

Which route should I start with?​

If you are building a new feature and want Claude to check it in a real browser, start with the MCP server. If you have an app with no tests and want a first batch quickly, try the agents. If you already have a Playwright suite and conventions, plain test files with a short note in your CLAUDE.md about locators, fixtures and test data will keep new tests consistent with the old ones.

A common pattern is to use MCP to explore, ask Claude to write the result down as a Playwright test, and then run that test without the agent. The file is what you keep. The browser session was only how Claude learned the page.

What Claude Code and Playwright do not tell you​

Claude Code is good at writing Playwright tests, and Playwright is a good runner. Together they leave four questions open, and they are the ones that matter once the suite grows:

  • Which of these tests did a person read? A green run from a test Claude wrote and Claude healed has not been reviewed by anyone.
  • What is covered? Each session sees one flow. Nothing adds them up against what users do.
  • What drifted? When a requirement changes, older tests can keep passing while checking the old behavior.
  • What should be tested next? Claude tests what it is asked to test.

This is the layer TestChimp adds on top of whatever your agent already uses. Scenarios live as Markdown in your repo, tests link to them, and agent-edited tests are flagged for human review. TrueCoverage, which compares production behavior with test coverage, is available on the Growth plan or during the trial. For the Claude Code specific setup, see How to test apps built with Claude Code, and for the review half of the loop, see How to trust AI-written tests.

Frequently asked questions

How do I add Playwright to Claude Code?

Run claude mcp add playwright npx @playwright/mcp@latest in your terminal. The server is available in your next Claude Code session. Node.js 18 or newer is required.

Can Claude Code write Playwright tests?

Yes. Install @playwright/test, ask Claude Code to write a spec file, and let it run npx playwright test and fix failures. You can also use the Playwright Test Agents or the Playwright MCP server to let it explore the app first.

What does npx playwright init-agents --loop=claude do?

It adds the Playwright planner, generator and healer agent definitions to your project for use with Claude Code. The Playwright docs say to regenerate them whenever you update Playwright.

Do I need Playwright MCP to use Claude Code with Playwright?

No. MCP lets Claude control a browser, which helps with exploring and debugging. Claude Code can also write and run ordinary Playwright test files with no MCP server installed.

How do I share the Playwright MCP setup with my team?

Add --scope project to the claude mcp add command, or add the server under mcpServers in a .mcp.json file at the project root and commit it. The default local scope is private to you.

Does Claude Code with Playwright tell me which tests matter?

No. It writes and runs tests. Knowing which scenarios are covered, which tests a person reviewed, and what to test next needs a layer above the browser tool, such as TestChimp.

Let Claude Code write the tests. Know which ones matter.

Keep Claude Code and Playwright. TestChimp links tests to scenarios, shows coverage, and flags agent-edited tests for review. 14-day free trial, no credit card.

Start a 14-day free trial · Book a demo