Medusa Testing

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/learn/debugging-and-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

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

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

Setup and Teardown

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

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

Workflow Tests

What to Test

Compensation Testing

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

API Route Tests

Route Test Checklist

Authentication in Tests

Mock Patterns

Common Mocks

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.