You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Official API for extending the play function context (e.g. play: ({ canvas, helpers }) => …)
#37273
Is your feature request related to a problem? Please describe.
We maintain a large suite of Storybook interaction tests (Storybook 9.1, @storybook/addon-vitest). Many tests share project-specific helpers, such as grid or form interaction helpers, that need the story's canvasElement and the instrumented userEvent. Today each helper takes { canvasElement, userEvent } as an argument, or the test imports it and wires it up by hand.
We'd like to expose project helpers on the play context, so a story can write:
From reading the preview runtime, StoryRender builds one context object and passes the same object to loaders, then beforeEach, then play. Storybook itself assigns canvas and the instrumented userEvent onto it this way. A preview-level beforeEach can therefore add a property, and a module augmentation types it:
We verified a minimal version with addon-vitest: a plain button and list, injection via beforeEach, and the same via a withHelpers(play) wrapper. Both pass and typecheck. Three details we hit:
beforeEach has to be used, not loaders. Loaders in the same phase run in parallel, so context.userEvent may not exist yet.
beforeEach receives a StoryContext, which lacks the augmented property, so the hook has to be typed with StoryContext and assign it (e.g. via Object.assign).
Raw composedStory.play() builds a fresh context and copies only loaded, so the injected property is missing there. Only run() goes through the whole pipeline.
Describe alternatives you've considered
Instead of mutating the context, a wrapper builds the helpers and passes an extended context to the play function:
The wrapper needs no preview wiring and no global type augmentation. It also works with a raw composed story.play(). The costs are one wrapper call per story, and the injection is visible only where the wrapper is applied. We spiked both approaches and both pass under addon-vitest. We prefer the context approach for ergonomics, but it relies on undocumented behavior, which is why we're asking.
Are you able to assist to bring the feature to reality?
yes, I can
Additional context
Nothing in the docs describes extending the context. The beforeEach docs only cover setup and cleanup. PlayFunction and PlayFunctionContext are only exported from storybook/internal/csf. We found no existing discussion of this.
Questions
Is mutating the context in beforeEach intended to be supported, or an implementation detail that may change?
If it's an implementation detail, would the team consider a documented extension point, for example a context annotation in the preview, or typed ProjectAnnotations that extend the play context? Or is a wrapper like the one above the recommended pattern?
Should composed stories' play() (not just run()) apply beforeEach mutations to the context?
Happy to put together a PR or a minimal repro repo if that's useful.
reacted with thumbs up emoji reacted with thumbs down emoji reacted with laugh emoji reacted with hooray emoji reacted with confused emoji reacted with heart emoji reacted with rocket emoji reacted with eyes emoji
Uh oh!
There was an error while loading. Please reload this page.
Is your feature request related to a problem? Please describe.
We maintain a large suite of Storybook interaction tests (Storybook 9.1,
@storybook/addon-vitest). Many tests share project-specific helpers, such as grid or form interaction helpers, that need the story'scanvasElementand the instrumenteduserEvent. Today each helper takes{ canvasElement, userEvent }as an argument, or the test imports it and wires it up by hand.We'd like to expose project helpers on the play context, so a story can write:
Describe the solution you'd like
From reading the preview runtime,
StoryRenderbuilds one context object and passes the same object to loaders, thenbeforeEach, thenplay. Storybook itself assignscanvasand the instrumenteduserEventonto it this way. A preview-levelbeforeEachcan therefore add a property, and a module augmentation types it:We verified a minimal version with
addon-vitest: a plain button and list, injection viabeforeEach, and the same via awithHelpers(play)wrapper. Both pass and typecheck. Three details we hit:beforeEachhas to be used, notloaders. Loaders in the same phase run in parallel, socontext.userEventmay not exist yet.beforeEachreceives aStoryContext, which lacks the augmented property, so the hook has to be typed withStoryContextand assign it (e.g. viaObject.assign).composedStory.play()builds a fresh context and copies onlyloaded, so the injected property is missing there. Onlyrun()goes through the whole pipeline.Describe alternatives you've considered
Instead of mutating the context, a wrapper builds the helpers and passes an extended context to the play function:
The wrapper needs no preview wiring and no global type augmentation. It also works with a raw composed
story.play(). The costs are one wrapper call per story, and the injection is visible only where the wrapper is applied. We spiked both approaches and both pass underaddon-vitest. We prefer the context approach for ergonomics, but it relies on undocumented behavior, which is why we're asking.Are you able to assist to bring the feature to reality?
yes, I can
Additional context
Nothing in the docs describes extending the context. The
beforeEachdocs only cover setup and cleanup.PlayFunctionandPlayFunctionContextare only exported fromstorybook/internal/csf. We found no existing discussion of this.Questions
beforeEachintended to be supported, or an implementation detail that may change?contextannotation in the preview, or typedProjectAnnotationsthat extend the play context? Or is a wrapper like the one above the recommended pattern?play()(not justrun()) applybeforeEachmutations to the context?Happy to put together a PR or a minimal repro repo if that's useful.
All reactions