Storybook play function "expect(...).toBeInTheDocument is not a function" in CI

A play function used a DOM matcher like toBeInTheDocument, but the test-runner's expect does not have the jest-dom matchers unless you extend it. In CI, where nothing set them up implicitly, the matcher is undefined.

What this error means

An interaction test fails with "TypeError: expect(...).toBeInTheDocument is not a function" inside a story's play function.

TypeError: expect(...).toBeInTheDocument is not a function
    at play (Button.stories.tsx:22:41)

Common causes

jest-dom matchers were never registered

The play function relies on @testing-library/jest-dom matchers, but nothing extended expect with them for the runner.

The setup ran locally but not in CI

A local editor or config extended expect implicitly, while the CI runner uses a bare configuration.

How to fix it

Extend expect in the test-runner config

1. Create .storybook/test-runner.ts (or .js).
2. Import the jest-dom matchers so expect gains DOM assertions.
3. Re-run the runner.

// .storybook/test-runner.ts
import '@testing-library/jest-dom';

Install the matcher package

Ensure the jest-dom package is a dependency so CI can import it.

npm install -D @testing-library/jest-dom

How to prevent it

• Register jest-dom matchers in the test-runner config, not ad hoc.
• Keep @testing-library/jest-dom in package.json.
• Run the test-runner locally with the same config CI uses.

Related guides