Screenshot Visual Diff

Capture public pages or compare existing PNG/JPEG images with deterministic changed-pixel metrics and red-highlighted visual diff images.

What is Screenshot Visual Diff?

Screenshot Visual Diff captures public web pages or compares two existing images and reports exactly which pixels changed. It is designed for visual regression checks where a team needs a repeatable pass/fail decision plus an image that makes the changed region easy to inspect: for example, staging against production before a release, or today's page against a saved baseline.

The Actor accepts 1 to 10 baseline/current pairs in one run. Every pair produces a dataset record and, when both images are valid, a PNG with changed pixels highlighted in red. One invalid pair returns an error record without cancelling the remaining comparisons.

How to use it

1. Supply each baseline and current image as base64 with a filename, or give a public HTTP/HTTPS URL to capture. The example input compares two small built-in images, so you can run it as it is.
2. Set pixelThreshold to ignore small channel differences, such as anti-aliasing noise.
3. Set maxDiffRatio to the largest share of changed pixels your release allows.
4. Run the Actor, read the dataset metrics and open the PNG stored in the key-value store under diffKey.

A pixel counts as changed when its largest RGB channel difference is strictly greater than pixelThreshold. The overall status is fail only when changedPixels / totalPixels is strictly greater than maxDiffRatio; equality passes. Transparent pixels are composited over white before comparison.

Input and output example

Compare a staging page with production at the same viewport:

{
  "comparisons": [
    {
      "baseline": {"url": "https://www.example.com/pricing"},
      "current": {"url": "https://staging.example.com/pricing"}
    }
  ],
  "viewportWidth": 1280,
  "viewportHeight": 720,
  "waitMs": 500,
  "pixelThreshold": 16,
  "maxDiffRatio": 0.001
}

A completed comparison has this output shape:

{
  "comparisonId": "comparison-0002",
  "baseline": "base64:baseline.png",
  "current": "base64:changed.png",
  "width": 64,
  "height": 32,
  "changedPixels": 272,
  "totalPixels": 2048,
  "diffRatio": 0.1328125,
  "maxChannelDifference": 215,
  "diffBounds": [40, 8, 56, 25],
  "pixelThreshold": 16,
  "maxDiffRatio": 0.001,
  "status": "fail",
  "error": null,
  "diffKey": "diff-comparison-0002.png"
}

IDs are positional, so repeated image pairs remain independent. The Actor saves each result and its diff image before processing the next pair.

Scope and limits

The Actor supports public HTTP/HTTPS pages on default ports and existing PNG or JPEG images. Browser traffic goes through a proxy inside the Actor that allows only public network destinations; Service Workers are blocked. When robots.txt checking is enabled, it covers document redirects too. Capture covers the viewport only. It does not support login, cookies, CAPTCHA solving or protected pages.

Images can be up to 20 MB and 4 million pixels each, and the viewport width times height must not exceed 4 million pixels. Both images in a pair must have identical dimensions; the Actor does not resize them. Base64 image content is never copied into dataset records or error messages.

Use the Actor only for pages you are allowed to access, such as your own sites. Stop if a site's terms or robots.txt rules disallow it or the site owner objects.

Pricing

Pay-per-event pricing: $0.0015 per Actor start plus $0.004 per completed comparison, whether the result is pass or fail. Both screenshots and the diff image are included. Pairs that end with an error, such as a failed capture or mismatched dimensions, are not charged. If a run reaches your maximum cost per run, the Actor stops after the last comparison that fits.

Troubleshooting and support

• DIMENSION_MISMATCH: capture both images at the same width and height.
• TOO_MANY_PIXELS: reduce image dimensions within the 4 million pixel limit.
• IMAGE_TOO_LARGE: reduce file size or adjust maxBytes within the documented limit.
• INVALID_BASE64: supply raw base64 bytes without a data-URL prefix.
• UNSUPPORTED_IMAGE_FORMAT: convert the source to PNG or JPEG.
• CAPTURE_FAILED, CAPTURE_TIMEOUT or ROBOTS_DISALLOWED: check that the page is public, loads within timeoutSecs and allows automated access.

For bug reports, use Actor Issues in Apify Console. Include the run ID and the returned error code. Do not post private URLs, credentials or personal data.