Automatic visual tests in Storybook, plus 2.2x faster build times for React+TSVisual test with Chromatic
Back to integrations
Add your integration
  • ⭐️ Popular
  • 🧩 Essentials
  • 🛠 Code
  • ⚡️ Data & state
  • ✅ Test
  • 💅 Style
  • 🎨 Design
  • ⚙️ Appearance
  • 🗄 Organize
How to install addons Create an addon
Visual Tests
Visual Testing addon with Chromatic
npm install @chromaui/addon-visual-tests
Last updated 2 days ago
Downloads per week
Readme View on GitHub

Storybook Visual Testing addon

The Visual Testing addon enables you to run visual tests on your stories and compare changes with the latest baselines across multiple viewports and browsers to catch UI regressions early in development without leaving Storybook.


Getting Started

Run the following command to install the addon and automatically configure it for your project via Storybook's CLI:

npx storybook@latest add @chromaui/addon-visual-tests

Start Storybook and navigate to the Visual Tests panel to run your first visual test with Chromatic!


By default, the addon offers zero-config support to run visual tests with Storybook and Chromatic. However, you can extend your Storybook configuration file (i.e., .storybook/main.js|ts) and provide additional options to control how tests are run. Listed below are the available options and examples of how to use them.

Option Description
buildScriptName Optional. Defines the custom Storybook build script
options: { buildScriptName: 'deploy-storybook' }
debug Optional. Output verbose debugging information to the console.
options: { debug: true }
projectId Automatically configured. Sets the value for the project identifier
options: { projectId: Project:64cbcde96f99841e8b007d75 }
projectToken Automatically configured. Sets the value for the project token
options: { projectToken: 'chpt_b2ae83517a0a706' }
zip Recommended for large projects. Configures the addon to deploy your Storybook to Chromatic as a zip file.
options: { zip: true }
// .storybook/main.ts

// 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 = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  addons: [
    // Other Storybook addons
      name: '@chromaui/addon-visual-tests',
      options: {
        projectId: 'Project:64cbcde96f99841e8b007d75',
        projectToken: 'chpt_b2ae83517a0a706',
        buildScriptName: 'deploy-storybook',
        zip: true,
        debug: true,

export default config;

Updating the GraphQL schema

The addon uses the Chromatic public GraphQL API. We rely on its schema to generate type definitions. The schema needs to be manually updated whenever it changes. To update, take and save it under src/gql/public-schema.graphql.


Running Storybook with the addon enabled throws an error

When installed, running Storybook may lead to 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"

Alternatively, you could use a different package manager (npm, pnpm).


We welcome contributions to the Storybook Addon Visual Tests! If you're a maintainer, refer to the following instructions to set up your development environment with Chromatic.



Join the community
6,322 developers and counting
WhyWhy StorybookComponent-driven UI
Open source software

Maintained by
Special thanks to Netlify and CircleCI