How to Compare Full-Page Screenshots with Reg-suit

Direct answer: Reg-suit compares image files that your project has already captured. It does not capture a page in its documented workflow. Use a browser automation tool to save a full-page screenshot into the directory configured as core.actualDir, configure how Reg-suit finds and stores expected screenshots, then run npx reg-suit run. Reg-suit syncs the expected images, compares them with the current images, creates an HTML report, and publishes artifacts when a publisher is configured. Review differences to decide whether they reflect an intended UI change or a regression.

There is no special Reg-suit full-page capture flag in the documented configuration. Full-page capture belongs to the upstream browser tool. For useful comparisons, keep the capture scope and browser conditions consistent between baseline and current runs; that is practical guidance for comparing supplied images, not a Reg-suit guarantee. Reg-suit’s repository documentation and its Puppeteer example describe this separation.

1. Capture a full-page screenshot

The following runnable example uses Playwright with Node.js to open a route and save a full-page PNG. It captures the page; it does not configure or run Reg-suit. Install Playwright and its Chromium browser in your project, then save this as capture.mjs.

import { chromium } from 'playwright';
import { mkdir } from 'node:fs/promises';

const target = process.env.TARGET_URL ?? 'http://localhost:3000';
const output = process.env.OUTPUT ?? 'screenshots/home.png';

const browser = await chromium.launch({ headless: true });
try {
  const page = await browser.newPage({
    viewport: { width: 1440, height: 900 },
    deviceScaleFactor: 1
  });
  await page.goto(target, { waitUntil: 'networkidle', timeout: 60000 });
  await page.screenshot({ path: output, fullPage: true, animations: 'disabled' });
  console.log(`Saved ${output}`);
} finally {
  await browser.close();
}

Run it with node capture.mjs. Set TARGET_URL and OUTPUT in your shell or CI job to select the route and file. Create the output directory before capture if your script or tool does not do so; this example uses screenshots, which Playwright may require to exist.

One safe adjustment is to create the parent directory in the script. Add this before launching the browser:

import { dirname } from 'node:path';
await mkdir(dirname(output), { recursive: true });

Keep captures comparable

Use the same route, viewport dimensions, device scale factor, browser version, and full-page capture setting for baseline and current images.
Wait for the page state your application needs. Network idle can time out on pages with polling or long-lived requests; in that case wait for a meaningful selector or application-ready signal instead.
Stabilize changing content such as timestamps, rotating promotions, randomized data, cursors, and animations. Disable animations where practical and use deterministic fixtures for test data.
Ensure fonts and images have loaded before capture. If layout shifts after the screenshot, wait for a known element or font readiness in your capture script.
Save one image per route with a stable relative path. Reg-suit needs corresponding current and expected image sets to compare.

These controls are practical ways to reduce noise in image-to-image comparisons; Reg-suit does not make browser rendering deterministic.

2. Install and initialize Reg-suit

Follow the official getting-started flow: install the CLI, initialize its configuration, choose plugins, and then run it. The exact plugin setup depends on where you store snapshots and how your project chooses a comparison key.

npm install --save-dev reg-suit
npx reg-suit init

Initialization guides you through configuration. Reg-suit’s documented plugin families include key generators, publishers, and notifiers. For example, the Git-hash key generator can select a baseline through Git branch history; publisher plugins include S3 and GCS options. Consult the official README for plugin installation and provider-specific credentials because these are separate packages and their setup varies.

3. Point Reg-suit at current screenshots

Set core.actualDir to the directory where the capture job writes current screenshots. workingDir is optional and defaults to .reg; the README says this working directory is ordinarily added to .gitignore. A minimal illustrative configuration shape is:

{
  "core": {
    "actualDir": "screenshots",
    "workingDir": ".reg"
  }
}

Use the configuration file format generated by your installed Reg-suit version and initialization flow; retain the plugin configuration that reg-suit init creates. The snippet shows the key directories, not a complete publisher or key-generator setup. Without configured expected-image lookup and storage, Reg-suit cannot provide the baseline workflow described here.

Choose and publish a baseline

On the initial run, images without a prior expected counterpart can be reported as new. Once published through your configured publisher, those images can serve as expected snapshots for a later comparison. With the Git-hash plugin, the comparison key is chosen by walking Git branch history to identify a base commit. Keep the intended baseline branch and its history available in CI.

The documented run command coordinates three stages: sync-expected fetches expected images using the configured key-generator and publisher plugins; compare compares them with files in actualDir and creates the report; and publish -n publishes the comparison result and actual images through the publisher plugin. Configured notifier plugins can also send a status or message.

4. Run the comparison and review the report

Capture the current images first, then run:

npx reg-suit run

Inspect the generated HTML difference report and classify each change. A visible difference is a prompt for review, not proof of a defect. If the UI change is intentional, update the expected snapshot through your team’s baseline workflow; if it is unexpected, fix the application or capture instability and run again.

5. Tune sensitivity and report detail

Reg-suit exposes comparison settings that trade sensitivity against tolerance for rendering variation. Its README sample includes thresholdRate: 0.05, but the documented default for thresholdRate is 0. Do not treat the sample as a universal recommendation.

Setting	Purpose	How to choose
`thresholdRate`	Tolerates a share of differing pixels relative to the whole image.	Use only a rate your project can justify; a larger tolerance can hide small real changes.
`thresholdPixel`	Provides an absolute differing-pixel count threshold.	Useful when an absolute count better matches the expected noise than a proportion.
`matchingThreshold`	YUV color-distance matching threshold from 0 to 1; smaller values make comparison more sensitive.	Adjust deliberately against representative pages and review the report.
`enableAntialias`	Optionally ignores anti-aliased pixels.	Consider it when edge-rendering variation creates noise; check that important edge changes remain visible.
`ximgdiff`	Optional structural detail in the report, including parts identified as inserted or moved.	Enable when structural context helps reviewers interpret changes.

Thresholds are project policy, not a substitute for stable screenshots. Start with sensitivity appropriate to your regression risk, inspect actual reports, and adjust based on recurring noise rather than copying a sample value.

6. CI, artifacts, and notifications

For CI, make the order explicit: check out the intended branch with sufficient history, install the browser and dependencies, capture all target routes into actualDir, run Reg-suit, and retain or publish the resulting report using your configured publisher. The repository documents S3 and GCS publisher plugins. It also lists notifier plugins for GitHub, GitLab, GitHub Enterprise, Slack, and Chatwork; each requires its own plugin and external service configuration.

A known Git-based CI pitfall is detached HEAD. The Git-hash plugin needs a branch name to find the base commit. If expected images appear missing or the wrong baseline is selected, check checkout state and available branch history first. The repository’s documented workaround is to attach or check out the branch explicitly in the CI job. Avoid loosening thresholds to compensate for a baseline lookup problem.

7. Troubleshooting

Symptom	Likely cause	Fix
No current images or an empty comparison	The capture step did not write files where `core.actualDir` points.	Check the capture output path, create its parent directory, and confirm the configured directory matches it.
Images are all marked new	No expected set was found for the selected key, or this is the first published run.	Check key-generator and publisher configuration, baseline key, and whether a prior run published snapshots.
Wrong or missing baseline in CI	Git-hash key generation may not find the base from a detached HEAD or shallow checkout.	Check out the branch explicitly and make the needed branch history available before changing thresholds.
Large diffs on every run	Viewport, browser environment, fonts, dynamic content, or wait conditions differ.	Standardize capture settings and data; wait for stable page state and suppress known volatile regions in the capture fixture.
Page capture times out	A route may never reach network idle because it polls or holds connections open.	Use a route-specific readiness selector or application signal in the browser capture step, with a bounded timeout.
Diffs appear around text edges	Anti-aliasing or font availability changed between environments.	Install consistent fonts and browser dependencies; consider `enableAntialias` only if its impact is acceptable.
Report lacks comparison artifacts in storage	No publisher is configured correctly, or its credentials and destination are unavailable.	Review the selected publisher’s setup, credentials, bucket or destination, and CI permissions.
Differences are silently tolerated	Threshold settings may be too permissive.	Review `thresholdRate`, `thresholdPixel`, and `matchingThreshold`; compare their effect in the report.

8. Performance, reliability, and cost

Reg-suit’s comparison work scales with the number and dimensions of supplied images, while the upstream browser capture step adds page-load and rendering time. Full-page images can be tall and large, so capture only the routes and states your regression suite needs, and avoid duplicate captures. These are general operational considerations; the research sources provide no benchmark figures.

Reliability depends on both sides of the workflow: reproducible browser captures and a retrievable expected snapshot set. Preserve the CI report and artifacts so reviewers can investigate changes, and ensure storage credentials and branch history are available. Reg-suit’s documented S3 and GCS publishers provide storage integrations, but storage charges and CI costs depend on your providers and workload; no fixed cost estimate follows from the Reg-suit documentation.

Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server. You can use it to generate the image that Reg-suit compares; Reg-suit still handles the baseline and visual comparison. Its API takes one GET request with a URL and returns an image or PDF. For a full-page image, request the full_page option as documented.

curl -G "https://api.screenshotneo.com/v1/shot" \
  -d access_key=YOUR_API_KEY \
  --data-urlencode url=https://stripe.com \
  -d full_page=true \
  -o shot.webp

See the ScreenshotNeo API documentation for authentication and options. Cookie banners, popups, and chat widgets are removed before the shot; bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000.

FAQ

Does Reg-suit take a full-page screenshot?

Its documented workflow compares image files. Use a browser capture tool to create the full-page image before running Reg-suit.

Does every visual difference fail the test?

A difference indicates that the current and expected images differ. Review the report to determine whether the change is intended or a regression.

Can I use a screenshot API to generate Reg-suit inputs?

Yes. Save the API’s image response into the directory configured as core.actualDir, then run the same expected-image and comparison workflow.