Playwright Report MCP

编剧报告MCP

一个MCP（模型上下文协议）服务器，用于运行Playwright测试并读取结构化结果、失败的测试细节和附件内容，专为进行测试失败分析的AI代理而设计。

______________________________________________________________________

目录

• 这是什么
• 它不是什么
• 为什么
• 快速启动
• 工具
• 附件
• 安装
• 配置
• 需求
• 故障排除
• 发展
• 切割释放
• 贡献
• 发布
• 许可证

______________________________________________________________________

这是什么

编剧报告MCP 为AI代理提供结构化、令牌高效的Playwright测试结果访问。它运行您的测试套件，读取JSON报告器输出，并准确显示代理需要什么：哪些测试失败，错误是什么，以及相关附件的内容。

它不是什么

有许多Playwright MCP服务器控制浏览器——它们导航页面、单击元素、填写表单和截图。剧作家报告MCP不是其中之一。

______________________________________________________________________

为什么

现有方法的问题

默认报告器(list / dot) --Playwright的默认报告器将人类可读的输出打印到stdout。紧凑但有损：没有附件路径，没有重试故障，没有结构化数据。

HTML报告器 (report.html)--一个自包含的SPA包（通常为2-50MB）。不是机器可读的文本，并且超出了任何LLM上下文窗口。

阅读 results.json 直接 --可以，但即使是一个小型测试套件的完整JSON报告也需要10000-20000个令牌。对于失败的测试，其中大部分是通过您不需要的测试元数据。

剧作家报告MCP做了什么

• 过滤器 results.json 仅限于未通过的测试
• 返回结构化、类型化的JSON，代理可以立即对其执行操作
• 按名称显示单个附件，以便代理只获取它需要的内容
• 对任何人产生的结果都有效——CI管道、人类或代理本身

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

基于以下内容的大致输入令牌计数 克劳德标记化 （对于混合JSON/文本内容，每个令牌约3-4个字符）。

¹ 自定义文本附件 --例如，通过添加AI诊断（约500-2000个令牌）和控制台日志（约200-500个令牌） testInfo.attach() 在你自己的赛程中。 ² 全页HTML快照 --一个自定义夹具，在失败时附加完整的渲染页面HTML。无论是否使用MCP，仅大页面就可以达到30000-80000个代币，并主导成本。

主要观察结果：

• 对于实时运行，stdout(list/dot)结构紧凑，但无法让代理访问附件内容——这是深入分析的死胡同
• 阅读 results.json 即使只有一个测试失败，直接花费约12500-23000个令牌，其中大部分是通过代理不需要的测试元数据
• 最大的MCP增益在中间几行：从位于的现有结果中获取错误消息+页面状态 ~4–45倍的代币成本降低
• 无论哪种方式，全页HTML快照都占主导地位；跳过它以支持 error-context 是可用的最大单一优化

CI故障分析

主要用例：您的CI管道运行测试，代理在事后获取结果并诊断故障。 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报告器添加到您的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.问你的人工智能代理

运行剧作家测试，告诉我失败了什么。

______________________________________________________________________

兼容性

经过测试 克劳德代码（CLI）。应适用于任何支持stdio传输的MCP兼容客户端，包括Claude Desktop、Cursor、Cline、Windsurf和Continue.dev，但这些尚未经过验证。

______________________________________________________________________

工具

所有四个工具都接受可选 workingDirectory 参数--请参见 多工作台支架.

run_tests

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

返回：退出代码、运行统计数据以及所有测试的摘要，包括每个项目的状态、持续时间和错误。

get_failed_tests

返回上次运行失败的测试，并显示错误消息和附件路径。不重新运行测试--读取现有的 results.json.

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

get_test_attachment

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

返回：附件内容为文本。超过1 MB的二进制附件和文件因错误而被拒绝。附件路径记录在 results.json 逃跑 workingDirectory （通过 .. 或指向其他地方的绝对路径）被拒绝。

list_tests

列出所有测试及其规范文件和标签，而不运行它们。

______________________________________________________________________

附件

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

这 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_RESULTS_FILE 如果你的 playwright.config.ts 将报告写入非默认位置。在多工作台设置中保持未设置状态，以便每个 workingDirectory 得到自己的 test-results/results.json.

多工作台支架

run_tests, list_tests, get_failed_tests，以及 get_test_attachment 全部接受可选 workingDirectory 参数--绝对值，或相对于MCP服务器的启动目录。这使得一个长寿命的MCP会话可以在多个git工作树上进行驱动测试，而无需重新启动。

因为Playwright配置是一个节点模块，在 playwright test 启动时，服务器会用一个满列表来保护参数。打电话给这一点 workingDirectory 在外部目录中 PW_ALLOWED_DIRS 如果出现结构化错误，则不会生成子进程。

默认值（无工作树）。 离开 PW_ALLOWED_DIRS 未设置。对抗主义者变成 "." --只有启动目录和默认目录 workingDirectory （也 ".")解析到启动目录。零配置。

兄弟姐妹的工作树。 集 PW_ALLOWED_DIRS=".." 在你的 .mcp.json 授权启动目录的每个兄弟。相对条目在启动时解析为启动cwd，因此相同 .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 每次通话。allowlist检查在路径段边界运行，因此条目授权 /src/my-app 不会授权 /src/my-app-evil.

突破性变化（2.x→ 下一页）： 这 PW_DIR env-var已被删除。从Playwright项目目录中启动MCP客户端（零配置，默认 workingDirectory: "." 作品），或通行证 workingDirectory 每次通话和设置 PW_ALLOWED_DIRS 因此。

______________________________________________________________________

需求

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

剧作家的默认记者(list 当地， dot 在CI上）只写入stdout——它们在运行后不会产生可读取的文件。在您已经使用的任何报告器旁边添加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

这 --list 输出格式可能已在Playwright版本中更改。使用您的Playwright版本和原始stdout输出打开一个问题。

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

测试使用 维测试 并覆盖 collectSpecs 助手（单元）和所有四个MCP工具 InMemoryTransport （整合）。运行测试套件不需要构建步骤或Playwright安装。

______________________________________________________________________

切割释放

发布是通过推送 v* 标签。 拾取标签，验证标签是否与所有三个版本字段匹配，运行 npm ci + npm run build + npm test，创建一个GitHub版本，其中自动生成的注释按以下分类 .github/release.yml （功能/Bug修复/文档/依赖关系/其他更改），并发布到npm。 然后解开链子 Release 通过 workflow_run 并出版 server.json 到MCP注册表。合并到 main 不会触发发布。

版本存在于三个地方，在推送之前，这三个地方都必须与标签匹配：

• package.json → version
• server.json → 最重要的 version
• server.json → packages[0].version

将所有三个PR合并到一个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. 标记bump commit v 并按下标签。
3. release.yml 验证标签/版本对齐，运行 npm ci，确认该版本尚未在npm上发布，运行 npm run build + npm test，创建GitHub Release，然后发布到npm npm publish --access public --provenance.
4. publish-mcp.yml （由以下因素触发 workflow_run 上 Release)重新验证版本字段，确认该版本尚未在MCP注册表中，并发布 server.json 到 register.modelcontextprotocol.io.

不需要存储库机密。 npm和MCP注册表都通过GitHub OIDC进行身份验证().npm的可信发布者在npmjs.com上的包下配置 设置→ 发布访问权限→ 受信任的发布者 部分--否 NPM_TOKEN 秘密存在或需要。

从失败的发布中恢复： npm拒绝重新发布现有版本，并限制72小时后取消发布。如果发布因任何原因失败，请在新PR中跳到下一个补丁版本并剪切新版本——不要尝试重新运行失败的版本。

______________________________________________________________________

贡献

看 贡献.md 用于错误报告、拉取请求、开发设置和提交约定。

______________________________________________________________________

许可证

麻省理工学院 --版权（c） 休伯特·加耶夫斯基