How to set up Reg-suit with Storybook

To set up Reg-suit with Storybook, first capture your stories as image files, then point Reg-suit’s core.actualDir at that output directory. Configure a key generator and a publisher plugin so Reg-suit can retrieve the prior snapshots, compare them with the new images, and publish an HTML report. Reg-suit performs the comparison and publishing; it does not render Storybook stories into screenshots.

The pipeline is: Storybook renders components, a capture tool saves story images, and Reg-suit compares those images with a stored baseline. The directory of captured images is the handoff between the capture tool and Reg-suit.

1. Confirm Storybook renders the right stories

Before setting up visual comparison, make sure the project’s Storybook starts and its stories render in the intended state. Storybook may need project-specific build configuration, runtime providers or decorators, styles, fonts, and static assets. If the rendered stories do not match the application, fix that rendering setup before establishing a baseline; otherwise the comparison may report differences caused by missing setup rather than a component change.

Follow the installation and configuration instructions for your Storybook framework and version. Keep application data deterministic where possible, and check that external fonts or network resources are available when captures run.

2. Choose a capture tool that supports your Storybook version

Pick a capture tool based on the exact Storybook major version, whether you will capture a running server or a built Storybook, and whether you need per-story timing or viewport controls. Verify the package’s current compatibility and requirements before copying its configuration:

• Storycap: its documentation describes capture from a running Storybook URL and lists Storybook 7.x and 8.x as tested. Simple mode captures a URL; managed mode adds the addon and a withScreenshot decorator for per-story options.
• Storycapture: its Storybook integration page describes support for Storybook v9 with Storycap.
• StoryFreeze: its listing describes an independent Playwright-based tool for Storybook 10 and requires Node.js 22 or newer.

These are source-specific compatibility notes, not a guarantee that every framework and package combination works. Check the capture tool’s documentation against your installed versions.

3. Capture the stories into a directory

With Storycap, you can capture a running Storybook server and choose an output directory with -o or --outDir. Its documented default is __screenshots__.

npx storycap http://localhost:9001 -o __screenshots__

Start the server separately before running that command. Alternatively, Storycap documents a --serverCmd option to launch the project’s Storybook start command for capture:

npx storycap http://localhost:9001 --serverCmd "<project Storybook start command>" -o __screenshots__

Replace the placeholder with the command used by your project. For built Storybook capture, build the static Storybook, serve its output directory locally, and point the capture tool at the served URL. This separates the build from capture and lets CI capture the same built files it intends to validate.

For Storycap managed mode, add storycap to the addons in .storybook/main.js and register withScreenshot in .storybook/preview.js, following the tool’s version-specific setup instructions. Per-story options can control such details as capture delay, viewport, and whether a story should be skipped. Use explicit timing or viewport settings when stories need them, and keep those settings consistent between runs.

After capture, inspect the output directory. It should contain actual image files for the stories you expect to compare. Keep story names stable so corresponding images can be matched across runs.

4. Configure Reg-suit and its plugins

Install and initialize Reg-suit using the documented first-run command. The interactive initializer can install and configure Reg-suit and selected plugins. The project also documents prepare for configuring installed plugins. A key generator selects the snapshot set, while a publisher retrieves earlier images and stores current images and the report.

For example, this illustrative regconfig.json uses Storycap’s documented output directory and an S3 publisher:

{
  "core": {
    "workingDir": ".reg",
    "actualDir": "__screenshots__",
    "thresholdRate": 0.05
  },
  "plugins": {
    "reg-keygen-git-hash-plugin": {},
    "reg-publish-s3-plugin": {
      "bucketName": "your-bucket"
    }
  }
}

Change actualDir if your capture command writes somewhere else. The directory must contain the actual images Reg-suit should test. Replace your-bucket with the bucket configured for your project; Reg-suit also documents a Google Cloud Storage publisher. Plugin configuration can substitute environment variables, so keep credentials and bucket configuration in your CI secrets mechanism rather than committing secret values.

The Git-hash key generator is one documented option. Reg-suit also lists a simple key generator for an arbitrary string. Select a key policy that fits your branch workflow: the publisher and key generator together determine which prior image set is retrieved for comparison. Confirm the selected plugin’s behavior for your branches and first run.

5. Run the capture and comparison flow

Make sure image generation runs before Reg-suit. A package script can express the order; adapt the Storybook build and serving commands to your project:

{
  "scripts": {
    "storybook:build": "storybook build",
    "visual:capture": "npx storycap http://localhost:9001 -o __screenshots__",
    "visual:compare": "reg-suit run"
  }
}

This sketch assumes the Storybook server is already available at that URL. In CI, start the server or serve the built Storybook before visual:capture, wait until it is ready, then run the comparison command. Reg-suit documents run as equivalent to syncing expected images, comparing, and publishing with -n; an installed notifier plugin can send notifications. Review the generated HTML comparison report.

On the first run, there may be no prior baseline. Treat the initial published snapshots as an intentional baseline decision. Inspect the images and report, confirm they represent the state your team wants to compare against, then use the project’s chosen branch and storage workflow for later runs.

6. Set comparison sensitivity deliberately

Rendering differences can come from code changes or from changes in fonts, assets, browser rendering, viewport, or timing. Reg-suit documents several controls; choose them to reflect the project’s rendering stability and document the policy so that reviewers understand what a reported change means.

Setting	What it controls	Practical guidance
thresholdRate	A changed-pixel ratio from 0 to 1.	Use it when you want a ratio-based tolerance. The example value in a sample config is not a universal recommendation.
thresholdPixel	An alternative absolute changed-pixel threshold.	Consider it when an absolute count better fits the image sizes and changes you expect.
matchingThreshold	YUV color-distance matching behavior.	Smaller values are more sensitive. Adjust only after reviewing actual diffs.
Antialias detection	Whether antialiased pixels are detected by the comparison.	Enable it if appropriate for your rendering environment and policy.
Concurrency	How many comparison tasks run concurrently.	Adjust for the job’s available resources and image volume; more concurrency can increase resource use.

Changing thresholds can make small visual differences pass or fail. Do not use a permissive threshold to hide unstable rendering; stabilize fonts, viewport, timing, and assets first.

7. Keep CI captures repeatable

• Use the same Storybook build, capture tool version, viewport, and capture settings for comparable runs.
• Ensure the server is ready before capture, and ensure capture has finished before Reg-suit starts.
• Provide the same fonts, static assets, providers, and required data each run.
• Use stable story identifiers and output filenames so images map to the same stories across runs.
• Choose a key and publisher workflow that retrieve the intended baseline for each branch or commit.
• Review the HTML report before accepting visual changes or updating the baseline.

Common errors and fixes

Symptom	Likely cause	Fix
Reg-suit reports missing actual images or the actual directory is empty.	The capture command did not run, failed, or wrote to a different directory than core.actualDir.	Run capture first, inspect its exit status and output files, then make actualDir match the capture output path.
Many or all stories are missing.	The server URL or port is wrong, the server is not ready, or the capture tool cannot enumerate the stories.	Open the Storybook URL in the same environment, check the port and startup logs, wait for readiness, and verify the capture tool supports the Storybook version.
The baseline cannot be retrieved.	The publisher configuration, bucket access, credentials, or snapshot key does not point to the intended stored set.	Check the selected publisher’s configuration and access, confirm secrets are available in the job, and verify the key generator’s output and branch policy.
The first run reports no expected images.	No baseline has been published for that key yet.	Review the captured images and establish the initial baseline intentionally through the project’s publishing workflow.
Every run produces noisy differences.	Fonts, assets, viewport, timing, runtime providers, or external data vary between captures.	Make those inputs consistent, wait for the needed rendering state, and then tune thresholds based on reviewed diffs.
Some stories are blank or incomplete.	Capture started before asynchronous rendering or required resources completed, or the story lacks a provider or fixture.	Configure the capture timing supported by the chosen tool, supply the needed providers and data, and verify fonts and assets load.
Configuration copied from a guide does not work.	The guide assumes a different Storybook major, capture package, framework, or Node.js version.	Check the installed versions and the capture tool’s current compatibility notes; use the integration instructions for that combination.

Performance, reliability, and cost

Capture time depends on the number and complexity of stories, the browser runtime, and any waits for fonts, assets, or asynchronous UI. Keep the capture set focused on meaningful stories, avoid arbitrary long delays, and prefer a deterministic ready condition when the tool supports one. Concurrency can reduce elapsed comparison time when resources allow, but higher concurrency uses more resources.

For reliability, treat capture output as a build artifact that must exist before comparison. Keep the Storybook build, browser environment, and story inputs consistent; retain the report and snapshots according to your team’s review and storage workflow. Reg-suit documents S3 and GCS publisher plugins, but storage charges and CI compute costs depend on your provider, image volume, and retention choices. No universal runtime or cost estimate follows from the available project documentation.

Or skip the browser setup

For webpage screenshots outside the Storybook component pipeline, ScreenshotNeo is a website screenshot API and MCP server. It is not a replacement for rendering Storybook stories into a baseline set; use your capture tool and Reg-suit for that comparison workflow. When you need clean screenshots of web pages, one GET request returns an image or PDF:

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

See the ScreenshotNeo API documentation for the request options. Cookie and consent banners are accepted and more than 60 known consent platforms, newsletter popups, and chat widgets are removed before the shot; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers report the page verdict and billing status. An MCP server gives AI agents tools to take screenshots, get page information, and capture PDFs. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000. Create a free account and get 1,000 screenshots a month with no card.

FAQ

Does Reg-suit take the Storybook screenshots?

No. A capture tool renders stories into image files; Reg-suit consumes those files from core.actualDir for comparison and report publishing.

Can I compare a built Storybook?

Yes. Build it, serve the output locally, capture the served Storybook, and point Reg-suit at the resulting image directory.

Which publisher should I use?

Reg-suit documents S3 and GCS publisher plugins. Choose the provider and access setup your project already supports, then configure the key policy so the intended prior snapshots are retrieved.

What should I review before accepting a visual change?

Review the report and confirm the difference is expected. Check whether rendering inputs such as fonts, assets, viewport, providers, or timing changed before updating the baseline.