Run UI tests with Storybook
UI Tests pinpoint visual changes and verify user interactions. They capture a snapshot of every story in a cloud browser environment. Whenever you push code, Chromatic generates a new set of snapshots and compares them against baseline snapshots. If there are changes, you verify that they’re intentional. If there are test errors, you get notified to fix them.
Enable
Enable visual tests for your project on the manage page. If your stories have interaction tests, they’ll run automatically when visual tests are enabled.
All snapshots are taken in Chrome by default. Select additional browsers to expand test coverage in 1-click.
Establish baselines
Once visual tests are enabled, you can establish baselines by running a Chromatic build in a new project or on a branch without an ancestor. This captures a snapshot of each story in a cloud browser and sets it as the baseline. Subsequent builds will generate new snapshots that are compared against existing baselines to detect UI changes.
View changes between baselines
Each build, Chromatic compares new snapshots to existing baselines from previous builds. The list of changes are shown on the build page in the web app. The build will be marked “unreviewed” and the changes will be listed in the “Tests” table.
Why are my baselines inconsistent?
Here are common reasons baselines can be inconsistent and how to fix them.
If you’re not running Chromatic builds on your base branch (e.g., main) then Chromatic will not be able to track which baselines are associated with which commits and branches. We recommend that you always run Chromatic on your base branch to ensure reliable, consistent baselines.
If you’re not auto-accepting changes on your base branch (e.g., main) then Chromatic can’t enforce that your trunk branch is clean and passing. We recommend you add the --auto-accept-changes flag when running on the trunk branch to ensure all incoming changes will be accepted as baselines.
If you’re squash and rebase-merging, Chromatic will not be able to track baselines to commits accurately because squashing removes commits from git history. We recommend you enable Chromatic’s GitHub App to auto-detect squash and rebase merges which maintains your baselines.
What about component errors?
When a story fails to render it will be badged with “Component Error”. You will not be able to “pass” a build that has component errors. Fix story errors in Storybook and run the build again.
What about failed tests?
When interaction tests fail, the story will be badged with “Failed test.” You will not be able to “pass” a build that has failed tests. Fix interaction tests in Storybook and run the build again.
Verify UI changes
Chromatic detects UI changes but it’s still up to you to verify if changes are intentional. For intentional changes, you need to update the baseline so future tests will be compared to the latest baseline for the story. If a change is unintentional it needs to be fixed.
-
✅ Accept change: This updates the story baseline. When a snapshot is accepted it won’t need to be re-accepted until it changes, even through git branches or merges.
-
❌ Deny change: This marks the change as “denied” indicating a regression and immediately fails the build. You can deny multiple changes per build. Denying a change will force a re-capture on the next build, even if TurboSnap would otherwise skip it.
What’s the difference between denied and unreviewed changes?
The purpose of denying is to mark changes you’ve looked at but not accepted. When you’ve finished reviewing the build, the list of denied changes helps you track what needs fixing.
When it comes to baselines, denying and leaving unreviewed have the same effect. In both cases, the original baseline is used for comparisons. This means in subsequent builds, Chromatic compares the latest build to the original baseline (not the previously denied snapshot).
Denied changes will be marked as unreviewed in subsequent builds for you to review again.
Speed up review with keyboard shortcuts
Verify UI changes faster using keyboard shortcuts. Protip: Pressing 1 multiple times switches between the baseline and new snapshot in the 1up view.
What about baselines on other branches?
Chromatic automatically changes the baseline snapshots that it uses for each build depending on your branch. Each branch has a separate set of baselines.
This means you can update UI components on multiple feature branches in parallel without conflicts. When you merge branches, the most recent baseline takes precedence. Learn about branching and baselines »
How do I reproduce the snapshot?
Sometimes you need a closer look to determine why a snapshot is rendering as it does. Along with pixel and DOM diffs, Chromatic displays the interactive stories just as they appear in Storybook.
Click “Inspect snapshot” to open the Inspector. Switch between the “Canvas” and “Snapshot” tabs to compare the live component to the snapshot. Learn more about snapshots here.
Can I retake a snapshot?
Yes, rerun the latest build on your branch to retake snapshots of unreviewed or denied changes.
How are changes on builds different from those listed on the Review page ‘Changeset’ tab?
UI tests (shown on the build screen) detect changes between builds, specifically, between the last accepted baseline and the latest build. This is useful for detecting defects during the development process and when merging to the main branch to ship.
In contrast, the Review page shows the changeset between the latest commit on the PR branch (head) and the ‘merge base’ (base). Think of it like code review, but for UI.
Discussions
Reviewers can point out bugs or ask questions by creating discussions. Discussions are shown in situ of a UI change so all collaborators have the same reference point.
Pin discussions on a change to give precise feedback on what’s wrong. Pair discussions with denying a change to block merging until bugs are resolved.
Merge
If you accept all the changes, the build will 🟢 Pass. Future builds whose stories have the same appearance will pass.
If you deny any of the changes, the build will 🔴 Fail. You will need to make code changes (and thus start a new build) to get the build to pass.
When your build is passed (all changes accepted), you’re ready to merge visual changes with confidence knowing that your UI is bug free. Chromatic will update the PR check for “UI Tests” to reflect the build status.
After you merge your code, Chromatic will also apply accepted baselines to stories on the target branch. That means you’ll only need to accept baselines a single time.
Why is review disabled in the build page?
Reviewing is only enabled for the latest build on a branch to ensure that only the most up-to-date UI gets accepted as baselines.
Why is commenting disabled on old builds?
Comments are disabled on old builds to ensure that discussions are always on topic and up to date with the latest UI. This prevents the situation where different reviewers comment on different versions of the code.
Can I review the same commit on separate branches?
Yes, but it‘s not a best practice.
Every branch has independent baselines for each story until the branch gets merged. If two builds reference the same commit hash but are on different branches it will be possible to review those builds separately so long as they’re the latest build on their respective branches. We don’t recommend this because you’ll have to review the same change multiple times.
Instead, we recommend you regularly review builds to keep feature branches 🟢 passing.
PR check for “UI Tests”
Chromatic adds a ‘UI Tests’ check within the status checks for your pull/merge requests. The badge shows errors or changes that need to be reviewed. Require the check in GitHub, GitLab, or Bitbucket to prevent accidental UI bugs from being merged.
CI setup: Chromatic will return an exit code 0 on the CLI which can be used in CI/CD systems to indicate success and unblock deployment. Learn about CI.
Next: Learn about UI Review
Now that you can catch bugs during development, learn about how to invite stakeholders into Chromatic’s UI Review workflow to get the team sign off before merging.
Read next chapter
Troubleshooting
Snapshots don’t look right? Learn how to debug snapshots here.
Why are my builds failing because of component errors?
A build will fail if any of the snapshots fail to render (i.e. in rendering the latest version of the component, the snapshot throws a JavaScript exception). You’ll need to fix the code for errored components before we can pass the build.
Why do I see “Didn’t find any commits in this git repository in the last X builds”?
This means that across the last X unique commits across all builds in your app, we didn’t find a single one that exists in the repository you ran this build against. Commits can go missing if you rebase or perform squash-merges, however, if all of the previous X builds’ commits are missing, it is likely something has gone wrong.
If you’ve reached this situation and can’t work out why, please contact us through our in-app chat or email.
Why do I see “Failed to find common ancestors with most recent builds within X commits”?
This means that although we found recent builds that were in your git repository history (see above), we couldn’t find any common history between your checked out build and those builds within X commits.
Unless you are doing something unusual with your git repository, this is extremely unlikely. Either way, please contact us through our in-app chat or email.
Why do I see “Build X is based on a commit without ancestor builds”?
When we create a build, we search your git history for a recent Chromatic build based on a commit that is an ancestor (i.e. a commit that is in the direct history of this commit). Unless this is the very first build, if we do not find one, we will show you this message.
This is typically unusual, because in order to run Chromatic on a commit, chances are the commit that added Chromatic to your app is an ancestor!
However, this situation can arise due to the following:
-
You switched branches and re-ran Chromatic, without checking-in the code changes that installed Chromatic. In this case you can safely ignore this message.
-
You rewrote history in merging the Chromatic installation code (e.g. using GitHub’s “Squash and Merge” or “Rebase and Merge” buttons). Learn how to resolve
-
You are using a shallow clone of your repository when running Chromatic. Chromatic needs access to your full git history in order to find baselines (or at least the history until the previous Chromatic build, which depends on how often you push code/run builds). Learn about how we use Git for baselines »
-
Something else happened, perhaps a bug at our end? Please contact us through our in app chat if this is the case.
Can I disable UI Tests if I prefer not to use them?
Yes. Go to the manage page for your project where you can disable UI Tests. Chromatic will no longer add status checks to your PRs for UI Tests once it is disabled.
Can I rerun a build without running my whole CI workflow?
Yes you can rerun the latest build on any branch outside of your CI workflow. Go to the build page to kick off a new build that uses identical settings and configuration as your old build.
Why does my build have failed tests?
“Failed tests” happens when a story’s play function has an unexpected error that caused it to fail. You can learn more about interaction tests here.