How to Test Website Screenshots with Chromatic and Storybook

To test website screenshots with Chromatic and Storybook, add the official @chromatic-com/storybook addon to Storybook 7.6 or later, connect a Chromatic project, run a first build to establish screenshot baselines, and run visual tests again as stories change. Review each difference: accept it when the new appearance is intentional, or fix the component and rerun when it is a regression. Add the Chromatic step to CI so pull or merge requests receive a UI Tests check before merge. The rendered Storybook story is the test case, so the states covered depend on the stories your team writes.

What screenshot tests check

A visual test captures a rendered story and compares its pixels with a previously accepted image baseline. It can reveal changes in layout, color, size, contrast, and other visible details. A difference is a signal for review, not proof of a bug: some changes are intentional and should become the new baseline.

This differs from a DOM or HTML snapshot test, which compares markup rather than rendered appearance. Use screenshot comparisons when the question is “Does this still look right?” Use markup snapshots when the question is about generated structure or other non-visual output. Interaction tests answer a separate question: whether a user action produces the expected behavior. These test types complement one another.

Set up Chromatic with Storybook

Check the Storybook version. The documented Chromatic integration requires Storybook 7.6 or later. If you are on an older version, update Storybook before following this setup.
Install the official addon. From your project root, run the Storybook CLI command:

npx storybook@latest add @chromatic-com/storybook

Connect a Chromatic project. Sign in to Chromatic, choose an existing project or create one, then follow the addon’s setup prompts to link the project. The integration uses Chromatic’s cloud browsers to run the captures.
Run the first visual test. This initial build captures the stories and establishes the known-good image baselines for later comparisons. Make sure the stories represent the component states you intend to check.
Review the result. Open the Visual Tests panel in Storybook to inspect changed stories and their pixel differences. Accept a change if it is intentional. If it is unexpected, correct the component or story and run the test again.
Run it on subsequent changes. Stories act as test cases. As code or story changes affect their rendered output, Chromatic captures them again and compares each result with its baseline.

Build useful story coverage

Chromatic can only check the visual states represented in the stories you have authored. Treat story coverage as a deliberate part of the test design: include the component variations and states where a visual defect would matter. For example, a component with distinct variants should have stories that render those variants. If a state is absent from the story set, it cannot be covered by that run.

Keep stories focused enough that a reported change is understandable. When a diff appears, identify which story changed and whether its rendered state is the one you meant to test. A stable, representative story set makes reviews more useful than a large set of poorly understood cases.

Review screenshot differences

Open the changed story in the Visual Tests panel.
Inspect the rendered result and the pixel difference in context.
Decide whether the change is intentional. A designed update can be accepted as the new baseline.
If the output is wrong, fix the component, its styles, or the story setup, then rerun the visual test.
For an intentional change, update the baseline so later runs compare against the approved appearance.

Do not accept every diff automatically. Baseline approval is a review decision: accepting an unintended change can make a regression part of the reference image, while rejecting an intended redesign leaves the baseline out of date.

Add Chromatic to CI

Run Chromatic in your continuous integration workflow so visual checks happen for code changes before merge. The project token authenticates the CI build, so store it as a CI environment variable or secret and reference that variable in the Chromatic step rather than committing the token to the repository.

Add a Chromatic step to the workflow that already runs for pull or merge requests.
Provide the Chromatic project token through the CI provider’s environment-variable or secret settings.
Run the visual build as part of the request’s checks.
Review changed stories and resolve diffs before merging.
If your team requires visual approval, configure the UI Tests check as a required status check in your Git provider.

The exact workflow syntax depends on your CI provider and repository configuration. Use the provider-specific instructions linked from the Storybook visual testing guide; the essential setup is a Chromatic build authenticated with the project token and a check attached to the request.

Or skip the browser setup

If you need screenshots of pages rather than story-based visual regression, ScreenshotNeo takes a screenshot or PDF with one API request. Its API is useful for ad hoc captures and capture workflows; Chromatic remains the documented route here for comparing Storybook stories against reviewed visual baselines.

See the ScreenshotNeo API documentation. For example, this cURL request saves a WebP screenshot:

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

The equivalent Python request is:

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)

And in Node.js:

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await import('node:fs/promises').then(fs => fs.writeFile('shot.webp', Buffer.from(await res.arrayBuffer())));

ScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots, and 1,000 screenshots a month are free with no card; paid plans start at $5 for 3,000. Sign up for free and get 1,000 screenshots a month with no card.

Performance, reliability, and cost considerations

Visual testing runs captures in Chromatic’s cloud browsers, so account for the time needed to build and review results in your CI workflow. The source material does not establish current build durations, browser coverage, pricing, plan limits, or service guarantees; check Chromatic’s current product documentation before making plans around those details.

For reliability, keep the project token in CI’s secret store, run the check on the requests where visual review matters, and keep stories representative of the states you need covered. A successful run only speaks to the stories included and their captured states. It does not establish that every page or interaction in the wider site is visually correct.

Troubleshooting

Symptom	Likely cause	What to do
The addon setup does not match the project	Storybook is older than the documented 7.6 minimum.	Check the Storybook version and update to 7.6 or later, then follow the addon setup again.
CI cannot authenticate the Chromatic build	The project token is missing, invalid, or not exposed to the job.	Verify the token in the CI secret settings and ensure the workflow passes it as an environment variable. Do not commit the token to source control.
A story is missing from visual results	The state may not be represented by a story in the set being tested.	Add or correct a story for the component state you want covered, then run the build again.
A diff appears after a change that was expected	The baseline still represents the previous appearance.	Inspect the story and diff, then accept the new baseline if the change is intentional.
A diff appears unexpectedly	A component, style, or story change altered the rendered pixels.	Use the Visual Tests panel to inspect the changed story, fix the source of the unintended appearance, and rerun.
The UI Tests check does not block merging	The Git provider may not have the check configured as required.	Configure the UI Tests check as a required status check in the repository settings if your workflow requires it.

FAQ

Does the first Chromatic run create the baseline?

Yes. The first successful visual test captures the stories and establishes the images used as the starting reference for later comparisons.

Does every screenshot difference mean a bug?

No. A difference may be an intentional design change. Review it and either accept the new baseline or correct the unintended output.

Are visual tests the same as snapshot tests?

No. Visual tests compare rendered screenshot pixels; DOM or HTML snapshots compare markup. Choose based on whether the behavior under test is appearance or markup.

Can Chromatic test a component state without a story?

The documented workflow uses rendered Storybook stories as test cases. Add a story for a state you want included in the visual test set.

Can I make the visual check required before merge?

Yes. With the UI Tests check on configured pull or merge requests, teams can make that check required in their Git provider.