Storybook Interaction Play Function Global Timeout Configuration

Direct Answer

Storybook 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 API

Project‑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 override

export 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 Behavior

• Timeout 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 Practice

1. Set a sensible project‑wide default (e.g., 5–10 s) in preview.js.
2. Override only the stories that genuinely need more time via parameters.interactions.timeout.
3. Wrap play in a helper that enforces idempotent setup/teardown if you need deterministic cleanup on timeout.

One Diagnostic Detail Needed

Which 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.