Playwright 1.64 Adds WebMCP Support: A Guide to Testing AI Agents

Playwright 1.64 introduces an experimental feature: support for WebMCP. This isn't an ordinary version update—it directly concerns whether your website provides AI agents with callable actions, and how you should test those actions.

WebMCP allows web pages to expose a set of callable tools to AI agents, and Playwright 1.64 lets testers list and invoke those tools. If your site hasn't registered any WebMCP actions, there's nothing to test for now; if your team is adding such actions, you can incorporate them into your normal page testing workflow today.

What WebMCP Is and Why Testing Needs to Care

The core idea of WebMCP is to let web pages proactively declare which AI-callable actions they provide. A "tool" is a callable action provided by the website, such as querying an order's delivery date or updating a record. Playwright 1.64's support for this is experimental and revolves around two APIs: tools() lists the currently registered tools, and callTool() invokes a specified tool and retrieves the result.

The impact on testing is this: traditional tests focus on whether human users can complete actions through the page, whereas WebMCP tests focus on whether the content returned when an AI agent invokes these actions is correct and whether the application state has changed as expected. The two have different verification goals and cannot substitute for each other.

MCP (Model Context Protocol) is an open protocol proposed by Anthropic in late 2024 for enabling AI models to discover and invoke external tools and data sources in a standardized way. In the classic MCP architecture, an AI client connects to a remote MCP server; WebMCP pushes this model down into the browser page itself: the web page becomes the tool provider, registering callable actions with the AI agent running inside the page through an interface exposed by the browser. This means AI agents no longer need to go through a separate backend service to invoke tools—they interact directly with the current page. Because this capability is still in the early stages of browser vendor implementation and standardization, interface naming and enablement methods differ across browsers. This is precisely why Playwright labels it an experimental API—the interface may change as browser implementations evolve.

Prerequisites: Browser and Page Registration

Before writing tests, several prerequisites must be met. Your application needs to register tools through the experimental WebMCP interface provided by the browser, and the browser itself must have WebMCP enabled.

The enablement method differs by browser: Chromium requires the --enable-features=WebMCP launch flag; Firefox requires both the dom.modelcontext.enabled and dom.modelcontext.testing.enabled preferences to be set; WebKit does not yet implement this feature.

Another common pitfall is frame selection. page.webmcp corresponds to the main frame's instance; if tools are registered in a subframe, you need to use that frame's own frame.webmcp instance. Choosing the wrong frame will result in an empty tool list—but this doesn't necessarily mean your test environment is broken; it may simply be that you're looking in the wrong place.

Input schema typically describes the parameters a tool expects to receive in the form of JSON Schema, including parameter names, types, whether they are required, and constraints. The input structure returned by Playwright's tools() is a mapping of this declaration. The significance of validating the schema during testing is that AI agents construct invocation parameters based on the schema; if the schema is inconsistent with the actual implementation (for example, declaring an optional parameter that is actually required in the implementation), the agent may construct failing calls in real operation. Therefore, schema validation is not merely a documentation-level check—it is also a prerequisite for the agent to successfully invoke the tool.

Listing Tools: First Confirm What's on the Page

tools() returns the list of currently registered tools in the specified frame. Once you have the list, you should compare each tool's name, description, and input structure against the application's design intent. The input schema describes the parameters the tool expects to receive, and this information also needs to be validated.

There's a security-related detail worth noting here: names, descriptions, input rules, and annotations provided by the page should all be treated as untrusted input. An annotation marking an operation as "read-only" is merely a hint provided by the page and does not prove that the operation truly won't modify data. During testing, rely on actual behavior rather than trusting these declarations.

If tools are found to be missing, the recommended troubleshooting order is: first confirm whether the frame selection is correct, then check the registration timing, and finally confirm whether the application actually registered the tool. Additionally, when the browser doesn't support WebMCP, tools() may also throw an exception, which needs to be handled properly in tests.

Invoking Tools: Verify Return Values and State Changes

callTool() is used to invoke a named tool in the specified frame. When choosing actions, pick operations that have known expected results in your own application, and provide inputs according to their schema. The result returned by the call is provided by the tool on the page.

Take the delivery date query from the original article as an example: suppose order 1043's delivery date is October 16. After invoking the query tool for that order number, compare the returned result with the known date, and confirm that the relevant record hasn't been unexpectedly modified. If invoking an operation that changes data, you need to read the saved record after the call to check whether the expected change took effect and confirm that other records are unaffected.

It's important to be clear that a return value only shows that the tool "answered"—it does not prove the answer is correct or that an update has been persisted. Save timing should follow the application's own documentation. For operations that modify data, use controlled records to avoid touching sensitive flows such as real purchases and customer notifications.

Test Scenario	What Playwright Exposes	Key Points to Check
Tool and input both valid	Result returned by the page	Expected content and related application state
Tool returns isError: true	An error result	Reported error message and whether state matches expectations
Tool name not registered	Exception, reporting execution failure	Expected registration status and reported error
Tool callback throws an exception	Exception, reporting execution failure	Reported error and final application state

The last two scenarios both fail as exceptions, but the exception itself cannot distinguish the specific cause. You need to combine the registered names with the controlled failure scenarios you constructed to pinpoint the problem.

isError: true in a tool result is an application-layer error expression defined by the MCP protocol: the call returns successfully at the protocol level, but the tool itself reports execution failure. This is fundamentally different from invoking an unregistered tool name or a tool callback directly throwing an exception—the latter two manifest as call exceptions on the Playwright side. Distinguishing these two types of failure is important for testing: isError is a business result that the application under test needs to handle and report correctly, while exceptions more often indicate a broken invocation contract. Test cases should cover both separately to avoid conflating them and masking real defects.

Don't Drop Regular Page Tests

WebMCP tests answer the question of "what did the AI-facing operation report and what did it change"—they cannot replace full browser journey tests for human users. Visible controls, toast messages, and end-to-end user tasks still require independent test coverage—these checks answer a different question: can a person complete the task through the page?

A Practical Checklist

For applications with tool-enabled pages, start with the following six questions:

1. In which frame are the tools registered? Is WebMCP enabled in the current browser?
2. Does tools() show the expected actions and input structures?
3. For known inputs, does callTool() return the expected content?
4. Is the application state consistent with that result?
5. How do the three cases behave: returned error, unknown name, and callback failure?
6. Can regular page controls still support users in completing the task?

This checklist can serve as a starting point for WebMCP testing under Playwright 1.64; specific expected results need to be adjusted according to your application's contract.