How to Run Chromatic Tests Locally Before Pushing a Branch
Run Chromatic from your repository before pushing, review visual changes, and diagnose Storybook build failures with the CLI or Storybook addon.
Run Chromatic from your repository with your project token:
npx chromatic --project-token YOUR_PROJECT_TOKENThis starts the workflow from your development environment, but the visual snapshots run in Chromatic’s cloud after Storybook is built and uploaded. A first build establishes baselines; later builds compare snapshots against them. Review the completed build and any visual changes before pushing. Chromatic CLI documentation and its Quickstart describe the workflow.
1. Prepare your Storybook and token
- Make sure the production Storybook build works in the repository. Chromatic’s CLI uses the
build-storybookscript by default. - Get the project token assigned to your Chromatic project. Keep it out of committed files and shared logs. For repeated use, set it as an environment variable:
export CHROMATIC_PROJECT_TOKEN=YOUR_PROJECT_TOKENThen run the CLI using the environment variable:
npx chromatic --project-token "$CHROMATIC_PROJECT_TOKEN"For CI, Chromatic documents storing the token in a CI secret or configuring CHROMATIC_PROJECT_TOKEN. See the Chromatic CI guide.
2. Run the pre-push check
From the project root, use the package runner that matches your project:
# npm / npx
npx chromatic --project-token YOUR_PROJECT_TOKEN
# Yarn
yarn chromatic --project-token YOUR_PROJECT_TOKEN
# pnpm
pnpm chromatic --project-token YOUR_PROJECT_TOKENWatch the command for build and upload status, then open the resulting Chromatic build to review visual changes. Accept intentional changes to update their baselines; investigate unexpected changes before pushing. A changed snapshot can produce a non-zero exit status when UI Tests or UI Review checks are enabled. That status does not by itself mean Storybook failed to build.
3. Reproduce a Storybook build failure locally
If Chromatic reports “Failed to build Storybook,” first reproduce the production build rather than debugging visual comparisons. A development server can work while the production build fails.
npm run build-storybook
npx http-server storybook-static -oFix any error reproduced by the production build, then rerun Chromatic. If you build Storybook in a separate step or use a custom output directory, point the CLI to that directory:
npx chromatic --project-token YOUR_PROJECT_TOKEN --storybook-build-dir=storybook-staticIf your project customizes how Storybook is invoked, ensure its production build script includes the configuration needed for the Chromatic build.
4. Use CLI options to diagnose issues
| Option | Use |
|---|---|
--dry-run |
Debug without publishing or running a Chromatic build. It does not verify a completed cloud visual-test run. |
--diagnostics-file |
Write process context to a diagnostics file before termination. |
--no-interactive |
Use more elaborate logs, similar to CI output. |
--debug |
Enable verbose logging and non-interactive mode. |
--trace-changed |
Print the dependency tree for changed files when diagnosing TurboSnap. |
--only-story-names |
Limit a build to specified story names. |
--list |
List stories; this option requires a Chromatic build. |
Examples:
npx chromatic --project-token YOUR_PROJECT_TOKEN --dry-run --diagnostics-file=chromatic-diagnostics.json
npx chromatic --project-token YOUR_PROJECT_TOKEN --debug
npx chromatic --project-token YOUR_PROJECT_TOKEN --trace-changed5. Choose CLI or the Storybook addon
The CLI suits a repeatable pre-push command and detailed diagnostics. The Storybook Visual Tests Addon offers an on-demand workflow from Storybook: use its play control, then review highlighted stories and pixel changes in the addon panel. The addon sends stories to Chromatic’s cloud for snapshots. Accepting changes updates baselines that sync to the cloud, where people checking out the branch can access them. This is a local interface for cloud-backed testing, not offline snapshot computation. See the Visual Tests Addon documentation.
6. Enable TurboSnap only when its setup is understood
TurboSnap uses Git changes and story dependency information to limit testing to potentially affected stories. It is optional; become familiar with the default workflow first. Chromatic’s setup guide lists these prerequisites:
- Chromatic CLI 10.0 or later and Storybook 6.5 or later, or Vitest 4 or later.
- Git 2.28.0 or later, a Webpack- or Vite-based project, correctly configured stories, and enabled UI Tests.
- A GitHub Actions
pushworkflow requirement described in the setup guide.
The guide says TurboSnap is unlocked after ten successful CI builds. When ready, enable it with --only-changed or the corresponding configuration option. In a monorepo, verify that the Storybook base and config directories resolve correctly. Path mismatches between generated Storybook stats and Git’s changed-file paths can stop TurboSnap from associating files with stories. The documented helper can inspect or update configuration:
npx @chromatic-com/turbosnap-helperSee Chromatic’s TurboSnap setup guide and TurboSnap troubleshooting.
7. Troubleshooting checklist
| Symptom | Likely cause | What to do |
|---|---|---|
| “Failed to build Storybook” | The production Storybook build is failing. | Run npm run build-storybook, serve storybook-static, and fix the reproduced build error before investigating publishing. |
| Local build succeeds, Chromatic publishing fails | Publishing or environment diagnostics are needed, or the CLI is using a different build output. | Try --debug or --diagnostics-file; if building separately, pass --storybook-build-dir=storybook-static. |
| Token or authentication error | The project token is missing, incorrect, or not available to the process. | Check the token for the intended project and how the environment variable is set. Do not commit the token or paste it into shared logs. |
| Non-zero exit after snapshots changed | An enabled UI Test or UI Review check detected changes. | Review the Chromatic result. Accept intentional visual updates or fix unintended changes; distinguish this from a build failure. |
| TurboSnap misses affected stories | Prerequisites, Git change information, or Storybook and Git paths may not line up. | Check the documented prerequisites and monorepo paths, then inspect changed-file dependencies with --trace-changed. |
| Need to isolate a few stories | The full story set may not be necessary for diagnosis. | Use --only-story-names for selected stories. Use --list to inspect story names, keeping in mind that it requires a build. |
8. Performance, reliability, and cost considerations
- Build time: Chromatic’s workflow includes a production Storybook build and upload. Keep the production build reproducible and use the build directory option when a separate build step creates the artifacts.
- Scope: Start with the default behavior. TurboSnap can reduce the stories considered based on changed files, but incorrect paths or configuration can undermine that association.
- Reliability: A local production build is a useful first diagnostic. A successful local build does not prove that the cloud publishing and visual-test workflow completed; inspect the Chromatic build result too.
- Cost: This research dossier does not specify Chromatic pricing, so check the current Chromatic plan details for usage and billing.
Or skip the browser setup
Chromatic tests Storybook components in its cloud. If the task is capturing a website screenshot from a URL, ScreenshotNeo provides a screenshot API and MCP server. One GET request returns a PNG, JPEG, WebP, or PDF. 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.webpCookie banners are accepted like a visitor 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 identify the page verdict and billing status. An MCP server lets AI agents use take_screenshot, get_page_info, and capture_pdf. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Sign up for 1,000 free screenshots a month, with no card.
FAQ
Does “locally” mean Chromatic snapshots run offline?
No. You start the workflow locally, but Chromatic builds and uploads Storybook and runs visual snapshots in its cloud.
Can I use the addon without the CLI?
The addon provides an on-demand Storybook interface for cloud-backed snapshots. Use the CLI when you want its command-line workflow and diagnostics.
Does dry-run confirm my visual changes?
No. It helps debug without publishing or running a Chromatic build, so it cannot confirm a completed cloud visual-test run.
Should I turn on TurboSnap for my first build?
It is not required. Learn the default workflow and verify TurboSnap’s prerequisites and path configuration before enabling it.
