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 with this body:
{
"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"
}
]
}- 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.
- 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.
- 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.
The use case this job follows, with its automation and trigger: Write the missing tests.
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
More jobs like this: Write the missing tests
- Write Japa Tests for an AdonisJS API (AdonisJS)
- Write Jest Tests for a React Native App (React Native)
- Write Jest Unit Tests for a NestJS API (NestJS)