[RFC]: Add the .test method to CSF factories

[kasperpeulen]

Note

This is now available experimentally in Storybook 10 pre-releases for React-based frameworks, when you enable it via the experimentalTestSyntax feature flag.

We have adapted this RFC to reflect the current state of the feature and serve as an API reference and usage guide.

ℹ️ Why we're proposing this

We've learned over the years that many teams use or want to use Storybook to test their components. That's why we've built interaction testing, the test runner, and our Vitest addon.

We've also learned that learning a new testing API can be a barrier to adoption. Many teams are already familiar with tools like Vitest and Jest, and would prefer to use similar syntax when writing tests in Storybook.

At the same time, there's a competing concern about cluttering the Storybook sidebar with too many stories. If every test case is a separate story, it can quickly become overwhelming and hard to navigate.

That's why we're proposing to add the .test method to CSF Factories, which allows you to write tests using a syntax more similar to traditional testing tools (while still sharing most of its API with the play function) and presents them in a way that reduces clutter in the sidebar.

This approach has several benefits:

• Familiarity: Developers can use a syntax they are already familiar with, reducing the learning curve and making it easier to adopt Storybook for testing.
• Ergonomics: Test names are written as strings, making them easier to read and understand than a story's PascalCase name.
• Organization: Tests are nested under their parent story in the sidebar, reducing clutter for documentation-focused users while still being easily accessible for those who need them.

---

📺 Prefer video? We just hosted a webinar covering both CSF Factories and the .test method.

What is it?

The .test method is a new addition to the Component Story Format (CSF) Factories. It allows you to define test cases for your stories directly within the story file, using a syntax more similar to traditional testing tools like Vitest or Jest.

Here's an example stories file using CSF Factories, which defines a test with the .test method:

// Button.stories.ts
import preview from '../.storybook/preview';

import { Button } from './Button';

// 👇 CSF Factories: Fully type-safe, with no type assignment!
const meta = preview.meta({ component: Button });

// 👇 CSF Factories: Fully type-safe, with no type assignment!
export const Primary = meta.story({ args: { primary: true } });

// 👇 CSF Factories: Easily extend another story
export const Disabled = Primary.extend({ args: { disabled: true } });

// 🆕 .test method: Attach tests to a story!
//    The test function can run the same code as the play function
Disabled.test('should be disabled', async ({ canvas, userEvent, args }) => {
  const button = await canvas.findByRole('button');
  await userEvent.click(button);

  await expect(button).toBeDisabled();
  await expect(args.onClick).not.toHaveBeenCalled();
});

Tip

Need more details on CSF Factories? Check the docs!

Importantly, tests have different presentation than stories in the Storybook UI:

• In the sidebar, tests are nested under their parent story and collapsed by default.
  • They can also be easily hidden using the filter menu, allowing you to focus on just the stories when needed.
• Tests are excluded from autodocs.

Here's how the above is shown in Storybook's UI, after the Disabled story's tests have been expanded:

Get started

Tip

Just want to give it a quick spin? You can try it out here:

• Demo repo
• Live demo on StackBlitz (keep in mind that running tests via Storybook UI is not supported in Stackblitz environments)

To use the .test method in your project:

1. Upgrade to the latest Storybook pre-release:

   npx storybook@next upgrade

2. Run the automigration to convert your stories to use the new CSF Factories format:

   npx storybook@next automigrate csf-factories

   When you run this command, you will be prompted with two choices.

   First, you can choose to use relative imports (recommended) or absolute imports within your story files.

   Second, you will prompted for a glob pattern to match the story files that you want to convert. We strongly recommend first running the command with a pattern that matches only a few files, to verify that the conversion works as expected. Once you are happy with the results, you can run the command again with a broader pattern to convert all your stories.

   After answering, the automigration will update your .storybook/preview.js|ts, .storybook/main.js|ts, and requested story files to use the new CSF Factories format. Please see the CSF Factories documentation for more details.

3. Enable the experimentalTestSyntax feature flag in your main.ts:

   // .storybook/main.ts
   // Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite)
   import { defineMain } from '@storybook/your-framework/node';
   
   export default defineMain({
     //...
     features: {
       experimentalTestSyntax: true,
     },
   });

4. You can now add tests to your stories using the .test method, which we'll cover in the next section. When you do, they'll appear in the sidebar, nested under their parent story.

Writing tests

The .test method is called on a story, and takes two (or three) arguments: a name for the test and an async function that contains the test code. The test function receives a context object, which includes the same properties as the play function context, such as canvas, userEvent, args, and step.

// Button.stories.ts
import preview from '../.storybook/preview';

import { Button } from './Button';

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

export const Disabled = meta.story({ args: { disabled: true } });

// 🆕 .test method: Attach tests to a story!
//    The test function can run the same code as the play function
Disabled.test('should be disabled', async ({ canvas, userEvent, args }) => {
  const button = await canvas.findByRole('button');
  await userEvent.click(button);

  await expect(button).toBeDisabled();
  await expect(args.onClick).not.toHaveBeenCalled();
});

A few things to note:

• Because tests don't need to be exported, they don't need an export name, just a string identifier. This makes them more ergonomic than stories for writing descriptive test names.
• Because the callback function uses the exact same API as the play function, all of our guidance on interaction testing also applies. That includes querying for elements, assertions, beforeEach, steps, etc. If/when the .test method becomes stable, that documentation will be updated to reflect both APIs.

When to write a test

Tests can be used to verify just about any aspect of a component, e.g. visual appearance, interactivity, or accessibility. However, they are particularly well suited for testing non-visual logic and behavior, such as:

• Ensuring that a button is disabled when it should be
• Verifying proper keyboard navigation
• Checking that an input validates various text correctly

When to write a test vs. a story

Let's look more closely at the last example above, because it can help illustrate when to write a test vs. a story.

Imagine we have an email input component, and we want to ensure that it correctly validates email addresses. We can create stories for some known valid and invalid email addresses, which we can visually test to ensure their appearance. That covers the basic cases.

But there are multiple paths that we also need to verify to have full coverage of our invalidation logic. Each of these paths all produce similar visual results and aren't useful as examples to learn from, so we don't need separate stories for each one. Doing so wouldn't provide helpful documentation for our teammates and would likely be considered noise in our sidebar.

Instead, we can write tests to cover these cases. Because they're nested under the parent story, they don't clutter the sidebar, but are still easily accessed when we need them.

In general, if the result of your story or test serves as documentation or can be referenced as an example, it should be a story. If it is purely for verification and doesn't add to the documentation value of your component, it should be a test.

When to write a test vs. a play function

Everything tested in play function can be done in a test instead. However, that doesn’t mean you should remove or stop using all of your play functions. They are still useful for placing your components in a usable state (e.g. opening a select menu).

Stories with play functions can also be combined with tests. You could have a story for a Select component which defines the args and a play function that opens the menu. And that story could have tests to verify that the correct menu items are displayed.

Although test and play are in many ways interchangeable, the big difference is how they appear in the sidebar: tests are nested under stories and hidden by default (they're also hidden entirely from documentation). That means that choosing between test and play comes down to the non-testing aspects: Will the example be useful as documentation? Do you think you'll reference it with colleagues? Then choose a play function. Otherwise, choose a test.

In other words, for teams choosing to use tests in their project, we believe the most typical usage will break down something like this:

Example purpose	API to use
Purely development or documentation	Story, possibly with a play function (which can still be tested)
Both documentation and testing	Story, likely with a play function
Purely testing	Test

Using tests

Tests can, of course, be tested with the Vitest addon, either in the Storybook UI with the test widget or in your CLI/CI.

They also integrate with Storybook 10's improved sidebar filtering. Once you have a test in your project, you will see a new Testing item in your filter menu:

You can choose to include tests, which will filter the sidebar to only show tests. Or you can exclude them, which hides them from the sidebar. By default, neither selection is made, but this behavior can be configured (see the "Exclude all tests from the sidebar" technique, below).

Advanced techniques

Overwriting annotations in a test

If you’re writing a test against a story and need to adjust the context (tags, parameters, etc.), you can do so by passing a context object (the same shape as the context argument for meta.story()) as the second argument, in between the name and callback function:

// Button.stories.ts
import preview from '../.storybook/preview';

import { Button } from './Button';

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

export const Disabled = meta.story({
  args: {
    disabled: true,
  },
});

// 👇 You can also provide specific overrides for a particular test.
Disabled.test(
  'should be disabled on a particular page',
  { parameters: { route: '/xyz' } },
  async ({ canvas, userEvent, args }) => {
    const button = await canvas.findByRole('button');
    await userEvent.click(button);

    await expect(button).toBeDisabled();
    await expect(args.onClick).not.toHaveBeenCalled();
  }
);

Reusing test logic

You can reuse logic between multiple tests by extracting it into a function and calling it within each test:

// Button.stories.ts
import preview from '../.storybook/preview';
import { fn } from 'storybook/test';

import { Button } from './Button';

const meta = preview.meta({
  component: Button,
  args: {
    onClick: fn,
  },
});

// 👇 Reusable function to find and click a button
//    Note that it accepts the full context argument from the test callback function
async function clickButton(context: StoryContext<React.ComponentProps<typeof Button>>) {
  const { canvas, userEvent } = context;
  const button = await canvas.findByRole('button');
  await userEvent.click(button);
}

export const Basic = meta.story();

Basic.test('should be clickable', async (context) => {
  const { args } = context;
  // 👇 Reuse the clickButton function
  const button = await clickButton(context);

  await expect(button).toBeEnabled();
  await expect(args.onClick).toHaveBeenCalled();
});

export const Disabled = meta.story({
  args: {
    disabled: true,
  },
});

Disabled.test('should be disabled', async (context) => {
  const { args } = context;
  // 👇 Reuse the clickButton function
  const button = await clickButton(context);

  await expect(button).toBeDisabled();
  await expect(args.onClick).not.toHaveBeenCalled();
});

Exclude all tests from the sidebar

By default, tests are nested and collapsed under their stories. But you can also filter them out entirely, so that they're only visible by deselecting the filter in the menu. To do this, configure the built-in _test tag, which is automatically applied to all tests.

You can make this conditional, e.g. dependent on an environment variable to only filter them out in the published Storybook.

// .storybook/main.ts
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite.
import { defineMain } from '@storybook/your-framework';

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  tags: {
    // 👇 Adjust the default configuration of the tag applied to all tests
    _test: {
      defaultFilterSelection: process.env.PUBLISHED ? 'exclude' : undefined,
    },
  },
});

Proposed future work

All of the above is available today, in Storybook 10. The following work is being considered for future releases:

Sharing data

We can share data between the story and the test in a typesafe way.

One possible API would be to return that data from the story's play function, and receive it as part of the test's callback context:

export const LabelForm = meta.story({
  async play({ mount, canvas }) {
    const label = await db.labels.create({
      data: {
        title: 'Some label',
        createdBy: 'storybookjs',
      },
    });
    await mount(<AddLabelForm id={label.id} />);
    return { label };
  },
});

LabelForm.test('submitting invalid label shows inline error', async ({ label }) => {
  await userEvent.click(canvas.getByText(label.title));
});

Requested feedback

Thanks for considering this proposal! We'd love to know any thoughts or suggestions you have, particularly:

• How does the .test syntax feel?
• If you use play functions today, would you be likely to switch to .test? Even if only for new test cases?
• Does the sidebar hierarchy feel right? Is it useful to you in practice?
• Does the sidebar filtering meet your needs?

And finally, a reminder that you do not need to use .test (which is still experimental) to use CSF Factories (which is part of CSF Next, currently in preview, the stage before stable). So if you migrated your stories to use CSF Factories as part of evaluating this RFC, you should keep that part!

[DEfusion]

This looks great and is better than what I was imagining when commenting on #22361

I love that you've put tons of thought into this especially things like them not cluttering the sidebar until you open the parent story, just come up with an awesome icon for them 😄

[Sasza666]

Agree with it

[Sidnioulz]

A derivative of the AAA pattern consists of writing data suites for tests, and then running tests on each item of a data suite.

How could we do that with stories acting as test data? Could I bundle together a bunch of stories (e.g. different variants of a button) and check they all satisfy a behaviour (e.g. all become aria-disabled once clicked and until the click handler returns, or all contain an aria-label and role button)?

I don't know how this should be written so here are a bunch of proposals in no particular order and to which I have no particular attachment, just for the sake of triggering conversation.

// meta providing an each method?
meta
  .each([Primary, Secondary, Tertiary, Frogginary])
  .test('prevent double-submit by setting aria-disabled while the handler is running for variant %s', () => {
  // act
  // assert
})

// With a test global?
test
  .each([Primary, Secondary, Tertiary, Frogginary])
  ('prevent double-submit by setting aria-disabled while the handler is running for variant %s', () => {
  // implicit arrange?
  // act
  // assert
})

// If there is a test global, does it enable other syntax formats, e.g.
test('prevent double-submit by setting aria-disabled while the handler is running', () => {
  arrange(Primary); // or render(Primary), etc. naming here indicates purpose and is not an actual suggestion
  // act
  // assert
})

// Leading to an explicit handling of arrange in test.each?
test
  .each([Primary, Secondary, Tertiary, Frogginary])
  ('prevent double-submit by setting aria-disabled while the handler is running for variant %s', (story) => {
  arrange(story);
  // act
  // assert
})

[shilman]

On a related note we're considering bringing modes to Storybook

https://www.chromatic.com/docs/modes/

[Sidnioulz]

So you did tell me about modes! I missed that message!

On the naming: I feel modes is a fantastic name for that. It aligns with the vocabulary that Figma uses for contextual information that informs the values of Figma variables, and I think that's great news for DS folks.

I feel like modes and stories-as-data-suites are two distinct concepts that can be combined. If I went back to the OG RFC syntax and wanted to loop over my data, because my data is the object that provides the test method, I'd have an unusual syntax:

[Primary, Secondary, Tertiary, Frogginary].forEach(
  (story) => story.test(
    // Note the need to name / uniquely identify stories, I don't know if this has been discussed yet?
    `prevent double-submit by setting aria-disabled while the handler is running for variant ${story.name}`,
    () => {
      // act and assert, assuming arrange is done by the story
    }
  )
)

But this opens up a possibility for stories themselves to have an each method that takes modes as parameters.

const modes = ["light mobile", "dark mobile", "light desktop", "dark desktop"]

[Primary, Secondary, Tertiary, Frogginary].forEach(
  (story) => story.each(modes).test(
    `prevent double-submit by setting aria-disabled while the handler is running for variant ${story.name} and modes %s`,
    (modes) => {
      // now we probably need an explicit arrange where we pass the modes
      // act and assert
    }
  )
)

Of course you could create an eachMode method that hides away all the mode arranging and test duplication/naming, or any other such mechanism.

That begs the question whether end users need to be able to disable modes for a story's tests. If so, can that be done by defining modes on the story and having the test routine pick that up automatically ? If so, then all the conversation about providing API for explicit mode targeting is moot, isn't it?

[danceroutine]

This would be a dream come true, I wholeheartedly approve of this proposal.

The tiniest bit of feedback would be perhaps we can try to visually distinguish the tests in the sidebar when expanded so that they're more obviously "this is a test rather than a traditional story", that would be great since we also use Storybook for non-technical folks to be able to explore the current state of the application development.

Perhaps something like replacing the bookmark with a small "T" or "Test" (space depending) in some kind of badge styling?

[Sidnioulz]

@shilman do you provide tags for these test stories? I could augment https://github.com/Sidnioulz/storybook-addon-tag-badges's default config to display the badges already, if so.

[shilman]

Since .test will be a core feature we'll re-design the sidebar around it. It will probably show up with a different icon at the very least and we might even handle its interactions differently such as making it easy to hide/show all tests as a first class interaction

[domyen]

Do Storybook features like tags and parameters apply to these tests?

[shilman]

Yes. Under the hood a test would be very similar to a story and I believe we'll make it possible to configure tags/parameters/etc as an optional second argument to the test method.

[samsamit]

This looks awesome! This system could also benefit the ability to provide afterEach, beforeEach, ie. for tests in global or local scope. When Vitest is already being used under the hood implementing more vitest functionalities in this .test method would provide more usecases for this and might make writing Vitest tests unessessary in the future.

[Sidnioulz]

There is another RFC for afterEach: #29583

[MarceloPrado]

I love this! We've having similar organizational challenges here at Brex with the current approach. Having a clear separation between what's interaction testing and what's meant as documentation/snapshot testing would be awesome

[scottrippey]

Excellent proposal. I love the syntax, and love the idea of using play to arrange.

I do have a suggestion for the UI. IMO, the sidebar is not the right place to show these tests. Each storybook "tells a story" and the sidebar is how we navigate that story.
The tests are not a part of that story. They're just an implementation detail. Almost like documentation about the behavior.

So I would suggest these tests belong in the bottom "Component Tests" panel. It currently shows the steps of the current test. Imagine if this panel was split, and the left side was the list of tests. You select one from the list and watch it run.

[mpiroc]

Hi, I mentioned this feedback in yesterday's Storybook 9 webinar and was asked to share it here:

I use BDD-style (i.e. nested describes and its) organization for all of my tests. If Storybook only supports flat test suites (i.e. just a list of tests), I won't migrate my existing component tests to Storybook after this RFC is implemented.

With this RFC, I would like to be able to use all of vitest's organization features, including nested describes and its.

[shilman]

Thanks for sharing @mpiroc. I have questions!

Storybook already has an organization system that produces the hierarchical structure in its sidebar. If we were to generate Vitst tests that with the same structure would that be sufficient? If not, what's the biggest thing missing?

If we were to add a describe-style construct to organize your tests underneath a component, would that satisfy your needs?

[kettanaito]

Given the test-related hierarchy with describe and its potential visual clash with the rest of the items in the story tree, I would strongly suggest to consider displaying test suites and test cases in a separate view. Something like a "Tests" tab, perhaps?

In the end, tests aren't stories and it would be great to be able to view all the tests reflecting the user's describe/it/test nesting in the UI (and get inspired from Playwright with the "Go to test" button that opens respective test cases in your IDE!).

This UI is simply more future-proof, allowing you to build better experienced on it with time, like re-running a subset of tests, for example, from Storybook directly.

[kettanaito]

We've also had a great discussion with @MichaelArestad about the best way to present the testing information to the user. I still believe that a separate tab would be the best way forward. Storybook has quite a lot of horizontal real estate, which can be used to a great effect to display test steps, reference the source code, have rich actions next to the test cases (re-run, go to source, etc).

I also suggest outlining the user stories first. When would a Storybook user reach out to a test? When would they want to find one? Are they exploring a new code base, did they come from a failed CI—what do they wish to do at this moment? The answers to all of those will help shape the UI to serve the users better.

[Stadly]

This is grand! What is the status? Is there a branch or (draft) PR to look at?

[shilman]

Prototype here #31551

[lifeiscontent]

@shilman might be worth doing something like this via test.extend, you could probably model the same APIs where extend here would be able to allow you to have typed contexts for the test, and potentially use it to setup the metadata for storybook.

https://vitest.dev/guide/test-context.html#test-extend

[shilman]

This something that @kasperpeulen has explored. I don't know where we landed with that though.

[yannbf]

Hey everyone! Thank you so much for your comments and thoughts. While we can still add comments in this RFC, I'd like to invite you all to a new channel in our discord, #sb-test-early-access.

We will be implementing this RFC and would like to soon provide you canary versions with some prototypes for early feedback. We'd also like to hear more about your motivations, needs, etc, so we can note them down to consider. Please join and share your thoughts!

Pinging you all of you who have shown interest ❤️
@alextompkins @Blitz2145 @Catchpowle @DEfusion @gurobokum @honey32 @IntusFacultas @k1tikurisu @lifeiscontent @lishaduck @lukasjelonek @MarceloPrado @mikegreiling @mishaberezin @mmirus @mpiroc @noah-potter @nus3 @Parkreiner @pdemarino @philwolstenholme @rajeshshou @samsamit @scottrippey @Sidnioulz @skinread @Stadly @tommy-mitchell

[Stadly]

Nice! I just get this when visiting the link:

[yannbf]

If you're not part of our discord yet, you can join by clicking here! Then the channel should be available.

[yannbf]

Hey there! We just posted instructions on discord on how to try out our first canary release that includes the test syntax work. Please check it out!

[yannbf]

Hey everyone! Sorry again for the ping (last time, I promise!), but it's quite important that we gather feedback while we are developing the feature!
We already have a prerelease (based on Storybook 9) that contains the work, and we'd really appreciate if you tried it out and filled a small form to share your experience.

Check out the proposal here, and the feedback form at the bottom.

Thank you so so much 🙏

@cabbiepete @alextompkins @Blitz2145 @Catchpowle @DEfusion @gurobokum @honey32 @IntusFacultas @k1tikurisu @lifeiscontent @lishaduck @lukasjelonek @MarceloPrado @mikegreiling @mishaberezin @mmirus @mpiroc @noah-potter @nus3 @Parkreiner @pdemarino @philwolstenholme @rajeshshou @samsamit @scottrippey @Sidnioulz @skinread @Stadly @tommy-mitchell

[DEfusion]

Thanks for the poke, love the changes, had a problem getting them running as mentioned in the feedback form but I will definitely be changing a lot of our play functions to this and implementing a couple of tests that we've held back on as they weren't great with play function.

[lishaduck]

Are there any plans to support Svelte CSF?

[shilman]

I believe there's a proposal somewhere. @JReinhold can you please share?

[JReinhold]

@shilman its not public yet, as we haven't aligned on it within the team yet.

[Sasza666]

LFG, I think

[purecopy]

Are there any plans to allow separating tests from the story files? In general, I love the idea of getting visual feedback for my tests in Storybook, but I think mixing stories with tests might bloat the story files. Perhaps the solution is bringing tests based on portable stories from .test files into the Storybook UI?

[thobas-dnvgl]

I've started using .test() and I like it so far. https://github.com/storybookjs/storybook/blob/next/code/lib/eslint-plugin/docs/rules/await-interactions.md will need to be adapted to catch missing await in there too.

[sparta-dan]

what version is this on? can't seem to get it to work on 10.1.2