medusa testing

The helpers this package ships for your tests, by the path you import them from. How the test layers fit together is in the testing guide.

@evolve-framework/medusa/cleanup

Test-data cleanup through Medusa's admin API, for the command line and a test-support service.

cleanupClientAn admin client from MEDUSA_API_URL and MEDUSA_ADMIN_API_KEY, refused before any request unless SIMULATION_ENABLED=true.

import { cleanupClient } from "@evolve-framework/medusa/cleanup";

Only the command line and a test-support service build one. The subgraph never reads the key, so no admin credential is within reach of a request.

function cleanupClient(
  env?: ProcessEnv,
): {
  admin: AdminClient;
  baseUrl: string;
}

Returns { admin: AdminClient; baseUrl: string; }

deleteCustomerDelete a test customer; answers false for one that does not exist.

import { deleteCustomer } from "@evolve-framework/medusa/cleanup";

function deleteCustomer(
  admin: Medusa,
  identity: TestIdentity,
  customerId: string,
): Promise<boolean>

Option	Type	Description
domain	string	The reserved domain, e.g. test.example.com.
prefix	string	What every generated local part starts with, e.g. e2e-.

Returns Promise<boolean>

deleteCustomersByEmailDelete every customer holding a test identity's address, and answer how many there were.

import { deleteCustomersByEmail } from "@evolve-framework/medusa/cleanup";

function deleteCustomersByEmail(
  admin: Medusa,
  identity: TestIdentity,
  email: string,
): Promise<number>

Option	Type	Description
domain	string	The reserved domain, e.g. test.example.com.
prefix	string	What every generated local part starts with, e.g. e2e-.

Returns Promise<number>

deleteOrderTake a test order out of the way.

import { deleteOrder } from "@evolve-framework/medusa/cleanup";

function deleteOrder(
  admin: Medusa,
  identity: TestIdentity,
  orderId: string,
): Promise<boolean>

Option	Type	Description
domain	string	The reserved domain, e.g. test.example.com.
prefix	string	What every generated local part starts with, e.g. e2e-.

Returns Promise<boolean>

deleteOrdersOfCancel and archive every order a test customer placed; answers how many.

import { deleteOrdersOf } from "@evolve-framework/medusa/cleanup";

function deleteOrdersOf(
  admin: Medusa,
  identity: TestIdentity,
  customerId: string,
): Promise<number>

Option	Type	Description
domain	string	The reserved domain, e.g. test.example.com.
prefix	string	What every generated local part starts with, e.g. e2e-.

Returns Promise<number>

medusaCleanupEvery cleanup action the test-support service serves, for Medusa.

import { medusaCleanup } from "@evolve-framework/medusa/cleanup";

function medusaCleanup(admin: Medusa): CleanupHandlers

Returns CleanupHandlers

ADMIN_API_KEY_ENVThe Medusa secret API key test-data cleanup authenticates with.

import { ADMIN_API_KEY_ENV } from "@evolve-framework/medusa/cleanup";

const ADMIN_API_KEY_ENV: "MEDUSA_ADMIN_API_KEY"

AdminClientA Medusa client with admin rights, for test-data cleanup only.

import { type AdminClient } from "@evolve-framework/medusa/cleanup";

export type AdminClient = Medusa;

@evolve-framework/medusa/testing

A test client and mocked Store API handlers, for testing against Medusa without a server.

RequestLogRecords the locale each request carried, so a test can assert that a read actually asked Medusa for the right language instead of merely returning something plausible.

import { RequestLog } from "@evolve-framework/medusa/testing";

new RequestLog()

Method	Description
record(request: Request): void
reset(): void

createStoreHandlers

import { createStoreHandlers } from "@evolve-framework/medusa/testing";

function createStoreHandlers(
  fixtures?: StoreFixtures,
  log?: RequestLog,
): import("msw").HttpHandler[]

Option	Type	Description
regions?	unknown[]
products?	unknown[]
categories?	unknown[]
locales?	string[]	Locale codes the store reports as supported.

Returns import("msw").HttpHandler[]

createTestClientFactoryA factory pointed at the MSW base URL, for tests that need a real client.

import { createTestClientFactory } from "@evolve-framework/medusa/testing";

function createTestClientFactory(
  stores?: MedusaStoreConfigs,
): ClientFactory

Returns ClientFactory

MEDUSA_TEST_URLMSW handlers for the Medusa Store API.

import { MEDUSA_TEST_URL } from "@evolve-framework/medusa/testing";

There is no Medusa equivalent of @labdigital/commercetools-mock, so the adapter is tested against intercepted HTTP rather than by stubbing its own internals — the same reasoning, one layer lower: tests exercise the real request the adapter builds, including its headers.

Fixtures should be captured from a running local Medusa rather than written by hand. A handwritten fixture only proves the adapter agrees with itself.

const MEDUSA_TEST_URL: "http://medusa.test"

StoreFixtures

import { type StoreFixtures } from "@evolve-framework/medusa/testing";

export type StoreFixtures = {
  regions?: unknown[];
  products?: unknown[];
  categories?: unknown[];
  locales?: string[];
};

Commands

For data in a shared environment, the package also adds these commands:

• evolve cleanup: Development only. Delete what end-to-end runs left behind