How to Update Baseline Screenshots in Reg-suit

To update baseline screenshots in Reg-suit, first regenerate the intended screenshots in the configured actualDir, then run npx reg-suit run and review the HTML comparison report. The run fetches the existing expected images, compares them with your new actual images, and publishes the comparison and actual images under the current snapshot key. Those published snapshots can become the expected images used by a later run.

Reg-suit’s documented workflow does not provide a dedicated approve, accept, or update-baseline command. Treat baseline updates as a reviewed publish: confirm the visual changes are intentional, then retain the run that publishes the snapshots you want future comparisons to use.

Update a baseline in four steps

Make the intended UI change. Ensure your app is in the state you want to capture.
Regenerate actual screenshots. Use the project’s screenshot process to write images into the configured actualDir. Reg-suit compares these supplied images; it does not generate them itself.
Run Reg-suit. From the project root, run npx reg-suit run, or the equivalent local CLI command configured by the project.
Review the HTML report. Inspect each difference and decide whether it is expected. A detected difference is a signal for review; it does not by itself mean that the test failed.

If the report shows only intended changes, publish or retain that run according to your team’s workflow. The actual snapshots published by that run are used as expected images in a later run.

What `reg-suit run` does

The combined command performs the main snapshot workflow:

sync-expected retrieves previously published expected images. The configured key-generator selects the expected key, and the publisher plugin fetches the images.
compare compares the images in actualDir with the fetched expected images and creates an HTML report.
publish -n publishes the comparison result and actual images under the current snapshot key using the configured publisher. Notifications are sent if configured.

The exact key and storage location depend on the project’s key-generator and publisher plugins. This matters when updating baselines: the run must use the branch or commit key your project intends, and publish to the configured storage.

Check the project configuration

Reg-suit reads regconfig.json from the project root. A typical configuration includes a required actualDir, an optional temporary workingDir, a comparison threshold, a key-generator plugin, and a publisher plugin. For example, the official README demonstrates images as the actual directory, .reg as working storage, a threshold rate of 0.05, Git-hash key generation, and an S3 publisher.

{
  "core": {
    "workingDir": ".reg",
    "actualDir": "images",
    "thresholdRate": 0.05
  },
  "plugins": {
    "reg-keygen-git-hash": {
      "branch": "main"
    },
    "reg-publish-s3": {
      "bucketName": "your-bucket-name"
    }
  }
}

This is an illustrative configuration shape, not a complete provider setup: publisher plugins may need credentials and additional settings. Use the configuration generated for your project by npx reg-suit init and its installed plugins as the source of truth. The official README documents S3 and Google Cloud Storage publisher options. The Puppeteer demo uses S3 for images and reports; S3 is an example, not a requirement.

actualDir: required path containing the screenshots to compare.
workingDir: optional temporary working directory; the README’s example is .reg, commonly ignored by Git.
thresholdRate: comparison threshold shown in the README example. Keep the project’s chosen threshold consistent; changing it can affect which differences appear significant.
Key-generator plugin: determines which snapshot key is used for expected and actual images.
Publisher plugin: retrieves existing expected images and stores comparison results and current actual images.

For initial setup, the official Puppeteer demo shows npx reg-suit init. To revisit plugin setup, it shows npx reg-suit prepare --plugin publish-s3. Follow the prompts and the documentation for the publisher installed in your project.

Run the steps separately when debugging

If the combined command makes it hard to identify the failing stage, run the documented operations individually from the project root:

npx reg-suit sync-expected
npx reg-suit compare
npx reg-suit publish

Use the same project configuration, branch, and commit context for all three. The separate commands help determine whether the issue is fetching expected images, comparing local files, or publishing results.

Review before accepting the new snapshots

Open the report produced by the comparison.
Check that expected and actual images correspond to the same pages and states.
Inspect each changed region for unintended layout shifts, missing content, or rendering differences.
Confirm the changes match the intended UI update.
Confirm the run is using the correct snapshot key and publisher.
Publish the run whose actual screenshots should serve as future expected images.

A report can contain differences without indicating a broken test. The team must judge whether each visual change is intended. Avoid publishing a run as the new baseline until that review is complete.

CI and Git key considerations

When the key-generator relies on Git history, Reg-suit needs the branch context to identify the comparison base. CI checkouts with detached HEAD or shallow history can prevent it from resolving the intended key. The official README’s GitHub Actions example uses fetch-depth: 0 before running Reg-suit.

# GitHub Actions checkout configuration example
- uses: actions/checkout@v4
  with:
    fetch-depth: 0

- name: Run visual comparison
  run: npx reg-suit run

Use your repository’s actual workflow syntax and ensure the intended base branch is available. The README also describes CI-specific workarounds for Travis CI, Wercker, AppVeyor, and GitLab CI. If your setup uses one of those providers, consult the relevant section of the README rather than assuming the GitHub Actions configuration applies unchanged.

Common problems and fixes

Symptom	Likely cause	What to check
No actual screenshots are compared	The capture process wrote files somewhere other than `actualDir`, or the configured directory is wrong.	Check `actualDir` in root-level `regconfig.json` and confirm the generated image files are present there.
Expected images cannot be fetched	The selected expected key has no published snapshots, or the publisher cannot retrieve them.	Check the key-generator’s branch/commit context, publisher configuration, credentials, and whether a prior run published images for that key.
CI cannot determine the base snapshot	The checkout is detached or lacks enough Git history or the base branch.	Make the branch available to the job and fetch the history needed by the key-generator. For GitHub Actions, the README example uses `fetch-depth: 0`.
The report shows many unexpected differences	The actual screenshots may have been captured in a different app state, or expected and actual images may not represent matching pages.	Verify the capture inputs and page state before publishing. Review the report image by image.
Publish fails after comparison succeeds	The publisher may be misconfigured or its storage credentials may be unavailable.	Check the installed publisher’s required settings and credentials, plus access to its configured storage.
A difference is mistaken for a failed test	Reg-suit reports visual changes for human judgment; a difference alone does not establish that the change is wrong.	Use the HTML report to decide whether the visual change was intended before updating the baseline.

Performance, reliability, and storage costs

Reg-suit’s documented workflow fetches expected images, compares them, and publishes results and actual images. Runtime therefore depends on the number and size of screenshots, comparison work, and the configured publisher’s storage operations. The research documentation does not provide benchmarks, so estimate using your own project’s screenshot set and CI runs.

For reliability, keep the capture step and Reg-suit configuration repeatable, provide CI with the correct Git context, and review the report before publishing intended baselines. Snapshot storage costs depend on the publisher and the volume and retention of stored artifacts; the Reg-suit documentation does not state a fixed cost.

Or skip the browser setup

If you need to generate website screenshots for your own comparison inputs, ScreenshotNeo is a website screenshot API and MCP server from Yorker Media. It returns PNG, JPEG, WebP, or PDF from one GET request. It does not replace Reg-suit’s expected-image keys, comparison report, or baseline publishing workflow; it can provide screenshots for a capture pipeline.

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

See the ScreenshotNeo API documentation for request options and response details. 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, and paid plans start at $5 for 3,000.

FAQ

Is there a command that only updates the baseline?

The reviewed official documentation describes sync-expected, compare, publish, and the combined run workflow. It does not document a separate approval or baseline-update command.

Does every detected difference mean the run failed?

No. The report is for judging whether a visual difference is intended; a detected change alone does not mean the test failed.

Which snapshots become expected next time?

The snapshots published in an execution are used as expected images in a subsequent run.

Do I need S3?

No. S3 is one documented publisher example. The README also lists Google Cloud Storage, and the project must use a supported, configured publisher.