Chromatic Review for Visual Regression Testing

Chromatic is a cloud service for visual regression testing and review. In its Storybook workflow, you publish stories as reproducible UI states; Chromatic captures snapshots in cloud browsers, compares later builds against accepted baselines, and gives reviewers a link to inspect detected changes. It also documents integrations for Vitest, Playwright, and Cypress. Those visual checks complement functional tests: a button can still respond to a click while a layout change makes it obscured or confusing. [Chromatic documentation]

How does visual testing work?

Visual regression testing compares a rendered interface with a known reference. The reference is usually called a baseline. A detected difference is a signal for review, not proof of a defect: intended design changes also produce differences and need to be accepted into the baseline.

Define UI states. In Storybook, stories describe reproducible component states and variations. Each story can serve as a visual test case.
Publish or capture a build. The Chromatic CLI builds and uploads Storybook to Chromatic’s cloud. For Vitest, Playwright, or Cypress, Chromatic documents integrations or flags that capture UI archives as the tests run.
Capture snapshots. Chromatic renders the states in cloud browsers and saves their snapshots. The first run establishes the initial baselines.
Compare later builds. New snapshots are compared with accepted baselines. A difference appears in the review workflow.
Review and decide. Inspect the changed result, then accept an intended change or fix an unintended one. The accepted result becomes the reference for subsequent comparisons.

This flow makes the test input and the review decision explicit. Reliable coverage depends on the UI states you supply: a component state absent from your stories or test cases cannot be checked through those inputs.

How Chromatic fits into a frontend stack

Storybook

Storybook is the central documented workflow. Stories provide isolated, repeatable component states, and the Chromatic CLI builds and uploads the Storybook. This suits component libraries and design systems where the same components appear across many products or pages. Add stories for meaningful variants and states, such as loading, validation errors, long content, and disabled controls, so those states are represented in the captured build.

Vitest, Playwright, and Cypress

Chromatic also documents integrations for these test frameworks. In this route, your existing tests exercise the UI and Chromatic captures UI archives while they run. Consult the current integration documentation for the setup and flags for the framework and version you use; those details can change. Do not assume a framework integration automatically covers every route, state, browser, or viewport. Coverage follows the tests and configurations you run.

Functional, visual, and accessibility checks

Functional tests ask whether interactions behave as intended. Visual checks ask whether the rendered appearance changed. Chromatic’s overview also documents interaction tests that simulate actions such as clicking, typing, hovering, and dragging, and accessibility checks using axe. The accessibility guide describes tracking violations against a baseline for each story, which helps distinguish new findings from existing ones. Treat these as documented product capabilities; actual coverage depends on setup and test inputs. [Chromatic feature overview] [Accessibility testing documentation]

Set up the Storybook workflow

Use the current official quickstart for the exact install command and project-specific configuration. The high-level workflow below shows what to wire up; it is not a substitute for version-specific CLI instructions.

Make the Storybook build representative. Add stories for the component states and variants that matter. Keep test data stable so a change in fixture content does not create noise.
Create a Chromatic project. Follow the quickstart to connect the project and obtain its project token. Treat that token as a secret.
Install and run the CLI. Add the CLI using the documented setup for your package manager, then run it against the project token. The CLI builds and uploads Storybook.
Review the first build. The first run establishes snapshots and baselines. Check that the captured states look as expected before relying on later comparisons.
Add the command to CI. Run Chromatic when relevant code changes are proposed. Follow the official GitHub Actions guide or your CI provider’s documented setup, and store the project token as a secret rather than committing it.
Review changes on each build. Use the Chromatic result link to inspect visual differences. Accept intended changes so subsequent builds compare against the reviewed state.

For exact install commands, token options, framework flags, and CI configuration, use the official quickstart, CLI documentation, and GitHub Actions guide. These are version-sensitive implementation details; check them for your project rather than copying an unverified command.

Run visual checks in CI and during local development

CI is the repeatable checkpoint for pull requests: it publishes a build, compares snapshots, and lets the team review changes in context. Chromatic’s pull-request workflow documentation describes comparisons across dimensions such as browsers, viewports, themes, locales, and CSS media features. Configure only the dimensions that reflect your supported product experience; each additional combination increases the set of snapshots to review.

The Storybook Visual Tests addon supports on-demand tests during local development, which can help catch a change before pushing it. Its documentation says it does not replace CI. Keep CI as the shared check so results are not dependent on an individual developer’s local session. The addon documentation also notes snapshot usage against a plan allowance; the research available for this article does not establish current pricing or limits. [Visual Tests addon documentation] [Pull request workflow]

Baselines, branches, and review decisions

A baseline is the accepted snapshot used for comparison. Your first build creates the initial reference; subsequent builds compare new captures with those accepted snapshots. The important operational question is who reviews and accepts a difference. Establish a team convention so intended design changes are explicitly approved, while unexplained differences are investigated before acceptance.

Review the changed state alongside the intended design or code change.
Check whether the difference is limited to the expected component and states.
Investigate unexpected changes before accepting them; a broad baseline update can hide unrelated regressions.
Keep the story or test case that exposed the difference stable and useful for future changes.

Chromatic’s documented workflow links visual changes to builds and pull-request review. Read its current guidance on branch and baseline behavior for the repository strategy you use; the exact mechanics and options are product-specific and can evolve.

Coverage choices that affect results

Choice	What it changes	Practical guidance
Stories or test cases	Which UI states are captured	Cover representative states, edge cases, and high-impact components instead of only the default appearance.
Browsers	Which browser rendering differences can be observed	Choose browsers based on your supported audience and documented configuration.
Viewports	Which responsive layouts are compared	Include widths where the layout meaningfully changes, such as around your responsive breakpoints.
Themes and locales	Which appearance and content variants are checked	Include dark themes, long translations, and other variants where they can alter layout or contrast.
CSS media features	How the page renders under media conditions	Include relevant modes your product supports; avoid combinations that users cannot encounter.
Interactions	Which post-action states are exercised	Use documented interaction testing or framework tests for meaningful states that do not appear until a user acts.

Chromatic’s overview describes checks for appearance, layout, fonts, and colors. Its pull-request documentation lists browser, viewport, theme, locale, and CSS media feature dimensions. These are documented capabilities, not a guarantee that a project automatically tests every combination. [Feature overview] [Pull request workflow]

Keep visual tests useful and reliable

Make rendering repeatable. Use stable fixtures and avoid data that changes between runs. If time, animation, or external content affects a story, control it using your app’s test setup.
Wait for the intended state. A capture taken before fonts, images, or asynchronous content finish rendering can differ from the state a reviewer expects. Use the relevant framework’s supported synchronization and Chromatic’s current configuration guidance.
Keep stories focused. Isolated components make a changed region easier to diagnose than a large page with many unrelated moving parts.
Choose coverage intentionally. A large matrix of browsers, viewport sizes, themes, and locales raises snapshot volume and review effort. Prioritize supported combinations and high-risk layout changes.
Route results to reviewers. Run the checks where pull-request authors and reviewers can inspect them, and define who resolves or accepts a detected change.
Use functional tests too. A matching screenshot cannot establish that controls work or that an interaction is correct. Pair visual tests with the functional and accessibility checks appropriate to your app.

Visual tests can be stable only to the extent that the rendered inputs are stable. Differences caused by changing data, browser rendering, or incomplete loading need diagnosis; repeatedly accepting unexplained changes weakens the baseline.

Troubleshooting common Chromatic issues

Symptom	Likely cause	What to check
Build cannot find or build Storybook	The CI command, working directory, dependencies, or Storybook build configuration does not match the project.	Run the same build in the repository’s CI environment, confirm the working directory and scripts, and compare them with the current CLI quickstart.
Authentication or project upload fails	The project token is missing, invalid, or unavailable to the CI job.	Check the secret name and job access, confirm the token belongs to the intended project, and avoid printing the token into logs.
Many unexpected visual changes appear	A shared style, font, fixture, viewport, theme, or rendering condition changed; the build may also capture before content settles.	Inspect representative changes first, check shared assets and test data, then verify waits and capture configuration before accepting baselines.
A changed component is not reported	The state may not be represented in a story or executed test, or the relevant build may not have run.	Confirm the story/test exists, is included in the build, and ran in CI. Add an explicit case for the missing state.
Local results do not match CI expectations	Local on-demand testing and CI have different environments or roles in the workflow.	Use local tests for early feedback, then rely on the documented CI run and its review result as the shared checkpoint.
Snapshot usage grows unexpectedly	More stories, browsers, viewports, themes, locales, or other capture combinations are being tested.	Review the test matrix and current plan allowance in Chromatic’s official product documentation. This article does not establish current prices or limits.
Framework integration does not capture expected screens	Integration flags or setup may differ by framework version, or the relevant test path may not execute.	Check the current Vitest, Playwright, or Cypress integration instructions and verify the test runs in the same CI job that uploads results.

For exact error messages and current configuration details, use the relevant Chromatic documentation. Framework and CLI behavior can change between versions.

Performance, reliability, and cost considerations

Chromatic runs captures in cloud browsers, so the workflow depends on building and uploading the UI inputs and waiting for remote capture and review results. Keep the build focused, avoid unnecessary test combinations, and run it at a point in CI where reviewers can act on its result. The documentation establishes the workflow but does not provide a universal runtime benchmark; build size, number of stories, selected dimensions, and CI environment affect the experience.

For reliability, treat the captured output as a function of application state, assets, test data, and the chosen browser and viewport configuration. Stable inputs and explicit states make differences easier to interpret. A visual pass is evidence that the configured captures matched their baselines; it does not prove all routes or interactions are correct.

Cost depends on the plan and snapshot usage. The reviewed material notes that the Visual Tests addon documentation refers to snapshot use against a plan allowance, but it does not establish current plan limits or prices. Check Chromatic’s current pricing and plan documentation before budgeting or selecting a test matrix. The overview’s TurboSnap cost reduction is a vendor claim and is not used here as an independent performance or savings result.

Chromatic and ScreenshotNeo serve different capture jobs

Chromatic is for reviewing changes to application UI through stories or supported test-framework integrations, baselines, and pull-request workflows. ScreenshotNeo is a website screenshot API and MCP server for developers: a GET request with a URL returns a PNG, JPEG, WebP, or PDF. It can help when you need a clean capture of a live page, a rendered asset for a workflow, or screenshot access from an AI agent. It does not replace Chromatic’s story-based visual regression review.

ScreenshotNeo’s API supports full-page capture, element selection, device and viewport options, custom CSS and JavaScript, waits, request blocking, caching, async jobs, and more. Its documented clean-capture behavior accepts cookie and consent banners and removes known consent platforms, newsletter popups, and chat widgets; these steps can be disabled individually. Only clean shots are billed, and response headers report page verdict and billing status. See the ScreenshotNeo website and API documentation.

Or skip the browser setup

For a one-off capture of a live page, call the ScreenshotNeo API. Get an API key, then run one of these examples. The cURL and Python examples save the response as a WebP file. The Node.js example makes the request and shows how to save the returned bytes.

cURL

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

Python

import requests

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

Node.js

import { writeFile } from 'node:fs/promises';

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 writeFile('shot.webp', Buffer.from(await res.arrayBuffer()));

These examples use the documented endpoint and parameters; replace the target URL with the page you need. For output formats, capture options, authentication details, and response headers, see the ScreenshotNeo API documentation.

Cookie banners, popups, and chat widgets are removed before the shot.
Bot checks, blank pages, and failed loads are never billed.
An MCP server lets AI agents use screenshot tools.
1,000 screenshots a month are free with no card; paid plans start at $5 for 3,000.

Frequently asked questions

Does Chromatic replace functional tests?

No. Visual snapshots can reveal appearance changes, while functional tests establish behavior. Use both for the states and interactions your application needs.

Can I use Chromatic without Storybook?

Chromatic documents integrations for Vitest, Playwright, and Cypress in addition to its Storybook workflow. Follow the current integration guide for your chosen framework.

Does a visual difference always mean a bug?

No. It may be an intended design change or an unintended regression. Review the change and accept it only when the rendered result is expected.

Does the local Visual Tests addon replace CI?

No. Chromatic’s addon documentation says it supports on-demand local testing and does not replace CI.

Does a passing visual test prove accessibility?

No. Chromatic documents separate axe-based accessibility checks. A matching image alone does not establish accessibility or interaction correctness.