# Run Storybook Stories as Tests in CI

Yes. An agent adds the Storybook test runner so every story renders in headless Chromium, runs it against a built Storybook in your CI job, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-storybook-test-runner/storybook/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads what Storybook already has. In a React app laid out like alan2207/bulletproof-react, `apps/react-vite/.storybook/main.ts` uses `@storybook/react-vite` with the `actions`, `links`, `essentials`, `interactions`, `docs` and `a11y` addons and a stories glob of `../src/**/*.stories.@(js|jsx|ts|tsx)`; `preview.tsx` wraps every story in a `BrowserRouter` and imports `src/index.css`. Eleven story files sit under `src/components/ui/`, for the button, dialog, confirmation dialog, drawer, dropdown, form, link, md-preview, notification, spinner and table. `package.json` pins `storybook` and its packages at `^8.0.9`, has `storybook` and `build-storybook` scripts, and already has `@playwright/test` for the e2e suite. `.github/workflows/react-vite-ci.yml` never builds Storybook, so a story that throws on render is found by whoever opens it next.

It adds `@storybook/test-runner` on the 8.x line as a devDependency and a `test-storybook` script. The runner visits every story in a headless Chromium through Playwright, fails a story that throws during render, and runs any `play` function a story defines, so the `interactions` addon's checks become assertions rather than a panel. A `.storybook/test-runner.ts` is kept minimal: a `preVisit` that sets a fixed viewport so the table and drawer stories render the same in CI as locally. The agent does not add axe checks here, since the `a11y` addon is already configured for the browser and a separate change can turn it into failures.

In CI a new `storybook` job follows the `all-cli-checks` pattern: `actions/setup-node@v4` with `lts/*`, `yarn install`, `yarn playwright install --with-deps chromium` as the `e2e` job does for its browsers, then `yarn build-storybook --quiet` and `npx concurrently -k -s first "npx http-server storybook-static --port 6006 --silent" "npx wait-on tcp:6006 && yarn test-storybook"`, which is the runner's documented way to test a static build without a dev server. Testing the built output rather than `storybook dev` means the job checks the same bundle a deploy would serve. `storybook-static` is already in `.gitignore`.

The agent runs the whole thing in its sandbox: builds Storybook, runs the test runner against the static build, and reads the per-story results. A story that fails on first run is reported in the pull request with the error, not patched silently, because a render error in a story is either a bug in the component or a story that needs a decorator, and that is the reviewer's call. It runs `yarn lint` and `yarn check-types` too, since the new config file is TypeScript.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Run the Storybook stories as tests in CI for apps/react-vite. Read package.json, .storybook/main.ts, .storybook/preview.tsx, the story files under src/components/ui, .gitignore and .github/workflows/react-vite-ci.yml first. Add @storybook/test-runner on the same major line as storybook and a test-storybook script, and a minimal .storybook/test-runner.ts that fixes the viewport. Add a storybook job to the CI workflow that installs dependencies, installs Chromium for Playwright, builds Storybook with yarn build-storybook --quiet, serves storybook-static with http-server and runs yarn test-storybook against it with concurrently and wait-on. Build Storybook and run the test runner against the static build in your sandbox, report any story that fails without changing the component, run yarn lint and yarn check-types, and open a pull request quoting the per-story results.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

What comes back is a pull request that adds the devDependency, the script and `.storybook/test-runner.ts`, and one job in `react-vite-ci.yml`. The description quotes the runner's output with every story and its result, the build time of the static Storybook, and the lint and type-check output.

The run's record keeps the build and the test runner's output, so a reviewer can see each of the eleven story files pass in Chromium rather than read a count.

Before merging, a reviewer decides whether the job should block merges like `all-cli-checks` does or run beside it, and whether to add `play` functions to the form and dialog stories so the runner asserts behaviour and not only rendering. The pull request names the two stories where that would pay off first.

## Run it on every pull request that changes a component

Once the job exists, CI runs every story on every push. For the stories that have no `play` function, an automation in the Project with a `github` trigger on `pull_request.opened` and `pull_request.synchronize` can run a prompt that reads the pull request's changed files under `src/components/ui`, finds a story for each changed component with no interaction test, and posts a review comment proposing one, so coverage grows with the components rather than in a separate effort. The trigger adds the event after the prompt.

A team with several Storybooks starts one run per repository with one `POST /o/{org}/sessions` each, this prompt as `input` and the repository in `resources`, with a `request_id` that is a UUID v5 of the repository's full name so a retry returns the run it already started. Each run reads its own `main.ts` and workflow, so a Storybook on Webpack or with a different stories glob gets a job that fits.

## Why run it on Rush?

The test runner is easy to install and awkward to run right: it needs a browser, a served Storybook and a port to wait on, and a story that renders fine in the dev server can fail against the static build. The agent builds and serves the static output in its own sandbox, runs the runner against it, and keeps the per-story results, so the first run's failures are in the pull request rather than in a red CI job.

The pull request is a config file, a script and one job, so review is a list of stories and their results. Across several apps the job runs in parallel, one sandbox and one pull request each, with the job fitted to that app's build.

## Frequently asked questions

### Why test the static build rather than storybook dev?

Because the static build is what gets deployed, and a story that depends on the dev server's hot reload or an unbundled asset passes in `storybook dev` and fails in `storybook-static`. Serving the build with `http-server` and waiting on the port is the runner's documented CI setup.

### Does this need the Playwright browsers the e2e job installs?

Only Chromium. The job installs it with `yarn playwright install --with-deps chromium`, the same command family the `e2e` job uses, so no new tooling enters the workflow.

### What does the runner assert for a story with no play function?

That it renders without throwing. That already catches a missing provider, a bad prop default or a component that reads `window` at import time. A `play` function adds clicks and expectations on top, and the pull request names the stories where that would matter first.

### Can the a11y addon fail the run too?

Yes, with `axe-playwright` in a `postVisit` hook in `test-runner.ts`. The agent leaves it out here because the addon's findings are not yet triaged, and turning them into failures is a separate change with its own list of violations to review.

## More Storybook jobs

- [Add Visual Regression Tests to Storybook Stories](https://getrush.ai/run/add-visual-regression-tests/storybook/)
- [Upgrade Storybook to the Latest Version](https://getrush.ai/run/upgrade-storybook/storybook/)
- [Write Interaction Tests for Storybook Stories](https://getrush.ai/run/write-interaction-tests/storybook/)

## More jobs like this: Write the missing tests

- [Run Prisma Tests Against Their Own Database, Not the Dev One](https://getrush.ai/run/add-test-database-isolation/prisma/)
- [Add Test Retries for Flaky Jest Tests in CI](https://getrush.ai/run/add-test-retries/jest/)
- [Add Test Retries to a Playwright Suite](https://getrush.ai/run/add-test-retries/playwright/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
