orcaqubits/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/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.