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.
Chromatic CLI
Publishes your Storybook to Chromatic and kicks off tests if they're enabled.
Documentation
👉 See the Chromatic CLI docs.
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 master 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:
yarn build
- Updated CHANGELOG.md
- Committed and pushed everything
- Decide on the proper semver bump (major/minor/patch)
Doing a dev
or rc
release
We have two types of pre-releases: dev
and rc
. dev
releases are intended for development purposes and should not be used in production, as they may only work against a staging or dev environment. rc
releases should be valid, working releases that can potentially be used by early adopters of new features, for example to handle a support request.
For the first dev
(or rc
) release, bump the version like so (depending on the semver bump):
npm version <premajor|preminor|prepatch> --preid dev
For consecutive dev
releases on the same version:
npm version prerelease --preid=dev
Then push and publish:
git push --follow-tags
npm publish --tag dev
Make sure to replace dev
with rc
if appropriate.
Doing a final release
npm version <major|minor|patch>
git push --follow-tags
npm publish
yarn publish-action
And finally, remove the dev
and/or rc
tag, if any:
npm dist-tag rm chromatic dev