All jobs

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

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

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

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

The same job on other stacks

Keep reading