Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
medusaIntegrationTestRunner
✓ import { medusaIntegrationTestRunner } from 'medusa-test-utils'
✗ const { medusaIntegrationTestRunner } = require('medusa-test-utils')
This is the primary utility for setting up and running full Medusa integration tests. Expects a Jest-compatible test suite. For Medusa v2.x, use '@medusajs/test-utils'.
moduleIntegrationTestRunner
✓ import { moduleIntegrationTestRunner } from 'medusa-test-utils'
✗ import moduleIntegrationTestRunner from 'medusa-test-utils'
Used for testing individual Medusa modules in isolation. For Medusa v2.x, use '@medusajs/test-utils'.
initDb
✓ import { initDb } from 'medusa-test-utils'
Directly initializes a test database instance. Typically handled internally by `medusaIntegrationTestRunner` but can be useful for granular control.
dropDb
✓ import { dropDb } from 'medusa-test-utils'
Drops the test database instance. Often paired with `initDb` in `beforeEach`/`afterEach` hooks for clean test runs.
Demonstrates how to use `medusaIntegrationTestRunner` to set up an integration test suite for Medusa v1.x, including database access, service resolution, and making API requests. It also shows a basic Jest setup with an increased timeout.
import { medusaIntegrationTestRunner } from 'medusa-test-utils';
import { jest } from '@jest/globals';
// Set a longer timeout for integration tests due to database operations and server startup
jest.setTimeout(60 * 1000);
medusaIntegrationTestRunner({
testSuite: ({ db, api, getContainer }) => {
describe('Medusa API Endpoints', () => {
let productService;
beforeAll(async () => {
// Resolve a service from the Medusa container
productService = getContainer().resolve('productService');
});
it('should retrieve a product by ID', async () => {
// Example: Create a product and then retrieve it
const productData = {
title: 'Test Product',
description: 'A product for testing',
is_giftcard: false,
discountable: true,
status: 'published',
thumbnail: 'https://example.com/thumbnail.jpg',
options: [{ title: 'Size' }],
variants: [
{
title: 'Small',
prices: [{ currency_code: 'usd', amount: 1000 }],
options: { size: 'S' }
}
]
};
const createdProduct = await productService.create(productData);
const retrievedProduct = await api.get(`/store/products/${createdProduct.id}`);
expect(retrievedProduct.status).toBe(200);
expect(retrievedProduct.data.product.id).toBe(createdProduct.id);
expect(retrievedProduct.data.product.title).toBe('Test Product');
});
it('should create a new order via API', async () => {
// This is a simplified example, a real test would involve more setup (customer, region, cart)
const payload = {
email: 'test@example.com',
items: [], // Assuming items would be added to a cart first
shipping_address: { address_1: '123 Main St', city: 'Anytown', province: 'Anystate', country_code: 'us', postal_code: '12345' },
billing_address: { address_1: '123 Main St', city: 'Anytown', province: 'Anystate', country_code: 'us', postal_code: '12345' },
region_id: 'reg_test_region' // Placeholder, would need to be a valid region ID
};
// Note: Direct order creation via /store/orders is usually more complex (cart flow expected)
// This test primarily demonstrates API interaction, not full commerce flow validity.
const response = await api.post('/store/orders', payload);
// A successful order creation typically returns 200 or 201 status
// Depending on Medusa configuration, direct order creation might be restricted.
// For robust testing, a cart-to-checkout flow is usually preferred.
expect(response.status).toBeGreaterThanOrEqual(200);
expect(response.status).toBeLessThan(300);
expect(response.data.order).toBeDefined();
});
});
},
});
Errors
Common errors & fixes
Error: Cannot find module 'typeorm' from 'medusa-test-utils'
The `typeorm` package is a peer dependency but is not installed or the installed version conflicts with what `medusa-test-utils` expects.
fixEnsure `typeorm` is installed as a direct dependency in your project (`npm install typeorm@^0.2.43` or `yarn add typeorm@^0.2.43`). If other packages require a newer `typeorm` version, consider using `resolutions` or `overrides`.
Timeout - Async callback was not invoked within the 60000 ms timeout specified by jest.setTimeout.
Medusa integration tests involve spinning up a server and database, which can take longer than the default Jest timeout, or the test logic itself is too slow.
fixIncrease the Jest timeout for your test suite or individual tests, for example, by adding `jest.setTimeout(60 * 1000);` (for 60 seconds) at the top of your test file or within a `beforeAll` hook.
Audit
Dependencies
axiosrequiredUsed for making HTTP requests in API tests.
pg-godrequiredManages PostgreSQL database setup and teardown for isolated tests.
expressrequiredUnderpins the Medusa API server, necessary for testing API routes.
typeormrequiredORM used by Medusa v1.x for database interactions in tests.
get-portrequiredDynamically assigns available ports for test servers.
@medusajs/medusarequiredCore Medusa application, essential for running integration tests against.
@medusajs/modules-sdkrequiredProvides SDK utilities for Medusa modules within the test environment.