SavePage
·SavePage Team

Using Screenshot APIs for Visual Regression Testing

testingci-cdautomation

Visual regression testing catches UI changes that unit tests and integration tests miss. A button that shifted 2 pixels to the left, a font that changed weight, a background color that lost its transparency. These are real bugs that real users notice.

The traditional approach involves running a headless browser in your CI pipeline, capturing screenshots of key pages, and comparing them pixel-by-pixel against baseline images. This works, but it adds significant complexity to your pipeline.

The screenshot API approach

Instead of managing browser infrastructure in CI, you can use a screenshot API to capture the images and handle the comparison locally. The workflow looks like this:

  1. Deploy your changes to a preview environment
  2. Call the screenshot API for each page you want to test
  3. Compare the new screenshots against your baseline images
  4. Flag any differences above a threshold
import requests
import hashlib

API_KEY = "YOUR_API_KEY"
PAGES = ["/", "/pricing", "/docs", "/about"]
BASE_URL = "https://preview.example.com"

for page in PAGES:
    response = requests.get(
        "https://api.savepage.io/v1/",
        params={
            "url": f"{BASE_URL}{page}",
            "width": 1440,
            "height": 900,
            "format": "png",
        },
        headers={"Authorization": f"Bearer {API_KEY}"},
    )
    data = response.json()
    print(f"{page}: {data['image']}")

Advantages

No browser in CI. Your CI server does not need Chrome, Puppeteer, or any browser dependencies. It just needs to make HTTP requests.

Consistent rendering. Every screenshot is taken in the same browser version on the same infrastructure. No more "it looks different on the CI server" issues.

Mobile testing. Change the viewport dimensions to test mobile layouts without configuring device emulation locally.

Full page captures. Test long pages with the fullpage parameter without writing scroll-and-stitch logic.

Comparison strategies

Once you have the screenshots, there are several ways to compare them:

  • Pixel diff -- Compare images pixel by pixel, highlight differences. Tools like pixelmatch or ImageMagick compare handle this.
  • Perceptual diff -- Use algorithms that account for anti-aliasing and sub-pixel rendering differences.
  • Structural similarity -- Compare the structural layout rather than exact pixels.

For most use cases, a pixel diff with a small tolerance (1-2%) catches meaningful changes without producing false positives.

Integration with CI

The screenshot comparison can run as a step in your existing CI pipeline. If differences are detected above your threshold, the step fails and blocks the merge. The diff images can be uploaded as build artifacts for manual review.

This approach works with any CI system: GitHub Actions, GitLab CI, CircleCI, Jenkins, or any platform that can run a script and make HTTP requests.

All posts