How to use Chromatic for visual testing of a Storybook

To use Chromatic for visual testing of a Storybook, connect a Chromatic project to your Storybook, run a build with its project token, and review the captured stories against their baselines. The first build establishes the baseline; later builds show visual differences for your team to accept or fix. Once that workflow is reliable, run it in CI and consider TurboSnap to reduce recaptures.

Chromatic’s CLI builds and uploads Storybook to its cloud to start publishing and UI tests. See the Quickstart, CLI reference, and visual testing guide for current details.

1. Understand what Chromatic checks

A Storybook story describes a rendered component state or variation. Chromatic captures that state in a cloud browser and compares it with the corresponding baseline. A difference is a signal to review, not proof of a defect: intentional design changes should be accepted, while unexpected changes should be investigated and corrected.

Visual snapshots complement accessibility and interaction checks; they do not replace them. The number of snapshots can grow when the test matrix includes multiple browsers, devices, themes, or viewports. See Chromatic’s snapshot documentation.

2. Connect Storybook to a Chromatic project

Create a project in Chromatic and copy its project token. Treat the token as a credential, especially in CI.
Install the CLI as a development dependency, or invoke it with your package manager. The examples below use npm.
Ensure the Storybook build command represents the configuration you want tested. The CLI uses the project’s build-storybook script by default; if your build relies on custom settings, use equivalent settings for the Chromatic build.
Run the first Chromatic build. Inspect the published stories and use this build to establish the initial baselines.

npm install --save-dev chromatic
npx chromatic --project-token=YOUR_CHROMATIC_PROJECT_TOKEN

Replace the placeholder with the project token from Chromatic. Do not commit a real token to source control. In local development, you can keep it in a shell environment variable and pass that variable to the CLI according to your shell and package scripts.

3. Review visual changes

After the initial build, run Chromatic again whenever you want to check a new version of the Storybook. The service captures the stories and presents differences from the baseline.

Open the build’s visual review.
Inspect each changed story in context. Check whether the change matches the intended code or design update.
Accept changes that are intentional so the baseline can sync.
For unexpected changes, fix the component, story, data, or styling and publish another build.

Keep stories representative and deterministic. Unstable content such as time-dependent values, random data, or environment-specific styling can create noisy differences that are hard to review.

4. Run visual tests from Storybook

If you prefer to start checks from the Storybook interface, install the Visual Tests addon. Chromatic’s current setup guide lists Storybook 7.6 or higher as a requirement.

Follow the addon’s installation instructions for your Storybook version.
Authenticate the addon and connect it to the relevant Chromatic project.
Use the addon sidebar to run visual tests.
Inspect highlighted differences and accept intentional changes so the baseline can sync.

The addon is an alternate way to launch and review visual tests from Storybook. The CLI remains useful for repeatable local commands and CI automation.

5. Automate Chromatic in CI

Run Chromatic after the Storybook build is ready in your CI workflow. Store the project token in the CI system’s secret store under CHROMATIC_PROJECT_TOKEN; do not put its value in a checked-in workflow file.

npm install --save-dev chromatic
npx chromatic --project-token="$CHROMATIC_PROJECT_TOKEN"

Add these commands to a job that checks out the repository, installs dependencies, and has access to the project token. Adapt the job to your CI provider and package manager. The Chromatic CI guide has provider-specific setup. Make sure the build uses the same relevant Storybook options as your normal build.

Use CI results as a review signal in the code change workflow. A detected difference still needs a human decision: accept an intended UI update or investigate an unintended one.

6. Add TurboSnap after the default workflow is stable

TurboSnap uses Git changes and a Webpack or Vite dependency graph to select affected stories for new captures. Snapshots for unaffected stories may be copied from a baseline. Chromatic recommends getting familiar with the default behavior first because complex dependency configuration can make debugging harder or miss UI changes.

The setup guide lists these prerequisites: CLI 10.0 or later, Storybook 6.5 or later or Vitest 4 or later, Git 2.28.0 or later, and ten successful CI builds. Check the current TurboSnap setup guide before enabling it.

Enable the option in one of the supported ways:

CLI: pass --only-changed.
GitHub Action: set onlyChanged.
Configuration file: set onlyChanged: true in chromatic.config.json.

Static assets and files outside the usual dependency graph need attention. Prebuilt Storybooks may need stats output. Check the CLI output to verify it identifies changed files and affected stories. If expected stats are missing, Chromatic may fall back to an unoptimized build; investigate that output rather than assuming only changed stories were captured. Read the TurboSnap overview for its model and limitations.

7. Plan snapshot usage

Chromatic’s billing documentation expresses usage in billed snapshots: a captured snapshot counts as 1, a copied TurboSnap snapshot as 0.2, and a bypassed snapshot as 0. These are usage units, not prices. Total usage depends on tests, builds, browsers, modes, and accessibility snapshots. Estimate from your own test matrix and check the current billing documentation and plan details.

For example, adding another browser or theme can increase the set of rendered states. TurboSnap may reduce recaptures for unaffected stories, but it adds dependency-tracking requirements. Confirm that the optimized build reports the affected stories you expect.

8. Troubleshoot common problems

Symptom	Likely cause	What to check
Authentication fails	The project token is missing, malformed, or belongs to another project.	Copy the token from the intended Chromatic project. In CI, confirm the secret name and that the job receives it.
Chromatic cannot build Storybook	The build script, dependencies, or custom build settings differ from the working local setup.	Run the Storybook build locally, inspect the CLI output, and pass equivalent configuration to the Chromatic build.
Many changes appear on the first run	The initial run is establishing baselines, or the environment differs from the intended reference.	Review the first build carefully, verify representative stories, and accept the intended initial states.
The same story changes on every run	Rendered content may be nondeterministic or dependent on time, random values, external data, fonts, or environment settings.	Make story inputs stable and ensure required assets and styling are available in the build environment.
The addon does not appear or cannot run tests	Storybook may be below the documented minimum, installation may be incomplete, or the addon may not be connected to a project.	Check the current addon setup requirements; the guide lists Storybook 7.6 or higher. Complete authentication and project connection.
TurboSnap captures more than expected	Dependency stats may be missing, or changes may affect many stories through the dependency graph.	Inspect CLI output and stats generation. For a prebuilt Storybook, follow the setup guide’s stats instructions.
A TurboSnap build uses the unoptimized path	Expected dependency information was unavailable.	Check for fallback messages and verify the stats output before relying on optimization.

9. Keep the workflow reliable

Start with a normal Chromatic build and review several change cycles before enabling TurboSnap.
Keep story data deterministic and make stories cover meaningful component states.
Protect the project token in local and CI environments.
When expanding browser, device, theme, or accessibility coverage, account for the added snapshot work.
Review optimized-build output after enabling TurboSnap, especially when adding static assets or dependencies outside the normal graph.

Or skip the browser setup

Chromatic tests rendered Storybook stories against visual baselines. For a straightforward website screenshot from a URL, ScreenshotNeo provides a screenshot API and MCP server. Its one-call API can return a PNG, JPEG, WebP, or PDF. See the ScreenshotNeo API documentation for the available parameters.

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

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

ScreenshotNeo accepts cookie and consent banners as a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each cleanup step can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers report the page verdict and billing status. Its MCP server offers take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients. The free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots. Every feature is available on every plan.

FAQ

Does a visual difference automatically mean a bug?

No. Review the rendered change against the intended design and code update. Accept intentional changes; correct unexpected ones.

Can Chromatic check more than one browser or theme?

Chromatic can produce multiple snapshots across browser, device, theme, and viewport dimensions. Include those states deliberately and account for their usage.

Should I enable TurboSnap on the first build?

Establish and understand the normal baseline workflow first. TurboSnap relies on a dependency graph and Git changes, so it is easier to diagnose after the default build and review cycle is familiar.

Is a screenshot of a website the same as a Storybook visual test?

No. A website screenshot captures a page at a URL. A Chromatic visual test captures Storybook story states and compares them with reviewed baselines.