The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Run Chromatic from your repository with npx chromatic --project-token YOUR_PROJECT_TOKEN. The command starts a production Storybook build and uploads it to Chromatic, where the visual tests run in the cloud. You can start the workflow and review its results from your development environment, but the snapshot testing itself is not fully offline.
Run Chromatic from your repository
-
Make sure Storybook builds successfully in production and that you have the project token for your Chromatic project. By default, the CLI uses the
build-storybookscript. If your project customizes how Storybook is invoked, ensure that its production build script includes the configuration needed for the stories you want to test. See Chromatic’s CLI documentation and Quickstart documentation.As an Amazon Associate I earn from qualifying purchases.
-
From the repository root, run the command for your package manager:
Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.npx chromatic --project-token YOUR_PROJECT_TOKENyarn chromatic --project-token YOUR_PROJECT_TOKENpnpm chromatic --project-token YOUR_PROJECT_TOKEN
-
Wait for the build and upload to finish, then review the results before pushing. The first build establishes baselines; later builds compare their snapshots against those existing baselines.
#1 Best Overall
-
For a completed run, inspect changed snapshots and decide whether each change is intentional. Accept intentional changes as new baselines; fix unintended visual regressions before pushing.
Keep the project token private. Chromatic’s CI guidance describes using CHROMATIC_PROJECT_TOKEN as an environment variable or CI secret. Avoid putting a real token in a committed command, shared documentation, or logs.
Understand what “locally” means
The CLI runs on your machine and initiates the build-and-upload workflow, but Chromatic’s visual snapshots run on its cloud infrastructure. The Storybook Visual Tests Addon offers another way to initiate and inspect that cloud-backed workflow from Storybook; it does not turn snapshot testing into an offline process.
Use the CLI for a repeatable pre-push check
The CLI is the straightforward choice when you want a command you can run from the repository and diagnose from terminal output. It also lets you use options such as --dry-run for diagnostics or --debug for more verbose logs.
Use the Storybook addon for on-demand review
With the Visual Tests Addon installed, use its play control in Storybook to start tests. The addon panel lets you inspect highlighted stories and pixel changes. Stories are sent to Chromatic for snapshots; accepting changes updates baselines that sync to the cloud and are available to others checking out the branch. See Chromatic’s Visual Tests Addon documentation.
Reproduce a failed Storybook build before debugging Chromatic
If the CLI reports “Failed to build Storybook,” treat it first as a production Storybook build problem, not proof that a Chromatic visual test failed. A development server can work even when the production build does not. Reproduce the production build locally:
-
Build Storybook:
npm run build-storybook. -
If the build succeeds, serve the generated output:
npx http-server storybook-static -o.Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy. -
Check the production Storybook output and correct any build or configuration errors. Once the local production build works, retry Chromatic.
If you build Storybook separately, tell Chromatic where the output is with --storybook-build-dir=storybook-static. If the local build succeeds but publishing still fails, collect CLI diagnostics to investigate the publishing step.
Choose CLI options for diagnosis
Use the option that matches the problem rather than treating every unsuccessful run as a snapshot regression. Chromatic documents these troubleshooting flags in its CLI guide:
--dry-runhelps debug without publishing or running a Chromatic build. It does not verify that a cloud visual-test run completed successfully.--diagnostics-filewrites process context tochromatic-diagnostics.jsonbefore termination.--no-interactiveproduces more elaborate logs, similar to CI.--debugenables verbose logging and--no-interactive.--trace-changedprints a dependency tree for changed files when diagnosing TurboSnap.--listlists stories, but requires a Chromatic build.--only-story-nameslimits a build to specified stories.
Interpret the result and exit status
A non-zero exit status does not necessarily mean Storybook failed to build. When UI Test or UI Review is enabled, detected snapshot changes can produce a non-zero status. Open the Chromatic results, review the affected stories, and either accept intentional changes or fix regressions before pushing. The CI documentation explains this behavior.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Enable TurboSnap only after the default workflow is clear
TurboSnap uses Git changes and story dependency information to limit testing to stories that may have been affected. It is optional, and Chromatic cautions that its configuration is more involved than the default workflow. Get familiar with the default behavior first. Chromatic says TurboSnap unlocks after ten successful CI builds; it is not a prerequisite for your first local run.
Best Value
Check the documented prerequisites
Chromatic’s TurboSnap setup guide lists these requirements:
- Chromatic CLI 10.0 or later.
- 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, as described in the guide.
Check changed-file paths, especially in a monorepo
When you enable it, use chromatic --only-changed or the corresponding configuration option. Confirm that Chromatic resolves the Storybook base and config directories correctly. In a monorepo, a mismatch between the paths in Storybook’s generated stats and Git’s changed-file paths can stop TurboSnap from connecting changed files to stories. Chromatic documents a helper for inspecting or updating configuration: npx @chromatic-com/turbosnap-helper.
Or skip the browser setup
Chromatic is for visual testing of Storybook stories; ScreenshotNeo is a separate website screenshot API and MCP server. If what you need is a webpage capture rather than a Storybook visual-test run, you can make a single request. See the ScreenshotNeo API documentation.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp
Quick Recap
ScreenshotNeo accepts cookie banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each of those steps can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and responses identify page verdict and billing status in headers. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. The free plan includes 1,000 screenshots a month without a card; paid plans start at $5 for 3,000 shots. Learn about ScreenshotNeo or sign up for 1,000 free screenshots a month, no card required.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
