chromatic
Advanced tools
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.
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);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 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 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.
Publishes your Storybook to Chromatic and kicks off tests if they're enabled.
npx chromatic --project-token <your token>
After the first run, the CLI will automatically ask you to add a script to your package.json.
Optionally, you can install chromatic as a dependency, while using the same script above.
npm install -D chromatic
If you don't install chromatic as a dependency, npx will download and run the latest version automatically. This has pros and cons:
There are examples here: /.github/workflows.
Do not run this based on a github pull_request event. If you do, the commit and branch will get reported wrong, use https://github.com/chromaui/action instead.
--project-token <your token>
You can also use the environment variable: CHROMATIC_PROJECT_TOKEN
Note: this option was previously known as "--app-code". If you encounter an error referring to this, you should upgrade to the latest version of the Chromatic CLI. See Migrating to the new CLI package.
--build-script-name [name], -b The npm script that builds your Storybook [build-storybook]
--storybook-build-dir, -d <dirname> Provide a directory with your built storybook; use if you've already built your storybook
Deprecated options (for tunneled builds):
--script-name [name], -s The npm script that starts your Storybook [storybook]
--exec <command>, -e Alternatively, a full command to run to start your storybook
--do-not-start, -S Don't attempt to start or build; use if your Storybook is already running
--storybook-port <port>, -p What port is your Storybook running on (auto detected from -s, if set)
--storybook-url <url>, -u Storybook is already running at (external) url (implies -S)'
--storybook-https Use if Storybook is running on https (auto detected from -s, if set)
--storybook-cert <path> Use if Storybook is running on https (auto detected from -s, if set)
--storybook-key <path> Use if Storybook is running on https (auto detected from -s, if set)
--storybook-ca <ca> Use if Storybook is running on https (auto detected from -s, if set)
These options are not required, this CLI is zero-config if you have a build-storybook script in your package.json.
--allow-console-errors Continue running chromatic even if some there are errors logged during Storybook initialization
--auto-accept-changes [branch] Accept any (non-error) changes or new stories for this build [only for <branch> if specified]
--exit-zero-on-changes [branch] Use a 0 exit code if changes are detected (i.e. don't stop the build) [only for <branch> if specified]
--exit-once-uploaded [branch] Exit with 0 once the built version has been sent to chromatic [only for <branch> if specified]
--ignore-last-build-on-branch [branch] Do not use the last build on this branch as a baseline if it is no longer in history (i.e. branch was rebased) [only for <branch> if specified]
--preserve-missing Treat missing stories as unchanged (as opposed to deleted) when comparing to the baseline
--no-interactive Do not prompt for package.json changes
--only <component:story> Only run a single story or a glob-style subset of stories (for debugging purposes)
--skip Skip chromatic tests (mark as passing)
--list List available stories (for debugging purposes)
--ci This build is running on CI, non-interactively (alternatively, pass CI=true)
--debug Output more debugging information
This package will load any variables from a .env file if present
If you encounter issues with the CLI please report them via the in-app chat (Intercom widget) or at https://github.com/chromaui/chromatic-cli/issues. Thanks!
Because of the nature of this package: it being a connector between Storybook and a web service, you may need a project token to test this locally. Just send us a message at opensource@hichroma.com or sign up for an account!
All contributions are welcome!
--config flagWe publish with a script:
./scripts/publish.js
You can pass any flags to this you'd normally be able to pass to npm publish, such as --dry-run or --tag="alpha".
Before publishing we check if the current user has permissions and if the version isn't already on npm
Compatibility is guaranteed between this package and Chromatic like so:
To facilitate upgrading in the future, removing and adding features, this is the process:
This package was previously named storybook-chromatic. If you still have storybook-chromatic installed, you should remove it and install chromatic instead:
With npm:
npm uninstall --save-dev storybook-chromatic
npm install --save-dev chromatic
With yarn:
yarn remove --dev storybook-chromatic
yarn add --dev chromatic
FAQs
Automate visual testing across browsers. Gather UI feedback. Versioned documentation.
The npm package chromatic receives a total of 1,732,260 weekly downloads. As such, chromatic popularity was classified as popular.
We found that chromatic demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 9 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
An advanced npm supply chain attack is leveraging Ethereum smart contracts for decentralized, persistent malware control, evading traditional defenses.
Security News
Research
Attackers are impersonating Sindre Sorhus on npm with a fake 'chalk-node' package containing a malicious backdoor to compromise developers' projects.
Security News
The npm package for the LottieFiles Player web component was hit with a supply chain attack after a software engineer's npmjs credentials were compromised.