Storybook · Writing and testing · all subjects

play functions & interactions

10 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Import test utilities from storybook/test not @storybook/test

In Storybook 9, import test utilities like fn from 'storybook/test' instead of '@storybook/test'. Update imports from `import { fn } from '@storybook/test'` to `import { fn } from 'storybook/test'`.

Play function parameters: canvas and canvasElement

The play function receives parameters including `canvas` which has query methods similar to testing-library, and `canvasElement` which is the actual DOM element. The `canvas` parameter already has query methods built-in, so do not wrap it with `within()`. Use `canvas` directly for queries like `canvas.getByLabelText('Submit').click()`.

Do not use within(canvas) in play functions

Do not use `within(canvas)` in play functions because `canvas` already has query methods built-in. Using `within(canvas)` is redundant and incorrect. Either use `canvas` directly with query methods, or use `within(canvasElement)` where canvasElement is the actual DOM element.

Transform canvasElement to canvas using within

If working with `canvasElement` instead of `canvas`, use the `within` function imported from 'storybook/test' to transform it: `const canvas = within(canvasElement)`. This gives you an object with query methods like `canvas.getByLabelText()`.

Verify mocked callback functions were called with assertions in play functions

When passing `fn` functions as `args` for callback functions, add a play function that interacts with the component and use assertions to verify the callback was called. Use `await expect(library).toHaveBeenCalled()` to assert the mock was invoked during the interaction.

Add interaction tests with play functions for interactive components

For interactive components, add interaction tests using play functions that drive the UI with storybook/test utilities like fn, userEvent, and expect. Simulate key user flows: clicking buttons/links, typing, focus/blur, keyboard navigation, form submission, async responses, toggle/selection changes, pagination/filters, etc.

Assert visible outcomes in play function assertions

In play function assertions, assert the visible outcome of the interaction such as text changes, aria state, enabled/disabled status, class/state changes, and emitted events. Prefer role/label-based queries over other selector types.

Pass full context when invoking play function from another story

When invoking the play function from another story, you must pass the full context as an argument. The context that Storybook provides to the play function contains internal functionality necessary for interactions to work correctly. Do not pass just the canvasElement or omit context entirely.

Correct pattern for calling play function from another story

When calling another story's play function from within a play function, pass the full context object: await MyOtherStory.play(context). Alternatively, if destructuring context in the function signature, you can pass the context property: await MyOtherStory.play(context).

Incorrect patterns for invoking play functions

Do not invoke another story's play function without passing context: await MyOtherStory.play(). Also do not pass only the canvasElement: await MyOtherStory.play({ canvasElement }). Both patterns lack the internal functionality needed for interactions to work correctly.

Give your agent this brain