Visual Tests addon for Storybook
Pinpoint visual bugs in local development without leaving Storybook.
Installation
Run the following command to install the addon:
yarn add --dev @chromatic-com/storybook
Storybook 7.6 and higher required. Read the migration guide for help migrating Storybook versions.
Update your Storybook configuration file .storybook/main.js|ts
file to include the addon:
// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite)
import type { StorybookConfig } from "@storybook/your-framework";
const config: StorybookConfig = {
stories: ["../src/**/*.mdx", "../src/**/*.stories.@(js|jsx|mjs|ts|tsx)"],
addons: [
// Other Storybook addons
"@chromatic-com/storybook",
],
};
export default config;
When you start Storybook, you’ll see a new addon panel for “Visual Tests” where you can run tests and view the results.
Authentication
Sign in to Chromatic to create a new project or link an existing project.
You’ll see list of available projects that you have access to. Select a project to finish setup. The addon will automatically adjust the configuration file, add the necessary project identifiers, and retrieve any existing baselines if available.
Configure
Chromatic is configured using the ./chromatic.config.json
file. By default, the recommended configuration for most projects is already applied. You can also customize the default behavior and provide additional options for full control.
Addon configuration options
The shortlist of options that are addon-specific are below. View the full list of options.
Option | Description |
---|---|
projectId | Automatically configured. Sets the value for the project identifier "projectId": "Project:64cbcde96f99841e8b007d75" |
buildScriptName | Defines the custom Storybook build script "buildScriptName": "deploy-storybook" |
debug | Output verbose debugging information to the console "debug": true |
zip | Recommended for large projects. Configures the addon to deploy your Storybook to Chromatic as a zip file "zip": true |
{
"projectId": "Project:64cbcde96f99841e8b007d75",
"buildScriptName": "deploy-storybook",
"debug": true,
"zip": true
}
Custom addon config files & environments
If you have separate config for different environments, use configFile
to specify which file to load. Here’s how you’d apply one config for development
and another for production
.
// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite)
import type { StorybookConfig } from "@storybook/your-framework";
const config: StorybookConfig = {
stories: ["../src/**/*.mdx", "../src/**/*.stories.@(js|jsx|mjs|ts|tsx)"],
addons: [
// Other Storybook addons
{
name: "@chromatic-com/storybook",
options: {
//👇 Loads the configuration file based on the current environment
configFile:
process.env.NODE_ENV === "development"
? "chromatic.config.json"
: "production.config.json",
},
},
],
};
export default config;
How to run visual tests
Click the ▶️ Play button in the Storybook sidebar to start visual testing. Behind the scenes, this sends your stories to the cloud to snapshot and find visual changes.
Review changes
The addon highlights which stories require your attention 🟡 in the Storybook sidebar. Results will stream in while the test runs.
Use the “Visual Tests” addon tab to see which pixels changed. If the changes are intentional, accept them as baselines. If they’re not intentional, fix the story and run the tests again with the ▶️ Play button.
When you finish accepting changes as baselines in the addon, you’re ready to push the code to your remote repository. If you have Chromatic running in CI (recommended), your updated baselines will be reconciled automatically without you having to re-accept changes.
Frequently asked questions
What are "local" builds and how are they different from builds?
A build is an automated visual test run. When you set up Chromatic in CI, a build runs every time you push a commit to your repository.
With the addon, you’re able to visually test uncommitted code. This is useful when you want to quickly check your work in progress for visual changes. The addon creates local builds to designate ephemeral uncommitted code from normal builds which use committed code. “Local” just means local to you.
Updating baselines in local builds only affects your other local builds on a given branch. This allows you to iterate quickly in development without affecting teammates. When you want to update the baselines with teammates, you commit and push your work, which triggers a normal build via CI.
If the code is the same between your last local build and the normal build triggered by CI, Chromatic will automatically auto-accept baselines in the normal build so that you don’t need to review twice. If you have TurboSnap, Chromatic will intelligently test only the stories that changed and copy over snapshots from stories that were unchanged.
What’s the difference between testing with the addon vs. CI?
The addon allows running tests on-demand to detect bugs earlier in development. It saves time because you don’t have to wait for CI jobs to finish running. But the addon doesn’t replace CI, Chromatic still requires CI to do its job.
Why are Doc pages missing in the published Storybook generated by my "local" build?
By default, Docs are disabled in local builds created by Visual Tests addon.
You can enable Docs by setting the following flags: disableBlocks
, disableAutoDocs
, disableMDXEntries
, and disableDocgen
to false
in your .storybook/main.ts
. Learn more about these flags here.
// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite)
import type { StorybookConfig } from "@storybook/your-framework";
const config: StorybookConfig = {
// ...
build: {
test: {
disableBlocks: false,
disableAutoDocs: false,
disableMDXEntries: false,
disableDocgen: false,
},
},
};
export default config;
That said, we don’t recommend turning Docs on for local builds because this will cause the build time to increase considerably.
Troubleshooting
Running Storybook with the addon enabled throws an error
When running Storybook with the addon enabled, you may encounter the following error:
const stringWidth = require('string-width');
Error [ERR_REQUIRE_ESM]: require() of ES Module /my-project/node_modules/string-width/index.js is not supported.
This is a known issue when using an older version of the Yarn package manager (e.g., version 1.x). To solve this issue, you can upgrade to the latest stable version. However, if you cannot upgrade, adjust your package.json
file and provide a resolution field to enable the Yarn package manager to install the correct dependencies. In doing so, you may be required to delete your node_modules
directory and yarn.lock
file before installing the dependencies again.
{
"resolutions": {
"jackspeak": "2.1.1"
}
}
Does the addon affect snapshot usage?
The Visual Tests addon uses the same pricing tiers as Chromatic, providing the number of snapshots subscribed to in your plan. If you have any questions about snapshot costs or billing, please contact us via in-app chat.
Does the addon support TurboSnap?
Yes. Visual Tests addon supports TurboSnap via the ./chromatic.config.json
file.
Can I deny a change with the addon?
No. Denying changes is only available when running builds from CI or the CLI. If you need to, you can revert changes by clicking the ”Unaccept” button in the addon panel.
Do I need Git to run the addon?
Yes, Visual Tests addon requires Git to track baselines for each story. To use Chromatic, you need to have git initialized in your project repository and have at least one commit.