Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

storybook-chromatic

chromaui34.7kMITdeprecated4.0.2

Please switch to the 'chromatic' package

Visual Testing for Storybook

readme

Chromatic CLI

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

Install

yarn add chromatic

Usage

You can use this package normally, which means installing it and adding a script called chromatic to your package.json

  "chromatic": "chromatic",

But alternatively (and this is useful for testing) you can use npx:

Use a git branch:

npx -p chromaui/chromatic-cli#master chromatic --dev

Use a debug version on npm:

npx -p chromatic chromatic

Using npx has pros and cons:

  • 👍 You'll never be out of date, you'll use the latest version every time, never have to worry about upgrading this.
  • 👍 You don't need this package as a dependency, and don't need to install it during local development
  • 👎 This will add a delay when you actually do want to run this, like in your CI, delaying feedback.

Usage in a github action

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.

Main options

--project-token="<your token>"

You can also use the environment variable: CHROMATIC_PROJECT_TOKEN

Storybook options

--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 0-config if you have a build-storybook script in your package.json.

Chromatic options

--allow-console-errors  Continue running chromatic even if some stories throw an error
--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

Debug options

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

Environment variables

This package will load any variables from a .env file if present

Issues

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!

Contributing

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!

Future plans:

  • We'd like to unify this so there's just a single package on npm.
  • Migrate to Typescript
  • Deprecate all the Storybook options in favor of a sane --config flag

Publishing to npm

We 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 & 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

changelog

3.5.2 - 2020-02-18

3.5.1 - 2020-02-06

3.5.0 - 2020-01-28

3.4.0 - 2019-12-25

  • FIX pubish script

3.3.0 - 2019-12-25

  • IMPROVE logging when git fails
  • FIX script for windows
  • ADD --exit-once-uploaded flag
  • FIX escape chararacters in error messages

3.2.0 failed upload to npm

3.1.0 - 2019-11-04

  • ADD jsdom shim for SVG elements
  • ADD jsdom shim for fetch
  • Bugfix jsdom shim for Intl

3.0.3 - 2019-10-15

  • ADD compatibility with github action
  • ADD test with github action
  • ADD compatibility with github env vars for tracing git branch
  • Bugfix running on windows by using cross-spawn

3.0.2 - 2019-10-09

  • ADD licence file
  • Bugfix compatibility with CHROMA_APP_CODE
  • Bugfix report list of addons

3.0.1 - 2019-10-08

  • ADD chroma bin

3.0.0 - 2019-10-03

  • Bugfix indentation of messages in terminal
  • REMOVE the need for the clientside addon
  • unify the 2 related packages into a single repository

2.2.2 - 2019-08-25

  • Bugfix for compatibility with localtunnel`

2.2.0 - 2019-08-23

  • Add support for docs-mode (Storybook 5.2 feature).

  • Add support for a new parameter: pauseAnimationsAtEnd. Read about it here: https://www.chromatic.com/docs/animations

  • Retry requests to uploading storybooks in case of network problems.

2.1.1 - 2019-08-06

  • Upgrade axios dependency for security update

2.1.0 - 2019-07-17

  • Add a --skip flag to indicate a commit is not going to be built (and still tag the PR as passing).
  • Allow chromatic story parameters to be functions of ({ id, kind name }) -- in particular e.g. chromatic: { viewport: () => [/*something dynamic based on story info */]}
  • A fix for issues involving story listings differing between browsers.

2.0.0 - 2019-07-17

  • We now default to building and uploading your storybook, rather than starting and tunneling it. This has many benefits including increased reliability and better support for Live View. You'll need to ensure you have a build-storybook script defined in package.json (as added by the Storybook CLI). To get the old behaviour, pass -s to the chromatic test command.

  • We now support HTTPS storybooks (using the --ssl flag and friends).

  • We polyfill window.Intl in our JSDOM environment.

  • We polyfill window.customElements in our JSDOM environment.

1.4.0 - 2019-06-20

  • Retry requests to the API server if one fails rather than bailing out on builds.

1.3.3 - 2019-04-19

  • Fixed issue with uploaded builds and Storybook 5 URLs.

1.3.2 - 2019-04-02

  • Added a new diffThreshold Storybook parameter you can use to control the anti-aliasing threshold we use for diffing if you find that certain images are tripping our diff.

  • Fix an issue with handling rebased branches in unusual CI systems.

1.3.1 - 2019-03-21

  • Add a dedicated endpoint for isChromatic so you don't need to load our full package to use it (which is useful if you want to use it inside your app, which we generally don't advise).

1.3.0 - 2019-02-28

  • Change the default behaviour around starting the storybook; if we find something running on the port, we assume it's your storybook, instead of requiring you to pass -S/--do-not-start.

  • Add a new flag --preserve-missing which means any stories that are missing from the last build will be assumed to be unchanged. Use this if you are doing tricky things around dynamically building your Storybook based on code changes.

1.2.6 - 2019-02-05

  • Fix an issue with Angular/zone.js failing to patch our MutationObserver mock

1.2.5 - 2019-01-30

  • Fix an issue with using isChromatic() inside Jest (storyshots).

  • Some rendering timing fixes to better support Storybook version 5

1.2.4 - 2019-01-18

  • Added an export isChromatic() to determine if code is running under test.

  • Added JSDOM mocks for CreateObjectUrl and MutationObserver

  • Added a parameter { chromatic: { disable: true } } to skip a story in chromatic

  • Added a parameter { chromatic: { noScroll: true } } to avoid scrolling screenshots in (non-chrome) browsers.

1.2.3 - 2018-12-28

  • Allow overwriting the polyfills we create in JSDOM mode. (This is a bugfix for some libraries that bundle their own polyfills).

1.2.2 - 2018-12-10

  • Allow controlling package initialization timing via import configure from 'storybook-chromatic/configure'; configure()

  • Add a flag --ignore-last-build-on-branch=X to not use the last build on a branch no matter what (which helps with rebasing, see: http://docs.chromaticqa.com/branching-and-baselines#rebasing).

1.2.1 - 2018-12-04

  • Update logging dependency from loggly to node-loggly-bulk due to security vulnerabilities. NOTE: this package was only used by our CLI tool and so there is no need for concern, but this new version should avoid tripping security tools.

1.2.0 - 2018-10-29

1.1.0 - 2018-10-15

  • Fix to work on Windows CI

  • Added a --storybook-build-dir parameter that allows you to upload a pre-built storybook.

1.0.2 - 2018-08-23

1.0.1 - 2018-07-26

  • We now set the CHROMATIC_APP_CODE variable for you, with explicit instructions to remove it (and set via CI) in less secure applications.

  • Some small bugfixes to support unusual usages.

1.0.0 - 2018-07-02

  • Renamed the package from react-chromatic to storybook-chromatic, to indicate support for all view layers that Storybook supports!

  • Tweaked to focus soley on Storybook -- simply import 'storybook-chromatic'; (no /storybook-addon required). Run tests with chromatic test --app-code (no --storybook-addon required).

  • Changed some URL parameters for the test command:

    • --port renamed --storybook-port
    • --url renamed --storybook-url
    • --app-path removed (it's always /iframe.html, as per Storybook).
    • --exec added to run arbitrary commands as an alternative to --script-name
    • --no-interactive added to disable interactive mode (and we do so automatically when on CI)

  • We no longer require you to have npm installed if you are using yarn.

  • Small bug fixes for missing git repositories, various failure modes.

  • We now track your Storybook version and view layer so we know when to ship/change features.

As react-chromatic

0.8.4 - 2018-06-07

  • Fix an issue for stories that use navigator.mimeTypes

0.8.3 - 2018-04-26

  • Fix a bug where sometimes the package did not detect the checked out branch.

0.8.2 - 2018-04-18

  • Better support for rebasing branches - we now always treat the last build on this branch as a baseline, even if strictly it is not a git ancestor of the current commit. This helps deal with the situation where you rebase a branch off master, and still want to use the previously approved snapshots.

  • Improved support for CI systems, especially Netlify and Travis PR builds. Travis PR builds are a special case, read more about how to handle them in Chromatic here: https://www.chromatic.com/docs/ci#travis

0.8.1 - 2018-03-28

  • Fix a small bug in the git algorithm for old Chromatic projects.

0.8.0 - 2018-03-28

  • Reworked the git baseline detection algorithm to use a different technique that should be more reliable across many different modes of usage.

  • Gather stories from Storybook 3.4 without requiring direct installation.

  • Added --auto-accept-changes to avoid approvals on certain branches

  • Added --only flag to run a single story

0.7.11 - 2018-03-15

  • Handle the case where the last few Chromatic builds were run against commits which are no longer in the repository (due to rebasing or squashing). This could cause the tool to crash or fail to find a baseline for a build.

  • Add a --url argument to allow running tests against arbitrary running apps.

0.7.10 - 2018-02-22

  • Small API change for querying build change counts.

0.7.9 - 2018-01-23

  • Our test script now warns you if your Storybook logs any errors. This can sometimes help reveal subtle problems that are caused by the script evaluating your Storybook in JSDOM. If you have legitimate things logged to console.error this may cause noise---you should probably get rid of them.

0.7.8 - 2018-01-18

  • We no longer write your app code to your package.json by default; instead we prefer you pass it via the CHROMATIC_APP_CODE environment variable. (You can still optionally use --app-code=xyz if you are comfortable with the security of your package.json).

  • We now show the final part of your Story's kind as the component name in the Chromatic UI. So "Webapp/UserList" will appear in Chromatic as "UserList".

0.7.7 - 2017-12-21

  • This version sends us a little more information about the environment the package runs in -- is it CI? which package version?

0.7.6 - 2017-12-19

  • Fix an issue where we did not pass the context to stories in the right format.

0.7.5 - 2017-12-19

  • We detect a running process on your app's port and don't try and start the app if so. Pass --do-not-start if you've already started the app.

0.7.3 - 2017-12-09

  • We now upload your application bundle to our tunnel server directly from the package. This means that on slower uplinks, we no need to set arbitrary timeouts in our server process; instead we simply will not start your Chromatic build until we've verified the bundle has uploaded successfully.