Registry / testing / medusa-test-utils

medusa-test-utils

JSON →
library1.1.45jsnpmunverified

medusa-test-utils is a utility package designed to facilitate integration testing for applications built with Medusa, specifically targeting Medusa v1.x installations. It provides essential tools for setting up and tearing down isolated test environments, managing database interactions (primarily PostgreSQL with `pg-god`), and interacting with the Medusa container and API layer. This package, at version 1.1.45, is part of the older Medusa ecosystem, which relied on `TypeORM` v0.2.x. While still functional for legacy projects, the Medusa core has since transitioned to v2.x, which utilizes the `@medusajs/test-utils` package for its testing framework. Therefore, `medusa-test-utils` (v1.x) is considered to be in maintenance mode, receiving fewer updates compared to its successor. Its key differentiators include deep integration with the Medusa v1.x architecture, providing direct access to services and database operations within a controlled test scope.

npm install medusa-test-utils
INSTALL
IMPORT
SIG · MEDUSA-TEST-UTILS
M
medusa-test-utils
testingjavascriptv1.1.45
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
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
musl
node 18226 runs
build_error
glibc
node 18226 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(); }); }); }, });
Debug
Known issues
breakingThe `medusa-test-utils` package is primarily for Medusa v1.x. For Medusa v2.x and newer, the testing framework has been repackaged and renamed to `@medusajs/test-utils` with potentially breaking API changes and different internal implementations. Projects upgrading to Medusa v2.x must migrate their test setup to use the new package.
fix
For Medusa v2.x projects, install `@medusajs/test-utils` and consult the Medusa v2.x documentation for updated testing patterns. For existing v1.x projects, remain on `medusa-test-utils`.
affects: >=1.0.0
gotchaVersion 1.1.45 of `medusa-test-utils` lists `typeorm: ^0.2.43` as a peer dependency, which can lead to conflicts with Medusa core versions (e.g., v1.20.0+) that might require `typeorm: ^0.3.x`. This mismatch can cause dependency resolution issues or runtime errors related to TypeORM.
fix
Carefully manage `typeorm` versions in your `package.json` to ensure compatibility between `medusa-test-utils`, `@medusajs/medusa`, and any other TypeORM-dependent packages. Consider using `resolutions` (Yarn) or `overrides` (NPM/PNPM) if a direct upgrade is not feasible.
affects: 1.1.45
gotchaWhen running integration tests with `medusa-test-utils`, especially for HTTP routes, the test runner can produce verbose `console.log` output from `module-test-runner.js`. This noise can make debugging difficult and clutter CI logs.
fix
Monitor GitHub issues or Medusa documentation for updates regarding configurable logging. As a workaround, you might need to filter console output in your CI environment or, if possible, modify the test runner's source locally for development (not recommended for production). In later versions of `@medusajs/test-utils` (v2.7.1+), there's an open issue for making this configurable via `process.env.TEST_UTILS_VERBOSE`.
affects: >=1.0.0
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.
fix
Ensure `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.
fix
Increase 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.
Upgrade
Version history
1.1.45latest on npm
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.
Agent activity
29 hits · last 30 days
node
26
Resources
medusa-test-utils — npm install medusa-test-utils · libregistry