reg-suit: Visual Regression Testing for Screenshots and Rendered Pages

Snapshot Testing Applied to Images

reg-suit is a command line interface for visual regression testing, and the way it works is best described as snapshot testing applied to images.

The Compare Images feature is the core. reg-suit is inspired by snapshot testing, and it compares the current images with the previous images, creating an HTML report for their differences. All you need is to give images to assert, which is the important simplification. There is no DOM snapshot, no serialised state and no semantic comparison; the assertion is on the pixels, and the failure artefact is a report a human can look at.

The Store Snapshots feature handles the other half. reg-suit automatically stores snapshot images to external cloud storage, with AWS S3 and Google Cloud Storage given as the examples, and you can review the result of the comparison and the differences at any time you want.

The third feature is the one that decides where the tool fits. reg-suit is just a CLI, so it is easy to integrate with your project, and it works at any CI service and even on your local machine. That is a deliberate constraint, because a visual test that only runs in one vendor's CI is a visual test that a contributor cannot reproduce before pushing.

Plugins Split the Problem Into Keys, Publishers and Notifiers

reg-suit has its own plugin system, and plugins integrate various functions and services into your project. The published set divides into three roles, and understanding them is the fastest way to know what you need to install.

The key generator decides which snapshot you compare against. reg-keygen-git-hash-plugin provides functions to identify what commit hash should I compare to, walking the git branch graph, and reg-simple-keygen-plugin allows an arbitrary string to be used as the snapshot key. The git hash variant is the interesting one, because comparing a branch against the commit it branched from is a different, and usually more useful, question than comparing against the last main.

The publisher decides where the images go. reg-publish-s3-plugin fetches the previous snapshot images from an S3 bucket, and those fetched snapshots are used as the expected images in the comparison, and after the comparison the plugin pushes the current, the actual, snapshot images and the report of the comparison result. reg-publish-gcs-plugin is the alternative, described as so similar to the S3 plugin but using Google Cloud Storage instead.

The notifier decides who hears about it. There is a plugin for a GitHub app that delivers results as a commit status and a pull request comment, one for GitLab merge request comments, one for GitHub Enterprise repositories, one for a Slack channel using an incoming webhook, and one for a Chatwork channel using the Chatwork API token.

A typical setup, as the README describes it, is the keygen git hash plugin with the publish S3 plugin, which gives you the GitHub flow.

The run Command Is Three Commands in a Row

The CLI surface is reg-suit with options and a command, and the command set is small enough to understand in a minute.

The run command performs the visual testing, publishes the current snapshot images and sends the notifications, and the README notes that it is equivalent to running reg-suit sync-expected, then reg-suit compare, then reg-suit publish -n. That equivalence is the key to the tool, because the three steps can be run separately and that is what you need when something in the middle fails.

sync-expected fetches images published already as the expected snapshot data into the working directory. The expected key is detected with the installed key generator plugin, and the installed publisher plugin fetches the images data. compare then compares the images in the actualDir with the images fetched at sync-expected and creates the HTML report. publish publishes the compare result and the actual images to external storage with the publisher plugin, using the actual snapshot key generated by the key generator plugin, and the -n flag sends the notification using the installed notifier plugins.

Two more commands handle setup. init installs and configures reg-suit and plugins into your project, with a --use-yarn flag because the cli installs packages using npm by default and a --use-yarn-ws flag for yarn workspaces. prepare configures the installed plugins, and the -p or --plugin option selects which ones.

The global options are the usual safety valves: -c for the configuration file path, -t for a trial with no changes in dry-run mode, -v for debug logging and -q to suppress logging messages.

Configuration Lives in regconfig.json

To configure reg-suit you put regconfig.json under the project root directory, and the file has two sections, core for the reg-suit core settings and plugins for the plugin specific options.

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

The split matters in practice. The core section describes where the images are and how strict the comparison is, and it is the same for every project using the same publishers. The plugins section holds the project specific values, in this case the bucket name for the S3 publisher.

The core options are also given as a typed shape in the README, which is a nice touch for a configuration file that people edit by hand:

{
  actualDir: string;
  workingDir?: string;        // default ".reg"
  thresholdRate?: number;     // default 0
  thresholdPixel?: number;    // default 0
  enableAntialias?: boolean;  // default false
  concurrency?: number;       // default 4
}

actualDir is required, and it is the directory containing the image files you want to test. workingDir is where reg-suit puts its temporary files, and the README notes it is ordinarily listed in .gitignore, which is the right default since that directory holds the fetched expected images and the report.

Thresholds Decide What Counts as a Regression

The threshold options are the part of the configuration that determines whether a visual test suite is useful or ignored.

thresholdRate is a proportion and thresholdPixel is a count, and the defaults for both are 0. That default is strict in the right way for a first run, because any difference at all is reported, and it is the setting you want when you are establishing your baseline. It is also the setting that will make your first CI run fail, and the README's example lowers it to 0.05, which is the number most projects settle on.

enableAntialias defaults to false, and it exists because anti-aliased edges are the usual source of a difference that is not a real change. Turning it on changes how the comparison treats those edges, which is the difference between a suite that fails on a font rendering difference on a different machine and one that does not.

The ximgdiff option with an invocationType of none or client, defaulting to client, selects how the image difference is computed, and concurrency defaults to 4, which is the number of comparisons run in parallel. Both are performance and portability settings rather than correctness ones, but concurrency is worth setting deliberately if your test suite is large, since the default is conservative and a suite of hundreds of images will be slow with four workers.

The net effect is that the core configuration is a policy statement: where the images are, how much difference is a failure, and how the comparison is performed.

A Lerna Monorepo With a Separate Package for Each Layer

The repository is a Lerna managed monorepo with yarn workspaces over packages/*, and the package layout mirrors the architecture of the tool.

The watch scripts name the layers directly: reg-suit-interface, reg-suit-core, reg-suit-cli and reg-suit-util, each with its own tsconfig.build.json and its own tsc watcher, run in parallel by the watch script. So the interface, the core logic, the command line and the shared utilities are separate packages with their own build configuration, and the CLI is the layer that assembles them.

There is also a reg-suit-toppage package with its own build and deploy scripts, and the top level deploy command runs the page deploy and the package publishing in sequence, with the package publish handled by lerna publish from-package. The build is lerna run prepublish across the workspace, and the tests are lerna run test.

The tooling is a bit dated, which is worth noticing in a project whose last release line moved from 0.14.3 in March 2024 to 0.14.6 in March 2026. TypeScript 4.5.2 and ESLint 7.32 are the pinned versions, with prettier 2.8.8 and the prettier configuration in a .prettierrc.yml, husky for the git hooks, and renovate for dependency updates. The .yarnrc and yarn.lock indicate yarn as the package manager for the monorepo itself, which is separate from the npm-based installation of the CLI on a user's machine.

The CI is CircleCI, and the repository is not archived, with the last push on 2026-10-13.

Editorial conclusion

reg-suit fits a team that renders images, whether from a browser, a component library or a design pipeline, and wants to fail a build when a pixel changes, with the diff visible in a report rather than in a log file. It is a poor fit for a project whose output is text or data rather than images, and a poor fit if you want an all-in-one tool, because the key generation, publishing and notification are plugins you have to choose and configure. Before adopting it, decide where the snapshots live, since the publisher plugin is what stores them, and set the comparison thresholds deliberately, because the default is to treat any difference as a failure and a sensitive threshold is how flaky visual tests get introduced. The tool is MIT licensed, the newest release is v0.14.6 from 2026-03-16, and the last push was on 2026-10-13.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. reg-viz/reg-suit on GitHub
5. Releases