{"id":17053,"library":"reg-cli","title":"reg-cli: Visual Regression Test Tool","description":"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.","status":"active","version":"0.18.14","language":"javascript","source_language":"en","source_url":"https://github.com/reg-viz/reg-cli","tags":["javascript"],"install":[{"cmd":"npm install reg-cli","lang":"bash","label":"npm"},{"cmd":"yarn add reg-cli","lang":"bash","label":"yarn"},{"cmd":"pnpm add reg-cli","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Runtime environment, explicitly requires Node.js v18+","package":"node","optional":false}],"imports":[{"note":"The primary class for programmatic usage is exported as a CommonJS default. ESM imports work via interop.","wrong":"import { RegCli } from 'reg-cli';","symbol":"RegCli","correct":"import RegCli from 'reg-cli';"},{"note":"Type definition for the RegCli class constructor options, primarily used in TypeScript projects.","wrong":"import { RegCliOptions } from 'reg-cli';","symbol":"RegCliOptions","correct":"import type { RegCliOptions } from 'reg-cli';"},{"note":"Type definition for the object returned by RegCli operations, useful for type-checking in TypeScript.","wrong":"import { RegResult } from 'reg-cli';","symbol":"RegResult","correct":"import type { RegResult } from 'reg-cli';"}],"quickstart":{"code":"import { spawn } from 'node:child_process';\nimport { mkdir, writeFile } from 'node:fs/promises';\nimport { join } from 'node:path';\n\nconst actualDir = './screenshots/actual';\nconst expectedDir = './screenshots/expected';\nconst diffDir = './screenshots/diff';\nconst reportPath = './reg-report/index.html';\n\nasync function setupDirs() {\n  await mkdir(actualDir, { recursive: true });\n  await mkdir(expectedDir, { recursive: true });\n  await mkdir(diffDir, { recursive: true });\n  // Simulate creating a dummy actual image\n  await writeFile(join(actualDir, 'test.png'), Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=', 'base64'));\n  // Simulate creating a dummy expected image for comparison\n  await writeFile(join(expectedDir, 'test.png'), Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=', 'base64'));\n}\n\nasync function runRegCli() {\n  await setupDirs();\n\n  const args = [\n    actualDir,\n    expectedDir,\n    diffDir,\n    '-R', reportPath,\n    '--matchingThreshold', '0.01',\n    '--thresholdRate', '0.001'\n  ];\n\n  const regCliProcess = spawn('npx', ['reg-cli', ...args], { stdio: 'inherit' });\n\n  regCliProcess.on('close', (code) => {\n    if (code === 0) {\n      console.log('reg-cli comparison completed successfully. Check report at', reportPath);\n    } else {\n      console.error(`reg-cli exited with code ${code}. Visual differences might have been found.`);\n    }\n  });\n}\n\nrunRegCli().catch(console.error);\n","lang":"typescript","description":"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."},"warnings":[{"fix":"Migrate your commands to use `--thresholdRate` and/or `--thresholdPixel` instead of `--threshold`. `--threshold` is now an alias for `--thresholdRate`.","message":"The `--threshold` option was deprecated and replaced by `--thresholdRate` and `--thresholdPixel` to provide more granular control over change detection.","severity":"breaking","affected_versions":">=0.11.0"},{"fix":"Upgrade your Node.js environment to version 18 or newer using a tool like `nvm` or by installing a recent Node.js distribution.","message":"Node.js v18 or higher is now required. Older Node.js versions are no longer supported, which may cause installation or runtime errors.","severity":"breaking","affected_versions":">=0.18.0"},{"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.","message":"By default, `reg-cli` will exit with a non-zero status code if image changes are detected (diff images are created).","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Review your visual regression tests after upgrading to ensure the new comparison engine yields expected results. Adjust `--matchingThreshold`, `--thresholdRate`, or `--thresholdPixel` if necessary.","message":"reg-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.","severity":"gotcha","affected_versions":">=0.7.0"},{"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.","message":"Recent versions include security updates for dependencies like `serve-static` and `tar`. Running older versions might expose your project to known vulnerabilities.","severity":"gotcha","affected_versions":"<0.18.14"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Update your Node.js environment to version 18 or newer. For example, using `nvm install 18 && nvm use 18`.","cause":"The installed Node.js version is below the minimum requirement (v18).","error":"Error: Node.js version too old. `reg-cli` requires Node.js v18 or higher."},{"fix":"Ensure that your `actual` image directory contains the images you intend to compare. Verify the paths provided to `reg-cli` are correct.","cause":"The specified 'actual' directory is empty or contains no images matching the expected comparison format.","error":"Error: No images found to compare."},{"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.","cause":"By default, `reg-cli` exits with an error code if visual differences, new images, or deleted images are detected.","error":"Command failed with exit code 2 (or similar non-zero code) after image comparison."},{"fix":"Replace `--threshold` with `--thresholdRate` (e.g., `--thresholdRate 0.05`) or `--thresholdPixel` (e.g., `--thresholdPixel 10`) depending on your desired comparison metric.","cause":"You are using the deprecated `--threshold` option in a version where it has been removed or strictly aliased.","error":"Error: Argument 'threshold' can't be used anymore. Use 'thresholdRate' or 'thresholdPixel'."}],"ecosystem":"npm","meta_description":null}