Playwright 1.64 新增 WebMCP 支持：AI 代理测试指南

Playwright 1.64 引入了一项实验性功能：对 WebMCP 的支持。这不是一个普通的版本更新——它直接关系到你的网站是否为 AI 代理提供了可调用的操作，以及你该如何测试这些操作。

WebMCP 允许网页向 AI 代理暴露一组可调用的工具（tools），Playwright 1.64 则让测试人员能够列出和调用这些工具。如果你的网站没有注册任何 WebMCP 操作，那暂时没有需要测试的东西；如果你的团队正在添加这类操作，现在就可以把它们纳入正常的页面测试流程中。

WebMCP 是什么，为什么测试需要关注

WebMCP 的核心思路是让网页主动声明自己提供了哪些可供 AI 调用的动作。一个“工具”就是网站提供的一个可调用动作，比如查询订单的配送日期、更新某个记录等。Playwright 1.64 对这部分的支撑是实验性的，围绕两个 API 展开：tools() 用于列出当前注册的工具，callTool() 用于调用指定工具并获取返回结果。

这对测试的影响在于：传统测试关注人类用户能否通过页面完成操作，而 WebMCP 测试关注的是 AI 代理调用这些操作时，返回的内容是否正确、应用状态是否发生了预期变化。两者的验证目标不同，不能互相替代。

MCP（Model Context Protocol） 是 Anthropic 于 2024 年底提出的一种开放协议，用于让 AI 模型以标准化方式发现并调用外部工具和数据源。在 MCP 的经典架构中，AI 客户端连接的是远端 MCP 服务器；而 WebMCP 把这一模型下沉到浏览器页面内部：网页本身成为工具提供方，通过浏览器暴露的接口向页面内运行的 AI 代理注册可调用动作。这意味着 AI 代理调用工具时不再需要经过独立的后端服务，而是直接与当前页面交互。由于该能力仍处于浏览器厂商的实现与标准化早期阶段，各浏览器的接口命名、开关方式并不统一，Playwright 将其标注为实验性 API 也正是出于这个原因——接口可能随浏览器实现变化而调整。

运行前提：浏览器与页面注册

在开始编写测试之前，有几个前提必须满足。你的应用需要通过浏览器提供的实验性 WebMCP 接口注册工具，同时浏览器本身也要启用 WebMCP。

不同浏览器的启用方式不同：Chromium 需要在启动时加上 --enable-features=WebMCP 参数；Firefox 需要同时设置 dom.modelcontext.enabled 和 dom.modelcontext.testing.enabled 两个偏好项；WebKit 目前尚未实现该功能。

另一个容易踩坑的地方是 frame 的选择。page.webmcp 对应的是主 frame 的实例，如果工具是在子 frame 中注册的，你需要使用该 frame 自己的 frame.webmcp 实例。选错 frame 会直接导致工具列表为空——但这并不一定意味着你的测试环境有问题，也可能只是你查错了地方。

输入 schema 通常以 JSON Schema 的形式描述工具期望接收的参数，包括参数名、类型、是否必填以及约束条件。Playwright 的 tools() 返回的输入结构正是这份声明的映射。测试时校验 schema 的意义在于：AI 代理是依据 schema 来构造调用参数的，如果 schema 与实际实现不一致（例如声明了可选参数但实现中必填），代理在真实运行时就可能构造出失败的调用。因此 schema 校验不仅是文档层面的检查，也是代理能否成功调用工具的前提条件。

列出工具：先确认页面上有什么

tools() 返回指定 frame 中当前注册的工具列表。拿到列表后，应该逐一比对工具名称、描述和输入结构是否符合应用的设计意图。输入 schema 描述了工具期望接收的参数，这部分信息同样需要验证。

这里有一个安全相关的细节值得留意：页面提供的名称、描述、输入规则以及注解（annotations）都应当被视为不可信输入。注解中标注某个操作是“只读”的，仅仅是页面给出的一个提示，并不能证明该操作真的不会修改数据。测试时需要以实际行为为准，而不是轻信这些声明。

如果发现工具缺失，排查顺序建议是：先确认 frame 选择是否正确，再检查注册时机，最后确认应用是否真的注册了该工具。另外，当浏览器不支持 WebMCP 时，tools() 也可能抛出异常，这需要在测试中妥善处理。

调用工具：验证返回值与状态变化

callTool() 用于调用指定 frame 中的具名工具。选择动作时，应挑选那些在你自己的应用中有已知预期结果的操作，并按照其 schema 提供输入。调用返回的结果由页面上的工具提供。

以原文的配送日期查询为例：假设订单 1043 的配送日期是 10 月 16 日，调用该订单号的查询工具后，将返回结果与已知日期比对，同时确认相关记录没有被意外修改。如果调用的是会变更数据的操作，则需要在调用后读取已保存的记录，检查预期变更是否生效，并确认其他记录未受影响。

需要明确的是，返回值只能说明工具“回答了”，并不能证明答案正确或更新已经持久化。保存时机应遵循应用自身的文档说明。对于会修改数据的操作，应使用受控记录，避免触碰真实购买和客户通知等敏感流程。

测试场景	Playwright 暴露的内容	应检查的要点
工具与输入均合法	页面返回的结果	预期内容及相关应用状态
工具返回 isError: true	一个错误结果	报告的错误信息及状态是否符合预期
工具名称未注册	异常，报告执行失败	预期的注册情况及报告的错误
工具回调抛出异常	异常，报告执行失败	报告的错误及最终应用状态

最后两种场景都会以异常形式失败，但异常本身无法区分具体原因。需要结合已注册的名称和你所构造的受控失败场景来定位问题。

工具结果中的 isError: true 是 MCP 协议约定的一种应用层错误表达：调用在协议层面成功返回，但工具自身报告执行失败。这与调用未注册的工具名或工具回调直接抛出异常有着本质区别——后两者在 Playwright 一侧表现为调用异常。区分这两类失败对测试很重要：isError 属于被测试应用需要正确处理并上报的业务结果，而异常更多指向调用契约被破坏。设计用例时应分别覆盖，避免把两者混为一谈而掩盖真实缺陷。

不要丢掉常规页面测试

WebMCP 测试回答的是“AI 面向的操作报告了什么、改动了什么”，它不能替代人类用户的完整浏览器旅程测试。可见控件、提示消息以及端到端的用户任务，仍然需要独立的测试覆盖——这些检查回答的是另一个问题：一个人能否通过页面完成任务。

一份可落地的检查清单

针对启用了工具页面的应用，可以从以下六个问题入手：

1. 工具在哪个 frame 注册？当前浏览器是否启用了 WebMCP？
2. tools() 是否显示了预期的动作和输入结构？
3. 对已知输入，callTool() 是否返回了预期内容？
4. 应用状态是否与该结果一致？
5. 返回错误、未知名称、回调失败三种情况分别表现如何？
6. 常规页面控件是否仍能支撑用户完成任务？

这份清单可以作为 Playwright 1.64 下 WebMCP 测试的起点，具体的预期结果需要根据你的应用契约来调整。