Visual Regression MCP

AI 辅助的视觉回归测试 MCP Server。像素对比找出差异，AI 判断这个差异是真 bug 还是可接受的变化。

为什么做这个

视觉回归测试不是新技术，但传统方案有个致命问题：误报太多。

字体渲染差异、动画时序、随机数据、时间戳——这些都会导致像素差异，但都不是 bug。团队引入视觉回归测试后，往往因为每次 CI 都红、但 90% 是误报，最后干脆关掉。

这个项目的思路是：像素对比只负责"找出哪里不一样"，判断"这是不是 bug"交给 AI。

工具返回的不只是差异百分比，而是差异图 + 当前截图 + 区域定位。AI 看到图之后可以判断：

• 差异集中在按钮区域，颜色从绿变红 → 可能是真 bug
• 差异散布全页、每处都是 1-2 像素 → 字体抗锯齿，可忽略
• 差异在时间戳区域 → 动态内容，应该 mask 掉

工具

工具	说明
capture_baseline	截图并保存为基线。支持全页/元素截图、自定义视口、遮盖动态区域
compare_visual	对当前页面截图并与基线做像素对比，返回统计数据 + 差异图 + 当前截图
list_baselines	列出所有已保存的基线及其截图参数
delete_baseline	删除过期基线（页面有意改版后）

降低误报的几个设计

这是项目的核心，不是简单调 pixelmatch 就完事：

1. 冻结动画 — 注入 CSS 把所有 animation-duration 和 transition-duration 归零，同时隐藏光标。CSS 动画是误报的头号来源。
2. 遮盖动态区域 — maskSelectors 参数可以把时间戳、广告位、随机内容用纯色盖住，让这些区域的像素稳定。
3. 参数持久化 — 基线保存时把视口尺寸、选择器、等待时间一起存下来，对比时用完全相同的参数重截。参数不一致的对比是无意义的。
4. 等待网络空闲 — waitUntil: "networkidle" 加可配置的额外等待，避免图片没加载完就截图。
5. 区域定位 — 把画面切成 3×3 网格统计差异分布。"差异集中在顶部导航"和"差异散布全页"含义完全不同，前者可能是布局 bug，后者多半是渲染差异。
6. 尺寸不匹配单独处理 — 页面高度变了说明内容增删，pixelmatch 无法对比，此时直接报告尺寸变化而不是崩溃。

安装

git clone <repo-url>/visual-regression-mcp.git
cd visual-regression-mcp
npm install
npx playwright install chromium
npm run build

配置

在 Claude Code 的 MCP 配置中添加：

{
  "mcpServers": {
    "visual-regression": {
      "command": "node",
      "args": ["/path/to/visual-regression-mcp/build/index.js"],
      "env": {
        "VISUAL_BASELINE_DIR": "/path/to/your/baselines"
      }
    }
  }
}

VISUAL_BASELINE_DIR 可选，默认存在 ~/.visual-regression-mcp/baselines/。

使用

配置后重启 Claude Code，直接用自然语言：

帮我给 http://localhost:3000/dashboard 建一个视觉基线，命名 dashboard

（改了代码之后）
对比一下 dashboard 有没有视觉回归

把时间戳区域 .timestamp 遮盖掉再建基线

AI 会调用工具、看差异图、然后告诉你这个差异是不是问题。

输出示例

{
  "status": "differences_found",
  "name": "dashboard",
  "diffPixels": 5107,
  "totalPixels": 480000,
  "diffPercent": 1.064,
  "diffRegions": [
    { "region": "middle-left", "diffPixels": 5107, "percentOfRegion": 9.58 }
  ],
  "note": "Pixel diff found. Inspect the diff image below..."
}

外加两张图：差异图（品红高亮变化像素）和当前截图，供 AI 视觉判断。

技术栈

• @modelcontextprotocol/sdk — MCP 协议
• playwright — 无头浏览器截图
• pixelmatch + pngjs — 像素级图像对比
• TypeScript + ESM

License

MIT