How to Ignore Dynamic Content in Reg-suit Screenshot Comparisons

Reg-suit compares image files; its documented core configuration does not include a per-element or per-region ignore setting. To keep dynamic content from causing noisy differences, make the page deterministic before capture, or hide or replace only the volatile element in the screenshot-generation step. Then save the prepared image in reg-suit’s configured actualDir and run the comparison as usual.

This distinction matters: thresholdRate and thresholdPixel tune tolerated image differences. They are not region masks and do not mean “ignore this timestamp.” The official reg-suit README describes it as a CLI for visual regression testing, and the official Puppeteer demo shows screenshots being generated before reg-suit reads and compares them.

1. Where dynamic-content handling belongs

The workflow has two distinct stages:

Capture: a browser or screenshot tool loads the page and writes image files. This is where you freeze data, set a stable test state, or hide/replace a volatile element.
Compare: reg-suit reads the supplied current images from actualDir, fetches expected images into its working directory, compares them, and produces an HTML difference report.

The documented core configuration covers comparison behavior such as thresholdRate, thresholdPixel, matchingThreshold, antialias handling, concurrency, and optional x-img-diff reporting. The displayed core options do not document a DOM selector, rectangle, or region-ignore option. The S3 and GCS publisher plugins store snapshot data; they do not change which pixels are compared.

2. Choose the narrowest stabilization strategy

Approach	Use it when	Trade-off
Fixed fixture data	The changing value can be controlled through test data or a stable account.	Best preserves the real layout and still tests rendering of the chosen value.
Freeze a relevant clock	The variation comes from dates, relative-time labels, or time-dependent content.	Use a fixed time that matches the scenario; other live sources may still vary.
Replace the element’s content	The element should keep its geometry, but its changing text or image is irrelevant.	Preserves layout space, though the replacement itself must be stable.
Hide the element while preserving its space	The content is irrelevant, but its dimensions affect nearby alignment.	Can still reveal layout shifts caused by its reserved space.
Remove the element	Neither its content nor its space belongs in the visual assertion.	May conceal genuine layout changes around the removed area.

Examples of candidates include a timestamp, rotating advertisement, random recommendation, live count, or user-specific value. Before suppressing anything, decide whether its content, dimensions, position, or loading behavior is part of what the test should verify. Keep the suppression selector as specific as practical; a broad parent selector can hide real regressions.

3. Prepare the screenshot before reg-suit runs

Identify the exact source of nondeterminism and whether it is controlled by your application, test data, the clock, or an external service.
Prefer stable fixtures, a fixed clock, and a known test account when those make the scenario deterministic without suppressing UI.
If the content must remain dynamic, apply a narrowly scoped hide or replacement in the capture setup. Preserve its space when surrounding alignment is under test.
Write the resulting screenshot to the directory configured as reg-suit’s actualDir.
Run reg-suit normally and inspect its HTML difference report. Keep the preparation logic with the screenshot generation so it is reproducible in local and CI runs.

For example, a Puppeteer capture step can alter a specific element before writing the image. This is capture-stage code; it is not a reg-suit masking API:

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch({ headless: true });
  try {
    const page = await browser.newPage({ viewport: { width: 1365, height: 900 } });
    await page.goto('https://example.com', { waitUntil: 'networkidle0' });

    // Replace only the volatile value and retain the element's layout.
    await page.evaluate(() => {
      const node = document.querySelector('[data-testid="live-count"]');
      if (node) node.textContent = '100';
    });

    // Ensure actualDir exists and points to this output location.
    await page.screenshot({ path: 'screenshots/actual/home.png', fullPage: true });
  } finally {
    await browser.close();
  }
})();

Adapt the selector, URL, viewport, output path, and readiness condition to your application. If you remove the element instead, that changes layout; if layout should remain, replace its contents or use a visibility strategy that retains its space. Avoid relying on arbitrary sleeps when a stable application signal or selector can tell the capture step the page is ready.

4. Configure reg-suit to compare the prepared files

Point actualDir at the directory produced by the capture step, then run the comparison command from your project’s reg-suit setup. A minimal configuration shape is:

// .regconfig.json
{
  "actualDir": "screenshots/actual"
}

Use the rest of your project’s existing reg-suit configuration for the expected-image publisher and comparison settings. The complete configuration depends on the chosen publisher and project setup; do not add a made-up ignore selector or rectangle. The capture step above is illustrative and does not replace the official demo’s project-specific setup.

5. Set thresholds without masking the problem

Reg-suit’s documented comparison thresholds determine how much difference is tolerated in a comparison. They can help account for small rendering noise, but they do not target a particular timestamp, ad, or region. Increasing tolerance to quiet one dynamic block can also make unrelated visual regressions less visible across the image. Stabilize the source or prepare the screenshot narrowly first, then tune comparison tolerance only for the remaining image-level noise your team accepts.

6. Troubleshooting

Symptom	Likely cause	Fix
The dynamic value still changes the diff	The element was altered after the screenshot, or the selector did not match at capture time.	Apply the change before writing the file; verify the selector against the rendered page and use a readiness condition.
Layout shifts after hiding content	The chosen hiding method removed the element’s layout space.	Replace the content or use a method that preserves geometry when surrounding layout matters.
Real regressions stop appearing near the ignored content	The selector or removed parent covers too much UI.	Narrow the target and check whether dimensions, spacing, or styling in that region should remain asserted.
Reg-suit reports missing actual images	The capture output path and configured `actualDir` do not agree, or the capture step did not write files.	Confirm the output directory exists, contains the expected images, and matches `actualDir`.
Images differ between local and CI	Browser dimensions, fixtures, time, account state, fonts, or external resources vary between environments.	Standardize the capture environment and state; block or stabilize external inputs where appropriate.
A threshold change does not remove one specific dynamic area	Thresholds apply to comparison tolerance rather than a region exclusion.	Prepare that region before capture; do not treat a threshold as a mask.

7. Performance, reliability, and cost considerations

Stabilizing data at its source usually avoids extra retries and makes failures easier to diagnose. A capture script that waits for a deterministic signal is generally easier to reason about than one that uses a long fixed delay. Hiding or replacing a small element adds little work, but broad page manipulation can make the captured state diverge from what users see; document why each suppressed selector exists.

Reg-suit’s documented concurrency setting controls comparison work, not browser capture behavior. Capture speed and reliability depend on the browser workflow that creates the files, while storage publisher choice (such as the documented S3 or GCS options) affects where snapshot data is stored, not comparison semantics. No performance benchmark or cost figure is established by the project documentation cited here, so size the capture and storage setup against your own CI volume and retention needs.

8. Or skip the browser setup

For a one-off clean capture, ScreenshotNeo provides a website screenshot API: one GET request returns an image or PDF. Its capture options include full-page screenshots, CSS selector targeting, custom CSS and JavaScript, wait conditions, and cache TTL. That can produce a prepared image upstream, while reg-suit still consumes the image file for comparison. See the ScreenshotNeo API documentation for parameters and response details.

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}`);

ScreenshotNeo accepts cookie or consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before the shot; each step can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers report the page verdict and billing status. Its MCP server lets AI agents use take_screenshot, get_page_info, and capture_pdf. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000. These clean-capture behaviors do not replace deterministic application fixtures for a visual regression test: keep test state stable and inspect the resulting files before comparison.

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

9. FAQ

Can reg-suit ignore a CSS selector directly?

The documented core configuration reviewed here does not specify a selector-based ignore option. Apply the change in the screenshot capture step instead.

Should I hide the whole changing section?

Only if none of its content, size, position, or surrounding layout is part of the assertion. Otherwise stabilize its data or target a smaller element.

Do S3 or GCS publishers affect dynamic-content handling?

No. They concern snapshot storage. The image supplied for comparison still needs to be prepared before reg-suit reads it.