Storybook .test Syntax in CSF

📖 Read the RFC for full details: Storybook .test RFC

We’ve started on an early prototype of the new Storybook test syntax. This allows you to define tests directly alongside your stories. The goal is to gather feedback quickly, so the prototype will have frequent updates.

Please try it out and 👉 **share your feedback here** 👈 as we release new canaries. Thank you!

What is this?

Storybook is evolving its CSF syntax and also including many testing features. In short, you are able to write tests in a more straightforward way, with strong type safety for your stories, and with test hooks available such as beforeEach and afterEach:

// Stories are now defined with factory functions, fully type safe
export const Disabled = meta.story({
  args: {
    disabled: true,
  },
  // hooks get applied to all child tests
  beforeEach: async () => {
    // you can define your spies and mocks
  },
  afterEach: async () => {
    // you can do cleanup (though spies are cleaned up automatically)
  },
})
// 👇 Now you can attach tests to a story! The test function can run the same
// code as the play function.
Disabled.test('should be disabled', async ({ canvas }) => {
  const button = await canvas.findByRole('button')
  await expect(button).toBeDisabled()
})

How to Try It Out

Keep in mind that this feature is currently only available for React based Storybooks, and it is built on top of Storybook 9 (soon Storybook 10!). We will actively work on bringing support for this feature for other renderers in the near future!

1. Live Demo

You can explore the syntax right away by:

👉 Checking out this GH repo

👉 Using the live demo on StackBlitz (keep in mind that running tests via Storybook UI is not supported in Stackblitz environments)

2. In Your Own Project

You can also try it locally in your project:

  1. Upgrade to the latest canary: npx [email protected] upgrade

  2. Migrate your Storybook to use the CSF Factory format. This is necessary as the base of the test syntax is the new CSF format. All the necessary changes are done automatically via the following codemod:

    npx storybook automigrate csf-factories

    Attention! The automigration will provide two sets of changes, which are important for CSF Factories to work:

    1. It will modify your .storybook/preview.ts and .storybook/main.ts files to use the new type safe utilities definePreview and defineMain.
      1. definePreview is a way to provide type safety when you're building stories. It's mainly a type wrapper over what you already had before. The only additional field in there is addons, which will load the addon annotations as well as provide autocompletion/type safety related to the addons you use (finally you will know the parameters without having to look them up!).
      2. defineMain is nothing more than a type wrapper, there are no new concepts there.

    image.png

    b. It will ask for a glob to match which stories you want to migrate to the CSF factories format. Provide just a single story or a minimal amount of story files so you can try this first. Later, you can rerun the same command and provide a broader glob which should change all of your files. This way you can focus minimally on the experience, and later provide the same experience for the rest of the codebase.

    image.png

Example Migration