When it comes to visually testing a collection of components, no other tool stands out quite like 

. Not only does Storybook provide an isolated environment for developing components and display their different rendered states, but Storybook also integrates with 

 to simulate and test component functionality that's triggered by a user interaction. For example, instead of just checking if a form renders correctly, you can also check if behavior like form submission and validation work correctly. This integration with Testing Library allows Storybook to capture all component states, those that can be reproduced solely with props and those that require user interaction to be reached.

Conventionally, developers run and receive feedback on tests written in Jest and Testing Library in the CLI. It prints several lines of text that report which assertions (

 statements) passed and failed. However, it never shows what the component looks like when rendered. With Storybook and a Storybook addon called 

, you get to view and interact with the rendered component in Storybook's Canvas. Plus, you get to see line-by-line reporting of the simulated user interactions and passed/failed assertions in Storybook's Interactions panel. By having everything under one roof this way, you only need to set up decorators like theming and routing just once, and the Storybook GUI trumps over the CLI for debugging UI issues.

, Storybook introduced browser-compatible wrappers of Testing Library and Jest that power interactive stories. These type of stories automate user interactions using a 

 function. A new feature to Component Story Format (CSF) 3.0, the 

 executes after the component has rendered in Storybook. Using methods from the Testing Library, the 

 for clicking an element, that simulate user interactions in the browser. 

Below, I'm going to show you how to write interaction tests directly in Storybook. 

For this tutorial, we will be testing the functionality of a line chart built with React and D3:

To get started, clone the following repository:

$ git clone --branch initial https://github.com/newline-sandbox/storybook-interaction-testing.git

This repository contains a visualization component library with a customizable, multi-line chart written in React, D3 and TypeScript.

Inside of the project directory, install the dependencies:

Then, run Storybook to view and interact with the multi-line chart component 

Currently, there are three stories defined for this component in Storybook: 

 stories visualize the closing prices of several popular technology stocks from May 2013 to May 2022: Apple (AAPL), Amazon (AMZN), Facebook (FB), Google (GOOGL), Netflix (NFLX) and Tesla (TSLA).

Before it renders a story, Storybook fetches the stock data with 

. Once fetched, the loaded data gets injected into the story via 

const Template: Story<TemplateProps> = ({ isEmpty, ...args }, { loaded }) => {
  return (
    <TimelineChart
      {...args}
      data={isEmpty ? args.data : loaded ? loaded.timelineChartData : args.data}
    />
  );
};

For interaction testing, we must have three addons/integrations installed:

Since initializing Storybook for a React project (via the 

$ npm install --save-dev @storybook/jest 

 for the command to choose the correct Storybook project type and install these Storybook addons/integrations.

 addon already registered. To enable the addon's experimental step debugging features, set 

module.exports = {
  // ...
  features: {
    interactionsDebugger: true,
  },
}

Let's write some interaction tests for the 

First, we will write an interaction test for validating the toggling behavior in the chart's legend. We expect the user to be able to toggle lines in the chart by checking/unchecking their corresponding legend keys.  

Initially, all the lines will be visible in the chart. The 

 function will simulate a user unchecking all of the legend keys but the first one. By the end, only the line corresponding to the first legend key that's left checked will remain rendered in the chart. The other lines will have been removed.

. Since the chart requires a legend for toggling, the story will accept the same set of arguments as the 

// ...

export const ToggledLines = Template.bind({});
ToggledLines.args = LEGEND_ARGS;

// ...

ToggledLines.play = async ({ canvasElement, args, loaded }) => {
  // ...
};

 object that contains lots of information about the story. For most interaction tests, you will be concerned with only three pieces of information:

 file, import several methods and objects from 

 to help simulate user interactions and perform assertions in the 

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

// ...

ToggledLines.play = async ({ canvasElement, args, loaded }) => {
  const canvas = within(canvasElement);

  loaded.timelineChartData.slice(1).forEach(async (arr) => {
    const legendKey = await canvas.getByTestId(
      `legend-key-${arr[0][args.categoryKey].toLowerCase()}`
    );
    await userEvent.click(legendKey);
  });

  await expect(
    canvas.getByTestId(
      `line-${loaded.timelineChartData[0][0][args.categoryKey].toLowerCase()}`
    )
  ).toBeInTheDocument();
};

 function so that it asserts that the lines corresponding to all but the first legend key no longer exist within the document. 

 story in the Storybook UI, you will notice that Storybook successfully simulated the user interactions and the assertion passed. Here, the canvas displays the component with only one line, the one that corresponds to the first legend key, which we left checked. 

Let's move on to the next interaction test.

For this interaction test, we will validate the behavior of the chart's bisector line and cursor.

When the user clicks on a line, the other lines fade out, and the bisector line and cursor appears and attaches to the clicked line. As the user moves their cursor, the bisector's infobox should display the exact value based on the nearest x-axis value.

. Since multiple lines should fade out when the user clicks on a line, and coloring each line helps the user track the stock that they're interested in, the story will accept the same set of arguments as the 

// ...

export const SelectedLines = Template.bind({});
SelectedLines.args = LEGEND_ARGS;

// ...

SelectedLines.play = async ({ canvasElement, args, loaded }) => {
  // ...
};

 lacks support for a mousemove event, we need to import 

import { within, userEvent, fireEvent } from "@storybook/testing-library";

// ...

export const SelectedLine = Template.bind({});
SelectedLine.args = LEGEND_ARGS;
SelectedLine.play = async (h) => {
  const canvas = within(canvasElement);

  const line = await canvas.getByTestId(
    `line-${loaded.timelineChartData[0][0][args.categoryKey].toLowerCase()}`
  );

  await userEvent.click(line);

  const bisectorArea = await canvas.getByTestId("bisector-area");

  await fireEvent.mouseMove(bisectorArea, {
    clientX:
      (args.baseDimensions.width -
        args.baseDimensions.margins.left -
        args.baseDimensions.margins.right) /
        2 +
      args.baseDimensions.margins.left,
    clientY:
      (args.baseDimensions.height -
        args.baseDimensions.margins.top -
        args.baseDimensions.margins.bottom) /
        2 +
      args.baseDimensions.margins.top,
  });

  await expect(canvas.getByTestId("bisector-infobox")).toBeInTheDocument();
  await expect(canvas.getByTestId("bisector-cursor")).toBeInTheDocument();
};

 story in the Storybook UI, you will notice that Storybook successfully simulated the user interactions and the assertions passed. Here, the canvas displays the component with only one line selected, the one that corresponds to the first legend key. A bisector line and cursor is attached to this line and is positioned in the center of the chart's bounded area. On September 1, 2017, the closing price of Apple stock (AAPL) was ~$41.01.

What if you wanted to test a scenario in which the user unchecks all but the first legend key, clicks on the line that corresponds to the first legend key and moves their mouse to the center of the chart's bounded area to see what the stock's closing price was at that date within the bisector's infobox?

A story that tests this scenario is a combination of the 

Rather than duplicating the simulated user interactions and assertions in these stories' 

 functions, you can re-use these stories' play functions and compose them to simulate complex scenarios like the one just mentioned, like so:

// ...

export const ToggledLinesAndSelectedLine = Template.bind({});
ToggledLinesAndSelectedLine.storyName = "Toggled Lines + Selected Line";
ToggledLinesAndSelectedLine.args = LEGEND_ARGS;
ToggledLinesAndSelectedLine.play = async (context) => {
  await ToggledLines.play(context);
  await SelectedLine.play(context);
};

 story in the Storybook UI, you will notice that Storybook successfully simulated the user interactions and the assertions passed. 

Here, the canvas displays exactly what the canvas for the 

 story displayed, but with only one line shown, the one that corresponds to the first legend key.

import React from "react";
import { Story, Meta } from "@storybook/react";
import { within, userEvent, fireEvent } from "@storybook/testing-library";
import { expect } from "@storybook/jest";

import { TimelineChart, TimelineChartProps } from "../components/TimelineChart";

export default {
  title: "Example/TimelineChart",
  component: TimelineChart,
} as Meta;

const BASE_ARGS = {
  baseDimensions: {
    get width() {
      return 800;
    },
    get height() {
      return 500;
    },
    margins: {
      top: 10,
      right: 30,
      bottom: 75,
      left: 60,
    },
  },
  dateFormat: "%Y-%m-%dT%H:%M:%S.%LZ",
  labels: {
    xAxis: "Date",
    yAxis: "Price (USD)",
  },
  yAxisTicksCount: 10,
  xAccessorKey: "date",
  yAccessorKey: "close",
};

interface TemplateProps extends TimelineChartProps {
  isEmpty?: boolean;
  isSingleLine?: boolean;
}

const Template: Story<TemplateProps> = (
  { isEmpty, isSingleLine, ...args },
  { loaded }
) => {
  return (
    <TimelineChart
      {...args}
      data={
        isEmpty
          ? []
          : loaded
          ? isSingleLine
            ? [loaded.timelineChartData[0]]
            : loaded.timelineChartData
          : args.data
      }
    />
  );
};

export const Default = Template.bind({});
Default.args = {
  ...BASE_ARGS,
  isSingleLine: true,
};

export const Empty = Template.bind({});
Empty.args = {
  ...BASE_ARGS,
  isEmpty: true,
};

const LEGEND_ARGS = {
  ...BASE_ARGS,
  categoryKey: "symbol",
  categoryColors: ["#754668", "#982649", "#9395d3", "red", "blue", "green"],
};

export const Legend = Template.bind({});
Legend.args = LEGEND_ARGS;

export const ToggledLines = Template.bind({});
ToggledLines.args = LEGEND_ARGS;
ToggledLines.play = async ({ canvasElement, args, loaded }) => {
  const canvas = within(canvasElement);

  loaded.timelineChartData.slice(1).forEach(async (arr) => {
    const legendKey = await canvas.getByTestId(
      `legend-key-${arr[0][args.categoryKey].toLowerCase()}`
    );
    await userEvent.click(legendKey);
  });

  await expect(
    canvas.getByTestId(
      `line-${loaded.timelineChartData[0][0][args.categoryKey].toLowerCase()}`
    )
  ).toBeInTheDocument();
};

export const SelectedLine = Template.bind({});
SelectedLine.args = LEGEND_ARGS;
SelectedLine.play = async ({ canvasElement, args, loaded }) => {
  const canvas = within(canvasElement);

  const line = await canvas.getByTestId(
    `line-${loaded.timelineChartData[0][0][args.categoryKey].toLowerCase()}`
  );

  await userEvent.click(line);

  const bisectorArea = await canvas.getByTestId("bisector-area");

  await fireEvent.mouseMove(bisectorArea, {
    clientX:
      (args.baseDimensions.width -
        args.baseDimensions.margins.left -
        args.baseDimensions.margins.right) /
        2 +
      args.baseDimensions.margins.left,
    clientY:
      (args.baseDimensions.height -
        args.baseDimensions.margins.top -
        args.baseDimensions.margins.bottom) /
        2 +
      args.baseDimensions.margins.top,
  });

  await expect(canvas.getByTestId("bisector-infobox")).toBeInTheDocument();
  await expect(canvas.getByTestId("bisector-cursor")).toBeInTheDocument();
};

export const ToggledLinesAndSelectedLine = Template.bind({});
ToggledLinesAndSelectedLine.storyName = "Toggled Lines + Selected Line";
ToggledLinesAndSelectedLine.args = LEGEND_ARGS;
ToggledLinesAndSelectedLine.play = async (context) => {
  await ToggledLines.play(context);
  await SelectedLine.play(context);
};

If you find yourself stuck at any point while working through this tutorial, then feel free to visit the 

Try migrating your own project's testing suite over to Storybook. 

If you want to learn more advanced techniques with Storybook, then check out the 

 course by Yann Braga, a senior software engineer at Chromatic and a maintainer of Storybook:

As a member of the Storybook team, Yann also worked on many of Storybook's testing-related packages, such as 

Learn

The newline Guide to Building Your First GraphQL Server with Node and TypeScript

Teach

Amelia Wattenberger

Author of Fullstack D3

Community

Interaction Testing in Storybook

Responses (0)

Masterclasses

Tutorials

Fullstack React with TypeScript