Reg-suit: What Does the Reference Store Do?

Direct answer: reg-suit’s reference store is the configured storage destination for visual regression snapshots. It supplies earlier screenshots as the expected baseline for comparison with current screenshots. After comparing them, reg-suit can publish the current snapshots and an HTML difference report back to the configured destination. The publisher plugin manages retrieval and publication.

The store is part of a workflow, not a single fixed service. The configured publisher determines where snapshots live and how reg-suit accesses them. The official project documentation gives AWS S3 and Google Cloud Storage as examples; a particular project’s backend and access rules depend on its plugin and configuration. reg-suit project

1. What the reference store contains

The reference set contains snapshot images from an earlier point in the project’s history. These images are the expected results against which newly generated images are compared. It is useful to think of them as versioned test inputs: the test runner creates current images, and the reference store makes the selected prior images available to reg-suit.

The store is not itself the comparison engine or the HTML report. A publisher plugin handles storage operations; reg-suit performs the comparison and produces the report.

2. How reg-suit uses the store

1. Generate current screenshots. A project’s visual test setup writes images into the configured actualDir.
2. Select the expected snapshot key. A key-generator plugin decides which reference set to use. The Git-hash key generator walks the Git branch graph to identify a commit for comparison.
3. Fetch the reference set. The publisher plugin retrieves the snapshot data associated with that key into reg-suit’s working area.
4. Compare and report. reg-suit compares actual images with the fetched expected images and creates an HTML report describing differences.
5. Publish results. The publisher can upload the current snapshots and comparison result to the configured storage destination. Notifier plugins can report results to services such as GitHub or GitLab.

The README describes run as the combined workflow: sync expected snapshots, compare, publish, and notify. The separate commands make the store’s role easier to isolate:

• sync-expected fetches the selected reference set.
• compare compares that set with the current images.
• publish uploads current images and the comparison result.

See the reg-suit README for workflow and configuration details.

3. Storage backends and what varies

The official README names S3 and Google Cloud Storage as example destinations. Its S3 publisher retrieves previous snapshots from an S3 bucket and pushes current snapshots and the report; the GCS publisher is another option. The storage service alone does not define reg-suit behavior: the installed publisher plugin and project settings determine how the data is addressed and accessed.

A community-maintained GitHub publisher plugin documents GitHub Releases and GHCR backends. Treat this as an alternative plugin maintained in a separate repository, not as a publisher guaranteed to be included in every reg-suit installation.

Question	What determines the answer
Where are reference images stored?	The configured publisher plugin and its destination.
Which earlier image set is fetched?	The key-generator plugin and the selected key.
How does authentication work?	The publisher and the project’s credentials or environment configuration.
How long are snapshots retained?	The backend and any retention settings configured for it.
Which storage is this project using?	Inspect the installed plugins and project configuration; the title or default workflow does not reveal it.

4. Where to look in configuration

The README’s configuration example uses a regconfig.json file with core and plugins sections. actualDir is required. workingDir is optional and defaults to .reg. Publisher-specific values belong under that publisher’s plugin configuration; for example, the README’s S3 example sets bucketName. That field is an example for that publisher, not a universal reg-suit setting.

{
  "core": {
    "actualDir": "path/to/actual",
    "workingDir": ".reg"
  },
  "plugins": {
    "reg-publish-s3-plugin": {
      "bucketName": "your-configured-bucket"
    }
  }
}

This is a structural illustration of the documented settings, not a complete credential or provider setup. Use the exact plugin name and required fields for the publisher installed in your project. The README also documents environment-value placeholders for plugin configuration, which can keep environment-specific values out of committed configuration files.

5. Practical setup and investigation checklist

1. Find the project’s regconfig.json and identify actualDir and any explicit workingDir.
2. Inspect the plugins section and confirm which key-generator and publisher plugins are configured.
3. Check the publisher’s own configuration and the environment in which the command runs. Confirm that the expected credentials and destination settings are available there.
4. Determine which key the key generator selects for the branch or commit being tested.
5. Run the project’s documented sync, compare, and publish workflow, or its combined run command. Review the generated HTML report and confirm that the expected images were fetched.
6. Before changing a baseline, verify that the current screenshots are intended to become the new expected results. Publishing current images updates the reference data used by later comparisons.

6. Troubleshooting reference-store problems

Symptom	Likely cause	What to check
No expected images are available	The publisher could not fetch the selected reference key, or no reference set exists for that key.	Check the key-generator result, publisher configuration, destination, and whether a baseline has previously been published.
Authentication or access failure	The publisher’s credentials are absent, invalid, or lack access to the configured destination.	Check the provider credentials available to the process and the publisher’s documented access requirements.
Images are missing from the comparison	actualDir may point to the wrong output directory, or the capture step may not have generated the expected files.	Confirm the actual image output and the configured directory before investigating storage.
The wrong baseline is used	The key generator selected a different commit or key than expected.	Inspect the branch graph and key-generator behavior for the current run.
Publication fails after comparison	The upload destination or its access settings may be misconfigured, even though fetching or comparing succeeded.	Check publisher settings and destination permissions separately from comparison output.
Configuration values are missing in CI	Environment placeholders may be unresolved or the CI process may not receive the expected values.	Check the CI environment and the placeholder syntax supported by the installed plugin.
A GitHub-based backend is not available	The project may not have installed the separate community publisher plugin.	Confirm the dependency and its configuration; do not assume that backend is built into every installation.

These checks separate capture problems, key selection, retrieval, comparison, and publication. That distinction helps locate whether the issue is in the screenshot-producing project, the key generator, or the configured publisher.

7. Reliability, performance, and storage cost

reg-suit’s reference flow depends on both the image-generation step and the configured storage provider. A missing baseline, unavailable destination, or unusable credentials can prevent retrieval or publication; a comparison report only reflects the images that were actually supplied. Keep the key-generation and publisher configuration consistent between local runs and CI so both environments select and access the intended reference set.

Storage costs and retention are backend-specific. The cited reg-suit documentation establishes example backends, but it does not establish current provider prices, quotas, or a project’s retention policy. Check the provider and plugin settings for those details. Avoid publishing a new baseline until the review confirms the current images should become the expected set.

8. FAQ

Does reg-suit store screenshots in Git by default?

The documented workflow uses a publisher plugin and gives external storage such as S3 and GCS as examples. The selected backend depends on the configured plugin.

Is the reference store the HTML report?

No. The reference store holds snapshot data used for expected images. reg-suit creates an HTML report from the comparison, and the publisher can publish that result.

Can I tell which backend a repository uses from its title?

No. Inspect its dependencies, regconfig.json, and runtime environment.

Does every reg-suit install support GitHub Releases or GHCR?

No such universal support is established by the official README. Those backends are documented by a separate community plugin repository.

Or skip the browser setup

If your workflow also needs website screenshots, ScreenshotNeo is a website screenshot API and MCP server. One GET request can return a PNG, JPEG, WebP, or PDF. Cookie banners are accepted and removed before capture, and known newsletter popups and chat widgets can be removed too. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing; response headers report the page verdict and billing status. Its MCP server gives AI agents tools to take screenshots, get page information, and capture PDFs.

Here is a one-call WebP capture. See the ScreenshotNeo API documentation for request options.

curl -G "https://api.screenshotneo.com/v1/shot" \
  -d access_key=YOUR_API_KEY \
  --data-urlencode url=https://stripe.com \
  -o shot.webp

ScreenshotNeo includes 1,000 screenshots a month free with no card; paid plans start at $5 for 3,000 screenshots. Sign up free and capture your first 1,000 screenshots a month with no card.