Playwright E2E MCP

playwright-e2e-mcp

AI Agent 的测试医生。
你的 Playwright 测试失败了。你的 AI 会查明原因、修复问题，并验证修复有效。

⭐ 如果它帮你省下了一次调试，点个星标，让更多 Playwright 用户发现它。

快速开始 · 工具 · 工具参考 · GitHub Action · 配置 · 更新日志 · 参与贡献

这是一个 MCP 服务和 Agent 技能，为你的 AI 助手 （Claude、Cursor、VS Code Copilot、Gemini、Codex）提供完整的 Playwright 工具包：测试运行器、 失败侦查工具和能检查自身工作结果的修复工具。其他工具让 AI 在浏览器里四处点击，而这个工具能让它保持你的测试套件全部通过。

❌ 没有它 / ✅ 有它

没有它，你的 Agent 看到 Timeout 5000ms exceeded waiting for getByTestId('checkout')， 就猜一个新选择器、修改测试，然后祈祷能成功。或者，它会围绕真实缺陷“修复”测试。

有了它，你的 Agent 会读取测试失败时的页面状态，换成一个已验证在该页面上唯一的定位器， 重新运行测试，并且只有测试通过才保留修改。如果按钮真的不见了，它会告诉你这是应用程序的缺陷。

run-test ──────┐
load-report ───┴─▶ get-failure ──▶ suggest-fix (apply + re-run) ──▶ green
 (CI job report)        │                 └─ refuses when the element is really gone (app bug)
                        └─ DOM at failure, failed requests, console errors
every run ──▶ analyze-history (flaky / broken / slow / which commit broke it)
test code ──▶ audit-tests (flake risks, ranked by history, verified rewrites)
red at HEAD ─▶ bisect-failure (runs it across git history, names the breaking commit)

主要功能

• 修复有验证，不靠猜测。 每次修复都会重新运行测试，通过后才保留；如果测试仍然失败，就会撤销修复。
• 诚实可靠。 不会掩盖真正的 Bug 来让测试通过。
• 也适用于 CI 失败。 加载 CI 作业的报告和跟踪记录，即可获得相同的诊断和修复。
• 有证据的脆弱性分析。 指出脆弱测试的名称、问题是竞态、共享状态还是测试顺序，以及能复现问题的种子值。
• 轻量。 使用 core 工具集时，查找并修复失效定位器约耗费 5,500 个令牌；使用 Playwright MCP 加 shell 则约耗费 7,900 个令牌。全部 19 个工具的定义会为每个请求增加约 16k 个令牌，因此只加载你会用到的配置方案（参见基准测试）。
• 免费且开源。 采用 MIT 许可证，无需账户或 API 密钥，也不收集遥测数据。所有工具均免费；可选的付费 Pro 仅增加托管 CI 历史记录功能。

🚀 只有这个 MCP 能做到的事

大多数测试 MCP 都能让 AI 操控浏览器：Microsoft 的 Playwright MCP、Chrome DevTools MCP、 ExecuteAutomation 的 mcp-playwright 和 Selenium MCP。它们都很适合用来点击浏览页面。截至 2026 年 10 月，它们都无法做到以下这些事，而这个 MCP 可以：

它与浏览器 MCP 配合使用，而不是取代后者：浏览器 MCP 操控页面，这个 MCP 则确保测试套件保持全绿。

可以让它做什么

要求

• Node.js 22 或更高版本
• 使用 @playwright/test 的项目，并已安装浏览器（npx playwright install chromium）
• Claude Code、Claude Desktop、Cursor、VS Code、Windsurf、Codex、Gemini CLI 或任何其他 MCP 客户端

开始使用

**最快方式：**在项目根目录运行以下命令。它会将服务添加到找到的每个客户端配置中 （Claude Code、Cursor、VS Code、Gemini CLI、Codex），并安装 Agent 技能，不会影响你的 其他服务：

npx -y playwright-e2e-mcp init            # --client all | cursor,vscode … · --dry-run
npx -y playwright-e2e-mcp doctor          # checks Node, Playwright, browsers and client setup

**或者让你的 Agent 来安装。**将以下内容粘贴到任意编码 Agent 中：

按照以下说明安装 playwright-e2e-mcp 服务和技能： https://raw.githubusercontent.com/xsignon-secure/E2E/main/llms-install.md

标准配置适用于大多数客户端：

{
  "mcpServers": {
    "playwright-e2e": {
      "command": "npx",
      "args": ["-y", "playwright-e2e-mcp"]
    }
  }
}

该服务会将其工作目录用作项目根目录。如果你的客户端在其他位置（例如你的主目录）启动它， 请添加 "env": { "PW_MCP_PROJECT_ROOT": "/path/to/your/project" }。

/plugin marketplace add xsignon-secure/E2E
/plugin install playwright-e2e-mcp@xsignon-secure

claude mcp add playwright-e2e -- npx -y playwright-e2e-mcp

code --add-mcp '{"name":"playwright-e2e","command":"npx","args":["-y","playwright-e2e-mcp"]}'

codex mcp add playwright-e2e -- npx -y playwright-e2e-mcp

[mcp_servers.playwright-e2e]
command = "npx"
args = ["-y", "playwright-e2e-mcp"]
startup_timeout_sec = 60
tool_timeout_sec = 600

gemini extensions install https://github.com/xsignon-secure/E2E

你的第一个提示词

重启客户端，然后询问：

Run my Playwright tests and fix whatever fails.

你的 Agent 应运行测试套件、读取失败信息，并提出一个已重新运行验证过的修复方案。如需在没有自己的测试时检查配置，请让它运行此代码库中的 examples/sample-test.spec.ts。

0.7 版新功能

• 安全地登录一次： save-login 使用从环境中读取的密钥登录（包括 2FA 验证码），验证会话并将其保存为 storageState 文件；会话失效前会重复使用。
• 防护修复回退： check-test-change 和 playwright-e2e-mcp guard 会阻止通过减少检查来通过测试的“修复”（例如删除断言、跳过测试、使用 .only）。
• 隔离不稳定测试： quarantine 会在指定时间内阻止已知的不稳定测试导致构建失败，并记录负责人和原因，同时继续运行并报告该测试。

0.6 版新功能

• 找出导致测试失败的提交： bisect-failure 会在临时工作树中跨 Git 历史运行测试，并指出第一个有问题的提交、该提交的变更以及当时的失败情况。
• 不稳定风险审计： audit-tests 会找出硬等待、一次性断言、缺少 await 和脆弱的选择器，按实际不稳定程度排序，并应用安全的改写后运行验证。
• 一键修复拉取请求： GitHub Action 会在 CI 中验证每项修复，并以建议的变更形式发布。
• doctor： npx playwright-e2e-mcp doctor 会检查 Node、Playwright、浏览器和客户端设置。
• 结构化结果： 每个工具都会返回 JSON 和 Markdown，并附带输出架构。
• 手机、平板、Chrome 和 Edge： 所有页面工具均支持 device 预设和 channel，并提供托管在 ghcr.io 的 Docker 镜像。
• 现在要求使用 Node 22 或更高版本，托管端点也会限制对其密钥的猜测。

所有发行说明

工具

所有参数和输出示例都在**工具参考**中。所有工具都带有 MCP 工具注释（readOnlyHint、destructiveHint，……），因此客户端可以展示准确的安全提示。

只需要修复循环？ --tools=core（或 PW_MCP_TOOLS=core）会开放七个工具，并将工具定义上下文减少约四分之三。其他配置：triage、inspect、author。

CI：GitHub Action 和 ci 命令

无需 Agent 也能运行相同的诊断。playwright-e2e-mcp ci 会运行套件（自动重试一次，因此偶发测试会报告为偶发，而不是失败），可选择为失败项生成 suggest-fix 差异和偶发性判定，并将一份 Markdown 报告写入标准输出、--output 指定的位置，以及设置了 GITHUB_STEP_SUMMARY 时的 GitHub 作业摘要。退出码：0 表示通过，1 表示测试失败，2 表示运行本身失败。

npx -y playwright-e2e-mcp ci --flaky-runs 3 --suggest 2 --output report.md
npx -y playwright-e2e-mcp ci --help

作为 GitHub Action，它会将报告添加到作业摘要中，并在运行失败时持续更新一条 PR 评论。在拉取请求中，它还会使用建议的修复重新运行每个失败的测试，并将通过的修复作为失败代码行上的建议更改发布，这样审查者可以点击提交建议按钮来应用（仅限 PR 中更改过的代码行；其余内容仍保留在报告中）：

permissions:
  contents: read
  pull-requests: write   # for the PR comment and the suggested fixes
steps:
  - uses: actions/checkout@v6
  - uses: actions/setup-node@v6
    with: { node-version: 24 }
  - run: npm ci && npx playwright install --with-deps chromium
  - uses: xsignon-secure/[email protected]
    with:
      flaky-runs: 3      # 0 skips the flaky verdict
      suggest: 2         # suggest-fix diffs for the first 2 failures
      # args: --browser chromium tests/checkout

完整且可直接复制的工作流见 examples/github-actions/playwright-e2e.yml，其中包括产物上传，以及 guard: true 和 Pro Cloud 的注释选项。

输入：project-root、args、flaky-runs、suggest、comment、review、 verify-fixes、guard、pro-key、pro-url、fail-on-failure、version、github-token。输出：exit-code、 report、guard。

此处同样会遵循隔离测试（playwright-quarantine.json，见 quarantine）：如果所有失败项都已隔离且尚未过期，ci 会以 0 退出，并在报告中列出这些测试。

CI 中的修复防护。 guard: true 会先对照基础分支检查 PR 中更改的测试；如果测试是通过减少检查内容而通过的，则作业会失败。不使用 Action 时：

npx -y playwright-e2e-mcp guard --base origin/main   # exit 1 on BLOCK; --strict fails on warnings too

配置

{"time":"2026-10-07T08:00:00.000Z","level":"info","message":"server ready","name":"playwright-e2e-mcp"}

基准测试

bench/token-benchmark.mjs 会破坏商店页面中结账按钮的测试 ID，并通过两种方式修复：使用此服务（run-test → suggest-fix → 应用）和使用 Playwright MCP 加 shell（playwright test、browser_navigate + browser_snapshot、编辑、重新运行）。最新结果（完整输出）：

Token 数量按字符数 ÷ 4 计算。此处实际工作（运行、诊断、修复、验证）约需 700 个 token，而使用 Playwright MCP 则约需 2,600 个；但工具定义会随每次请求发送：加载全部 19 个工具时，定义所占用的 token 会超过节省的数量，因此，如果只修复失败的测试，请设置 PW_MCP_TOOLS=core（或其他配置）。Playwright MCP 方案提供的是较低估值：它假设 Agent 首次尝试就能从快照中选出正确的定位器，而此处服务能代为完成。使用 0.7.0 和 Playwright 1.64.1，于 2026-10-28 运行；可通过 npm run build && node bench/token-benchmark.mjs 重新运行。

演示

通过 stdio 调用 npx -y playwright-e2e-mcp，针对捆绑的 examples/sample-test.spec.ts 运行真实的 run-test（实际输出，未经编辑）：

免费且开源

• 采用 MIT 许可证。 可使用、修改，并用于商业项目；不收取费用，也不会限制任何功能。可选的 Pro 方案提供托管服务（跨机器的 CI 运行历史），不包含工具；此处的任何功能都不需要 Pro。
• 无需账户、API 密钥或注册。 运行 npx -y playwright-e2e-mcp init 即可完成全部设置。
• 无遥测。 它不会向外发送任何数据；除非设置 Pro 密钥并上传，否则测试、跟踪记录和运行历史都保留在本机。
• 依赖项均免费： MCP SDK（Apache-2.0）、zod（MIT）、axe-core（MPL-2.0），以及项目已有的 Playwright（Apache-2.0）。
• 也可免费自行托管： HTTP 桥接服务可部署到免费的 Vercel 账户（请参阅托管端点）。

它不会做什么： 它不会逐步驱动探索式浏览会话，也不会取代 VS Code 中 Playwright 自带的 Test Agents。交互式浏览请使用 Playwright MCP，运行、诊断和修复测试套件请使用此服务。两者可以配合使用。

更多文档

• 工具参考：每个参数、输出示例及已处理的边缘情况
• 托管端点：供 ChatGPT 和 claude.ai 连接器使用的 HTTP 桥接服务
• 安全：安全模型及漏洞报告方式
• 开发：构建、测试、Docker、签名和发布
• 贡献指南 · 行为准则

许可证

MIT。如果它帮你省下了一次调试，不妨给仓库点个 ⭐，让更多 Playwright 用户发现它。