Interaction tests

In Storybook, interaction tests are built as part of a story. That story renders the component with the necessary props and context to place it in an initial state. You then use a play function to simulate user behavior like clicks, typing, and submitting a form and then assert on the end result.

You can preview and debug your interaction tests using the Interactions panel in the Storybook UI. They can be automated using the Vitest addon, allowing you to run tests for your project in Storybook, terminal, or CI environments.

Writing interaction tests

Every story you write can be render tested. A render test is a simple version of an interaction test that only tests the ability of a component to render successfully in a given state. That works fine for relatively simple, static components like a Button. But for more complex, interactive components, you can go farther.

You can simulate user behavior and assert on functional aspects like DOM structure or function calls using the play function. When a component is tested, the play function is ran and any assertions within it are validated.

In this example, the EmptyForm story tests the render of the LoginForm component and the FilledForm story tests the form submission:

There’s a lot going on in that code sample, so let’s walk through the APIs one-by-one.

Querying the canvas

canvas is a queryable element containing the story under test, which is provided as a parameter of your play function. You can use canvas to find specific elements to interact with or assert on. All query methods come directly from Testing Library and take the form of <type><subject>.

The available types are summarized in this table and fully documented in the Testing Library docs:

The subjects are listed here, with links to their full Testing Library documentation:

1. ByRole — Find elements by their accessible role
2. ByLabelText — Find elements by their associated label text
3. ByPlaceholderText — Find elements by their placeholder value
4. ByText — Find elements by the text they contain
5. ByDisplayValue — Find input, textarea, or select elements by their current value
6. ByAltText — Find elements with the given alt attribute value
7. ByTitle — Find elements with the given title attribute value
8. ByTestId — Find elements with the given data-testid attribute value

Note the order of this list! We (and Testing Libary) highly encourage you to query for elements in a way that resembles the way a real person would interact with your UI. For example, finding elements by their accessible role helps ensure that the most people can use your component. While using data-testid should be a last resort, only after trying every other approach.

Putting that altogether, some typical queries might look like:

// Find the first element with a role of button with the accessible name "Submit"
await canvas.findByRole('button', { name: 'Submit' });

// Get the first element with the text "An example heading"
canvas.getByText('An example heading');

// Get all elements with the role of listitem
canvas.getAllByRole('listitem');

Querying within shadow DOM

If your components use the shadow DOM, you can query elements within a shadow root with the help of shadow-dom-testing-library, which provides versions of the queries above that can pierce the shadow boundary. For example, findByRole → findByShadowRole, getByText → getByShadowText, and so on.

With a bit of configuration, you can use these queries in your play function. Add the following code to your .storybook/preview.js|ts file:

Now, those queries are available on the canvas object in your play function:

Simulating behavior with userEvent

After querying for elements, you will likely need to interact with them to test your component’s behavior. For this we use the userEvent utility, which is provided as a parameter of your play function. This utility simulates user interactions with the component, such as clicking buttons, typing in inputs, and selecting options.

There are many methods available on userEvent, which are detailed in the user-event documentation. This table will highlight some of the commonly-used methods.

userEvent methods should always be awaited inside of the play function. This ensures they can be properly logged and debugged in the Interactions panel.

Asserting with expect

Finally, after querying for elements and simulating behavior, you can make assertions on the result which are validated when running the test. For this we use the expect utility, which is available via the storybook/test module:

import { expect } from 'storybook/test';

The expect utility here combines the methods available in Vitest’s expect as well as those from @testing-library/jest-dom (which, despite the name, also work in Vitest tests). There are many, many methods available. This table will highlight some of the commonly-used methods.

expect calls should always be awaited inside of the play function. This ensures they can be properly logged and debugged in the Interactions panel.

Spying on functions with fn

When your component calls a function, you can spy on that function to make assertions on its behavior using the fn utility from Vitest, available via the storybook/test module:

import { fn } from 'storybook/test'

Most of the time, you will use fn as an arg value when writing your story, then access that arg in your test:

Run code before the component gets rendered

You can execute code before rendering by using the mount function in the play method.

Here's an example of using the mockdate package to mock the Date, a useful way to make your story render in a consistent state.

There are two requirements to use the mount function:

1. You must destructure the mount property from the context (the argument passed to your play function). This makes sure that Storybook does not start rendering the story before the play function begins.
2. Your Storybook framework or builder must be configured to transpile to ES2017 or newer. This is because destructuring statements and async/await usages are otherwise transpiled away, which prevents Storybook from recognizing your usage of mount.

<If renderer={['react', 'vue', 'svelte']}>

Create mock data before rendering

You can also use mount to create mock data that you want to pass to the component. To do so, first create your data in the play function and then call the mount function with a component configured with that data. In this example, we create a mock note and pass its id to the Page component, which we call mount with.

When you call mount() with no arguments, the component is rendered using the story’s render function, whether the implicit default or the explicit custom definition.

When you mount a specific component inside the mount function like in the example above, the story’s render function will be ignored. This is why you must forward the args to the component.

You can execute code before the component is rendered by defining an asynchronous beforeEach function for the story.

Run code before each story in a file

Sometimes you might need to run the same code before each story in a file. For instance, you might need to set up the initial state of the component or modules. You can do this by adding an asynchronous beforeEach function to the component meta.

You can return a cleanup function from the beforeEach function, which will run after each story, when the story is remounted or navigated away from.

Generally, you should reset component and module state in the preview file's beforeAll or beforeEach functions, to ensure it applies to your entire project. However, if a component's needs are particularly unique, you can use the returned cleanup function in the component meta beforeEach to reset the state as needed.

Set up or reset state for all tests

When you alter a component's state, it's important to reset that state before rendering another story to maintain isolation between tests.

There are two options for resetting state, beforeAll and beforeEach.

beforeAll

The beforeAll function in the preview file (.storybook/preview.js|ts) will run once before any stories in the project and will not re-run between stories. Beyond its initial run when kicking off a test run, it will not run again unless the preview file is updated. This is a good place to bootstrap your project or run any setup that your entire project depends on, as in the example below.

You can return a cleanup function from the beforeAll function, which will run before re-running the beforeAll function or during the teardown process in the test runner.

beforeEach

Unlike beforeAll, which runs only once, the beforeEach function in the preview file (.storybook/preview.js|ts) will run before each story in the project. This is best used for resetting state or modules that are used by all or most of your stories. In the example below, we use it to reset the mocked Date.

You can return a cleanup function from the beforeEach function, which will run after each story, when the story is remounted or navigated away from.

It is not necessary to restore fn() mocks, as Storybook will already do that automatically before rendering a story. See the parameters.test.restoreMocks API for more information.

Make assertions after interactions

Sometimes, you may need to make assertions or run code after the component has been rendered and interacted with.

afterEach

afterEach runs after the story is rendered and the play function has completed. It can be used at the project level in the preview file (.storybook/preview.js|ts), at the component level in the component meta, or at the story level in the story definition. This is useful for making assertions after the component has been rendered and interacted with, such as running checks on the final rendered output or logging information.

Like the play function, afterEach receives the context object, which contains the args, canvas, and other properties related to the story. You can use this to make assertions or run code after the story has been rendered.

You should not use afterEach to reset state in your tests. Because it runs after the story, resetting state here could prevent you from seeing the correct end state of your story. Instead, use the beforeEach's returned cleanup function to reset state, which will run only when navigating between stories to preserve the end state.

Group interactions with the step function

For complex flows, it can be worthwhile to group sets of related interactions together using the step function. This allows you to provide a custom label that describes a set of interactions:

This will show your interactions nested in a collapsible group:

Mocked modules

If your component depends on modules that are imported into the component file, you can mock those modules to control and assert on their behavior. This is detailed in the mocking modules guide. You can then import the mocked module (which has all of the helpful methods of a Vitest mocked function) into your story and use it to assert on the behavior of your component:

Running interaction tests

If you're using the Vitest addon, you can run your interaction tests in these ways:

• In the Storybook UI
• In your editor
• Via the CLI
• In CI environments

In the Storybook UI, you can run interaction tests by clicking the Run component tests button in the expanded testing widget in the sidebar or by opening the context menu (three dots) on a story or folder and selecting Run component tests.

If you're using the test-runner, you can run your interaction tests in the terminal or in CI environments.

Debugging interaction tests

If you check the Interactions panel, you'll see the step-by-step flow defined in your play function for each story. It also offers a handy set of UI controls to pause, resume, rewind, and step through each interaction.

Any test failures will also show up here, making it easy to quickly pinpoint the exact point of failure. In this example, the logic is missing to set the submitted state after pressing the Log in button.

Permalinks for reproductions

Because Storybook is a webapp, anyone with the URL can reproduce the failure with the same detailed information without any additional environment configuration or tooling required.

Streamline interaction testing further by automatically publishing Storybook in pull requests. That gives teams a universal reference point to test and debug stories.

Automate with CI

When you run your tests with the Vitest addon, automating those tests is as simple as running your tests in your CI environment. Please see the testing in CI guide for more information.

If you cannot use the Vitest addon, you can still run your tests in CI using the test-runner.

Troubleshooting

What’s the difference between interaction tests and visual tests?

Interaction tests can be expensive to maintain when applied wholesale to every component. We recommend combining them with other methods like visual testing for comprehensive coverage with less maintenance work.

What's the difference between interaction tests and using Vitest + Testing Library alone?

Interaction tests integrate Vitest and Testing Library into Storybook. The biggest benefit is the ability to view the component you're testing in a real browser. That helps you debug visually, instead of getting a dump of the (fake) DOM in the command line or hitting the limitations of how JSDOM mocks browser functionality. It's also more convenient to keep stories and tests together in one file than having them spread across files.

More testing resources

• Vitest addon for running tests in Storybook
• Accessibility testing for accessibility
• Visual testing for appearance
• Snapshot testing for rendering errors and warnings
• Test coverage for measuring code coverage
• CI for running tests in your CI/CD pipeline
• End-to-end testing for simulating real user scenarios
• Unit testing for functionality
• Test runner to automate test execution