# Write Integration Tests for a Medusa Backend

Yes. An agent writes HTTP integration tests for your Medusa backend's custom routes and seed data with medusaIntegrationTestRunner, run on Postgres, in a PR.

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

## What the agent does

The agent reads how the backend is wired for tests before it writes one, because a Medusa project often ships the harness without a single test behind it. In a monorepo laid out like medusajs/dtc-starter, `apps/backend/package.json` pins `@medusajs/medusa`, `@medusajs/framework` and `@medusajs/test-utils` at 2.22.1 and defines three scripts: `test:unit`, `test:integration:modules` and `test:integration:http`, each setting `TEST_TYPE` and `NODE_OPTIONS=--experimental-vm-modules` and running Jest 29 with `--runInBand --forceExit`. `jest.config.js` transforms TypeScript with `@swc/jest`, calls `loadEnv("test", process.cwd())`, registers `integration-tests/setup.js` (which clears MikroORM's `MetadataStorage`) and chooses `testMatch` by `TEST_TYPE`: HTTP suites live at `integration-tests/http/*.spec.ts`. That directory holds only `setup.js`; no `__tests__` folder exists under `src/`, the root `pnpm test` goes through turbo to a backend that defines no plain `test` script, and `.github/workflows/` contains only `update.yaml`, which opens Medusa upgrade pull requests. `AGENTS.md` says the storefront has no suite and that integration suites need a live Postgres.

Then it reads what there is to test. `src/api/store/custom/route.ts` and `src/api/admin/custom/route.ts` each export a `GET` that answers `res.sendStatus(200)`; `src/api/middlewares.ts` applies `configureStoreSearch` to `POST /store/search` so only the `product` index is queryable; `src/search/product.ts` defines that index with `defineSearchIndex`, searchable `title`, `description` and `option_values`, facetable `category` and `labels`, and price fields from `helpers/pricing`. `src/migration-scripts/initial-data-seed.ts` runs with `medusa db:migrate` and creates a default store and sales channel, one `Europe` region in `eur` covering seven countries with `DEFAULT_REGION_STORE_POLICIES` from `src/lib/region-store-policies.ts` as its metadata, a tax region per country, a `European Warehouse` stock location with standard and express shipping options priced in `eur` and `usd`, a publishable API key linked to the channel, and product categories and products, all through the `core-flows` workflows. `medusa-config.ts` reads `DATABASE_URL`, the three CORS lists and the JWT and cookie secrets, which `.env.template` lists.

The agent writes `integration-tests/http/custom-routes.spec.ts`, `integration-tests/http/seed.spec.ts` and `integration-tests/http/store-products.spec.ts`, each wrapped in `medusaIntegrationTestRunner` from `@medusajs/test-utils`, which boots the backend against a fresh database per file and hands the tests an `api` client and the container. The first file asserts `GET /store/custom` answers 200 with a publishable key header and is refused without one, and that `GET /admin/custom` answers 401 anonymously and 200 for an admin user the test creates in `beforeEach` through the user and auth modules. The second resolves the region and store modules from the container after the migration script has run and checks that the `Europe` region exists with `eur`, its seven countries and every key of `DEFAULT_REGION_STORE_POLICIES` in its metadata, that a tax region exists per country, and that the publishable key is linked to the sales channel. The third lists `GET /store/products` with that key and a region id and asserts the seeded products come back with calculated prices, and that a draft product does not.

To run them the agent starts Postgres in its sandbox, sets `DB_USERNAME` and `DB_PASSWORD` the way the runner reads them, runs `pnpm install` at the root with the pinned pnpm 10.11.1 on Node 22, then `pnpm --filter @dtc/backend test:integration:http`, and reads the failures until the three files pass. It adds `.github/workflows/test.yml` with a `postgres:15` service and that one command, triggered on pull requests, so the suite runs where the upgrade pull requests from `update.yaml` land. `medusa lint` runs on the new files too, since `eslint.config.ts` loads `@medusajs/eslint-plugin`.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Write HTTP integration tests for this Medusa backend. Read apps/backend/package.json, jest.config.js, integration-tests/setup.js, medusa-config.ts, .env.template, src/api/middlewares.ts, every route.ts under src/api, src/search/product.ts, src/lib/region-store-policies.ts, src/migration-scripts/initial-data-seed.ts, AGENTS.md and .github/workflows first. Use medusaIntegrationTestRunner from @medusajs/test-utils and put each suite at integration-tests/http/<name>.spec.ts so the existing test:integration:http script picks it up. Cover the custom store and admin routes (with and without a publishable key, anonymous and as an admin user you create in the test), what the initial data seed leaves behind (the Europe region, its countries and store policy metadata, the tax regions, the sales channel and its publishable key), and the store product listing with calculated prices for a seeded region. Install Postgres in your sandbox, run pnpm --filter @dtc/backend test:integration:http until every test passes, run medusa lint on the new files, add a GitHub Actions workflow with a Postgres service that runs the same command on pull requests, and open a pull request with the Jest output. Do not change any route, workflow or seed.",
  "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 three files under `apps/backend/integration-tests/http/` and one workflow, `.github/workflows/test.yml`. Its description pastes the Jest summary from the sandbox run, with each suite's name and the number of passing tests the agent counted in that output, and the `medusa lint` result.

Every test runs against a database the runner creates for that file, so nothing in the suite depends on a developer's local data or on the order files run in. The custom routes, the search middleware, the seed script and `medusa-config.ts` are unchanged; the tests describe what they do today, which is what makes them useful on the next Medusa upgrade pull request.

Before merging, a reviewer checks that the seed assertions name the region, countries and currencies the business actually configured rather than whatever the starter shipped, that the admin test creates its user through the modules rather than a hard-coded token, and that the workflow's Postgres version matches the one in production.

## Run it on every Medusa upgrade pull request

The backend's `update.yaml` workflow opens a pull request whenever a Medusa release is published. A pull request a bot opens fires no `github` trigger, so an automation in the Project uses `pull_request.labeled` with a label the team puts on those upgrade pull requests; it starts a read-only run that reads the diff and the suite's result on the pull request and comments on which tests a release note says should change, so the suite grows with the framework instead of lagging it.

The automation's prompt is the only instruction; Rush appends the pull request event after it. The run has its own `max_runs_per_hour` cap and can comment but not push, which is the right shape for a review of someone else's upgrade.

## Why run it on Rush?

A Medusa integration suite only means something when it ran against a real database with the real HTTP layer, and that is the part a laptop makes awkward: a Postgres on the right version, a database per test file, the pinned pnpm and Node. The agent sets all of that up in its own sandbox, runs the suite until it passes and keeps the output, so the pull request shows tests that were seen to pass rather than tests that look right.

The run's record holds every command, including the first failing runs and what the agent changed in response, which is where a reviewer learns whether an assertion was weakened to pass or the test was wrong. Several backends can get suites at once, each in its own sandbox, with no shared database between them.

## Frequently asked questions

### Why HTTP integration tests rather than unit tests?

The custom routes, the search middleware and the seed script only do anything inside a running Medusa container with a database behind it. A unit test would mock most of that away. `medusaIntegrationTestRunner` boots the real backend per file, so the tests cover the route registration, the publishable key check and the workflows the seed calls as they behave in production.

### Does the runner need my .env file?

No. `jest.config.js` loads the `test` environment and the runner creates its own database from `DB_USERNAME` and `DB_PASSWORD`, which the workflow sets for the Postgres service. The CORS lists and secrets in `.env.template` are not read by the tests.

### Will the tests run on every pull request?

Only once the new workflow is merged. The repository today has no workflow that runs tests; `update.yaml` only opens upgrade pull requests. The added `test.yml` runs the HTTP suite with a Postgres service on each pull request, so those upgrades get a result.

### How long does the suite take?

The agent does not estimate that. Each file boots the backend and migrates a fresh database, so the Jest output in the pull request is the only honest number, and the scripts run with `--runInBand`, so files do not overlap.

## More Medusa jobs

- [Write Unit Tests for a Medusa Backend](https://getrush.ai/run/write-unit-tests/medusa/)
- [Add Dependabot to a Medusa Monorepo](https://getrush.ai/run/add-dependabot/medusa/)
- [Add a Dev Container to a Medusa Monorepo](https://getrush.ai/run/add-dev-containers/medusa/)

## The same job on other stacks

- [Write Integration Tests for a Reflex App](https://getrush.ai/run/write-integration-tests/reflex/)
- [Write Integration Tests for a Sequelize and Express API](https://getrush.ai/run/write-integration-tests/sequelize/)
- [Write Integration Tests for a Socket.IO Chat Server](https://getrush.ai/run/write-integration-tests/socket-io/)

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