# Write Vitest Tests for a Shopify App's Webhooks and Actions

Yes. An agent adds Vitest to your Shopify app, tests the webhook handlers and admin actions with Shopify and Prisma mocked, wires CI, and opens a PR.

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

## What the agent does

The agent first reads what the app does on the server, because that is where the tests pay off in a Shopify app. In one generated from Shopify/shopify-app-template-react-router, `app/shopify.server.ts` builds the app with `shopifyApp` from `@shopify/shopify-app-react-router/server`, `ApiVersion.October26`, `PrismaSessionStorage` over the `Session` model in `prisma/schema.prisma` (SQLite at `file:dev.sqlite`), `AppDistribution.AppStore` and the `expiringOfflineAccessTokens` flag, and exports `authenticate`, `unauthenticated`, `login`, `registerWebhooks` and `sessionStorage`. Routes come from `flatRoutes()` in `app/routes.ts`: `webhooks.app.uninstalled.tsx` calls `authenticate.webhook(request)` and, when a session comes back, deletes every session for that shop; `webhooks.app.scopes_update.tsx` writes `payload.current` into the session's `scope`; `webhooks.products.update.tsx` logs the event payload and answers 200; `app._index.tsx`'s action calls `admin.graphql` twice, `productCreate` for a randomly coloured snowboard and `productVariantsBulkUpdate` to set the first variant's price to `100.00`. `shopify.app.toml` subscribes the two app webhooks and an `events` subscription on product price changes with a `query_filter` on active products.

Then it reads the tooling. `package.json` has `lint`, `typecheck` (`react-router typegen && tsc --noEmit`), `build` and `setup`, no `test` script and no test runner; it pins `react-router` 7.18.2 and needs Node 22.12 or newer, and `vite` 7 is already a dependency. `vite.config.ts` loads `reactRouter()` and `tsconfigPaths()`, with a block that rewrites `HOST` into `SHOPIFY_APP_URL` for the CLI's tunnel. `.github/workflows/ci.yml` runs type checking, ESLint, `prisma generate && prisma validate` and the build on a matrix of Node 22 and 24 under npm, yarn and pnpm, and no test. `tsconfig.json` includes every `.ts` and `.tsx` file, so new test files are type-checked by the existing `typecheck` step whether or not they run.

The agent adds `vitest` as a dev dependency and a separate `vitest.config.ts` that uses `tsconfigPaths()` only and `environment: 'node'`, rather than reusing `vite.config.ts`, because the React Router plugin and the `SHOPIFY_APP_URL` rewrite have no place in a unit test process. It writes `app/routes/__tests__/webhooks.test.ts` and `app/routes/__tests__/app._index.test.ts`. The webhook tests `vi.mock('../../shopify.server')` so `authenticate.webhook` resolves to a fixed `{ shop, topic, session, payload }`, and `vi.mock('../../db.server')` with a stub whose `session.deleteMany` and `session.update` are spies: the uninstalled handler deletes sessions for the shop when a session is present and calls nothing when it is not, the scopes handler writes `current.toString()` against the session id, and the products handler answers 200 with no body. The action test mocks `authenticate.admin` to return an `admin.graphql` spy that answers each mutation with the shape the code reads, then asserts the two calls happen in order, that the variant id from the first response goes into the second with price `100.00`, and that the returned JSON contains both.

It adds `"test": "vitest run"` to `package.json` and a `Run tests` step to `ci.yml` after ESLint, inside the same matrix, so the suite runs under all three package managers like everything else. In its sandbox it runs `npm install`, `npm run typecheck`, `npm run lint` and `npm test`, and reads the output until all pass; the Prisma client is generated by `npm run setup` first, since `db.server.ts` imports `@prisma/client` even when the test replaces it.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add Vitest to this Shopify app and write tests for its server code. Read package.json, vite.config.ts, tsconfig.json, app/shopify.server.ts, app/db.server.ts, app/routes.ts, every file under app/routes, prisma/schema.prisma, shopify.app.toml and .github/workflows/ci.yml first. Add vitest as a dev dependency with its own vitest.config.ts (tsconfigPaths only, node environment; do not reuse vite.config.ts, which loads the React Router plugin). Mock the shopify.server and db.server modules with vi.mock and test the three webhook routes (the uninstalled handler deletes the shop's sessions only when a session is returned, the scopes_update handler stores payload.current on the session, the products update handler answers 200) and the app._index action (productCreate then productVariantsBulkUpdate with the first variant's id and price 100.00, both results returned). Add a test script that runs vitest run and a CI step after ESLint inside the existing matrix. Run the Prisma generate step, typecheck, lint and the tests in your sandbox until they pass, and open a pull request with the Vitest output. Change no route, the Prisma schema or shopify.app.toml.",
  "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

The pull request adds `vitest.config.ts` and two test files under `app/routes/__tests__/`, and changes `package.json` (the dev dependency and the `test` script) and `.github/workflows/ci.yml` (one step). Its description shows the Vitest summary from the sandbox, the number of tests per file as counted in that output, and the passing `typecheck` and `lint` runs.

No route changes. The handlers, the Prisma schema, the webhook subscriptions in `shopify.app.toml` and the build are as before; the tests describe what the server code does today, and the CI matrix now fails when a change to a webhook handler or the product action breaks that behaviour under any of the three package managers.

Before merging, a reviewer checks that the mocks mirror what `authenticate.webhook` and `authenticate.admin` return for this version of `@shopify/shopify-app-react-router`, that the test for the uninstalled webhook covers the redelivery case where no session exists, and whether the team wants the test step outside the package-manager matrix to keep CI time down.

## Run it on every new webhook handler

An automation in the Project with a `github` trigger on `pull_request.opened` starts a read-only run that reads the diff and comments when a new `webhooks.*.tsx` route or an action using `admin.graphql` arrives without a test beside it, and says nothing on a pull request that touches no route. Its prompt says what a complete test looks like for this app; Rush appends the pull request event after it.

That run comments and cannot push. A developer who wants the test written rather than requested sends this page's body with the pull request URL in `resources`, as `https://github.com/your-org/your-app/pull/<n>`, so the run works on that branch and pushes the test to it.

## Why run it on Rush?

The slow part of adding tests to a Shopify app is not writing assertions, it is finding the seam: what `authenticate.webhook` returns, what the Prisma session storage expects, why the Vite config with the React Router plugin cannot be reused as is, and getting the Prisma client generated before the first import. The agent works that out in its own sandbox with the real packages installed, runs the suite under the same commands CI will use, and opens a pull request only once typecheck, lint and tests pass together.

The run keeps every command and its output, so a reviewer can see which mock shapes were tried and why the final ones are right. Several apps generated from the same template can be covered in one batch, each run reading its own routes rather than copying a fixture.

## Frequently asked questions

### Why not reuse vite.config.ts for Vitest?

The app's Vite config loads the React Router dev plugin and rewrites `HOST` into `SHOPIFY_APP_URL` for the CLI's tunnel. Neither belongs in a unit test process, and the plugin expects a full React Router build. A small `vitest.config.ts` with `tsconfigPaths()` keeps the `~` style imports working and nothing else.

### Do the tests talk to Shopify or the database?

No. `authenticate.webhook` and `authenticate.admin` are mocked to return the shapes the handlers read, and `db.server.ts` is replaced with spies for `session.deleteMany` and `session.update`. The tests check what the handlers do with those results. Verifying a real webhook signature is the library's job and is covered by its own tests.

### Will the typecheck step complain about the test files?

`tsconfig.json` includes every `.ts` file, so the tests are type-checked by `npm run typecheck`. The agent runs that step in its sandbox before opening the pull request, which is why the mocks are typed against the exported `authenticate` rather than left as `any`.

### Why run the tests under npm, yarn and pnpm?

Because `ci.yml` already runs every other step under all three, and the template exists to be cloned by teams using any of them. The step is added inside the matrix so a lockfile-specific resolution difference shows up. A team that finds it slow can move it to one job; the pull request notes that choice.

## More Shopify app jobs

- [Add Subscription Billing to a Shopify App](https://getrush.ai/run/add-app-billing/shopify-app/)
- [Add an App Proxy to a Shopify App](https://getrush.ai/run/add-app-proxy/shopify-app/)
- [Add a Checkout UI Extension to a Shopify App](https://getrush.ai/run/add-checkout-ui-extension/shopify-app/)

## The same job on other stacks

- [Write Vitest Tests for a SvelteKit App](https://getrush.ai/run/write-vitest-tests/sveltekit/)
- [Write Vitest Tests for a tRPC Router](https://getrush.ai/run/write-vitest-tests/trpc/)
- [Write Vitest Tests for a Turborepo Monorepo](https://getrush.ai/run/write-vitest-tests/turborepo/)

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