Playwright Autopilot

正在使用 Selenium、Cypress 或 WebDriverIO？ E2Epilot 为 6 种框架（包括 Selenium Java、SeleniumBase 等）带来了相同的 AI 分诊引擎。 网站：e2epilot.com | npm：@e2epilot/cli

这是一个 Claude Code 插件，可以自主调试并修复 Playwright E2E 测试。它通过完整的操作捕获（DOM 快照、网络请求、控制台输出、截图）来运行测试，然后像高级 QA 工程师一样调查故障并提交修复方案。

https://github.com/user-attachments/assets/26f734a5-d05e-41c9-bc3f-2b58561c2ce0

快速入门

# Add the marketplace
/plugin marketplace add kaizen-yutani/playwright-autopilot

# Install the plugin
/plugin install kaizen-yutani/playwright-autopilot

然后让 Claude 修复失败的测试或对整个测试套件进行分诊：

/playwright-autopilot:fix-e2e tests/checkout.spec.ts
/playwright-autopilot:triage-e2e e2e

或者只需描述您的需求——Claude 将自动使用 MCP 工具：

Fix all failing e2e tests in the "e2e" project

Related MCP server: Browser Testing MCP Server

功能特性

测试运行期间的每一个浏览器操作都会被捕获，包括：

• 操作前后的 DOM 快照 — 每次点击、填充、导航前后页面的 aria 树

• 网络请求 — URL、方法、状态、耗时、请求/响应体

• 控制台输出 — 与产生这些输出的操作相关联的错误、警告和日志

• 截图 — 在故障点捕获

当测试失败时，Claude 不会进行猜测——它会读取实际的页面状态，检查失败的 API 调用，并通过操作时间轴追踪根本原因。

工作原理

1. 捕获钩子 (Capture Hook)

一个轻量级的 CJS 钩子 (captureHook.cjs) 通过 NODE_OPTIONS --require 注入到 Playwright 的测试工作进程中。它通过 monkey-patch 修改 BrowserContext._initialize，添加一个仪器监听器，以完整的上下文捕获每个浏览器操作。无需修改 Playwright 源代码——适用于任何 Playwright 安装。

2. MCP 工具

该插件通过 Model Context Protocol 暴露了 37 个工具，供 Claude 按需调用。这种设计具有极高的 Token 效率——Claude 不会将整个追踪记录转储到上下文中，而是只提取它需要的内容：

测试执行与调试：

交互式浏览器探索：

browser_* 工具会启动一个真实的 Chrome 实例，让 Claude 交互式地探索您的应用程序——导航页面、点击元素、填充表单，并通过 ARIA 快照观察页面状态。每次交互都会返回时间、网络请求、DOM 变化和更新后的快照。在编写测试前使用此功能了解应用、直观地调试 UI 问题或验证修复方案。

3. 流程记忆 (Flow Memory)

在修复（或验证）测试后，插件会保存确认的应用程序流程——即构成成功路径的一系列用户交互。这些流程持久化在 .e2e-flows.json 中，并在会话间累积。

下次测试中断时，Claude 已经了解预期的用户旅程，并直接识别出发生了什么变化。代理会随着时间的推移变得越来越智能。

4. 不稳定检测 (Flaky Detection)

两种用于识别不稳定测试的互补模式：

retries: N — 在独立的 Playwright 进程中运行测试 N+1 次。每次运行都有自己的 runId 和完整的操作捕获。返回结论：FLAKY（不稳定）、CONSISTENT PASS（持续通过）或 CONSISTENT FAIL（持续失败）。最适合使用 2-3 次重试进行调试。

e2e_run_test(location: "tests/checkout.spec.ts:15", retries: 2)

repeatEach: N — 原生 Playwright --repeat-each。所有迭代在同一个进程中运行。用于确认不稳定性的快速压力测试——建议使用 30-100 次以确保置信度。

e2e_run_test(location: "tests/checkout.spec.ts:15", repeatEach: 40)

5. 证据包 (Evidence Bundles)

e2e_get_evidence_bundle 将所有故障证据打包成一个响应——错误、重现步骤、操作时间轴、带有请求体的失败网络请求、控制台错误、DOM 快照和截图。无需分别调用 6 个以上的工具。

传入 outputFile: true 可将 markdown 文件写入 test-reports/ 以便作为 Jira 附件。

6. HTML 报告

批量运行（无 location 参数）会自动生成一个独立的 HTML 报告，包含：

• 带有状态徽章的通过/失败摘要

• 可折叠的每个测试部分

• 操作时间轴、失败的网络请求、控制台错误

• 故障点的 DOM 快照

• 作为内联 base64 图片的截图

报告将写入 test-reports/report-<runId>.html。您也可以手动为任何运行调用 e2e_generate_report。

7. 套件分诊与健康跟踪

运行整个套件，对每次故障进行分类，并生成管理级报告：

/playwright-autopilot:triage-e2e e2e

Claude 将每次故障分类为 已知问题 (Known Issue)、应用 Bug (App Bug)、测试更新 (Test Update)、不稳定 (Flaky) 或 新故障 (New Failure)——关联 Jira 现有工单，为应用 Bug 创建带有证据包的新工单，并保存分诊运行记录以进行趋势跟踪。

e2e_get_stats 提供了一个套件健康仪表板——通过率趋势、按评分排名的不稳定测试、故障类别细分以及新故障——所有这些都基于本地历史记录，无需运行测试。

9. 覆盖率分析

e2e_suggest_tests 扫描您的整个项目以发现覆盖率差距：

1. 未测试的页面对象方法 — .page.ts / .service.ts 文件中没有被任何规范调用的方法

2. 缺失的流程变体 — 带有前置条件（例如“不存在草稿”）但缺乏后续变体的流程

3. 未覆盖的流程步骤 — 已确认流程中列出但没有任何规范执行的操作

10. 架构感知

在编写任何修复方案之前，插件会扫描您的项目以查找页面对象、服务层和测试夹具。它遵循您现有的模式：

• 使用您的 页面对象模型 (Page Object Model) 方法，而不是编写原始的 Playwright 调用

• 尊重您的 业务/服务层 分离

• 使用 getByRole()、getByTestId() 和 Web 优先的断言

• 生成 最小差异 (minimal diffs) — 通常只增加一两行代码

调试理念

该插件遵循严格的诊断方法论：

以用户流程而非选择器进行思考。 在触碰代码之前，它会映射预期的用户旅程。当某个步骤缺失时——例如从未选择下拉菜单、从未填充必填字段——它会找到现有的页面对象方法并添加调用。

四个根本原因类别：

1. 缺失测试步骤 — 测试跳过了应用程序所需的 UI 交互

2. 测试代码 Bug — 错误的选择器、过时的断言、错误的测试数据

3. 应用程序 Bug — 应用程序本身已损坏（已报告，而非绕过）

4. 脏状态 — 上次测试运行的残留物干扰了当前运行

拒绝黑客手段。 该插件绝不会使用 page.evaluate()、page.route()、page.addInitScript() 或任何 JavaScript 注入来绕过失败的测试。如果修复需要这些手段，说明解决的问题方向错了。

配置

多项目设置

如果您的 Playwright 项目所在的目录与 Claude Code 运行的目录不同，请在 .mcp.json 中设置 PW_PROJECT_DIR 环境变量：

{
  "mcpServers": {
    "playwright-autopilot": {
      "command": "node",
      "args": ["path/to/plugin/server/mcp-server.js"],
      "env": {
        "PW_PROJECT_DIR": "/path/to/your/playwright/project"
      }
    }
  }
}

要求

• Claude Code CLI

• Playwright 测试项目

• Node.js 20+

许可证

MIT