Write snapshot tests
Snapshot tests compare the rendered markup of every story against known baselines. It’s a way to identify markup changes that trigger rendering errors and warnings.
Storybook is a helpful tool for snapshot testing because every story is essentially a test specification. Any time you write or update a story, you get a snapshot test for free.
If you're upgrading to Storybook 8.0 and were using the Storyshots addon for snapshot testing, it was officially deprecated and removed with this release. See the migration guide for more information.
Automate snapshot tests with the test-runner
Storybook test-runner turns all of your stories into executable tests. Powered by Jest and Playwright. It's a standalone, framework-agnostic utility that runs parallel to your Storybook. It enables you to run multiple testing patterns in a multi-browser environment, including interaction testing with the play function, DOM snapshot, and accessibility testing.
Setup
To enable snapshot testing with the test-runner, you'll need to take additional steps to set it up properly. We recommend you go through the test-runner documentation before proceeding with the rest of the required configuration to learn more about the available options and APIs.
Add a new configuration file inside your Storybook directory with the following inside:
The postVisit
hook allows you to extend the test runner's default configuration. Read more about them here.
When you execute the test-runner (for example, with yarn test-storybook
), it will run through all of your stories and run the snapshot tests, generating a snapshot file for each story in your project located in the __snapshots__
directory.
Configure
Out of the box, the test-runner provides an inbuilt snapshot testing configuration covering most use cases. You can also fine-tune the configuration to fit your needs via test-storybook --eject
or by creating a test-runner-jest.config.js
file at the root of your project.
Override the default snapshot directory
The test-runner uses a specific naming convention and path for the generated snapshot files by default. If you need to customize the snapshot directory, you can define a custom snapshot resolver to specify the directory where the snapshots are stored.
Create a snapshot-resolver.js
file to implement a custom snapshot resolver:
Update the test-runner-jest.config.js
file and enable the snapshotResolver
option to use the custom snapshot resolver:
When the test-runner is executed, it will cycle through all of your stories and run the snapshot tests, generating a snapshot file for each story in your project located in the custom directory you specified.
Customize snapshot serialization
By default, the test-runner uses jest-serializer-html
to serialize HTML snapshots. This may cause issues if you use specific CSS-in-JS libraries like Emotion, Angular's ng
attributes, or similar libraries that generate hash-based identifiers for CSS classes. If you need to customize the serialization of your snapshots, you can define a custom snapshot serializer to specify how the snapshots are serialized.
Create a snapshot-serializer.js
file to implement a custom snapshot serializer:
Update the test-runner-jest.config.js
file and enable the snapshotSerializers
option to use the custom snapshot resolver:
When the test-runner executes your tests, it will introspect the resulting HTML, replacing the dynamically generated attributes with the static ones provided by the regular expression in the custom serializer file before snapshotting the component. This ensures that the snapshots are consistent across different test runs.
What’s the difference between snapshot tests and visual tests?
Visual tests capture images of stories and compare them against image baselines. Snapshot tests take DOM snapshots and compare them against DOM baselines. Visual tests are better suited for verifying appearance. Snapshot tests are useful for smoke testing and ensuring the DOM doesn’t change.
Learn about other UI tests
- Test runner to automate test execution
- Visual tests for appearance
- Accessibility tests for accessibility
- Interaction tests for user behavior simulation
- Coverage tests for measuring code coverage
- Snapshot tests for rendering errors and warnings
- End-to-end tests for simulating real user scenarios
- Unit tests for functionality