UI tests protect your project from accidental regressions. However, before you’re ready to ship, you’ll want to invite developers, designers, PMs, and stakeholders to help review the changes to make sure they’re correct. This closes the feedback loop between disciplines and helps you find the answer to “does this look right?”.
Chromatic’s UI review workflow pinpoints the exact visual changes introduced by a PR. It gives you the ability to assign reviewers and in turn those reviewers can comment and ask for tweaks on changes which aren’t quite right. Chromatic compiles a ‘UI checklist’ which must be completed before a feature is ready to merge. Think of it like a code review for your UI.
Find the PR you’d like reviewed, either by navigating to the ‘PRs’ link in the sidebar or following the ‘UI Review’ link from the PR status checks in your Git provider. Use the Assign Reviewers link on the PR Activity screen to choose reviewers from the project’s collaborators. Reviewers will be emailed a link to the PR screen to begin their review.
Review UI Changes
The PR screen includes a ‘UI Changes’ tab showing a side-by-side view of all visual changes introduced by the code in the PR. You can toggle between viewing a highlighted diff or simply showing the component before/after this PR would be applied.
Reviewers can request updates to the implementation via the comment box beneath each change. Discussions are threaded and attached to the specific story represented by the change.
Chromatic builds a list of tasks that need to be completed before a PR is considered safe to merge from a UI review perspective. This is the UI checklist and is shown at the bottom of the activity tab of the PR screen. Once all items are completed the status light will turn green and the PR is ready to merge.
In order to complete the checklist, the following must be completed:
- All outstanding discussions must be resolved. This can be done by clicking ‘Resolve’ on the comments UI.
- All reviewers must have approved their review. They can do so by clicking ‘Approve’ button in the top right of the activity tab.
Git provider status checks
Chromatic will include a ‘UI Review’ badge within the status checks for each PR on your Git provider. The badge will show a summary of the state of the UI Checklist. Every PR for which Chromatic detects UI changes will initially start in the unreviewed state, ensuring that every impactful change has been noticed and considered before hitting production.
Frequently Asked Questions
How is UI review different from testing?
Testing is done primarily by developers, most often iteratively during development. The focus is on preventing UI regressions (bugs) and maintaining a clean set of baselines to test against.
Review is usually performed by designers, PMs, customers, and other stakeholders. The focus is not on finding bugs (this should have already happened through testing) but rather to find cases where the implementation is not quite as was intented by the design or specifications. The modern development process moves quickly and often developers are filling in gaps according to their best guess. UI review is an opportunity for developers to sync with other teammates to get a final OK before shipping with confidence.
When should I ask for UI Review?
You can initiate a UI review at any time. However, we recommend doing it later in the development cycle, once baselines have been approved and UI Tests are green.
What commits does Chromatic use to calculate UI changes?
Just like GitHub, Chromatic compares between the latest commit on the PR branch and the ‘merge base’ commit, that is the commit that is the shared ancestor between the PR branch and the branch it was created from. It is important that Chromatic has run a build on both commits outlined above. If you’ve just enabled CI and have existing PRs that you would like to review, ensure Chromatic has run in CI for both branches of that PR.
The process might look something like:
- Create a new PR to
masteradding Chromatic to CI
- Merge that PR when everything works well.
- Update your existing feature PR(s) w/ the latest from
master(either merge or rebase from master).
Can I disable UI Review if I’d prefer not to use it?
Yes. Go to the manage page for your project where you can disable UI Review. Chromatic will no longer add status checks to your PRs for UI Review once it is disabled.
You’re all set up!
🎊 You’re all setup with Chromatic. Testing and review are essential to maintaining high quality UIs, but there’s always more to learn. Checkout how to get the most out UI components with handy Storybook guides written by our team. Don’t hesitate to ask us questions via email or our in-app chat.
- Visual Testing Handbook a free 31-page walkthrough for visual testing with Storybook
- The Delightful Storybook Workflow Learn how productive teams get the most out of Storybook. Featuring devs from Squarespace, Discovery Network, Major League Soccer, Apollo GraphQL, Storybook, and Chroma.
- UI Component Playbook a 5-step guide to designing and engineering frontends with components
- Visual Test-Driven Development - how visual testing helps your team build robust UIs faster.