To run Reg-suit visual regression testing in GitHub Actions, first generate screenshots with a browser or test step, then run npx reg-suit run to compare them with expected images and produce a comparison report. Reg-suit does not capture screenshots; its required core.actualDir setting must point to the files your capture step creates.
How the workflow fits together
A visual regression workflow has distinct stages: create the current screenshot files, locate the expected baseline images, compare the two sets, and make the comparison report available to reviewers. Reg-suit handles comparison and, depending on its plugins, snapshot synchronization, publishing, and notifications. The separate reg-actions project also expects screenshots to exist already; its README explicitly says, “So, this action does not take screenshot, please generate images by your self.”
- Generate: Run a browser automation or other capture step to write screenshots to a directory.
- Compare: Configure
actualDirto that directory and runnpx reg-suit run. - Review: Publish the report and snapshots through a reg-suit storage plugin, or use reg-actions to upload workflow artifacts and report in the pull request or workflow summary.
The official Puppeteer demo shows this separation: a capture script writes an image, then Reg-suit runs comparison.
Set up the GitHub Actions workflow
Build the application and start it in the workflow if your capture script needs a running site. The example below uses the current major versions of the official checkout and setup-node actions, Node.js 22, and npm. Adjust the Node version and commands to match your project. Commit your lockfile and use npm ci for a repeatable dependency install.
#1 Best Overall
name: Visual regression
on:
pull_request:
push:
branches: [main]
jobs:
visual-test:
runs-on: ubuntu-latest
steps:
- name: Check out repository history
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Set up Node.js
uses: actions/setup-node@v4
with:
node-version: 22
cache: npm
- name: Install dependencies
run: npm ci
- name: Build application
run: npm run build
# If capture requires a server, start it here and wait until it is ready.
- name: Generate screenshots
run: npm run screenshots
- name: Compare screenshots with Reg-suit
run: npx reg-suit runThis is a workflow pattern, not a universal project configuration: npm run screenshots must be a script in your repository that actually writes image files, and the build/server steps depend on your application. The Reg-suit README’s workflow example uses full Git history (fetch-depth: 0); that is especially relevant when your selected snapshot-key generator depends on Git history. Confirm action versions and runtime support against the projects’ current documentation when updating a workflow.
Make the screenshot command produce stable files
Have the capture command write a predictable set of image files into the directory configured as actualDir. Keep viewport, device scale, fonts, locale, timezone, test data, and animation behavior consistent between runs where your browser tool allows it. Differences in rendering conditions can look like application regressions even when the UI code is unchanged.
If capture needs a local web server, start it before the screenshot command and wait for a known-ready URL or health check rather than relying on a fixed short delay. Ensure the command exits unsuccessfully when capture fails; otherwise the comparison may run against an empty or stale directory.
Configure Reg-suit and the actual image directory
Reg-suit reads regconfig.json. At minimum, set core.actualDir to the directory containing generated screenshots. The exact plugin configuration depends on the key-generation and publishing approach you choose; place plugin settings under plugins and follow the configuration documented by the selected plugin.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →{
"core": {
"actualDir": "screenshots"
},
"plugins": {}
}This minimal example establishes the actual-image location only. It does not configure a key generator or a publisher, so add the appropriate plugin setup before expecting Git-based baseline selection or external report publication. The options below can tune comparison behavior; use only options relevant to your project and the installed Reg-suit version.
| Setting | What it controls | Practical use |
|---|---|---|
actualDir |
Required location of current generated images. | Match the output path of your screenshot command exactly. |
workingDir |
Working directory used by Reg-suit. | Set when the configuration or image paths need a particular project-relative context. |
thresholdRate / thresholdPixel |
Comparison tolerance controls. | Use deliberately: permissive thresholds may hide small changes; strict thresholds can expose rendering noise. |
matchingThreshold |
Threshold used when matching corresponding images. | Adjust only if image matching behavior needs tuning. |
enableAntialias |
Controls antialias-related handling in comparison. | Consider for rendering differences at text and shape edges. |
concurrency |
Comparison concurrency. | Adjust for the number and size of images and the available runner resources. |
| x-img-diff reporting | Optional reporting integration for image differences. | Configure through its supported plugin setup when its report format suits your review process. |
Reg-suit’s run command combines expected-image synchronization, comparison, publishing, and optional notifications configured through plugins. The plugin architecture separates snapshot-key generation, publishing, and notification, so choose and configure each role that your workflow needs. See the official reg-suit README for the current configuration and plugin details.
Choose how baselines and reports are stored
The main choice is whether Reg-suit’s publishing plugins manage persistent snapshots and reports in external storage, or whether your workflow uses reg-actions to save run outputs as GitHub artifacts and surface the report in the pull request or workflow summary.
| Approach | Screenshot generation | Storage and retention | How reviewers access results | Git-based baseline selection |
|---|---|---|---|---|
| Reg-suit with a publisher plugin | Your own browser/test step generates the files. | Publisher plugins include AWS S3 and Google Cloud Storage (GCS); the S3 plugin is described as fetching expected snapshots and pushing actual snapshots and the comparison report. Retention depends on your storage configuration; the README does not state a default period. | Through the published comparison report and configured notifications. | Depends on the configured key generator; the Git-hash generator uses branch history to identify the comparison commit. |
| reg-actions | Your own step generates the files before the action runs. | Uploads images and report as workflow artifacts; its README documents a 30-day default artifact-retention period. | Can comment on pull requests and report in the workflow summary. Comment modes are always, changes, and never. |
The action compares branch artifacts; it is a separate artifact/report approach rather than a requirement to use Reg-suit’s Git-hash baseline selection. |
Use persistent external storage when you need baselines and reports retained independently of a workflow run, and choose S3 or GCS according to your existing storage setup. Use reg-actions when workflow artifacts and pull-request or summary reporting fit your review process; account for its documented default retention period. The reg-actions README describes its inputs and reporting options.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Handle Git history and branch context
When using Reg-suit’s Git-hash key generator, comparison selection depends on walking the Git branch graph to find the commit used as the baseline. A shallow checkout or missing branch identity can therefore prevent it from choosing the intended expected snapshot. Full history via fetch-depth: 0 addresses the history side of that issue.
The official Reg-suit example also notes that the Git-hash plugin needs a branch name and demonstrates a detached-HEAD workaround. A detached checkout is not automatically a problem in every event or setup; first check what branch/ref information the event provides and how the selected generator interprets it. Apply the workaround only if the checkout context is actually preventing baseline selection, and validate it for the event types you run, such as pull requests and pushes.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Troubleshoot common failures
- No screenshots found or comparison has no actual images: Check that the capture step ran successfully, wrote files in the expected location, and that
core.actualDirmatches that path relative to the workflow’s working directory. - The comparison uses an unexpected or missing baseline: Confirm which key generator and plugin configuration are active, whether the workflow has adequate Git history, and whether the event supplies the branch context the generator expects.
- The report or snapshot publish step fails: Verify the selected publisher is configured as required by its own plugin documentation, along with the credentials and storage access it needs. Credential names and setup are plugin-specific, so do not copy settings for one publisher into another.
- Reviewers cannot find old artifact results: reg-actions documents 30 days as its default artifact-retention period. Check the repository or workflow artifact retention setting and download or publish results elsewhere if they must remain available longer.
- Many changes appear despite unchanged UI: Compare the browser environment and screenshot inputs across runs, including viewport, fonts, data, and timing. Then evaluate comparison tolerance options carefully rather than masking broad differences with a high threshold.
Or skip the browser setup
If you want a screenshot-producing step without maintaining browser-capture setup in this workflow, ScreenshotNeo provides a screenshot API. It is separate from Reg-suit: use it to create an image file, then configure actualDir and run Reg-suit as above. See the ScreenshotNeo website and its API documentation.
For example, this cURL request saves a screenshot of the target URL as a file:
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Best Value
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpMove or write the result into the directory configured by actualDir, and ensure the API request succeeds before starting the comparison. ScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, and failed loads are not billed. It also offers an MCP server for AI agents, and includes 1,000 screenshots a month free with no card; paid plans start at $5 for 3,000. Sign up for the free plan.
Frequently Asked Questions
Does reg-actions take screenshots for me?
No. It expects image files generated by an earlier capture step.
Does every Reg-suit workflow need Git-hash snapshot keys?
No. Git-history and branch requirements apply when you choose the Git-hash key generator; other configurations may use a different snapshot-key strategy.
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.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Repair Windows errors before they cause bigger problems3Scan for outdated or missing drivers - takes under a minute
