[RFC]: Making Storybook a first-class test framework with CSF factories

[kasperpeulen]

Rejected in favor of:
#29658
#30119

Storybook has long been a favorite tool for documenting and developing design system components in isolation. Over time, it has evolved to offer more powerful testing features—with hooks such as play and beforeEach—that position it as a UI testing framework. However, leveraging Storybook for testing often requires learning a new testing syntax and best practices built on top of Storybook’s Component Story Format (CSF).

In this guide, we'll explore how CSF factories can transform Storybook into a first-class testing framework. We'll demonstrate how to enable more standard testing capabilities while reducing boilerplate in the args-based CSF syntax.

Reducing CSF Boilerplate with Factories

Writing a type-safe CSF3 story typically involves a significant boilerplate. Here's an example of a standard CSF3 story for a Button component:

// Button.stories.ts
import type { Meta, StoryObj } from '@storybook/react';
import { Button } from './Button';

const meta = { component: Button } satisfies Meta<typeof Button>;
 
export default meta;

type Story = StoryObj<typeof meta>;
 
export const Primary: Story = {
  args: {
    primary: true,
    label: 'Button',
  },
};

To streamline this process, we can introduce factories that require no extra type annotations for type safety. Here's how the Button story would look using factories:

import { config } from '#.storybook/preview';
import { Button } from './Button';

const meta = config.meta({ component: Button });

export const Primary = meta.story({
  args: {
    primary: true,
    label: 'Button',
  },
});

This approach reduces the need for explicit type declarations and manual repetitive code, minimizing the chances of errors. It makes the story definitions more concise and easier to understand.

The preview file

The preview file is central to configuring Storybook's behavior and addons. Here's a .storybook/preview.ts file using factories:

// .storybook/preview.ts
import { defineConfig } from '@storybook/nextjs';
import essentials from '@storybook/addon-essentials/preview';
import chromatic from '@chromatic-com/storybook/preview';

export const config = defineConfig({
  addons: [essentials(), chromatic()],
  decorators: [...]
})

To leverage type information from addons within your stories, explicitly import the preview config:

import config from '#.storybook/preview';

// ProfilePage.stories.tsx
const meta = config.meta({ 
  component: ProfilePage,
  parameters: {
    // autocompleted and typesafe!!
    chromatic: { diffThreshold: 0.2 },
    nextjs: {
      navigation: {
        pathname: '/profile',
      },
    },
  }, 
});

Note: While you can use relative imports for the preview file, we recommend adopting this standard-based absolute import convention, popularized by Kent C. Dodds. Learn more about this convention

Making Storybook a First-Class Test Framework

While Storybook excels at developing and documenting components, its potential as a testing framework is often underutilized. It's not immediately obvious how to translate tests written with tools like Vitest or Jest into Storybook. Consider the following tests:

test('handles a server error response', () => {
  msw.use(
    http.get('/user', () => new HttpResponse(null, { status: 500 }))
  )
  const { getByRole } = render(<RestaurantDetailPage data="data"/>);
  await userEvent.click(getByRole(...))
  expect(...)
})

test('handles a success response', () => {
  const { getByRole } = render(<RestaurantDetailPage data="other data"/>);
  await userEvent.click(getByRole(...))
  expect(...)
})

We propose a way to write these tests within Storybook in a very similar fashion:

import config from '#.storybook/preview';
import { Button } from './Button';

// Note that it is not required anymore to write a "meta" in this proposal

export const HandlesServerErrorResponse = config.play(async ({ mount }) => {
  msw.use(
    http.get('/user', () => new HttpResponse(null, { status: 500 }))
  )
  const { getByRole } = await mount(<RestaurantDetailPage data="data"/>);
  await userEvent.click(getByRole(...))
  await expect(...)
});

// 👇 We need this to be an ESM export instead of a dynamic `test` call
// This ensures we can position all stories in the sidebar in a performant way
export const HandlesSuccessResponse = config.play(async ({ mount }) => {
  const { getByRole } = await mount(<RestaurantDetailPage data="other data"/>);
  await userEvent.click(getByRole(...))
  await expect(...)
});

The above is a shortcut for writing a story with only a play function. It can be expanded as follows:

export const HandlesServerErrorResponse = config.story({
  // use other story properties such as args/parameters here
  async play({ mount }) {
    msw.use(
      http.get('/user', () => new HttpResponse(null, { status: 500 }))
    )
    const { getByRole } = await mount(<RestaurantDetailPage data="data" />);
    await userEvent.click(getByRole(...))
    await expect(...)
  })
});

export const HandlesSuccessResponse = config.story({
  async play({ mount }) {
    const { getByRole } = await mount(<RestaurantDetailPage data="other data" />);
    await userEvent.click(getByRole(...))
    await expect(...)
  })
});

Note: The mount function is also already available in storybook 8: #27389

We envision that many test users prefer doing everything in the play function, rather than using separate CSF constructs such as args, component, decorators, parameters, and render.

In this proposal, users don’t necessarily need any of those constructs. You can still use them—they are powerful abstraction mechanisms—but you are not forced to learn them.

For example, if you want to make the props of your component interactive in Storybook, you can opt-in to using meta and args:

// 👇 rendered by default when mounting
const meta = config.meta({ component: RestaurantDetailPage });

export const HandlesServerErrorResponse = meta.story({
  // 👇 used as props of the component in the mount call below
  args: { data: "data" },
  async play({ mount }) {
    msw.use(
      http.get('/user', () => new HttpResponse(null, { status: 500 }))
    )
    // 👇 as we’ve provided `component` and `args` above
    // mount() will now render <RestaurantDetailPage data="data" /> by default
    const { getByRole } = await mount();
    await userEvent.click(getByRole(...))
    await expect(...)
  })
});

export const HandlesSuccessResponse = meta.story({
  args: { data: "other data" },
  async play({ mount }) {
    const { getByRole } = await mount();
    await userEvent.click(getByRole(...))
    await expect(...)
  })
});

What’s changed here? We’ve substituted the mount(<RestaurantDetailPage .../>) with a more abstract construct — we’ve moved the component up to the meta and we’ve moved the props to the args annotation. Why?

By telling Storybook explicitly you are “rendering component X with props Y” it allows us to do a bunch of powerful things that the more freeform Jasmine API cannot:

• Docgen: Automatic documentation generation of the component.
• Interactive Controls: Change args dynamically via the UI.
• Action Logging: Monitor events within the component.
• Source Snippets: View the example code of the component directly in Storybook.

But it is optional. Users can also get lots of benefits from Storybook without this args-refactor:

• Develop: Develop and test components at the same time inside of storybook.
• Visual Testing: Perform automatic visual tests.
• Visual Debugging: Debug UI components visually with the interaction debugger.
• Publish: Easily share your Storybook with others.

Factory for CSF1-style stories

It is popular to write stories as a component when using React:

export const SomeStory = () => <Cmp><Child/></Cmp>;

In this proposal, you will be able to use this pattern with CSF factories as well:

export const SomeStory = meta.render(() => <Cmp><Child/></Cmp>);

Full control of the test lifecycle

In the example above, you might wonder how to configure msw so that it can be used in the play function in Storybook. Where do you start the service worker? How do you reset handlers? For full control of the test lifecycle, we have added beforeEach and beforeAll as part of the Component Story Format recently.

Setting up MSW with beforeAll and beforeEach

Here is an example how you can fully setup msw manually without the need to use the official MSW addon:

// .storybook/preview.ts
import { defineConfig } from '@storybook/nextjs';
import essentials from '@storybook/addon-essentials/preview';
import chromatic from '@chromatic-com/storybook/preview';
import { setupWorker } from 'msw/browser'

export const msw = setupWorker();

export const config = defineConfig({
  addons: [essentials, chromatic],
  // beforeAll is only available for global config in preview.ts
  async beforeAll() {
    await msw.start()
    // 👇 beforeAll accepts a cleanup function
    // this will be called when storybook is reloaded or at the end of a CI run
    return msw.close;
  }),
  // beforeEach can be used on a config/meta and story level
  async beforeEach() {
    // 👇 place this in a beforeEach
    msw.resetHandlers();
  },
});

Proposal to add afterEach to storybook

We accept a cleanup callback in both `beforeAll` and `beforeEach`, but we haven’t yet adopted the `afterAll` and `afterEach` hooks.

Those after-hooks are tricky in an interactive test tool like Storybook. As a user, you might expect afterEach to run after the test is executed, and in other interactive test tools like Vitest's browser UI, this is where it runs.

But there's a problem here: if you reset MSW handlers after the test is executed, the handlers will be cleaned up when you interact manually with the browser after the test.

For a similar reason, Vitest has forked testing library to ensure dom cleanup is not run at the end of a test: https://github.com/vitest-dev/vitest-browser-react.

Unlike @testing-library/react, vitest-browser-react performs cleanup of the component before the test begins, allowing you to see the rendered result in your UI. If you prefer to disable auto-cleanup, you can import the render function from vitest-browser-react/pure.

We have considered adding afterEach and only running when switching to a new story, but then you can not do a generic post-test assertion anymore in afterEach:

const consoleError = spyOn(console, 'error');

const config = defineConfig({
  async afterEach() {
    await expect(consoleError).not.toHaveBeenCalled();
  }
});

For this reason, we recommend cleaning up global mock state at the very beginning of each test, in a global beforeEach. For example, running msw.resetHandlers() before each test.

If you want to clean up specific mock state constructed in the beforeEach of a meta or a story, we accept a cleanup callback:

// Calendar.stories.tsx
const meta = config.meta({
  component: Calendar,
  // 👇 Set the value of Date for every story in the file
  async beforeEach() {
    MockDate.set('2024-02-14');
 
    // 👇 Reset the Date after each story in this story file
    return () => {
      MockDate.reset();
    };
  },
};

Those cleanup callbacks are not called after the test has executed, but only when switching to a new story. We are considering adding afterEach in Storybook for executing post-test assertions:
#29583

Parametrizing tests in storybook

In many test frameworks, you can parameterize tests with an each method such as:

test.each<{ todos: Todo[] }>([
  { todos: [] },
  { todos: [{ description: "first todo" }] },
  { todos: [{ description: "first todo" }, { description: "second todo" }] },
])('todos are fetched and clickable', ({ todos }) => {
  msw.use(
    http.get('/todos', () => new HttpResponse(todos)
  )
  const { getByRole } = await render(<TodoList/>);
  await userEvent.click(getByRole(...))
  expect(...)
});

In Storybook, every tests must be an ESM export. This ensures we can position all stories in the sidebar in a performant way. In this proposal, you can parameterize a play function by adding custom parameters to meta:

const meta = config.meta<{ parameters: { todos: Todo[] } }>({ 
  async play({ mount, parameters }) => {
    // 👇 parameterize the call to /todos
    msw.use(
      http.get('/todos', () => new HttpResponse(parameters.todos)
    )
    const { getByRole, queryByRole } = await mount(<TodoList/>);
    await userEvent.click(getByRole(...))
    await expect(queryByRole('listitem').toHaveLength(parameters.todos.length);
  })
});

export const EmptyTodos = meta.story({ parameters: { todos: [] } });
export const OneTodo = meta.story({ parameters: { todos: [{ description: "first todo" }] } });
export const ManyTodos = meta.story({ parameters: { 
  todos: [{ description: "first todo" }, { description: "second todo" }] } 
});

Parameters are static in storybook, you can not change them dynamically in the UI. While args are dynamic and controllable by the control addon. At some point we want to support non-component args prefixed with a $. Normally, all args of the story are automatically applied as props of the component. We would like to introduce “$-prefixed-args” (aka non-component args) as a way to get all the power of controls and args for other purposes (aside from component props).

const meta = config.meta<{ args: { $todos: Todo[] } }>({ 
  async play({ mount, args }) => {
    // 👇 parameterize the call to /todos
    msw.use(
      http.get('/todos', () => new HttpResponse(args.$todos)
    )
    const { getByRole, queryByRole } = await mount(<TodoList/>);
    await userEvent.click(getByRole(...))
    await expect(queryByRole('listitem').toHaveLength(parameters.todos.length);
  })
});

export const EmptyTodos = meta.story({ args: { $todos: [] } });
export const OneTodo = meta.story({ args: { $todos: [{ description: "first todo" }] } });
export const ManyTodos = meta.story({ args: { 
  $todos: [{ description: "first todo" }, { description: "second todo" }] } 
});

All factories accept a generic type parameter. For example, addons can leverage that for adding new Storybook parameters:

// some-addon/preview.ts
export default defineConfig<{ parameters: { addonName?: AddonParameters } }>({
  decorators: [addonDecorator],
});

[kettanaito]

Hi! Thanks for opening this RFC. I believe this is a movement in the right direction. Below, I will share some of my thoughts regarding the proposed format (mostly around testing) and also things generally related to API design.

Story args vs play setup

I can hardly think of a situation when you would need additional setup in the play() function that isn’t already a part of your story’s args. With that in mind, I believe things like network mocking must live in args for they are needed to render the story as well:

export const Scenario = meta.story({
  args: {
    msw: {
      handlers: handlers
    }
  },
  async play() {}
})

We are working on the next iteration of msw-storybook-addon that will automatically apply args.msw.handlers to MSW’s worker without explicitly drilling them via msw.use(). That is the way.

That is not to say that one cannot rely on .use() in the play() function. Just a precaution of what to feature as the recommended way for most users.

play implies a single test case

From what I read, the play() function stands for a single test case associated with the story. In practice, that will not be enough, as UI components (let alone pages) often encompass multiple different behaviors. Putting them all into a single play() function will lead to a verbose test that won’t have much use.

I suggest you consider making play() reflect the multi-behavior nature of UIs. One way, which may be rather crude, is to support a list of play functions, each representing a test case:

export const Scenario = meta.story({
  play: [
    async firstTestCaseName(context) {},
    async secondTestCaseName(context) {}
  ]
})

Relying on functions names for test case names isn’t a good idea; this API is purely illustrational. Besides, extracting those names would mean full AST parsing of the module, which, I get an idea, you are trying to avoid.

Parametric tests

Parametric tests are rather niche. Most people shouldn’t be writing those, especially when testing UI components.

The proposed API (single test accepting parameters.todos) leads to smart tests. Those are the worst kind to work with. You don’t want to be smart in tests as a rule of thumb. Keep them explicit. From Storybook’s side, that means designing APIs that facilitate that explicitness rather that introduce implicit context (parameters) and test cases that are hard to read/toggle/debug/etc.

I would generally advice you to skip parametric tests altogether, and direct the effort elsewhere.

The Perfect™ API

Okay, let’s fantacize for a moment. What would a perfect test API look like in Storybook? The one that would leverage the user’s familiarity, make it more transferable, and yield a useful test case.

First, I describe the stories for my UI component. These are all the possible states that component can be in, alongside any args that are required to render that state.

// stories/button.stories.tsx
const meta = config.meta({ component: Button })

export const DefaultState = meta.story({
  args: allThisStoryNeedsToRender,
})

export const DisabledState = meta.story({ ... })

With the representation done, I can use individual stories as component in tests.

// tests/stories/button.test.tsx
import { render } from '@storybook/test-utils'
import * as ButtonStates from '~/stories/button.stories.jsx'

test('renders accessible button', async () => {
  const screen = await render(
	<ButtonState.DefaultState>
	  Hello world
	</ButtonState.DefaultState/>
  )

  expect(screen.getByRole('button', { name: 'Hello world' })).toBeVisible()
})

Notice that this is a regular test suite in Jest or Vitest. Storybook’s value here is giving me a preconfigured component state and a render() function to render that component in the browser (please use Vitest’s Browser Mode).

This gives me the most value as a developer, no matter if I’m familiar with Storybook or it’s my first time using it. I invest my time in learning CSF because it (1) creates an interactive showcase for my UI; (2) acts as a test setup phase for various UI states, which is neat. Those are two attractive reasons to consider Storybook.

This separation of concerns means more flexibility as well. Storybook’s responsibilities are now focused on configuring the component and rendering it. Everything else is the test framework’s responsibility. That is really nice, because it means less work for Storybook and more power to the end developer.

By this point, you may be wondering how to reuse a standalone, unrelated test module to play() it in Storybook’s preview? Depending on how interactive you want it to be, you can go from AST parsing and extraction of test case names to run them in a preview tab, all the way to hooking into test runner’s internals to use Storybook preview as an interactive step-through when debugging tests.

Going test-first also means less performance overhead as Storybook doesn’t need to translate individual stories’ play() function to test cases. It’s the other way around, and to me this way makes more sense. Most time is spent by CI/CD running tests, not developers using Storybook, if we compare. Perhaps a good idea to optimize for that.

That being said…

…the test-first direction may be against what you are trying to build. Please consider that, as I don’t have the full context here. I am sharing my thoughts from an average developer’s point of view, highlighting how I would use this and what I would expect. Hope this helps!

[kasperpeulen]

Thanks for the feedback @kettanaito.
This has raised a lot of discussion internally, I will post a new RFC shortly.

But let me first reply to your comments:

I can hardly think of a situation when you would need additional setup in the play() function that isn’t already a part of your story’s args.
There are some situations. E.g. opening dropdowns/modals etc. that can not be controlled using props.

With that in mind, I believe things like network mocking must live in args for they are needed to render the story as well.
We are working on the next iteration of msw-storybook-addon that will automatically apply args.msw.handlers to MSW’s worker without explicitly drilling them via msw.use(). That is the way.

We can move this discussion to another place, but I think that moving msw handlers from parameters to args is not a good idea for 2 reasons:

1. args are automatically applied to the component, so some renderers will give errors when a non-existing msw prop is applied. We are considering non-component args though, prefixed with $ to not be automatically applied to the component (see the end of this RFC). So that would circumvent that problem.
2. Even if we have non-component args, I still think that moving handlers from parameters.msw to args.$msw is not a good idea. Because the main difference between args and parameters is that args are editable in the control addon. The handlers of msw are functions. So there is no real benefit of moving them from parameter to args.

The proposed API (single test accepting parameters.todos) leads to smart tests. Those are the worst kind to work with. You don’t want to be smart in tests as a rule of thumb. Keep them explicit. From Storybook’s side, that means designing APIs that facilitate that explicitness rather that introduce implicit context (parameters) and test cases that are hard to read/toggle/debug/etc.

I think you have a good point as it comes to test. Especially parametrizing act and assertions. As you want to easily see what the test is actually testing, and not abstract that awy.

I wonder though, if the same is true for stories? In some sense, args are really parametrizing a story. And it is powerful, as you can use the control panel in storybook to get into different states of the component interactively. But what if for some reasons your data doesn't live in props, but is part of the network?

Shouldn't you be able to change that network data in your control panel interactively?
When non-component args land, you can do that with beforeEach or in play:

const meta = config.meta<{ args: { $todos: Todo[] } }>({
  component: TodoList,
  beforeEach() => {
    msw.use(
      http.get('/todos', () => new HttpResponse(args.$todos)
    )
  })
});

export const EmptyTodos = meta.story({ args: { $todos: [] } });
export const OneTodo = meta.story({ args: { $todos: [{ description: "first todo" }] } });
export const ManyTodos = meta.story({ args: { 
  $todos: [{ description: "first todo" }, { description: "second todo" }] } 
});

Notice that this is a regular test suite in Jest or Vitest. Storybook’s value here is giving me a preconfigured component state and a render() function to render that component in the browser (please use Vitest’s Browser Mode).

In some sense, what you want is already the case. In our new experimental test addon, we automatically transform any story into a vitest test that is run by vitest browser mode. Even the vitest vscode extension works for stories.
https://storybook.js.org/docs/writing-tests/test-addon
https://www.youtube.com/watch?v=8t5wxrFpCQY

Also all our test helpers such spyOn, fn, expect that you can import from @storybook/test are coming from vitest. So they all have the same implementation/API.

It is also possible to write them in a separate vitest/jest file using portable stories:
https://storybook.js.org/docs/api/portable-stories/portable-stories-vitest
Note that this API already exists.

From what I read, the play() function stands for a single test case associated with the story. In practice, that will not be enough, as UI components (let alone pages) often encompass multiple different behaviors. Putting them all into a single play() function will lead to a verbose test that won’t have much use.

This is a good point. The pattern that most test-oriented storybook users use today is this:

export const AddLabelForm: Story = {
  args: {...}
};

export const SubmittingInvalidLabelShowsInlineError: Story = {
  ...AddLabelForm,
  async play() { 
    await canvas.getByText('Label :').type('invalid label').submit();
    await canvas.getByRole('button').click();
  }
})

export const AutocompletionSuggestionsAreShownWhenTyping: Story = {
  ...AddLabelForm,
  async play() { ... }
})

export const SubmittingCorrectLabelClosesTheModal: Story = {
  ...AddLabelForm,
  async play() { ... }
})

But it is indeed not immediately obvious from the API that this is the best-practice.
Also writing specs in PascalCase is rather awkward.

In the new RFC I will propose the following API, which is very close to your proposal (!) except that you will write the tests in the same file.

export const AddLabelForm = meta.story({
  // in most cases, you will just use args/parameters
  args: { labels: [] },

  // in other cases you might want to use full flexibility with `play`
  // for example, to open a modal/dropdown
  // or to pass args to msw
  async play({ args, mount }) {
    // arrange
    // you can also just use msw.parameters for this
    msw.use(
      http.get('/labels', () => new HttpResponse([...])
    )
    const { getByText } = await mount();
    await getByText('Add label').click();
  },
});

AddLabelForm.test('submitting invalid label shows inline error', async ({ canvas }) => {
  // act/ assert
  // canvas object can still be used
  await canvas.getByText('Label :').type('invalid label').submit();
  await canvas.getByRole('button').click();
});

AddLabelForm.test('autocompletion suggestions are shown when typing', async ({ canvas }) => {
  //
});

AddLabelForm.test('submitting correct label closes the modal', async ({ canvas }) => {
  //
});

In this way, the test stories won't clutter the story sidebar, which is problematic when Storybook is used primarily for documentation. It is probably a good idea to split the story and test concept in a storybook. Both UI wise and API wise. Thanks for your suggestion Artem.

[kettanaito]

I wonder though, if the same is true for stories?

I think some stories can be parametric as some components are parametric (unless I'm misunderstanding args). That's not the case for tests.

Shouldn't you be able to change that network data in your control panel interactively?

We are crossing workflows here. You are talking about tweaking the story, my comment was concerning parametric tests. You can certainly tweak the network responses in the UI, but for the automated test I highly recommend making those as streamlined and simple as possible, even if that means repetition sometimes (repetition isn't inherently bad).

Note that this API already exists.

This is neat!

Also writing specs in PascalCase is rather awkward.

👍 to all of the above.

In the new RFC I will propose the following API, which is very close to your proposal (!) except that you will write the tests in the same file.

This one looks good.

Storybook is used primarily for documentation. It is probably a good idea to split the story and test concept in a storybook.

Hard agree.

I think you can strike gold utilizing Storybook for the setup phase, and leaning as much as you can into raw Vitest tests, just as we discussed. Excited about the direction here!