All jobs

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

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

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

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

The same job on other stacks

Keep reading