# 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` 无法对比，此时直接报告尺寸变化而不是崩溃。

## 安装

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

## 配置

在 Claude Code 的 MCP 配置中添加：

```json
{
  "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 会调用工具、看差异图、然后告诉你这个差异是不是问题。

## 输出示例

```json
{
  "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