Interaction tests

Interaction tests enable you to verify how a component responds to user behaviors like click, type, keyboard, and hover. It’s powered by Storybook’s play function.

Interaction tests require Storybook 6.5.10+. Check which version you have in package.json or open the “About Storybook” page in your Storybook.

How to write interaction tests

Add a play function to your component’s story to enable interaction tests. For example, if you want to validate a component’s behavior write the following story:

// RangeSlider.stories.js|jsx

import React from 'react';

import { within, userEvent } from '@storybook/testing-library';
import { expect } from '@storybook/jest';

import { RangeSlider } from './RangeSlider';

export default {
  component: RangeSlider,
  title: 'Library/Charts/RangeSlider',
};

const Template = (args) => <RangeSlider {...args} />;

export const InputRange = Template.bind({});
InputRange.play = async ({ canvasElement }) => {
  // Assigns canvas to the component root element
  const canvas = within(canvasElement);

  // 🔢 Type into input field
  await userEvent.type(canvas.getByTestId('input-max-range'), '15');

  // ✅ Assert that component is responding to user behavior
  const availableOptions = await canvas.findAllByTestId('highlighted-bar');
  await expect(availableOptions.length).toBe(15);
};

Read Storybook’s interaction testing docs. Get an API cheatsheet for user events here.

In Storybook, your interactions and assertions are visualized in the addon panel. Enable the playback controls to step through each interaction to confirm that it’s working as intended.

// .storybook/main.js|ts

module.exports = {
  stories: ['../src/**/*.stories.mdx', '../src/**/*.stories.@(js|jsx|ts|tsx)'],
  features: {
    interactionsDebugger: true, // 👈 Enable playback controls
  },
};

Storybook passed tests

Confirm interaction tests are working

Interaction tests run behind the scenes without you having to configure anything. To verify that they are working in Chromatic, publish your Storybook either via CLI or CI. You can confirm that they’re running with the “Interaction” label in the Build page’s Tests section.

Confirm interaction test run in the build summary

Debug test failures

Chromatic notifies you when an interaction errors or an assertion fails. We designate these as critical failures that need immediate attention. You won’t be able to pass the build until the test is fixed.

Build page with failed interaction test

To find out which steps failed in your interaction test, click on the change to see a snapshot of the state where the error occurred. You’ll see a detailed log and browser environment metadata to help with reproductions.

Test page with failed interaction test

Reproduce test failures with a URL

Go to your published Storybook to reproduce the exact state of your story when the test failed. Click the “View Storybook” button on the test page to open the failed story with the error message visible. Share the link with teammates to get a second opinion.

Storybook with failed interaction test

PR check for interaction tests

Interaction tests are reported in the UI Tests pull request check. When a test fails, you’ll see a “Failed tests” status message prompting you to fix the test before moving on.

Failed interaction tests in CI


Frequently asked questions

Why aren't my interaction tests working in IE11?

IE11 has entered the end of life and isn’t supported by the instrumented libraries that Chromatic relies upon to run interaction tests. We recommend previewing your tests using the other available browsers (e.g., Firefox, Chrome).

My interactions aren't getting snapshotted consistently with external web fonts?

Interactions run as soon as the DOM loads. But external resources like web fonts can load before or after the interaction runs depending on network latency. This can cause dialogs, tooltips, and menus to change position.

We recommend preloading fonts to ensure they’re available when the DOM renders. If preloading is not possible, try adding a delay before running interactions.