# Write Interaction Tests for Storybook Stories

Yes. The agent adds play functions that click, type and assert on your stories, runs them in a headless browser with Vitest and opens a pull request.

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

## What the agent does

The agent first works out how stories become tests in this repository, because that decides where a test goes and which command proves it. In a project set up like chromaui/intro-storybook-react-template, `vite.config.ts` defines a Vitest project named `storybook` that loads the `storybookTest` plugin from `@storybook/addon-vitest/vitest-plugin`, points it at `.storybook`, and runs in browser mode on headless Chromium through `@vitest/browser-playwright`, with `.storybook/vitest.setup.ts` applying the preview's annotations. Every story is already a test that passes when it renders without an error. What the setup lacks is a way to run it: `package.json` has `storybook` and `build-storybook` scripts and no `test` script, and there is no workflow in the repository.

It then lists what the stories assert today. Under `src/stories` there are three components. `Button.stories.ts` has `Primary`, `Secondary`, `Large` and `Small`, with `onClick: fn()` in the meta's `args`, so a spy is in place and nothing checks it. `Header.stories.ts` has `LoggedIn` and `LoggedOut` with spies for `onLogin`, `onLogout` and `onCreateAccount`. Only `Page.stories.ts` has a `play` function: its `LoggedIn` story finds the Log in button by role, clicks it and expects a Log out button. The agent reads the components for the behaviour that is untested: `Button.tsx` builds its class from `primary` and `size` and passes `backgroundColor` to an inline style, `Header.tsx` shows Log in and Sign up without a user and a welcome line with Log out when there is one, and `Page.tsx` holds the user in state and clears it on log out.

The tests it writes are `play` functions in those same story files, in the style the file already uses: `within(canvasElement)`, `userEvent` and `expect` imported from `storybook/test`, and queries by role and accessible name. For Button, a click calls `args.onClick` once, and the `primary` and `size` args produce the matching class. For Header, each button calls its own spy and no other, and the logged-in story shows the user's name. For Page, new stories walk the paths the existing one skips: signing up logs a user in, and logging out returns the page to its first state. Where a state has no story, such as a Button with a `backgroundColor`, it adds the story first so the state is also visible in the Storybook sidebar.

Then it runs them. `yarn install --immutable` uses the Yarn release the repository commits under `.yarn/releases`, `yarn playwright install --with-deps chromium` brings in the browser, and `yarn vitest run --project=storybook` runs every story. To show that a new assertion can fail, the agent breaks the component once per test, for instance by swapping two handlers in `Header.tsx`, confirms the run goes red, and restores the file. It adds a `test` script that runs the same Vitest command, runs `yarn tsc -b` because `tsconfig.app.json` type-checks `src` with `verbatimModuleSyntax` and `noUnusedLocals` on, and builds Storybook once with `yarn build-storybook` to confirm the new stories load.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Write interaction tests for the stories in this Storybook project. Read package.json, .storybook/main.ts, .storybook/preview.ts, .storybook/vitest.setup.ts, vite.config.ts, the tsconfig files and every component and story under src first. State how stories run as tests here and which command runs them. List every story, whether it has a play function, and which component behaviour no story asserts. Add play functions to the existing story files in the style they already use: queries by role and accessible name, userEvent for clicks and typing, expect from storybook/test, and the fn() spies already declared in args. Cover each callback prop (called once, with the right arguments, and no other spy called), each prop that changes what renders, and each state change a user can cause. Add a story where a state has none, and keep one behaviour per story with a name that says what it shows. Do not change component source to make a test pass and do not add a new test library. Install with yarn install --immutable, install Chromium with yarn playwright install --with-deps chromium, and run the stories with Vitest's storybook project. For each new assertion, break the component once, confirm the test fails, and restore it. Add a test script to package.json that runs the storybook project. Run yarn tsc -b and yarn build-storybook. Open a pull request listing each story you added or extended and what it asserts, with the output of the test run, the type check and the build. If a test exposes behaviour that looks wrong, keep the test, mark it in the description and leave the fix to us.",
  "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

A pull request that changes story files and `package.json` and leaves component source alone. The description is a table of stories: the ones that gained a `play` function, the ones that are new, and for each the behaviour it asserts in a sentence. Below it are the outputs of the Vitest run, `yarn tsc -b` and the Storybook build, and a short record of the deliberate breaks showing that each new assertion went red when the component was wrong.

Because the tests are stories, they do two jobs. The same file that fails in the terminal when a handler is wired to the wrong button also shows the interaction step by step in Storybook's Interactions panel for anyone who opens the story. A reviewer can run `yarn storybook`, open a new story and watch it play.

A reviewer checks that each story asserts something a user would notice, not an implementation detail. A class name is a fair assertion for a component whose whole job is styling, and a poor one for a page. They also decide whether the `test` script should run in CI; this repository has no workflow, and adding one is a separate request the agent names but does not make.

## Run it on every pull request labelled needs-stories

An automation in the Project that holds the repository, with a `github` trigger on `pull_request.labeled` and `needs-stories` in `labels`, starts one run when a maintainer applies the label. Its prompt asks for stories and `play` functions covering the components the pull request adds or changes. The trigger puts the pull request after the prompt and fills in nothing. The run opens its own pull request with the stories, which the author merges into their branch or cherry-picks from.

For a design system spread over several repositories, a script on your server sends this body to `POST /o/{org}/sessions` once per repository, each with a `request_id` that is a UUID v5 of the repository's full name, so a retry starts nothing new. A `webhook_url` on the key receives `run.completed` for each run that key started.

## Why run it on Rush?

Interaction tests run in a real browser, and getting one going locally means a browser download and a Vitest browser session per attempt. Writing a good `play` function is a loop: run, read the failure, fix the query, run again, then break the component to see the test catch it. The agent does that loop in its own sandbox with Chromium installed there, and component libraries in several repositories get their runs at once.

The pull request arrives with the passing run and the failing-on-purpose runs behind it. Those commands and their output are kept in the session's transcript at `GET /o/{org}/sessions/{id}/messages`, so the claim that a story tests something is backed by a run in which it failed.

## Frequently asked questions

### Does it need the Storybook test runner or Jest?

No. This setup runs stories through the Vitest addon, which the repository already has in `devDependencies` and in `vite.config.ts`. The agent uses what is configured and adds no second runner. In a project that uses `@storybook/test-runner` instead, it reads that setup and runs that command.

### Will it rewrite my components to make them easier to test?

No. The prompt keeps component source unchanged. When an element has no accessible name to query by, the agent says so in the pull request, since that is usually an accessibility gap worth fixing, and uses the closest stable query for now.

### Can it test components that fetch data?

Yes, when the story can supply the data. This template installs `msw` and `msw-storybook-addon` but does not register the addon in `.storybook/preview.ts`, so the agent would report that and ask before wiring it, because it changes how every story loads. Components that take data as props need none of that.

### Why play functions and not separate test files?

A `play` function keeps the test next to the state it exercises and makes it visible in Storybook, where a designer or reviewer can step through it. The Vitest addon turns each story into a test, so nothing extra is needed to run them from a terminal or CI.

## More Storybook jobs

- [Add Accessibility Tests to Storybook](https://getrush.ai/run/add-accessibility-tests/storybook/)
- [Run Storybook Stories as Tests in CI](https://getrush.ai/run/add-storybook-test-runner/storybook/)
- [Add Visual Regression Tests to Storybook Stories](https://getrush.ai/run/add-visual-regression-tests/storybook/)

## More jobs like this: Write the missing tests

- [Write Japa Tests for an AdonisJS API](https://getrush.ai/run/write-japa-tests/adonisjs/)
- [Write Jest Tests for a React Native App](https://getrush.ai/run/write-jest-tests/react-native/)
- [Write Jest Unit Tests for a NestJS API](https://getrush.ai/run/write-jest-unit-tests/nestjs/)

## 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/)
