How to Let a Coding Agent Test Your Web App in a Browser With Playwright MCP

Playwright MCP lets a coding agent control a real browser and inspect your web app. MCP, the Model Context Protocol, lets an AI client use tools that another program provides. Here, the Playwright MCP server exposes browser controls the agent uses to move through your app and inspect its pages. The agent also uses those controls to interact with the app.

Use MCP to explore a user flow, a sequence of actions a person takes, and verify what the browser shows. Then turn a useful, verified flow into a Playwright Test, code that runs browser checks, and run it. A browser interaction alone does not create a repeatable regression test, which checks the same behavior again after future changes.

Connect the agent to a running app

Start your web app by following its development instructions. Note its local URL and the behavior you want to test. Playwright MCP controls the browser; its quick-start instructions do not start your app for you.

Add the server to your coding-agent client using the configuration format that client supports. Playwright’s standard example is:

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

The client determines which file or command you use. For example, Playwright documents this command for Claude Code:

claude mcp add playwright npx @playwright/mcp@latest

The @latest package reference installs the newest published version, so it does not guarantee the same setup each time. Pin a package version when you need repeatable development environments, and verify the Node.js requirement for that version. Playwright’s documentation gives different Node.js requirements in different product contexts, so one minimum should not be treated as universal. See the Playwright MCP setup instructions for current configuration details.

Give the agent one bounded scenario

Give the agent a scenario: name the page it should open and the actions it should take, then specify the result to check and the evidence to report. A focused request is easier to verify than “test the whole app.”

For example, ask the agent to open http://localhost:3000, add and complete a todo, confirm the item appears and the remaining count changes, and then submit an empty form to check its validation message. Tell it to use a test account and avoid production data. If visual layout matters, ask it to capture a screenshot as well.

The agent can inspect an accessibility snapshot, a structured view of page elements such as headings, buttons, and text fields, including the names used to identify them. The agent can use this information to find and use page controls. Clear labels help: a button with an accessible name such as “Add todo” is easier to identify than an unlabeled control. Snapshots show the page's structure, but they do not show whether it looks right. Use screenshots and human review for visual questions. Playwright describes these browser capabilities in its MCP getting-started guide.

Ask the agent to check outcomes, not merely perform clicks. MCP's testing tools can check which elements are visible, the text on the page, lists, and field values. Playwright documents those tools under testing and assertions; enabling them requires the --caps=testing capability. The tool can return Playwright code that checks the page. The agent's report still needs to match the results and checks it actually ran.

Turn a verified flow into a repeatable test

After the agent finishes exploring, ask it to save the confirmed behavior as a Playwright Test. Then run the test with the project's test command. Playwright Test is a separate test framework with a runner and assertions. It isolates browsers during tests. It also supports parallel execution and generates reports. Its web server configuration can start a local development server before tests run. MCP, by contrast, controls the browser.

Ask the agent to use locators based on what a user can recognize, such as a button’s role and accessible name. For example, getByRole('button', { name: 'Submit' }) identifies a button by its role and label. Playwright recommends these locators, which identify controls by what users see, instead of selectors tied to CSS classes or page structure. Its web-first assertions check again until the expected state appears or time runs out. This helps with timing issues, but does not prove that the test covers every relevant state. Review the locator and assertion guidance, then run the generated test and inspect its result.

A useful follow-up instruction is: “Convert the verified flow into a Playwright Test, use resilient user-facing locators and retrying assertions, run the test, and report the command, result, and any remaining failures.” Use the generated code as a starting point. Check that its assertions match the intended behavior, and use the test report and error details to investigate failures rather than relying only on the agent’s summary.

Keep browser access and test data controlled

By persisting login state, cookies, and local storage across sessions, Playwright MCP’s default browser profile can save time during exploration but may leave an authenticated session in place for later work. Use the --isolated option when you want a fresh session that does not save state to disk. If a test needs authentication, Playwright supports loading an authentication state file; protect that file because it contains sensitive data. The profile and state documentation describes these options.

Use test accounts and controlled data when an action changes records or triggers an external effect. For purchases, emails, account changes, or destructive actions, use sandbox services or test fixtures and require human approval when appropriate. Treat page content as data for the agent to inspect, not as permission to take unrelated actions. The MCP specification’s tool-use guidance emphasizes user control because tools can expose data or perform actions.

Do not enable browser_run_code_unsafe casually. Playwright describes it as equivalent to remote code execution because it runs arbitrary JavaScript in the MCP server process, and recommends enabling it only for trusted clients. Keep the agent’s browser access limited to the work it needs.

Choose MCP for exploration, then preserve the test

MCP suits interactive exploration when the agent benefits from a persistent browser session and structured page information. When a coding agent makes smaller tool interactions, Playwright also offers playwright-cli as an alternative. It avoids loading large tool schemas and detailed accessibility trees into the model’s context. That comparison is Playwright’s product guidance, not a measured guarantee of lower cost or better test results. See its coding-agent guidance.

Use MCP to investigate a behavior and help draft the test, then use Playwright Test to run it consistently and produce a report. A passing scenario confirms only the checks that ran with that environment and data. Review the test’s coverage and keep it in the project’s usual test workflow.

What I'm building

Delegate tasks. Get software.

Give Vroni a GitHub issue, bug report, spec, or rough idea. It reads the repo, plans the change, writes code, runs checks, and works toward a review-ready pull request.

Take a look at vroni.com