chromatic

What is chromatic?

The npm package 'chromatic' is a tool designed to help developers automate visual testing for their UI components. It captures snapshots of components and runs visual regression tests to ensure that changes do not break the visual appearance of applications. Chromatic integrates with Storybook to manage component libraries and streamline the testing process.

What are chromatic's main functionalities?

Visual Testing

This code sample demonstrates how to add a visual test for a simple button component using Chromatic with Storybook. The 'withChromatic' decorator is used to enable Chromatic's snapshot capabilities for the component.

import { storiesOf } from '@storybook/react';
import { withChromatic } from 'chromatic/isolated';

storiesOf('Button', module)
  .addDecorator(withChromatic)
  .add('default', () => <button>Click me</button>);

Snapshot Management

This code configures Chromatic to take snapshots after a delay and at specified screen widths, facilitating responsive visual testing. It helps in managing how snapshots are captured based on different device widths.

import { configure } from '@storybook/react';
import { setChromaticOptions } from 'chromatic';

setChromaticOptions({
  delay: 300, // Delay in ms before taking a snapshot
  widths: [320, 1200] // Array of widths for responsive testing
});

configure(() => require('./stories'), module);

Other packages similar to chromatic

storybook

Storybook is a user interface development environment and playground for UI components. It facilitates building UI components in isolation and structuring a component library. While it does not offer visual regression testing by itself, it is often used in conjunction with Chromatic to provide that functionality.

percy

Percy by BrowserStack is a visual testing and review platform that integrates with your CI/CD pipeline. It captures screenshots of web pages and components, compares them against the baseline, and highlights visual changes. Percy offers a more comprehensive CI/CD integration compared to Chromatic, which is more tightly coupled with Storybook.

backstopjs

BackstopJS automates visual regression testing of web applications by comparing DOM screenshots over time. It is a standalone tool that can be used without Storybook, providing a different approach to visual testing compared to Chromatic's dependency on Storybook for component management.

README

Chromatic CLI

Publishes your Storybook to Chromatic and kicks off tests if they're enabled.

Documentation

👉 Read the Chromatic CLI docs

📝 View the Changelog

Using a next version

From time to time we pre-publish a next version of the package to test new features. To use the next branch you can either:

Using npx

Change your script to use the next dist-tag:

npx chromatic@next --project-token ...

Using a dependency in package.json

Update to the latest next version with:

yarn add --dev chromatic@next

# or
npm i --save-dev chromatic@next

Using the github action

Use our chromatic-next action:

- uses: chromaui/action-next@v1

Contributing

Contributions of any kind are welcome! We're available to chat via the Intercom widget on the documentation site.

Compatibility & versioning

Compatibility is guaranteed between this package and Chromatic like so:

• Production Chromatic ensures it’s compatible with what’s on npm
• What's on the main branch is equal to what's published on npm
• This package ensures it’s compatible with production Chromatic

To facilitate upgrading in the future, removing and adding features, this is the process:

• Any new features will have to be on Chromatic production before they could be used in this package
• We can add feature flags to be able to test new functionality
• Chromatic production can not remove any features this package depends on until after the usage has been removed from this package in addition to a grace period to allow users to upgrade

Publishing a new version to npm

Before publishing, make sure you've done the following:

• Updated CHANGELOG.md
• Committed and pushed everything (clean working directory)
• Decide on the proper semver bump (major/minor/patch)
• Decide on the proper tag (canary/next/latest)

We have three types of releases:

• canary releases are intended for testing purposes and should not be used in production, as they may only work against a staging or dev environment.
• next releases should be valid, working releases that can potentially be used by early adopters of new features, for example to handle a support request.
• latest releases are the general audience production releases, used by most people.

For GitHub Actions, we publish chromaui/action-canary and chromaui/action-next, which contain the latest canary or next release, respectively. A latest release will also automatically update chromaui/action-next (besides chromaui/action), in order to keep users who happen to depend on chromaui/action-next up to date with the latest release.

A script is provided to create new releases:

yarn release <major|minor|patch> <canary|next|latest> [--dry-run]

This script ensures the version is bumped properly, the tag is set correctly and the corresponding GitHub Action is updated.

Examples:

yarn release patch canary

Releases e.g. 6.6.1-canary.0.

yarn release major latest

Releases e.g. 7.0.0.

Changelog

6.8.0 - 2022-08-26

• 630 Rename --only to --only-story-names but keep it as a deprecated alias
• 629 Deprecate --preserve-missing and raise a warning if it's being used

Use TurboSnap instead of preserveMissing

In order to support advanced use cases where only a subset of stories would be included in a Storybook, the --preserve-missing flag could be used to prevent excluded stories from being marked as "removed" in Chromatic. This behavior could lead to problematic situations regarding infrastructure upgrades and cause truly removed stories to never be removed from Chromatic. That's why we are sunsetting the "preserve missing" behavior. As of v6.8.0, using this flag will raise a warning message in the CLI. In a future major version, the flag will be removed completely, and continuing to use it with an older CLI version will start to fail your build.

To upgrade, you should remove the --preserve-missing flag from your CI and/or package.json scripts. If you use our GitHub Action, you should remove the preserveMissing input (with: ...) from your workflow config file. Furthermore, you should make sure that your build-storybook script builds all stories, not just a subset. Check your stories configuration in .storybook/main.js so it doesn't omit any stories (e.g. based on an environment variable).

Most likely you were using preserveMissing to cut down on the number of snapshots taken by Chromatic. To achieve the same goal, you have three options:

• Recommended: Use TurboSnap to automatically only snapshot stories for which related source files have changed.
• Use --only-story-names to only snapshot stories matching a glob pattern by component/story name.
• (Soon) Use --only-story-files to only snapshot stories matching a glob pattern by story filename.

In each of these cases, any stories that aren't captured are "inherited" from their baseline.