Storybook Interaction Play Function Global Timeout Configuration

Question

The goal is to introduce a configurable global timeout that applies to the entire play sequence in Storybook's Interaction Testing, reducing flakiness caused by unpredictable DOM update times.

Currently each asynchronous action relies on the default timeout of the underlying testing‑library wrapper, and there is no built‑in mechanism to override this globally or to define a cancellation policy when the limit is exceeded. This leaves teams uncertain about how to enforce uniform timing bounds across stories and how Storybook should react when a timeout occurs.

What API could be added to set a global timeout for all play functions? How should Storybook handle cancellation and cleanup when the timeout is reached? Should the timeout be adjustable at the project level, per‑story, or both?

Tasadduq Burney · Answer

Direct AnswerStorybook already supports a global interaction timeout via parameters.interactions.timeout in .storybook/preview.js (or main.js in newer versions). This value applies to every play function unless a story overrides it. When the limit is exceeded, the interaction is marked failed; Storybook unwinds pending DOM mutations and calls the test framework's error handler, but it does not automatically roll back component state. You can set the timeout at the project level and optionally override it per story by passing a timeout option to the play call.Confirmed Configuration APIProject‑level (global)// .storybook/preview.js
export const parameters = {
  interactions: {
    timeout: 10000 // milliseconds
  }
};In Storybook 8.x the same key works in main.js under previewAnnotations or directly in parameters.Per‑story overrideexport const MyStory = {
  play: async ({ canvasElement }) => {
    await within(canvasElement).findByText('Loaded', { timeout: 15000 });
  },
  parameters: {
    interactions: { timeout: 15000 }
  }
};The per‑story parameters.interactions.timeout merges with the global value and takes precedence for that story only.Cancellation and Cleanup BehaviorTimeout reached: The underlying testing‑library wrapper (usually @testing-library/dom) throws a timeout error. Storybook catches it, marks the story as failed in the UI, and stops further play execution for that story.DOM unwinding: Pending waitFor, findBy*, or within queries are aborted; any already‑applied DOM mutations remain unless your component implements its own rollback logic.No global cancellation: There is no built‑in API to cancel all in‑flight play functions at once (e.g., when a suite‑level timeout fires). Each interaction is independent.Recommended PracticeSet a sensible project‑wide default (e.g., 5–10 s) in preview.js.Override only the stories that genuinely need more time via parameters.interactions.timeout.Wrap play in a helper that enforces idempotent setup/teardown if you need deterministic cleanup on timeout.One Diagnostic Detail NeededWhich Storybook major version are you using (6.x, 7.x, or 8.x)? The exact parameter path (preview.js vs main.js vs previewAnnotations) and the testing‑library integration details differ slightly between versions, and confirming the version will let me point to the precise config location.

Storybook Interaction Play Function Global Timeout Configuration

1 answer

Direct Answer

Confirmed Configuration API

Project‑level (global)

Per‑story override

Cancellation and Cleanup Behavior

Recommended Practice

One Diagnostic Detail Needed

Your perspective belongs here.

0 question comments