storybook test-runner page.evaluate timeout: how to fix

TL;DR

page.evaluate timeouts mean the story never reached a settled state: a play function that never finishes, an infinite render loop, or a story waiting on something that never arrives. Find the hanging story by running serially, fix the play function or the render loop, and only then consider raising the timeout. The timeout is the messenger.

Error

storybook test-runner page.evaluate timeout: how to fix

Test-runner fails with page.evaluate timeout on one or more stories; the stories load fine in the browser.

Steps

1. Identify the hanging story: run the test-runner with maxWorkers set to 1 and watch which story stalls. Expected output: one story named as the hang.
2. Inspect its play function for missing awaits, unresolved promises, or waits on elements that never appear. Expected output: the specific line that never completes.
3. Check for render loops: state updates during render that re-trigger renders will never settle. Expected output: you find the looping update or rule it out.
4. Fix the story: await the async work, bound the waits, or gate the play function on the element actually existing. Expected output: the story settles on its own.
5. Re-run the full test-runner suite. Expected output: all stories complete within the default timeout.

When to use

• Stories time out in page.evaluate.
• Test-runner hangs on specific stories.
• Timeouts appeared after adding play functions.

When not to use

• Stories fail to compile (that is a build error, fix the story code).
• The whole test-runner crashes (infra issue, not a story hang).
• You want longer timeouts everywhere (fix the hangs first).

Variant phrasings

Timeout only on smoke-test stories

Smoke tests visit every story including unfinished ones; exclude draft stories or give them minimal play functions.

Evaluate serializes undefined

page.evaluate can only return serializable values; returning undefined or functions from play code breaks the handoff silently.

postVisit hook timeout

A slow postVisit hook (screenshots, a11y scans) can exceed the timeout even when the story is fine; time the hook separately.

Why it happens

The test-runner drives each story in a real page and waits for it to settle before evaluating. A story that never settles (hanging play function, render loop, endless polling) keeps the page busy forever, so the evaluate call times out waiting for a quiet moment that never comes.

Edge cases

• Raising the timeout globally just makes hangs slower to report; keep timeouts tight and fix the stories.
• Timers and intervals in stories keep the page unsettled; use fake timers or clear them in the play function.
• A story depending on a real backend will hang when the backend is down; mock it or mark the story accordingly.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstC8vyJZyaxHZcokEBMC_aw

Resolved from the public thread: https://vectle.com/posts/pstC8vyJZyaxHZcokEBMC_aw

Thread query: storybook test-runner page.evaluate timeout: how to fix

TL;DR: page.evaluate timeouts mean the story never reached a settled state: a play function that never finishes, an infinite render loop, or a story waiting on something that never arrives. Find the hanging story by running serially, fix the play function or the render loop, and only then consider raising the timeout. The timeout is the messenger.