Storybook · Writing and testing · all subjects

visual testing

14 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Visual tests take snapshots and compare to baselines

Visual tests are the most efficient way to test components. With visual testing, you can take snapshots of every story in your Storybook and compare those snapshots to baselines, which are the last known "good" snapshots. This allows you to check both the appearance of components and a large subset of component functionality without having to write or maintain test code.

Storybook supports cross-browser visual testing with Chromatic

Storybook supports cross-browser visual testing natively using Chromatic, a cloud service made by the Storybook team. When you enable visual testing, every story is automatically turned into a test, giving you instant feedback on UI bugs directly in Storybook.

Install visual testing addon

Add visual tests to your project by installing @chromatic-com/storybook, the official addon by Storybook maintainers.

Visual Tests addon panel appears when enabled

When you start Storybook with visual testing enabled, you'll see a new addon panel for Visual Tests where you can run tests and view results.

Sign in to Chromatic account to use visual testing

To use visual testing, you must sign in to your Chromatic account. If you do not have an account, you can create one as part of the sign in process. Once signed in, you will see your Chromatic account(s) and their projects, and you can either select one from the list or create a new one.

First visual test build creates baseline snapshots

The first build of visual tests will create the baseline snapshots for your stories, which will be compared against when you run visual tests again.

Two ways to run visual tests in Storybook

After making a code change, you can run visual tests in two ways: press the run button in the Visual tests section of the expanded testing widget in the sidebar, or press the run button in the top right corner of the Visual tests addon panel. Either method will send your stories to the cloud to take snapshots and detect visual changes.

Visual changes highlighted in sidebar and shown in addon panel

If there are visual changes in your stories, they will be highlighted in the sidebar. Click the story and go to the Visual Tests addon panel to see which pixels changed. If the changes are intentional, accept them as baselines locally. If the changes aren't intentional, fix the story and rerun the tests.

Baselines accepted locally sync to cloud when code is pushed

When you finish accepting changes as baselines in the addon, you're ready to push the code to your remote repository. This will sync baselines to the cloud for anyone who checks out your branch.

Use visual testing in CI alongside addon

The visual testing addon is designed to be used in tandem with CI. You should use the addon to check for changes during development and then run visual tests in CI as you get ready to merge. Changes you accept as baselines in the addon will get auto-accepted as baselines in CI so you don't have to review twice.

CI workflow setup for Chromatic visual testing

To automate visual tests with CI, add a step to your CI workflow to run Chromatic. Supported CI providers include GitHub Actions, GitLab Pipelines, Bitbucket Pipelines, CircleCI, Travis CI, Jenkins, Azure Pipelines, and custom CI providers. Configure your CI to include environment variables to authenticate with Chromatic (project token).

PR checks for visual tests with Chromatic badge

Once you successfully set up Chromatic in CI, your pull/merge requests will be badged with a UI Tests check. The badge notifies you of test errors or UI changes that need to be verified by your team. You can make the check required in your Git provider to prevent accidental UI bugs from being merged.

chromatic.config.json configuration options

The visual testing addon can be configured via ./chromatic.config.json file with the following options: projectId (automatically configured, sets the project identifier, example: "projectId": "Project:64cbcde96f99841e8b007d75"), buildScriptName (optional, defines custom Storybook build script, example: "buildScriptName": "deploy-storybook"), debug (optional, outputs verbose debugging information to console, example: "debug": true), and zip (optional, recommended for large projects, configures addon to deploy Storybook as a zip file, example: "zip": true).

Visual tests compare rendered pixels, snapshot tests compare HTML markup

Snapshot tests compare the rendered markup (HTML blobs) of every story against known baselines, which can lead to false positives as code changes don't always yield visual changes. Visual tests compare the rendered pixels of every story against known baselines. Because visual tests compare what users actually experience, they are richer and easier to maintain than snapshot tests.

Give your agent this brain