{"id":14697,"library":"medusa-test-utils","title":"Medusa Test Utilities (v1.x)","description":"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.","status":"maintenance","version":"1.1.45","language":"javascript","source_language":"en","source_url":"https://github.com/medusajs/medusa","tags":["javascript","typescript"],"install":[{"cmd":"npm install medusa-test-utils","lang":"bash","label":"npm"},{"cmd":"yarn add medusa-test-utils","lang":"bash","label":"yarn"},{"cmd":"pnpm add medusa-test-utils","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used for making HTTP requests in API tests.","package":"axios","optional":false},{"reason":"Manages PostgreSQL database setup and teardown for isolated tests.","package":"pg-god","optional":false},{"reason":"Underpins the Medusa API server, necessary for testing API routes.","package":"express","optional":false},{"reason":"ORM used by Medusa v1.x for database interactions in tests.","package":"typeorm","optional":false},{"reason":"Dynamically assigns available ports for test servers.","package":"get-port","optional":false},{"reason":"Core Medusa application, essential for running integration tests against.","package":"@medusajs/medusa","optional":false},{"reason":"Provides SDK utilities for Medusa modules within the test environment.","package":"@medusajs/modules-sdk","optional":false}],"imports":[{"note":"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'.","wrong":"const { medusaIntegrationTestRunner } = require('medusa-test-utils')","symbol":"medusaIntegrationTestRunner","correct":"import { medusaIntegrationTestRunner } from 'medusa-test-utils'"},{"note":"Used for testing individual Medusa modules in isolation. For Medusa v2.x, use '@medusajs/test-utils'.","wrong":"import moduleIntegrationTestRunner from 'medusa-test-utils'","symbol":"moduleIntegrationTestRunner","correct":"import { moduleIntegrationTestRunner } from 'medusa-test-utils'"},{"note":"Directly initializes a test database instance. Typically handled internally by `medusaIntegrationTestRunner` but can be useful for granular control.","symbol":"initDb","correct":"import { initDb } from 'medusa-test-utils'"},{"note":"Drops the test database instance. Often paired with `initDb` in `beforeEach`/`afterEach` hooks for clean test runs.","symbol":"dropDb","correct":"import { dropDb } from 'medusa-test-utils'"}],"quickstart":{"code":"import { medusaIntegrationTestRunner } from 'medusa-test-utils';\nimport { jest } from '@jest/globals';\n\n// Set a longer timeout for integration tests due to database operations and server startup\njest.setTimeout(60 * 1000);\n\nmedusaIntegrationTestRunner({\n  testSuite: ({ db, api, getContainer }) => {\n    describe('Medusa API Endpoints', () => {\n      let productService;\n\n      beforeAll(async () => {\n        // Resolve a service from the Medusa container\n        productService = getContainer().resolve('productService');\n      });\n\n      it('should retrieve a product by ID', async () => {\n        // Example: Create a product and then retrieve it\n        const productData = {\n          title: 'Test Product',\n          description: 'A product for testing',\n          is_giftcard: false,\n          discountable: true,\n          status: 'published',\n          thumbnail: 'https://example.com/thumbnail.jpg',\n          options: [{ title: 'Size' }],\n          variants: [\n            {\n              title: 'Small',\n              prices: [{ currency_code: 'usd', amount: 1000 }],\n              options: { size: 'S' }\n            }\n          ]\n        };\n\n        const createdProduct = await productService.create(productData);\n        const retrievedProduct = await api.get(`/store/products/${createdProduct.id}`);\n\n        expect(retrievedProduct.status).toBe(200);\n        expect(retrievedProduct.data.product.id).toBe(createdProduct.id);\n        expect(retrievedProduct.data.product.title).toBe('Test Product');\n      });\n\n      it('should create a new order via API', async () => {\n        // This is a simplified example, a real test would involve more setup (customer, region, cart)\n        const payload = {\n          email: 'test@example.com',\n          items: [], // Assuming items would be added to a cart first\n          shipping_address: { address_1: '123 Main St', city: 'Anytown', province: 'Anystate', country_code: 'us', postal_code: '12345' },\n          billing_address: { address_1: '123 Main St', city: 'Anytown', province: 'Anystate', country_code: 'us', postal_code: '12345' },\n          region_id: 'reg_test_region' // Placeholder, would need to be a valid region ID\n        };\n        \n        // Note: Direct order creation via /store/orders is usually more complex (cart flow expected)\n        // This test primarily demonstrates API interaction, not full commerce flow validity.\n        const response = await api.post('/store/orders', payload);\n        // A successful order creation typically returns 200 or 201 status\n        // Depending on Medusa configuration, direct order creation might be restricted.\n        // For robust testing, a cart-to-checkout flow is usually preferred.\n        expect(response.status).toBeGreaterThanOrEqual(200);\n        expect(response.status).toBeLessThan(300);\n        expect(response.data.order).toBeDefined();\n      });\n    });\n  },\n});","lang":"typescript","description":"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."},"warnings":[{"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`.","message":"The `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.","severity":"breaking","affected_versions":">=1.0.0"},{"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.","message":"Version 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.","severity":"gotcha","affected_versions":"1.1.45"},{"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`.","message":"When 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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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`.","cause":"The `typeorm` package is a peer dependency but is not installed or the installed version conflicts with what `medusa-test-utils` expects.","error":"Error: Cannot find module 'typeorm' from 'medusa-test-utils'"},{"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.","cause":"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.","error":"Timeout - Async callback was not invoked within the 60000 ms timeout specified by jest.setTimeout."}],"ecosystem":"npm"}