How to configure Reg-suit thresholds for screenshot differences

Configure screenshot-difference tolerance in the core section of the project-root regconfig.json. Use thresholdRate for a fraction of changed pixels from 0 to 1, or use thresholdPixel for a fixed changed-pixel count. These are alternatives; the reg-suit README does not document precedence when both are set, so choose one unless you have checked the implementation for your installed version. matchingThreshold is separate: it controls per-pixel YUV color-distance matching, and smaller values make comparisons more sensitive. [The reg-suit README](https://github.com/reg-viz/reg-suit/blob/master/README.md) documents the options and defaults.

1. Set a screenshot difference threshold

First, add or edit regconfig.json at your project root. The actualDir property is required. This example allows a 5% differing-pixel ratio:

{
  "core": {
    "actualDir": "images",
    "thresholdRate": 0.05
  }
}

Use a JSON number between 0 and 1, not a percentage string. For example, 0.05 means 5%. A threshold of 0 is the documented default and is the strict starting point. The project README’s basic configuration places actualDir and these options under core.

Use an absolute pixel count instead

If the desired allowance is a fixed number of changed pixels regardless of screenshot area, use thresholdPixel in place of thresholdRate:

{
  "core": {
    "actualDir": "images",
    "thresholdPixel": 120
  }
}

The value shown is an example, not a recommended tolerance. The README defines this option as an alternative absolute pixel threshold and documents a default of 0. Avoid configuring both threshold fields together without verifying the behavior in the version your project installs.

2. Choose between rate and pixel count

Option	Meaning	Useful when
`thresholdRate`	Ratio of differing pixels to the whole image, from 0 to 1; default 0.	Your tolerance should scale with screenshot dimensions.
`thresholdPixel`	Absolute count of differing pixels; default 0.	Your acceptable count should stay fixed across image sizes.
`matchingThreshold`	Per-pixel YUV color-distance matching sensitivity, from 0 to 1.	You need to adjust how sensitive each pixel comparison is, rather than the overall allowance.

A ratio scales with total image area: the same rate permits more differing pixels in a larger image. A fixed pixel count does not scale with image area. This follows from the documented definitions; it is not a benchmark or a claim about a specific site’s visual stability.

Do not confuse the two kinds of tolerance

thresholdRate and thresholdPixel set the allowed total difference using ratio or count. matchingThreshold affects how similar individual pixels must be to count as matching. The reg-suit README describes a range from 0 to 1 for matchingThreshold; smaller values make comparisons more sensitive. Adjust it only when the per-pixel color comparison itself needs tuning.

3. Tune thresholds using the visual report

Start with a strict configuration, normally the documented zero default, and capture representative pages in the same environment used by CI.
Run the project’s existing reg-suit comparison workflow and open its HTML report.
Inspect each difference. Decide whether it is an intended change, an unstable capture, or a regression that needs a fix.
Stabilize the capture conditions where possible, such as waiting for content and using consistent viewport and data.
Only then raise one threshold, in small steps, and review the report again. Keep the chosen tolerance in version control.

Reg-suit’s documented workflow compares current images with expected images and produces an HTML report. The related reg-puppeteer-demo also describes reviewing detected changes to decide whether they are intended. A permissive tolerance can conceal real visual regressions, so treat it as an explicit project policy rather than a way to silence unexplained failures.

4. Keep screenshot inputs comparable

Thresholds are meaningful only when captures are comparable. For stable visual checks, keep the browser, viewport, device scale, fonts, test data, locale, and animation state consistent between expected and actual captures. Wait for the page content under test to be ready; avoid capturing while images, asynchronous data, or transitions are still changing. These are practical capture controls, not additional reg-suit threshold settings.

Use the same screenshot dimensions for a given comparison when possible.
Make dynamic content deterministic or exclude it from the capture when it is not part of the test.
Review whether a one-pixel shift comes from layout, font rendering, or changed content before relaxing comparison sensitivity.
Keep separate threshold choices for genuinely different image classes rather than applying a broad tolerance that masks important pages.

5. Troubleshooting threshold configuration

Symptom	Likely cause	What to do
Changing the threshold has no effect.	The config may be in the wrong location or outside the `core` object; the installed version may also differ from the README branch.	Check that `regconfig.json` is in the project root and the key is nested under `core`. Check the installed reg-suit version and its matching documentation.
Configuration parsing fails.	Invalid JSON, such as a trailing comma, comments, quoted numeric values, or a missing brace.	Use strict JSON and numeric values, for example `0.05`, without a percent sign or quotes.
The comparison remains too strict.	The configured threshold is zero or too small, or per-pixel color matching is too sensitive.	Inspect the HTML report first. If the total amount of acceptable difference is the issue, adjust one total threshold. If color-distance matching is the issue, review `matchingThreshold`; smaller values are more sensitive.
Real regressions pass unexpectedly.	The allowed rate or pixel count may be too permissive for the image dimensions or content.	Lower the tolerance and inspect whether dynamic regions or unstable inputs should be controlled instead.
It is unclear which threshold applies when both fields are present.	The README documents `thresholdPixel` as an alternative, but does not state precedence.	Configure one threshold. If both are required for an experiment, inspect the installed version’s implementation and confirm behavior with representative screenshots.

6. Performance, reliability, and cost considerations

The dossier’s official documentation does not publish threshold-related performance benchmarks or a cost formula, so do not infer a speed or cost saving from raising tolerance. Threshold choice governs acceptance of image differences; it does not make the browser capture itself faster. For reliability, use repeatable capture inputs, retain reports for review, and tie the chosen tolerance to the risk of the pages being checked. A strict check catches more small changes but can require review of benign rendering variation; a permissive check reduces sensitivity and may let meaningful changes through.

7. Or skip the browser setup

If you need clean page screenshots for documentation, monitoring, or downstream visual review without maintaining browser capture code, ScreenshotNeo is a screenshot API and MCP server. Its API returns an image or PDF from one GET request; see the ScreenshotNeo API documentation for request options.

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

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

Cookie banners are accepted and removed before capture; known consent platforms, newsletter popups, and chat widgets can also be removed, with each cleanup step configurable.
Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed; response headers identify the page verdict and billing status.
An MCP server provides take_screenshot, get_page_info, and capture_pdf for AI agents and MCP clients.
The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots.

Create a free ScreenshotNeo account to get 1,000 screenshots a month with no card.

8. FAQ

Can I use a decimal percentage such as 5?

For a five-percent ratio, use 0.05. The documented range is 0 to 1.

Does reg-suit update expected screenshots automatically?

The threshold settings govern comparison tolerance. Review the project’s expected-image update workflow separately and accept baseline changes only after inspecting them.

Where can I confirm behavior for my installed release?

Check the reg-suit version recorded by your package manager and consult documentation or source for that version. The cited README is on the repository’s moving master branch and may not exactly match an older installation.

Sources

reg-suit README — configuration, threshold definitions, and comparison report workflow.
reg-cli README — corroborating descriptions of matching sensitivity and threshold concepts.
reg-puppeteer-demo README — example workflow for reviewing detected screenshot differences.