Storybook interaction test failure gating the pipeline in CI

By Kaveh Alemi·Latchkey

The test-runner executes each story's play function and fails the job if an assertion throws. Unlike a flaky infra error, this is a real behavioral assertion: the story rendered or interacted differently than the play function expected.

What this error means

The runner marks a story failed with the play function's assertion message (a role/text not found, or a value mismatch) and exits non-zero, blocking the merge.

FAIL browser: chromium src/Button.stories.tsx
  ● Button > Clickable
    Unable to find an accessible element with the role "button" and name "Submit"

Common causes

The component behavior changed

A label, role, or interaction changed, so the play function's query or assertion no longer matches the rendered output.

A race in the play function

The assertion runs before an async update settles, so an element is queried before it appears.

How to fix it

Fix the component or the assertion

1. Read which query or assertion failed and inspect the story.
2. If the behavior change is intended, update the play function; otherwise fix the component.
3. Re-run the runner to confirm the assertion passes.

Await async updates with findBy

Use findBy* and waitFor so the play function waits for the element instead of querying too early.

// in a story's play function
await canvas.findByRole('button', { name: 'Submit' });

How to prevent it

• Query by role/name and await async updates in play functions.
• Keep play assertions in step with component changes.
• Run the test-runner locally before pushing UI changes.

Frequently asked questions

Related guides

References

• GitHub Actions documentation