TestivAI

@testivai/mcp

MCP（Model Context Protocol）服务，让 AI 编码 Agent 能查看视觉回归结果。Agent 会修改 UI 代码、运行测试套件，然后使用这些工具查明屏幕上实际发生了哪些变化，以及这些变化是真实改动、可能是渲染噪声，还是 DOM 和样式信号无法判定的情况。

工具

工具	功能
get_visual_results	读取 visual-report/results.json；当两个或更多快照共享同一环境变化时，先用一行说明这一点以及其中有多少个属于渲染漂移；然后为每个快照返回一行判定：捕获不健康（当前捕获或基线中的网页字体或样式表加载失败，判定中会指出是哪一项：这是捕获故障或资源损坏，绝不是噪声，也绝不能批准为基线；此项会在任何其他解读之前说明）/ 已通过（自动通过的差异会指出通过它的已配置标准）/ 尺寸已改变（当前捕获的尺寸与基线不同：较高或较短的页面会结合 DOM 摘要和页面位移进行解读；若 DOM 相同，则表示相同内容采用了不同布局，而非增加了内容；宽度变化表示视口或设备缩放发生变化，而非页面发生变化；每个带填充的像素都计为变化，因此绝不会通过，也绝不是噪声）/ 渲染漂移（DOM 和计算样式均匹配，且自基线以来，捕获该快照的环境发生了变化：判定中会指出浏览器构建版本、操作系统或发行版、设备缩放或捕获方式；变化的是机器而非页面，因此绝不会称为噪声）/ 可能是渲染噪声（DOM 和计算样式均匹配，且差异较小、分散；但这仍不能作为证明）/ 集中在一个区域或差异较大（DOM 和计算样式均匹配，但所有差异区域都落在覆盖页面至多三分之一的方框内，或超过 1% 的像素不同：可能是捕获不佳，或样式检查未涵盖的变化，例如尺寸、溢出、变换或图像；批准前请先比较图像）/ 仅样式变化（DOM 相同，计算样式不同：这是真实变化）/ 结构变化（附带 DOM 摘要）/ 未比较样式（DOM 相同，但样式检查不可用：可能是渲染噪声，也可能只是样式表变化；批准前请先比较图像）。具有相同信号的快照（相同元素上的仅样式变化、相同的页面位移、DOM 相同但未比较样式、差异大且分散、可能是渲染噪声）会先分组；集中在一个区域的差异或捕获不健康的快照绝不会分组。每个缺少基线的快照（已提交，但本次运行没有捕获）都会单独列出一行（多个快照会共用一行判定，因此部分运行的输出仍然简短），且没有任何内容需要批准：若要有意移除基线，请删除基线目录。最后会列出用于打开 HTML 报告和每张差异图像的路径
explain_snapshot	提供单个快照的分层证据：像素区域和差异形态（layers.pixel.shape：分散、集中或较大）、元素归因（哪些选择器发生位移或变化、整页位移）、DOM/样式信号、捕获环境（layers.environment：自基线以来发生的变化、渲染变化的描述，以及差异是否属于渲染漂移）、捕获健康状况（layers.health：每次捕获中哪些内容加载失败，以及哪一侧不健康）和解读指南；若缺少基线，则返回状态 missing、已提交的基线文件以及应改为检查的内容
get_report	原始 results.json 负载，供解析结构化数据的 Agent 使用
get_diff（别名 get_snapshot_diff）	返回单个快照的基线、当前和差异图像，以便 Agent 查看变化：先返回缩小到适合模型上下文的整页图像（展示变化位置）；若图像必须缩小，则再返回每个变化区域的原始比例裁剪图，周围留出 32 px 边距，并铺满页面宽度（最高 1280 px），这样在高大的整页捕获图中，文字、换行和裁切仍清晰可读（每次调用最多 3 张裁剪图，每张至多 1280×1024 px，合计最多 2,000,000 px；相邻区域共用一张裁剪图，变化优先于位移，更宽的区域会以 1/2 或更小比例采样，更高的区域会显示顶部行；尺寸变化后，每次捕获图都会按各自边界裁剪）。region（响应中列出的索引），或 y 和 height（全宽条带），可指定仅返回对应裁剪图；若缺少基线，则仅返回已提交的基线图像
list_baselines	列出 .testivai/baselines/ 下已提交的基线
approve_snapshot / approve_all	将已审核的捕获提升为已提交的基线（等同于 testivai approve），仅可在人类确认后执行
该服务还提供两个提示词。review-visual-changes 会引导 Agent 完成全面审查：总结、针对每项变更调用 explain_snapshot、在证据含糊时查看差异图像，并针对每个快照给出建议。
triage-visual-diff（可选参数 snapshot 和 intent）会对每项差异以及每个缺失的基线进行分类，判断其属于显示故障、预期变更、错误还是可能的错误，并提供证据和后续步骤；DOM 发生变化或计算样式发生变化都不属于显示故障，缺失基线也不属于显示故障。这些规则也会通过 testivai/testivai-oss/review@v1 操作在 CI 中运行。

是否批准由人决定

approve_snapshot 和 approve_all 的作用是，让查看过差异的人可以在对话中说“批准”，并由 Agent 执行。它们不是让 Agent 自行决定是否批准的工具：批准会改写“正确”的定义，因此 Agent 批准自己的变更，可能会把回归问题混入基线。两个工具的说明、review-visual-changes 提示词以及每个 get_visual_results 响应中都明确说明了这一点。批准后，请提交 .testivai/baselines/。

在 Claude Code 中，客户端会强制执行此规则：两个批准工具都标记为 anthropic/requiresUserInteraction，因此每次调用批准工具时，Claude Code 都会向你确认，即使在自动批准权限模式下也是如此。如需关闭此功能，请使用 --no-approval-prompt 启动服务，或在 .testivai/config.json 中设置 "mcpApprovalPrompt": false（以该标志为准）；之后，批准工具将遵循客户端自身的权限设置。操作指南：在 Claude Code 中审查并批准。

其他批准方式仍然可用：在本地运行 npx testivai approve <name>，或在拉取请求中评论 /testivai approve <name>。

设置

Claude Code

claude mcp add testivai -- npx -y @testivai/mcp

Cursor / 其他 MCP 客户端

// .cursor/mcp.json (or your client's equivalent)
{
  "mcpServers": {
    "testivai": { "command": "npx", "args": ["-y", "@testivai/mcp"] }
  }
}

服务会从其工作目录读取项目（传入 --root <path> 可覆盖此设置），并遵循 .testivai/config.json 中的 reportDir。

Agent 的典型工作流程

1. Agent 编辑 UI 代码。
2. Agent 运行 npx playwright test（TestivAI reporter 会捕获并比较差异）。
3. Agent 调用 get_visual_results，例如看到：homepage: changed (4.20% pixels differ) and the DOM changed (2 added, 1 removed, 0 attribute changes) — a real structural change; confirm it is intended before approving。
4. Agent 调用 explain_snapshot homepage 查看证据，并调用 get_diff homepage 查看图像（先看完整页面，再以原始比例查看变更区域），然后确认变更符合任务要求（或修复自身引入的回归问题）。
5. Agent 向人说明：变更内容、变更看起来是否符合预期，以及哪些快照需要批准。如果人同意批准，Agent 就调用 approve_snapshot；否则，由人通过 npx testivai approve 或在 PR 中评论 /testivai approve 来批准。

仅本地模式——无需账户或 API 密钥，任何内容都不会离开本机。

完整集成指南（指令文件层级、MCP 层级、没有测试套件的应用、真实对话记录）：docs/guides/ai-agents.md