playwright-report-mcp

Playwright Report MCP

一个用于运行 Playwright 测试并读取结构化结果、失败测试详情和附件内容的 MCP（Model Context Protocol）服务，专为进行测试失败分析的 AI Agent 设计。

---

目录

• 它是什么
• 它不是什么
• 为什么
• 快速开始
• 工具
• 附件
• 安装
• 配置
• 要求
• 故障排除
• 开发
• 发布版本
• 贡献
• 发布
• 许可证

---

它是什么

Playwright Report MCP 为 AI Agent 提供结构化且节省令牌的方式，以访问 Playwright 测试结果。它运行测试套件、读取 JSON 报告器输出，并呈现 Agent 所需的确切信息：哪些测试失败、错误内容，以及相关附件的内容。

它不是什么

有许多 Playwright MCP 服务用于控制浏览器——它们可以浏览页面、点击元素、填写表单和截取屏幕截图。Playwright Report MCP 并非此类服务。

	浏览器自动化 MCP	Playwright Report MCP
示例	microsoft/playwright-mcp、executeautomation/mcp-playwright	本项目
目的	让 AI Agent 驱动浏览器	让 AI Agent 读取测试结果
运行测试	否	是
返回通过/失败结果	否	是
呈现错误消息	否	是
读取附件内容	否	是

---

为什么

现有方案的问题

默认报告器（list / dot）——Playwright 的默认报告器会将人类可读的输出打印到 stdout。输出简洁，但信息有损：没有附件路径、没有重试明细，也没有结构化数据。

HTML 报告器（report.html）——一个独立的 SPA 包（通常为 2–50 MB）。无法以文本形式供机器读取，且超出任何大模型的上下文窗口。

直接读取 results.json——虽然可行，但即使是小型测试套件，完整 JSON 报告也有 10,000–20,000 个令牌。对于失败测试，其中大部分都是你不需要的通过测试元数据。

Playwright Report MCP 的不同之处

• 只筛选 results.json 中的失败测试
• 返回 Agent 可立即采取操作的结构化、类型化 JSON
• 按名称提供单个附件，让 Agent 只获取所需内容
• 适用于任何人生成的测试结果——CI 流水线、人工或 Agent 自己

令牌成本对比（20 个测试套件中有一个测试失败）

基于 Claude 分词方式估算输入令牌数（对于混合 JSON/文本内容，每个令牌约对应 3–4 个字符）。

所需内容	不使用 MCP — 方式	令牌数（不使用 MCP）	使用 MCP — 工具调用	令牌数（使用 MCP）	节省
仅错误消息 — 实时运行	npx playwright test，读取 stdout（list/dot）	~500–1,200	run_tests + get_failed_tests	~300–500	~2×
仅错误消息 — 现有结果	读取完整的 results.json	~12,500–23,000	get_failed_tests	~300–500	~25–45×
+ 失败时的页面状态	+ 读取 error-context 文件	~15,000–26,000	+ get_test_attachment('error-context')	~2,800–3,500	~4–7×
+ 自定义文本附件¹	+ 读取附件文件	~16,200–28,500	+ get_test_attachment ×2	~3,300–5,500	~4–5×
+ 完整页面 HTML 快照²	+ 读取快照文件	~41,000–103,000	+ get_test_attachment	~33,300–85,500	~1.2×

¹ 自定义文本附件 — 例如通过你自己的 fixture 中的 testInfo.attach() 添加的 AI 诊断信息（约 500–2,000 个令牌）和控制台日志（约 200–500 个令牌）。

² 完整页面 HTML 快照 — 在失败时附加完整渲染页面 HTML 的自定义 fixture。仅大型页面就可能达到 30,000–80,000 个令牌，无论是否使用 MCP，都会占据主要成本。

主要观察：

• 对于实时运行，stdout（list/dot）内容精简，但无法让 Agent 获取附件内容，深入分析会陷入死路
• 即使只有一个测试失败，直接读取 results.json 也要花费约 12,500–23,000 个令牌，其中大部分是 Agent 不需要的通过测试元数据
• MCP 的最大优势体现在中间几行：从现有结果中获取错误消息和页面状态，令牌成本可降低 约 4–45 倍
• 无论采用哪种方式，完整页面 HTML 快照都会占据主要成本；改用 error-context 而跳过该快照，是目前最大的单项优化

CI 失败分析

主要用例：CI 流水线运行测试后，Agent 获取结果并诊断失败。无论由谁触发运行，get_failed_tests 都会读取 results.json。无需重新运行。

---

快速开始

1. 通过 npx 安装（推荐）

无需克隆或构建 — npx 会自动下载并运行服务：

{
  "mcpServers": {
    "playwright-report-mcp": {
      "command": "npx",
      "args": ["-y", "playwright-report-mcp"],
      "type": "stdio"
    }
  }
}

或者从源代码构建：

git clone https://github.com/hubertgajewski/playwright-report-mcp.git
cd playwright-report-mcp
npm install && npm run build

2. 将 JSON reporter 添加到你的 Playwright 项目

// playwright.config.ts
reporter: [
  ['json', { outputFile: 'test-results/results.json' }],
  ['html'], // keep any existing reporters
],

3. 在 .mcp.json 中注册

{
  "mcpServers": {
    "playwright-report-mcp": {
      "command": "npx",
      "args": ["-y", "playwright-report-mcp"],
      "type": "stdio"
    }
  }
}

4. 向你的 AI Agent 提问

运行 Playwright 测试，并告诉我哪些测试失败了。

---

兼容性

已通过 Claude Code（CLI） 测试。应该适用于任何支持 stdio 传输的 MCP 兼容客户端，包括 Claude Desktop、Cursor、Cline、Windsurf 和 Continue.dev — 但尚未对这些客户端进行验证。

stdio 服务通过单一入口点同时支持 MCP 协议的两个时期：

• **现代版：**协议修订版本 2026-07-28，由使用版本协商的客户端选择（例如 versionNegotiation: { mode: "auto" }）。
• **旧版：**支持 2025 年时期的修订版本，由使用传统 initialize 握手的客户端选择。这仍是 MCP client SDK 中的默认行为。

初始交互会为整个连接固定一个时期。若客户端固定使用不受支持的修订版本，则会收到明确的协商错误；服务不会悄悄切换到其他时期。

工具

项目范围的工具接受可选的 workingDirectory 参数——参见多工作树支持。get_run_status 可使用 run_tests 在 wait: false 时返回的 runId，也可通过 workingDirectory 查询最近一次跟踪的运行。

run_tests

运行 Playwright 测试套件，并返回结构化的通过/失败结果。

输入	类型	描述
workingDirectory	字符串（可选）	Playwright 项目目录。可使用绝对路径，或相对于 MCP 服务启动目录的路径。默认为 "."。必须位于 PW_ALLOWED_DIRS 之下——参见多工作树支持。
spec	字符串（可选）	相对于项目目录的规范文件路径，例如 tests/login.spec.ts。必须位于项目目录内。
browser	枚举（可选）	Chromium、Firefox、Webkit、Mobile Chrome、Mobile Safari
tag	字符串（可选）	标签筛选器，例如 @smoke
timeout	整数（可选）	整个测试运行的超时时间，单位为毫秒。默认为 300000（5 分钟）。长测试套件可设置更大的值，想要快速失败则设置较小的值。如果运行因超时而终止，工具会返回明确的错误，而非通用的非零退出码。
wait	布尔值（可选）	返回前是否等待完成。默认为 true。设为 false 可启动后台运行，并通过 get_run_status 轮询状态。
updateSnapshots	枚举（可选）	更新快照基线。可选值为 all、changed、missing、none。Playwright 默认值为 missing；changed 会更新有差异的基线以及缺失的基线。省略此项则保留现有基线。
headed	布尔值（可选）	使用可见的浏览器窗口运行。省略此项或设为 false，都不会修改 playwright.config.ts——Playwright 没有 --no-headed 标志，因此如果配置中设为 headed，false 不会强制启用无头模式。
workers	整数（可选）	并行工作线程数。仅支持正整数；暂不支持 "50%" 字符串格式。
retries	整数（可选）	不稳定测试的最大重试次数。0 表示明确禁用重试；省略此项则使用项目配置。
maxFailures	整数（可选）	达到此失败次数后停止运行。必须为正整数。
env	对象（可选）	合并到 Playwright 子进程环境中的字符串到字符串映射。每个键都必须列在 PW_ALLOWED_ENV 中。始终拒绝危险名称和机密名称。参见环境变量覆盖。
trace	枚举（可选）	强制指定 Playwright 跟踪模式，覆盖 playwright.config.ts。可选值为 on、off、on-first-retry、on-all-retries、retain-on-failure、retain-on-first-failure、retain-on-failure-and-retries。
返回：退出码、运行统计信息，以及各项目中所有测试的状态、耗时和错误摘要。

当 wait 为 false 时，会立即返回 runId、进程元数据、精简的数值进度和当前 results.json 状态。使用该 runId 轮询 get_run_status，直到 state 为 completed、failed 或 timedOut。服务会解析 stdout 中类似 [528/662] 的 Playwright 进度标记，并丢弃原始 stdout/stderr 文本，以便重复轮询时节省令牌。每个工作目录最多允许一个正在跟踪的运行，全局活动跟踪运行数设有上限，并会保留数量有限的近期终止运行记录，因此非常旧的 runId 可能会过期。

get_run_status

返回由 run_tests 以 wait: false 启动的非阻塞运行的当前状态。

输入	类型	描述
runId	string（可选）	run_tests wait=false 返回的运行标识符。提供此参数时，将选择指定的跟踪运行。
workingDirectory	string（可选）	如果省略 runId，则返回该目录中最新的跟踪运行；如果没有匹配项，则返回 idle。与 runId 一起提供时，必须与该运行的目录匹配。

如果两个字段都省略，workingDirectory 默认为 "."。如果解析后的目录中没有跟踪的运行，工具会返回 state: "idle"，以及 results.json 元数据和可读取时的上次解析统计信息。它不会扫描进程来查找未通过此 MCP 服务启动的外部 npx playwright test 命令。

返回：运行状态、跟踪标记、pid、时间戳、已耗时长、超时时间、命令元数据（executable、args、cwd）、可选的 envKeys（仅覆盖名称，不包含值）、progress: { current, total }、退出码、信号、存在时的启动/超时错误、results.json 的路径/是否存在/修改时间/大小/是否为最新，以及运行启动后报告更新时解析出的报告统计信息。如果尚未出现进度，current 和 total 为 null；如果终止运行有可读取的最终统计信息，则会将进度设为推导出的已完成总数。

get_failed_tests

返回上次运行中的失败测试及其错误消息和附件路径。不会重新运行测试，而是读取现有的 results.json。

输入	类型	描述
workingDirectory	string（可选）	参见多工作树支持。默认为 "."。

返回：失败测试数量、标题、文件路径、各项目状态、错误消息和附件路径。

get_test_attachment

读取上次运行中特定测试的指定文本附件内容。

输入	类型	说明
workingDirectory	string（可选）	请参阅多工作树支持。默认为 "."。
testTitle	string	报告中显示的准确测试标题
attachmentName	string	附件名称，例如 error-context、ai-diagnosis、page-html

返回：附件文本内容。二进制附件和超过 1 MB 的文件会被拒绝，并返回错误。如果 results.json 中记录的附件路径逃逸出 workingDirectory（通过 .. 或指向其他位置的绝对路径），则会被拒绝。

list_tests

列出所有测试及其规格文件和标签，不运行测试。

输入	类型	说明
workingDirectory	string（可选）	请参阅多工作树支持。默认为 "."。
tag	string（可选）	按标签筛选，例如 @smoke
env	object（可选）	与 run_tests 相同的子进程环境允许列表映射。请参阅环境覆盖。

---

附件

Playwright 会自动将文件附加到失败的测试。get_test_attachment 可以按名称读取任何文本附件。

附件名称	来源	每个项目都包含
error-context	Playwright 内置 — 失败时的 YAML 无障碍树快照	是
screenshot	Playwright 内置 — PNG 截图（二进制，无法读取）	是
video	Playwright 内置 — WebM 视频（二进制，无法读取）	是
自定义附件	通过 fixture 中的 testInfo.attach() 添加	取决于项目

对于没有自定义 fixture 的项目，error-context 附件最实用 — 无需任何设置，即可在失败时提供页面的语义化结构视图。

---

安装

通过 npx（推荐） — 使用快速开始中所示的 npx 配置。无需本地安装。

从源代码安装：

git clone https://github.com/hubertgajewski/playwright-report-mcp.git
cd playwright-report-mcp
npm install
npm run build

---

配置

在项目根目录的 .mcp.json 中添加：

{
  "mcpServers": {
    "playwright-report-mcp": {
      "command": "npx",
      "args": ["-y", "playwright-report-mcp"],
      "type": "stdio"
    }
  }
}

环境变量

变量	默认值	说明
PW_ALLOWED_DIRS	"."（仅授权启动目录）	以 path.delimiter 分隔的目录列表，workingDirectory 参数可指向这些目录。条目可以是绝对路径或相对路径（启动时会基于启动时的工作目录解析一次）。
PW_ALLOWED_ENV	未设置（禁用 env 工具参数）	以逗号分隔的环境变量名称列表，run_tests 和 list_tests 可覆盖这些变量。未设置或为空时，会拒绝任何 env 参数且不会启动子进程。请参阅环境变量覆盖。
PW_RESULTS_FILE	<workingDirectory>/test-results/results.json	JSON 报告器输出文件的绝对路径。设置后，将覆盖每次调用的默认值。

如果 playwright.config.ts 将报告写入非默认位置，请设置 PW_RESULTS_FILE。在多工作树配置中，请保持未设置，这样每个 workingDirectory 都会有自己的 test-results/results.json。

多工作树支持

run_tests、list_tests、get_failed_tests 和 get_test_attachment 都接受可选的 workingDirectory 参数——可以是绝对路径，也可以是相对于 MCP 服务启动目录的路径。若省略 runId，get_run_status 也接受 workingDirectory；若提供了 runId，则任何提供的 workingDirectory 都必须解析为该运行记录的目录。这样，单个长期运行的 MCP 会话无需重启即可在多个 git 工作树中运行测试。

由于 Playwright 配置是一个会在 playwright test 启动时执行的 Node 模块，服务会使用允许列表限制该参数。将 workingDirectory 指向 PW_ALLOWED_DIRS 以外目录的调用方会收到结构化错误，且不会启动子进程。

默认设置（无工作树）。 保持 PW_ALLOWED_DIRS 未设置。允许列表将变为 "."，即仅允许启动目录；默认的 workingDirectory（同样为 "."）也会解析为启动目录。无需任何配置。

同级工作树。 在 .mcp.json 中设置 PW_ALLOWED_DIRS=".."，即可授权启动目录的所有同级目录。相对条目会在启动时基于启动时的工作目录解析，因此所有贡献者都可以使用同一个 .mcp.json，无需写入绝对路径：

{
  "mcpServers": {
    "playwright-report-mcp": {
      "command": "npx",
      "args": ["-y", "playwright-report-mcp"],
      "env": { "PW_ALLOWED_DIRS": ".." },
      "type": "stdio"
    }
  }
}

然后将调用指向任意同级工作树：

{
  "name": "run_tests",
  "arguments": { "workingDirectory": "../my-app-feat-auth" },
}

多个项目。 可以从每个项目启动 MCP 客户端并使用默认允许列表，也可以将 PW_ALLOWED_DIRS 设置为共同的父目录，并在每次调用时传入 workingDirectory。允许列表检查会在路径段边界进行，因此授权 /src/my-app 的条目不会授权 /src/my-app-evil。

重大变更（2.x → next）： 已移除 PW_DIR 环境变量。请从 Playwright 项目目录内启动 MCP 客户端（无需配置，默认 workingDirectory: "." 即可），或在每次调用时传入 workingDirectory 并相应设置 PW_ALLOWED_DIRS。

环境覆盖项

run_tests 和 list_tests 接受可选的 env 映射。启动 Playwright 前，该映射会合并到 MCP 进程环境中。因此，子进程会在启动环境和父进程环境的基础上，看到操作员允许的覆盖项。若 Playwright 配置加载 dotenv 时不覆盖已有变量，则会保留工具提供的值。

只有操作员在 .mcp.json 中设置 PW_ALLOWED_ENV 后，env 参数才会启用。这与 PW_ALLOWED_DIRS 使用相同的限制模式：由人工扩大模型可执行操作的范围；模型无法自行扩大范围。

硬性拒绝名单始终优先于允许名单（比较时不区分大小写）：

• 前缀 NODE_、LD_、DYLD_、NPM_CONFIG_（子进程通过 npx 启动，npx 会从环境中读取 npm 配置）
• PATH、HOME、DOTENV_CONFIG_PATH
• 代理变量 HTTP_PROXY、HTTPS_PROXY、ALL_PROXY、NO_PROXY、FTP_PROXY
• 名称中匹配 PASSWORD、SECRET、TOKEN、API_KEY、ACCESS_KEY、CREDENTIAL、PRIVATE_KEY、AUTH_SOCK 或 AUTH_CONFIG 的任意变量

键必须是 POSIX 名称（^[A-Z_][A-Z0-9_]*$）。值不能包含 NUL，长度最多为 256 个字符，每次调用最多包含 16 个条目。ENV 的值还受到 ^[A-Za-z0-9._-]+$ 的限制，因此不能将其用作 POSIX shell 启动文件路径（ENV=/tmp/evil.sh 会被拒绝）。

机密信息（基本身份验证、密码、API 密钥）应保留在项目的 .env 文件或 MCP 启动环境中，绝不能作为工具参数传递。get_run_status 可以将覆盖项的名称列为 envKeys，但绝不会回显覆盖项的值。工具参数中没有 envFile。

目标环境名称（ENV=staging）：

{
  "mcpServers": {
    "playwright-report-mcp": {
      "command": "npx",
      "args": ["-y", "playwright-report-mcp"],
      "env": {
        "PW_ALLOWED_DIRS": "..",
        "PW_ALLOWED_ENV": "ENV"
      },
      "type": "stdio"
    }
  }
}

{
  "workingDirectory": "playwright/typescript",
  "env": { "ENV": "staging" }
}

其他项目开关（TEST_ENV 或 BASE_URL）：

{
  "mcpServers": {
    "playwright-report-mcp": {
      "command": "npx",
      "args": ["-y", "playwright-report-mcp"],
      "env": { "PW_ALLOWED_ENV": "TEST_ENV,BASE_URL" },
      "type": "stdio"
    }
  }
}

{ "env": { "TEST_ENV": "qa" } }

{ "env": { "BASE_URL": "https://stage.example.com" } }

---

要求

• Node.js 22+
• @playwright/test 1.40 或更高版本
• 在 Playwright 项目中配置 JSON 报告器

Playwright 的默认报告器（本地使用 list，CI 上使用 dot）只会写入标准输出，不会生成可在运行结束后读取的文件。请在现有报告器之外添加 JSON 报告器：

// playwright.config.ts
reporter: [
  ['json', { outputFile: 'test-results/results.json' }],
  ['html'],  // keep any existing reporters
  ['list'],
],

---

故障排除

No results.json found — run tests first

未配置 JSON 报告器，或报告器正在写入其他路径。请确认 playwright.config.ts 中有 ['json', { outputFile: 'test-results/results.json' }]。

list_tests parsed 0 tests from non-empty output

你所用 Playwright 版本的 --list 输出格式可能已更改。请提交 issue，并附上 Playwright 版本和原始标准输出。

Attachment "..." is binary and cannot be returned as text

screenshot 和 video 附件是二进制文件。使用 get_failed_tests 获取附件路径，并根据需要直接打开文件。

Attachment "..." is too large to return inline

附件超过 1 MB。请根据 get_failed_tests 返回的路径直接读取文件。

---

开发

npm test          # run tests once
npm run test:watch  # watch mode

运行时代码位于 src/ 下，并编译到 dist/。测试使用 Vitest，通过针对性单元测试覆盖辅助函数，并通过 InMemoryTransport 覆盖 MCP 工具集成。运行常规测试套件无需构建，也无需安装 Playwright。

---

发布版本

推送 v* 标签即可发布版本。.github/workflows/release.yml 会获取该标签，验证标签与全部三个版本字段一致，运行 npm ci、npm run build 和 npm test，根据 .github/release.yml 的分类（功能／错误修复／文档／依赖项／其他更改）自动生成发布说明并创建 GitHub Release，然后发布到 npm。.github/workflows/publish-mcp.yml 随后通过 workflow_run 接续 Release 工作流，将 server.json 发布到 MCP 注册表。合并到 main 不会触发发布。

版本号在三个位置，推送标签前这三处必须全部与标签一致：

• package.json → version
• server.json → 顶层 version
• server.json → packages[0].version

在一个 PR 中更新这三个版本号，并在发布前合并到 main。如果标签与其中任何一个值不一致，release.yml 就会导致工作流运行失败。

发布流程：

# After the version-bump PR has merged to main:
git checkout main && git pull
git tag v1.0.5
git push origin v1.0.5
# → release.yml fires: verifies tag, builds, tests, creates GitHub Release, publishes to npm
# → publish-mcp.yml chains off Release and publishes server.json to the MCP registry

步骤：

1. 创建一个更新全部三个版本字段的版本更新 PR，并将其合并到 main。
2. 为版本更新提交打上 v<version> 标签，并推送该标签。
3. release.yml 验证标签与版本号一致，运行 npm ci，确认该版本尚未发布到 npm，运行 npm run build 和 npm test，创建 GitHub Release，然后使用 npm publish --access public --provenance 发布到 npm。
4. publish-mcp.yml（由 Release 上的 workflow_run 触发）会再次验证版本字段，确认该版本尚未发布到 MCP 注册表，然后将 server.json 发布到 registry.modelcontextprotocol.io。

无需仓库密钥。 npm 和 MCP 注册表都通过 GitHub OIDC 进行身份验证（npm 受信任的发布者）。npm 的受信任发布者需在 npmjs.com 上的包设置中配置，路径为 Settings → Publishing access → Trusted Publisher；无需也不存在 NPM_TOKEN 密钥。

发布失败后的恢复： npm 不允许重新发布已存在的版本，并且限制在 72 小时后取消发布。如果发布因任何原因失败，请在新的 PR 中将版本号提升到下一个补丁版本，然后发布新版本；不要尝试重新运行失败的发布流程。

---

贡献

有关错误报告、拉取请求、开发环境设置和提交规范，请参阅 CONTRIBUTING.md。

---

许可证

MIT — 版权所有 (c) Hubert Gajewski