compare_html_to_image
Renders HTML and pixel-diffs it against a reference image to detect visual differences, with per-band localization for identifying mismatches in specific design elements.
Instructions
One-shot visual comparison: renders an HTML page/element with Playwright (chromium) and pixel-diffs it against a reference image (e.g. a Figma export). passed = diffRatio <= maxRatio (default 0.01 = 1%; raise maxRatio for rework/triage loops where you only need localization, not a strict gate). Returns diff ratio, anti-alias accounting (see methodology in the response), and per-band diff localization — equal-height bands or custom bandEdges so one band can map to one design element. Replaces the manual render_html_screenshot → write-a-diff-script two-step.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | Remote URL to render. | |
| html | No | Raw HTML string to render. | |
| bands | No | Split the image vertically into N equal-height horizontal bands and report per-band diff ratios. 0 = off. Ignored when bandEdges is set. | |
| fullPage | No | ||
| htmlPath | No | Path to a local HTML file. | |
| maxRatio | No | Pass line: passed = diffRatio <= maxRatio. Default 0.01 (1%). For rework rounds, raise it (e.g. 0.05) so the call still "passes" while you use bands/bandEdges to localize remaining diffs. | |
| selector | No | CSS selector for a partial (element) screenshot. | |
| settleMs | No | ||
| bandEdges | No | Custom band boundaries, e.g. [0,120,280,974] → 3 bands [0,120) [120,280) [280,974). Lets one band map to one design element. Values are clamped to the image height, sorted, deduped. Mutually exclusive with bands — when both are given, bandEdges wins. | |
| hideFixed | No | Hide position:fixed/sticky elements before shooting. | |
| imagePath | Yes | Path to the reference image (PNG) to compare against. | |
| threshold | No | pixelmatch color-delta threshold (0-1). Smaller = stricter per-pixel color comparison. | |
| initScript | No | JS run before page scripts (addInitScript) — passed through to the renderer, e.g. seed localStorage/state for multi-state replicas. | |
| outDiffPath | No | Where to save the diff PNG (red = mismatch). Temp file if omitted. | |
| outRenderPath | No | Also save the rendered screenshot to this path and return it as renderPath. Useful when you need the render PNG itself (e.g. measuring line widths) without a second render_html_screenshot call. | |
| viewportWidth | No | ||
| waitForImages | No | ||
| keepRenderPath | No | Deprecated alias of outRenderPath. If both are set, outRenderPath wins. | |
| viewportHeight | No |