All jobs

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 RushOpens 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 with this body:

{
  "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.

The use case this job follows, with its automation and trigger: Write the missing tests.

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

More jobs like this: Write the missing tests

Keep reading