Skip to content

Latest commit

 

History

History
163 lines (111 loc) · 9.22 KB

interaction-testing.md

File metadata and controls

163 lines (111 loc) · 9.22 KB
Raw
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.

In Storybook, this familiar workflow happens in your browser. That makes it easier to debug failures because you're running tests in the same environment as you develop components: the browser.

Storybook interaction testing

How does component testing in Storybook work?

You start by writing a story to set up the component's initial state. Then simulate user behavior using the play function. Finally, use the test-runner to confirm that the component renders correctly and that your interaction tests with the play function pass. Additionally, you can automate test execution via the command line or in your CI environment.

  • The play function is a small snippet of code that runs after a story finishes rendering. You can use this to test user workflows.
  • The test is written using Storybook-instrumented versions of Jest and Testing Library.
  • @storybook/addon-interactions visualizes the test in Storybook and provides a playback interface for convenient browser-based debugging.
  • @storybook/test-runner is a standalone utility—powered by Jest and Playwright—that executes all of your interactions tests and catches broken stories.

Set up the interactions addon

To enable interaction testing with Storybook, 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.

Run the following command to install the interactions addon and related dependencies.

<CodeSnippets paths={[ 'common/storybook-addon-interactions-addon-full-install.yarn.js.mdx', 'common/storybook-addon-interactions-addon-full-install.npm.js.mdx', ]} />

Update your Storybook configuration (in .storybook/main.js|ts) to include the interactions addon and enable playback controls for debugging.

<CodeSnippets paths={[ 'common/storybook-main-enable-interactive-debugger.js.mdx', ]} />

Write an interaction test

The test itself is defined inside a play function connected to a story. Here's an example of how to set up an interaction test with Storybook and 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));

Interactive debugger

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

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.

Interaction testing with a component

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

Execute tests with the test-runner

Storybook only runs the interaction test when you're viewing a story. Therefore, you'd have to go through each story to run all your checks. As your Storybook grows, it becomes unrealistic to review each change manually. Storybook test-runner automates the process by running all tests for you. To execute the test-runner, open a new terminal window and run the following command:

<CodeSnippets paths={[ 'common/storybook-test-runner-execute.yarn.js.mdx', 'common/storybook-test-runner-execute.npm.js.mdx', ]} />

Interaction test with test runner

💡 If you need, you can provide additional flags to the test-runner. Read the documentation to learn more.

Automate

Once you're ready to push your code into a pull request, you'll want to automatically run all your checks using a Continuous Integration (CI) service before merging it. Read our documentation for a detailed guide on setting up a CI environment to run tests.

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