Visual Tests addon for Storybook

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;

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.

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.

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.

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"
  }
}

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.

Yes. Visual Tests addon supports TurboSnap via the ./chromatic.config.json file.

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.

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.