[RFC] Allow play to mount the component of the story

[kasperpeulen]

Mount in play itself

In our effort to make Storybook as suitable as possible for UI unit testing, we started to realise that the current play semantics might be too constraining.

At the moment you might write a play function like this:

export const FilledForm: Story = {
  play: async ({ canvasElement }) => {
    const canvas = within(canvasElement);

    await userEvent.type(canvas.getByLabelText('Name:'));
    await userEvent.type(canvas.getByLabelText('Password:'));
    await userEvent.click(canvas.getByRole('button'));

    // Or instead make a visual snapshot
    await expect(
      canvas.getByText(
        'Everything is perfect. Your account is ready and we should probably get you started!',
      ),
    ).toBeInTheDocument();
  },
};

Now, let’s imagine that a user could instead write it like this:

export const FilledForm: Story = {
  play: async ({ mount }) => {  
    const canvas = await mount(<Form some='prop' />);
    // or just, if you filled in the component and args already
    const canvas = await mount();

    await userEvent.type(canvas.getByTestId('email'), '[email protected]');
    await userEvent.type(canvas.getByTestId('password'), 'a-random-password');
    await userEvent.click(canvas.getByRole('button'));

    await expect(
      canvas.getByText(
        'Everything is perfect. Your account is ready and we should probably get you started!',
      ),
    ).toBeInTheDocument();
  },
};

This could be seen as strictly better for several reasons:

• It is way more powerful, e.g. you can now do stuff before render
• It is very familiar to how people write unit tests with testing-library
• const canvas = await mount() is actually also a bit shorter than const canvas = within(canvasElement)

How to avoid making this a breaking change?

Introducing this new semantic to the play function (being able to mount itself), while not breaking existing users, is not easy, but we think possible.

We need to detect if the user wants to mount, so that storybook doesn’t mount before the play function starts. For that, we can use a similar trick that playwright and Vitest use in their fixture API:
https://playwright.dev/docs/test-fixtures
Both testing frameworks analyse the dependencies of a fixture or a test function by inspecting which arguments are destructured by inspecting fn.toString().

For example, in the above example, fn.toString() prints the following

> FilledForm.play.toString()
"async ({ mount }) => {\n    const canvas = await mount();\n\n    await userEvent.type(canvas.getByTestId('email'), '[email protected]');\n    await userEvent.type(canvas.getByTestId('password'), 'a-random-password');\n    await userEvent.click(canvas.getByRole('button'));\n\n    await expect(\n      canvas.getByText(\n        'Everything is perfect. Your account is ready and we should probably get you started!',\n      ),\n    ).toBeInTheDocument();\n  }"

This is a bit magical, but this allows us to introduce this change, with the following caveat:

If you want to mount inside of the play function, you must destructure mount from the story context.

In the future we might introduce fixtures ourselves as well, which would make this caveat possibly less controversial.

One downside of this is that it makes it harder to reuse play functions. We want to solve this by making the whole context itself also available on the context (self-referencing).

const Story = {
  async play({ canvasElement, args }) => {
    // whatever
  },
}

const AnotherStory = {
  async play({ mount, context }) {
    await mount();
    await Story.play(context);
  },
}

Comparison with a testing-library based unit test

One benefit of this change would be that it is super straight-forward to move a testing-library+ JSDOM based unit test to storybook.

In general, the semantics of the play function now gives you full control of the whole test execution.

test('renders a message', () => {
  // Note that we could recommend the exact same destructuring
  const { getByText } = await render(<Greeting />)
  expect(getByText('Hello, world!')).toBeInTheDocument()
})

// would become:
const RendersMessage = {
  async play({ mount }) {
    const { getByText } = await mount(<Greeting />)
    await expect(getByText('Hello, world!')).toBeInTheDocument()
  }
}
// and later refactored to:
export default { component: Greeting };
const RendersMessage = {
  async play({ mount }) {
    const { getByText } = await mount()
    await expect(getByText('Hello, world!')).toBeInTheDocument()
  }
}

We note that the refactoring in the third example would give user many of the benefits of using Storybook:

• docgen
• interactive controls
• source snippets
• etc.

But it is optional. User can also get lots of benefits from Storybook if they don’t do the refactor:

• Visual testing (manual in storybook or automatic with the visual test addon)
• Visual debugging
• Share-ability of the storybook

Allows for fewer hooks to be used for a single test

Some people might prefer doing everything in play in favor of using a separate CSF construct such as args, loaders, beforeEach, decorators, and render.

I think the strongest point of this proposal is that users don’t necessarily need any of those. You can still use them and they are powerful abstraction mechanisms that are great, but the user is not forced.

For example, instead of using beforeEach, you can just do:

const AddLabelWhenFormIsSubmitted = {
  async play({ mount }) {
    // setup mocks, can be placed in beforeEach, if shared between stories
    // but can also be placed in the play function directly!
    msw.use(githubAuthHandler);
    MockDate.set('2000-11-22');
    getAllLabels.mockResolvedValue(['existing label']);
    const addLabel = spyOn(API, "addLabel");

    // act
    const canvas = await mount(<Form some='prop' />);
    // or, if you filled in the component and args already, just:
    const canvas = await mount();

    // open the modal, fill in the form etc.
    await userEvent.click(canvas.getByText('Add label'))

    // assert some stuff, or just take an automatic visual snapshot with the visual test addon!
    await expect(addLabel).toHaveBeenCalled();
  },
}

If you have a story that needs async data, you don’t need to learn about the loaders API:

export const Primary = {
  loaders: [
    async () => ({
      user: await db.user.create({ name: 'Kasper' }),
    }),
  ],
  render: (args, { loaded: { user } }) => <Page {...args} params={{id: user.id}} />,
};

Not using any abstraction here, is shorter, more typesafe and easier to read:

export const Primary = {
  async play({ mount, args } ) {
    const user = await db.user.create({ name: 'Kasper' })
    await mount(<Page {...args} params={{ id: user.id }} />);
  }
};

Reuse the play function for different stories

That being said, we think that there are still many use cases, where the inheritance model of CSF makes a lot of sense. For example, you might want to set up a play function in your meta, and use that with a bunch of different UI.

const meta = {
  async play({ mount } ) {;
    MockDate.set('2000-11-22');

    // This will mount whatever element defined in the story below
    const canvas = await mount();
    await canvas.getByRole('dropdown').click();

    // assert some stuff, or just take an automatic visual snapshot with the visual test addon
  },
}

export const Checkboxes = () => (
  <DropdownMenu>
    <DropdownMenuTrigger>Open</DropdownMenuTrigger>
    <DropdownMenuContent>
      <DropdownMenuLabel>My Account</DropdownMenuLabel>
      <DropdownMenuSeparator />
      <DropdownMenuItem>Profile</DropdownMenuItem>
      <DropdownMenuItem>Billing</DropdownMenuItem>
      <DropdownMenuItem>Team</DropdownMenuItem>
      <DropdownMenuItem>Subscription</DropdownMenuItem>
    </DropdownMenuContent>
  </DropdownMenu>
);

export function Advanced() {
  return (
    <DropdownMenu>
      <DropdownMenuTrigger asChild>
        <Button variant="outline">Open</Button>
      </DropdownMenuTrigger>
      <DropdownMenuContent className="w-56">
        <DropdownMenuLabel>My Account</DropdownMenuLabel>
        <DropdownMenuSeparator />
        <DropdownMenuGroup>
          <DropdownMenuItem>
            <User className="mr-2 h-4 w-4" />
            <span>Profile</span>
            <DropdownMenuShortcut>⇧⌘P</DropdownMenuShortcut>
          </DropdownMenuItem>
          <DropdownMenuItem>
            <CreditCard className="mr-2 h-4 w-4" />
            <span>Billing</span>
            <DropdownMenuShortcut>⌘B</DropdownMenuShortcut>
          </DropdownMenuItem>
          <DropdownMenuItem>
            <Settings className="mr-2 h-4 w-4" />
            <span>Settings</span>
            <DropdownMenuShortcut>⌘S</DropdownMenuShortcut>
          </DropdownMenuItem>
          <DropdownMenuItem>
            <Keyboard className="mr-2 h-4 w-4" />
            <span>Keyboard shortcuts</span>
            <DropdownMenuShortcut>⌘K</DropdownMenuShortcut>
          </DropdownMenuItem>
        </DropdownMenuGroup>
        <DropdownMenuSeparator />
        <DropdownMenuItem>
          <Github className="mr-2 h-4 w-4" />
          <span>GitHub</span>
        </DropdownMenuItem>
        <DropdownMenuItem>
          <LifeBuoy className="mr-2 h-4 w-4" />
          <span>Support</span>
        </DropdownMenuItem>
        <DropdownMenuItem disabled>
          <Cloud className="mr-2 h-4 w-4" />
          <span>API</span>
        </DropdownMenuItem>
        <DropdownMenuSeparator />
        <DropdownMenuItem>
          <LogOut className="mr-2 h-4 w-4" />
          <span>Log out</span>
          <DropdownMenuShortcut>⇧⌘Q</DropdownMenuShortcut>
        </DropdownMenuItem>
      </DropdownMenuContent>
    </DropdownMenu>
  );
}

The API of mount

So what should the exact API of this mount function look like?

Arguments of mount

To make the API as familiar as possible and help people porting testing-library stories to storybook, we will make our mount API compatible with testing-library render function:

const ReactStory = {
  async play({ args }) {
    await mount(<Component {...args} />);
  },
};

const VueStory = {
  async play({ args }) {
    await mount({
      components: { Component },
      setup: () => ({ args }),
      template: '<Page v-bind="args" />',
    });
  },
};

const AngularStory = {
  async play({ args }) {
    await mount({
      props: args,
      template: `<storybook-page ${argsToTemplate(args)}>
        <my-checkbox [checked]="checked">Some Checkbox</my-checkbox>
      </storybook-page>`,
      declarations: [Page, CheckBoxComponent],
      imports: [CommonModule],
    });
  },
};

const SvelteStory = {
  async play({ args }) {
    await mount(Component, { props: args });
  },
};

For some renderers, testing-library has some extra features that we don’t plan to directly support. However, we can support a subset of those features of testing-library that easily map to properties that are already available, and can be returned from our existing render function.

Whatever is passed to mount will still be wrapped by storybook decorators. In some sense it is providing (or overriding) what you can now return from render in CSF with a slightly different syntax for some renderers.

Return type of mount

The return type of await mount() in testing-library is within(canvasElement) + some extra utils such as unmount and rerender.

But since testing-library/dom is heavy-dependency, we don’t want to always include it in storybook by default.

Therefore if @storybook/test is installed, the return type of mount will be within(canvasElement) and otherwise just be void. We have to investigate if this is possible with typescript.

We don’t plan to also directly support the extra utilities that testing-library returns (such as unmount and rerender).

How does this work with portable stories

Supporting a subset of the testing-library API in storybook, also unlocks an interesting opportunity for portable stories.

In storybook, you can use the composeStories API to reuse stories to run as a unit test:

import { composeStories } from '@storybook/react';
import { render } from '@testing-library/react';

import * as stories from './Button.stories';

const { Default } = composeStories(stories);

test('some-test', () => {
  render(<Default />);
});

However, this doesn’t run beforeEach and the play function that can be defined in a story. So we want to add the following API:

test('some-test', async () => {
  await Default.play({ mount: render })
});

If the mount API supports a subset of the testing-library features, this assignment just works, without any mapping. Of course, the user could also use another rendering library, which would mean it needs to do some manual mapping.

The user can set the mount definition once in portable stories using setPreviewAnnotations :

import { render } from '@testing-library/react';
import * as previewAnnotations from '../.storybook/preview';

setProjectAnnotations([previewAnnotations, { mount: render }]);

Configure mount

We could also allow people to configure mount themself in CSF, even outside of a portable story context.

Configure it with testing-library

For example we could allow someone to configure it using testing-library. This would allow users to use all the features of testing-library, and not only the subset that we can easily support ourself.

Especially with community renderers, but even for a renderer as angular, it would make it a lot easier to get feature parity with testing-library.

It is not completely straight-forward how to setup mount in storybook, while maintaining all storybook features, especially if it comes to reactivity. But it would probably look something like this:

// preview.ts
import { render } from '@testing-library/react';

const preview = {
  mount: ({ storyFn, forceRemount, canvasElement }) => {
    let mounted;   
    return (ui) => {
      if (!ui) ui = storyFn();
      if (!mounted || forceRemount) {
        mounted = render(ui, { container: canvasElement });
      } else {
        mounted.rerender(ui)
      }
      return mounted;
    };
  },
}

export default preview;

We could make this a recipe, or export some utilities to easily configure storybook to use testing-library for mounting.

Instead of this, we could also make a more general purpose API for users to add extra properties on the story context. And allow people to add or override existing context properties based on other context properties.

The playwright fixture API is doing this exactly:
https://playwright.dev/docs/test-fixtures
It has a couple of interesting features:

• add a new property to context
• be able to depend on other context properties
• automatically sort the order of execution fixtures based on the dependencies of the fixture
• lazily load the fixture in the test (can also be automatically loaded)
• allow some initialisation code and cleanup code in the definition of the fixture (similar as beforeEach/afterEach)

Configure it with another renderer

This feature was also requested before by Justin Fagnani:
https://x.com/justinfagnani/status/1542558568737452032
#20357

As there are many web-component flavours, and we now only support the LIT flavour. This would allow our web component framework be independent of Lit.

Another reason to support this feature, is that you may have multiple renderers in one storybook. Especially if you use web-components, it could be that you use Next/Sveltekit as a metaframework, but still use web components for your design system.

[andrejilderda]

The mount()-function seems very useful. Thanks for your work on this @kasperpeulen! However, I think it would be beneficial to add a third option for reusing the original Story inside the mount function. Currently, we have:

1. using the UI from the story by calling mount() without arguments or
2. provide a custom UI via mount(<div>...</div>).

A third option could be passing a function that receives the original Story’s UI, similar to how decorator functions work. Here’s an example:

  // ...
  play: async ({ mount }) => {
    const onChangeSpy = fn();

    // we pass a function here that receives the original Story's UI.
    await mount((Story) => (
      <Combobox.Root onChange={onChangeSpy}>
        <Story />
      </Combobox.Root>
    ));
  },
  // ...

As you can see in the example above this would make it possible to easily reuse the UI without having to repeat ourselves and assert on values defined in our test scenario.

This is particularly useful for stories of components that are composed out of multiple components, like headless components that are structured like so:

<Combobox.Root>
  <Combobox.Input />
  <Combobox.Options>
    <Combobox.Option {...}>
    <Combobox.Option {...}>
  </Combobox.Options>
</Combobox.Root

The example play-function outlined above would be applicable for Combobox.Input or Combobox.Option.

Curious to hear what you think of this idea. If I should add this suggestion somewhere else, please let me know.