medusa-testing

name	medusa-testing
description	Test Medusa v2 applications — Jest setup, module unit tests, workflow integration tests, API route tests, medusaIntegrationTestRunner, and mock patterns. Use when writing tests for Medusa projects.
allowed-tools	Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch

Medusa v2 Testing

Before writing code

Fetch live docs:

1. Web-search site:docs.medusajs.com testing for official testing guide and setup
2. Web-search site:docs.medusajs.com medusaIntegrationTestRunner for integration test utilities
3. Web-search site:docs.medusajs.com unit test module for module unit testing patterns
4. Fetch https://docs.medusajs.com/resources/medusa-testing and review test runner configuration
5. Web-search medusajs v2 jest test workflow 2026 for latest workflow testing patterns

Test Architecture

Test Pyramid

        ┌─────────┐
        │  E2E    │  API route tests (slow, high confidence)
        ├─────────┤
        │ Integr. │  Workflow + cross-module tests
        ├─────────┤
        │  Unit   │  Module service + utility tests (fast)
        └─────────┘

Test Types

Type	Scope	Runner	Speed
Unit	Single module service	Jest	Fast
Integration	Workflows, cross-module	medusaIntegrationTestRunner	Medium
API Route	HTTP endpoints	medusaIntegrationTestRunner + supertest	Slow
E2E	Full user flows	Playwright/Cypress (optional)	Slowest

Jest Setup

// Skeleton: jest.config.ts for Medusa v2
// Fetch live docs for current recommended config
module.exports = {
  preset: "ts-jest",
  testEnvironment: "node",
  // Fetch live docs for moduleNameMapper and transform
}

Package Dependencies

Package	Purpose
jest	Test runner
ts-jest	TypeScript support
@medusajs/test-utils	Medusa test utilities
supertest	HTTP assertion library

Fetch live docs for the current @medusajs/test-utils package exports and version compatibility.

Module Unit Tests

// Skeleton: module unit test
// Fetch live docs for module test setup
describe("ProductModuleService", () => {
  let service: IProductModuleService
  // Fetch live docs for beforeAll setup with test database
})

Service Method Testing

Test Target	What to Verify
createProducts	Returns product with correct fields
listProducts	Filters, pagination, sorting work
retrieveProduct	Relations loaded correctly
updateProducts	Partial updates applied
deleteProducts	Cascade behavior correct

Setup and Teardown

Hook	Purpose
beforeAll	Initialize module with test database
beforeEach	Seed test data
afterEach	Clean up created records
afterAll	Close database connection

Fetch live docs for test database initialization and module container setup.

Integration Tests with medusaIntegrationTestRunner

medusaIntegrationTestRunner provides a full Medusa application container with all modules, test database setup/teardown, API client, and seeded admin user.

// Skeleton: integration test — Fetch live docs for config
import { medusaIntegrationTestRunner } from "@medusajs/test-utils"

medusaIntegrationTestRunner({
  testSuite: ({ api, getContainer }) => {
    // Fetch live docs for api and container usage
  },
})

Runner Context

Property	Description
api	Pre-configured HTTP client (AxiosInstance)
getContainer	Returns the DI container for resolving services
dbConnection	Database connection reference
modulesConfig	Override module configurations (runner option)

Fetch live docs for the full context object shape and available helper methods.

Workflow Tests

What to Test

Aspect	Verification
Success path	Workflow completes, returns expected result
Side effects	Linked modules updated (pricing, inventory)
Compensation	Failed step triggers rollback of previous steps
Input validation	Invalid inputs produce expected errors
Idempotency	Repeated execution does not create duplicates

Compensation Testing

Strategy	Description
Force step failure	Mock a step to throw an error
Verify rollback	Check that previous steps are compensated
Check data state	Ensure database is clean after rollback

Fetch live docs for workflow step mocking and compensation test patterns.

API Route Tests

Route Test Checklist

Check	Description
Status code	Correct HTTP status for success and error
Response body	Expected fields present with correct types
Side effects	Database state updated correctly
Authentication	Unauthenticated requests rejected
Validation	Invalid inputs return 400 with errors
Pagination	List endpoints paginate correctly

Authentication in Tests

Actor	Header	Source
Admin	Authorization: Bearer <jwt>	Login via /auth/user/emailpass
Customer	Authorization: Bearer <jwt>	Login via /auth/customer/emailpass
Store API	x-publishable-api-key	Created in test setup

Mock Patterns

Pattern	When to Use
Full module mock	Unit testing code that depends on a module
Service method stub	Override specific method behavior
Test database	Integration tests with real data

Common Mocks

Mock Target	Purpose
Payment provider	Avoid real payment calls in tests
Fulfillment provider	Avoid real shipping API calls
Email service	Capture sent emails for assertion
Event bus	Capture emitted events for assertion

Fetch live docs for recommended mock patterns and test utility helpers.

Best Practices

Test Organization

• Co-locate tests with source: src/modules/product/__tests__/
• Name test files with .spec.ts suffix; group by feature, not test type
• Use factory functions to generate test data — avoid hardcoded fixtures

Test Data and Integration

• Use medusaIntegrationTestRunner for all cross-module tests
• Always test compensation (rollback) paths for critical workflows
• Clean up in afterEach to prevent pollution; seed minimal data

CI/CD and Coverage

• Run unit tests on every commit, integration tests on PR; target 80% coverage
• Use a dedicated test database — never test against production

Fetch the Medusa v2 testing documentation and @medusajs/test-utils reference for exact runner configuration, mock patterns, and test utility APIs before implementing.