reg-cli

library0.18.14jsnpmunverified

reg-cli is a command-line interface (CLI) tool for performing visual regression testing on images and generating a comprehensive, interactive HTML report. It helps developers detect unintended visual changes in user interfaces over time by comparing 'actual' images with 'expected' baseline images. The current stable version is 0.18.14, with development actively focused on minor feature enhancements to the report UI, dependency updates, and security patches. Key differentiators include its flexible image comparison logic with adjustable thresholds, support for parallel processing, and the ability to generate reports from pre-existing JSON data. It requires Node.js v18 or newer for execution, ensuring compatibility with modern JavaScript environments. It is primarily used via its CLI but also exposes a programmatic API for integration into custom build workflows.

testing

npm install reg-cli

github ↗package ↗

INSTALL

IMPORT

SIG · REG-CLI

reg-cli

testingjavascriptv0.18.14

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

RegCli

✓ import RegCli from 'reg-cli';

✗ import { RegCli } from 'reg-cli';

The primary class for programmatic usage is exported as a CommonJS default. ESM imports work via interop.

RegCliOptions

✓ import type { RegCliOptions } from 'reg-cli';

✗ import { RegCliOptions } from 'reg-cli';

Type definition for the RegCli class constructor options, primarily used in TypeScript projects.

RegResult

✓ import type { RegResult } from 'reg-cli';

✗ import { RegResult } from 'reg-cli';

Type definition for the object returned by RegCli operations, useful for type-checking in TypeScript.

This quickstart demonstrates how to run `reg-cli` from a Node.js script to compare images, generate a diff, and output an HTML report. It sets up dummy directories and files, then executes the CLI command with common options.

import { spawn } from 'node:child_process'; import { mkdir, writeFile } from 'node:fs/promises'; import { join } from 'node:path'; const actualDir = './screenshots/actual'; const expectedDir = './screenshots/expected'; const diffDir = './screenshots/diff'; const reportPath = './reg-report/index.html'; async function setupDirs() { await mkdir(actualDir, { recursive: true }); await mkdir(expectedDir, { recursive: true }); await mkdir(diffDir, { recursive: true }); // Simulate creating a dummy actual image await writeFile(join(actualDir, 'test.png'), Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=', 'base64')); // Simulate creating a dummy expected image for comparison await writeFile(join(expectedDir, 'test.png'), Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=', 'base64')); } async function runRegCli() { await setupDirs(); const args = [ actualDir, expectedDir, diffDir, '-R', reportPath, '--matchingThreshold', '0.01', '--thresholdRate', '0.001' ]; const regCliProcess = spawn('npx', ['reg-cli', ...args], { stdio: 'inherit' }); regCliProcess.on('close', (code) => { if (code === 0) { console.log('reg-cli comparison completed successfully. Check report at', reportPath); } else { console.error(`reg-cli exited with code ${code}. Visual differences might have been found.`); } }); } runRegCli().catch(console.error);

reg-cli --version

Debug

Known issues

breakingThe `--threshold` option was deprecated and replaced by `--thresholdRate` and `--thresholdPixel` to provide more granular control over change detection.

fix

Migrate your commands to use `--thresholdRate` and/or `--thresholdPixel` instead of `--threshold`. `--threshold` is now an alias for `--thresholdRate`.

affects: >=0.11.0

breakingNode.js v18 or higher is now required. Older Node.js versions are no longer supported, which may cause installation or runtime errors.

fix

Upgrade your Node.js environment to version 18 or newer using a tool like `nvm` or by installing a recent Node.js distribution.

affects: >=0.18.0

gotchaBy default, `reg-cli` will exit with a non-zero status code if image changes are detected (diff images are created).

fix

To prevent `reg-cli` from throwing an error and exiting non-zero when changes are detected, use the `--ignoreChange` (or `-I`) option. If you also want to ignore errors for added/deleted images, use `--extendedErrors` (or `-E`) in combination.

affects: >=0.1.0

gotchareg-cli switched its underlying image difference library from `image-diff` to `argos-ci/image-difference` due to `image-diff` no longer being maintained. This change may subtly affect comparison results.

fix

Review your visual regression tests after upgrading to ensure the new comparison engine yields expected results. Adjust `--matchingThreshold`, `--thresholdRate`, or `--thresholdPixel` if necessary.

affects: >=0.7.0

gotchaRecent versions include security updates for dependencies like `serve-static` and `tar`. Running older versions might expose your project to known vulnerabilities.

fix

Regularly update `reg-cli` to its latest patch version to ensure all dependency vulnerabilities are addressed. Use `npm audit` to check for specific issues.

affects: <0.18.14

Errors

Common errors & fixes

Error: Node.js version too old. `reg-cli` requires Node.js v18 or higher.

The installed Node.js version is below the minimum requirement (v18).

fix

Update your Node.js environment to version 18 or newer. For example, using `nvm install 18 && nvm use 18`.

Error: No images found to compare.

The specified 'actual' directory is empty or contains no images matching the expected comparison format.

fix

Ensure that your `actual` image directory contains the images you intend to compare. Verify the paths provided to `reg-cli` are correct.

Command failed with exit code 2 (or similar non-zero code) after image comparison.

By default, `reg-cli` exits with an error code if visual differences, new images, or deleted images are detected.

fix

If this is an expected outcome (e.g., in a CI pipeline where differences are allowed but reported), add the `--ignoreChange` flag to the `reg-cli` command. Use `--extendedErrors` in addition to `--ignoreChange` if you also want to ignore errors for added/deleted images.

Error: Argument 'threshold' can't be used anymore. Use 'thresholdRate' or 'thresholdPixel'.

You are using the deprecated `--threshold` option in a version where it has been removed or strictly aliased.

fix

Replace `--threshold` with `--thresholdRate` (e.g., `--thresholdRate 0.05`) or `--thresholdPixel` (e.g., `--thresholdPixel 10`) depending on your desired comparison metric.

Upgrade

Version history

0.18.14latest on npm

Audit

Dependencies

noderequiredRuntime environment, explicitly requires Node.js v18+

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/reg-viz/reg-cli ↗

packagehttps://www.npmjs.com/package/reg-cli ↗