page-diff

网页的视觉回归测试。比较截图以检测UI变化,生成突出显示差异的叠加图像。在前端更改后使用,以验证视觉正确性,捕获意外的副作用,或确认更改如预期所示。

📖 中文导读:网页的视觉回归测试。比较截图以检测UI变化,生成突出显示差异的叠加图像。在前端更改后使用,以验证视觉正确性,捕获意外的副作用,或确认更改如预期所示。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: page-diff description: Visual regression testing for web pages. Compares screenshots to detect UI changes, generates overlay images highlighting differences. Use after making frontend changes to verify visual correctness, catch unintended side effects, or validate that changes look as expected.

Page Diff

Compare screenshots to detect visual changes. Outputs similarity percentage and an overlay image with differences highlighted in magenta.

Usage

uv run .claude/skills/page-diff/scripts/diff.py <expected> <actual>

Output:

PASS: 99.2% similar (3,247 pixels differ)
/path/to/overlay.png

The overlay image shows the actual screenshot with changed regions tinted magenta. Use Read to view it.

Baselines

Store known-good screenshots in baselines/:

.claude/skills/page-diff/baselines/
├── demo.png
├── settings.png
└── upload-complete.png

Workflow:

  1. Capture baseline: browser_take_screenshot → save to baselines/demo.png
  2. Make changes, reload
  3. Capture current: browser_take_screenshot → /tmp/current.png
  4. Compare: uv run .claude/skills/page-diff/scripts/diff.py baselines/demo.png /tmp/current.png
  5. If diff is expected, update baseline

Interpreting Results

  • 100% identical: No visual changes
  • >99% similar: Minor differences (anti-aliasing, subpixel rendering) - usually a PASS
  • <99% similar: Meaningful changes detected - review the overlay

When similarity is lower than expected, view the overlay image to see exactly what changed. Correlate with your code changes to determine if the diff is intentional.

Options

--threshold, -t   Color difference threshold (0-1). Default: 0.1
                  Higher = more tolerant of minor color variations

--alpha, -a       Overlay tint transparency (0-1). Default: 0.5

--output, -o      Custom output path for overlay image

Fixes