storybook/docs/writing-tests/interaction-testing.md

title
Interaction tests

As you build more complex UIs like pages, components become responsible for more than just rendering the UI. They fetch data and manage state. Interaction tests allow you to verify these functional aspects of UIs.

In a nutshell, you start by supplying the appropriate props for the initial state of a component. Then simulate user behavior such as clicks and form entries. Finally, check whether the UI and component state update correctly.

Setup interactions addon

You can set up interaction testing in Storybook using the play function and @storybook/addon-interactions.

• The play function is a small snippet of code that runs after a story finishes rendering. You can use this to test user workflows.

• @storybook/addon-interactions includes helper utilities and a playback interface that simulates user behavior in the browser. It’s powered Testing Library and includes convenient instrumentation for debugging.

Here's an example of how to set up interaction testing in Storybook with the play function:

<CodeSnippets paths={[ 'react/login-form-with-play-function.js.mdx', 'react/login-form-with-play-function.ts.mdx', 'react/login-form-with-play-function.mdx.mdx', 'angular/login-form-with-play-function.ts.mdx', 'angular/login-form-with-play-function.mdx.mdx', 'vue/login-form-with-play-function.2.js.mdx', 'vue/login-form-with-play-function.mdx-2.mdx', 'vue/login-form-with-play-function.3.js.mdx', 'vue/login-form-with-play-function.mdx-3.mdx', 'svelte/login-form-with-play-function.js.mdx', 'svelte/login-form-with-play-function.mdx.mdx', ]} />

Once the story loads in the UI, it simulates the user's behavior and verifies the underlying logic.

API for user-events

Under the hood, Storybook’s interaction addon mirrors Testing Library’s user-events API. If you’re familiar with Testing Library you should be at home in Storybook.

Below is an abridged API for user-event. For more, check out the official user-event docs.

User events	Description
clear	Selects the text inside inputs, or textareas and deletes it userEvent.clear(await within(canvasElement).getByRole('myinput'));
click	Clicks the element, calling a click() function userEvent.click(await within(canvasElement).getByText('mycheckbox'));
dblClick	Clicks the element twice userEvent.dblClick(await within(canvasElement).getByText('mycheckbox'));
deselectOptions	Removes the selection from a specific option of a select element userEvent.deselectOptions(await within(canvasElement).getByRole('listbox','1'));
hover	Hovers an element userEvent.hover(await within(canvasElement).getByTestId('example-test'));
keyboard	Simulates the keyboard events userEvent.keyboard(‘foo’);
selectOptions	Selects the specified option, or options of a select element userEvent.selectOptions(await within(canvasElement).getByRole('listbox'),['1','2']);
type	Writes text inside inputs, or textareas userEvent.type(await within(canvasElement).getByRole('my-input'),'Some text');
unhover	Unhovers out of element userEvent.unhover(await within(canvasElement).getByLabelText(/Example/i));

Permalinks for reproductions

The play function is executed after the story is rendered. If there’s an error, it’ll be shown in the interaction addon panel to help with debugging.

Since Storybook is a webapp, anyone with the URL can reproduce the error 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.

---

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.

Learn about other UI tests

• Visual tests for appearance
• Accessibility tests for accessibility
• Interaction tests for user behavior simulation
• Snapshot tests for rendering errors and warnings
• Import stories in other tests for other tools