Run your screenshot-generation step first, then invoke npx reg-suit run on the generated images. Reg-suit compares image files and produces a difference report; it does not render your application. For GitLab CI, the key details are putting screenshots in the configured actualDir, making the correct baseline available to the configured key generator and publisher, and deciding whether to add optional merge-request notifications.
What Reg-suit does in a GitLab pipeline
Reg-suit compares current screenshot files with an expected snapshot, creates a report, and can publish the current images and report through configured plugins. Your application’s browser, Storybook, or other capture process must create the screenshots; Reg-suit consumes them.
As an Amazon Associate I earn from qualifying purchases.
The reg-suit run command is documented as a combined sync-expected, compare, and publish -n sequence. It retrieves the expected snapshot using the configured key generator and publisher, compares it with the files in core.actualDir, publishes the current images and report, and invokes installed notifier plugins. The exact baseline selection depends on the key generator you install; a GitLab merge request is not automatically guaranteed to select its target branch as the baseline. See the Reg-suit repository documentation.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Install and configure Reg-suit
-
Add Reg-suit as a project dependency and initialize its configuration. The project overview describes
reg-suit init; the README documents theinit,prepare, andruncommands. Use a project-local dependency so CI resolves the version specified by the project, then run it withnpx. -
Check that
regconfig.jsonsetscore.actualDirto the directory your capture step will populate. Reg-suit requires this directory. -
Choose a key generator and a publisher. The Git-hash plugin selects a comparison commit by walking the Git branch graph. Publisher plugins retrieve expected images and publish current images and reports; the project lists S3 and GCS publisher plugins. These choices determine baseline semantics and where snapshots are stored.
-
Run your screenshot generator locally or in CI and verify that it writes image files to
actualDir. Reg-suit is not a substitute for this step.Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
Add the job to GitLab CI
The following is a schematic ordering example, not a tested complete pipeline. It assumes the project provides npm run screenshots and has configured Reg-suit. Adapt the runner image, browser dependencies, services, artifacts, variables, and Git fetch behavior to the project’s capture tool and pipeline.
visual-regression:
stage: test
script:
- npm ci
- npm run build
- npm run screenshots
- git checkout "$CI_COMMIT_REF_NAME" || git checkout -b "$CI_COMMIT_REF_NAME"
- npx reg-suit runThe order matters: screenshots must exist before the Reg-suit command runs. The upstream GitLab example checks out $CI_COMMIT_REF_NAME before invoking the CLI because the Git-hash key generator needs a branch name when identifying a base commit. Treat that example as a starting point, not a universal modern GitLab recipe. Confirm the branch and commit history are available in the actual job. The sample also includes a git pull; do not copy that blindly without validating credentials, checkout depth, and branch availability for your project. See the Reg-suit README.
Keep the comparison baseline meaningful
Check out the history the key generator needs
GitLab jobs may not have the full branch graph available by default, depending on project and runner configuration. If the Git-hash generator cannot find the intended base commit, inspect the job’s checked-out branch and history, then adjust fetch and checkout behavior so the required commits are present. Do not assume Reg-suit will infer the merge-request target branch merely because the job is a merge-request pipeline.
Choose baseline semantics deliberately
The Git-hash key generator follows the Git branch graph to select a comparison commit. A simpler key generator may fit workflows where the project supplies a fixed or otherwise explicit key. Select based on how the team intends expected images to evolve; the project’s docs do not establish one universally correct GitLab merge-request baseline strategy.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Review thresholds against the application
The README documents thresholdRate as the ratio of changed pixels to all pixels, with values from 0 to 1, and thresholdPixel as an absolute changed-pixel threshold. Both defaults are 0. It also documents enableAntialias (default false), matchingThreshold, and comparison concurrency (default 4). These are configuration details, not universal recommendations: tune only after reviewing actual diffs and deciding what visual variation is acceptable for your application.
Optionally post results to a GitLab merge request
Comparison and report generation do not require a GitLab comment. To add one, install and configure the optional notifier plugin:
npm i reg-notify-gitlab-plugin -D
npx reg-suit prepare -p notify-gitlabThe plugin requires a GitLab project ID and API token in the general configuration. In GitLab CI, it can detect gitlabUrl and projectId from predefined environment values, so the project ID can be omitted in that context; the token is still required. Store the token in protected or masked CI configuration appropriate to the project, and verify current GitLab token permissions before deployment. The plugin documentation does not establish a currently authoritative minimum scope. Its output can go in a merge-request note, description, or discussion; the documented default is a note. See the GitLab notifier README.
Choose snapshot storage and access
Reg-suit lists S3 and GCS publisher plugins; storage is a project choice, not a prerequisite to every possible comparison setup. For the S3 plugin, the CI environment must have permission to access the bucket. Its documentation lists object read, write, and delete actions, plus bucket listing, and exposes settings including bucket name, ACL, server-side encryption, custom domain, path prefix, and SDK options.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchThe S3 README lists public-read as the default ACL. Review the bucket and object access settings for your use case rather than treating public access as necessary. See the S3 publisher README. The project’s GCS publisher is another documented option; access setup depends on that plugin and your cloud configuration.
Rank #4
Troubleshoot common failures
-
No actual screenshots or comparison input: the capture command may not have run, may have failed, or may have written elsewhere. Run it before Reg-suit and confirm its image files are in the configured
core.actualDir. -
Unexpected or missing baseline: check which key generator and publisher are configured, then inspect the checked-out branch and available commit history. For Git-hash selection, ensure the job has the branch and graph needed by the generator.
-
Git checkout or pull fails: confirm that the branch exists in the job’s checkout, that the pipeline has the required repository credentials, and that shallow history is not excluding commits the generator needs. The upstream sample’s pull step is not safe to assume without checking those conditions.
Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy. -
Screenshot generation fails on the runner: verify the runner image and project-specific browser dependencies, services, and environment required by your capture tool. Those requirements are not defined for every GitLab setup by Reg-suit’s general instructions.
-
Merge-request notification is missing: confirm the notifier plugin is installed and prepared, the token is available to that pipeline, and the configured project context is correct. Check the token’s current permissions in GitLab rather than assuming a minimum scope from the plugin README.
-
S3 snapshot access is denied: check the CI identity’s bucket access and the configured bucket, ACL, and path settings. Grant only the access the project intends to use and review whether objects should be publicly readable.
Or skip the browser setup
Reg-suit still needs image files to compare, but ScreenshotNeo can provide the screenshot-capture step through a single API request. The API accepts a URL and returns an image or PDF; capture your application’s URL and arrange for the resulting image file to land in the directory configured as Reg-suit’s actualDir.
For example, with cURL:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpReplace the target URL with the page your project needs to capture, and ensure the output path matches your Reg-suit workflow. See the ScreenshotNeo API documentation for setup and options.
- Cookie banners, popups, and chat widgets are removed before the shot.
- Bot checks, blank pages, and failed loads are never billed.
- An MCP server lets AI agents take screenshots.
- 1,000 screenshots a month are free with no card; paid plans start at $5 for 3,000.
Sign up for ScreenshotNeo free to get 1,000 screenshots a month with no card.
Frequently Asked Questions
Does Reg-suit capture screenshots from my app?
No. Your own browser, Storybook, or other capture step must generate the image files; Reg-suit compares those files.
Is the GitLab notifier required to run comparisons?
No. It is an optional plugin for posting results to a merge request; the comparison workflow can run without it.
Recommended Free Tools
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
