Catch UI Bugs Before They Catch You: The Magic of Visual Testing

We’ve all been there

The design team decides to modernize the look of our dashboard buttons. You dive into the shared component, tweak the styles, and, while you’re at it, clean up some redundant properties and hardcoded values. A quick check on a few pages confirms that the new design looks great. All unit tests pass with flying colors. Success!

Fast forward a few weeks. While working on an unrelated feature, you stumble upon something terrible: a modal that only appears under very specific conditions is completely broken. It turns out the modal relies on a custom version of the button that depended on one of those "redundant" properties you removed. That property might have seemed irrelevant at the time, but now it’s the culprit behind a regression that’s gone unnoticed for weeks.

Sure, one could argue that the custom property should’ve been scoped to the modal’s button styles and not the base component—and that’s absolutely correct! But the focus of this post isn’t about fixing mistakes or debating shared components best practices. Today, we’re talking about something equally important: detecting UI regressions before they wreak havoc across your application—and doing it without manually inspecting every corner of your UI.

Manual and automated functional tests excel at verifying behavior but often miss visual discrepancies like misaligned elements, spacing issues, or broken layouts. Manual testing is time-consuming and error-prone, while functional tests focus on logic rather than appearance. This gap leaves room for regressions that don’t break functionality but harm the user experience.

Enter: Visual Tests

Think of visual tests as your automated safety net. Like snapshots on steroids, they don’t just compare changes in your HTML structure. Instead, they render components and pages, highlighting visual differences like layout shifts, spacing issues, or style mismatches.

At Mixmax, we already use Storybook to develop and document our core components, so Chromatic was a natural choice for automating our visual tests. Chromatic captures screenshots of each component story from a given build (e.g. an open PR) and compares them with the baseline (main/master branch), providing a clean interface for reviewing and approving any changes.

It may seem simple, but being able to instantly see every piece of UI affected by a change is incredibly powerful! Found a new edge case we need to keep track of? Just create a Storybook story and it will never be broken by accident again. By integrating visual tests into our workflow, we can catch regressions early, save time, and ensure our UI looks as polished as our users expect.

But how, you ask?

Incorporating visual tests into your development workflow is simpler than you might think. Here’s how we do it step by step:

1. Install Chromatic

   First, we set up the chromatic npm package in the desired project and add a chromatic npm script. Check their docs for more details, including how to sign up and create a project.

   npm install --save-dev chromatic
   

   // package.json
   {
     "scripts": {
       "chromatic": "chromatic"
     }
   }
   

   When running this script, Chromatic will build your Storybook files and upload them to your project. It will trigger the tests and return a link to review the changes.

2. Add a New GitHub Action

   Next, we automate the process by adding a GitHub action that triggers visual tests whenever a new pull request (PR) is created or updated.

   //.github/workflows/chromatic.yml
   name: chromatic
   
   on:
     pull_request:
       branches:
         - main
   
   jobs:
     publish:
       steps:
         // Note you might need extra steps here before publishing to Chromatic
         // depending on how your github repo is configured
         - name: Publish to chromatic
           run: >
             npm run --if-present chromatic --
             --project-token='<your_project_token>'
             --branch-name='$'
             --exit-zero-on-changes
             --exit-once-uploaded
             --zip
   

   Note that we included some extra CLI options here to customize how chromatic publishes the code. You could add them directly to your npm script or create a chromatic.config.json file depending on your preference (more details in their docs). We added these to the workflow because it's reused between repos.

3. Open a PR

   With the setup in place, opening a PR will trigger the visual tests automatically and Github will show the state of each check with links to review them.

   

   To enforce quality control, we also configure the repo to mark the visual test results as a required check. This means a PR cannot be merged until the tests are reviewed and approved.

   

4. Review and Approve

   Chromatic highlights differences between the baseline and updated versions, making it easy to identify regressions or approve intentional updates.

   The reviewer is responsible for examining the “UI Review” test results alongside the standard code review and approving them (assuming the author has already reviewed these changes before requesting a review).

   Once all tests pass and the changes are approved, it’s the author’s responsibility to approve the “UI Tests” check, marking the new build as the baseline, and merge the PR.

   Thanks to this workflow, we can confidently ship updates, knowing the UI remains consistent and free of regressions.

Closing Thoughts

In the fast-paced world of frontend development, where design changes are frequent and user expectations are sky-high, visual testing is a game-changer. It helps you catch UI regressions early, save countless hours of manual checking, and deliver a polished, consistent experience to your users.

While no tool can completely replace good development practices, visual tests provide a powerful safety net, ensuring that even the smallest changes don’t ripple into big problems. By integrating them into your workflow, you’re not just safeguarding your UI—you’re building confidence within your team and improving your product’s reliability.

So why wait? Take the first step toward regression-free frontends by adding visual testing to your toolkit. Your future self—and your users—will thank you.

Interested in joining the team? Visit Mixmax Careers.