Testcontainers - DockerComposeEnvironment with Jest

Testcontainers - DockerComposeEnvironment with Jest

Overview

testcontainers provides programmatic Docker container lifecycle management for tests. This skill focuses on using DockerComposeEnvironment to start the project's docker-compose.yaml services (including Minio) inside Jest e2e tests via globalSetup and globalTeardown. The environment starts once before all tests and tears down after, making infrastructure available for the entire test run.

Key Concepts

• DockerComposeEnvironment: Starts services defined in a docker-compose file; supports wait strategies, partial startup, environment variable overrides
• globalSetup: Jest configuration option pointing to a module that exports setup() and teardown() functions - runs once before all test files in a separate process
• globalTeardown: Jest configuration option pointing to a module that exports a teardown function - runs once after all test files
• Wait.forLogMessage(msg): Wait strategy that polls container logs until a regex or string appears
• Wait.forHealthCheck(): Wait strategy that uses the service's docker-compose healthcheck
• getMappedPort(port): Returns the host port mapped to the given container port
• getHost(): Returns the host address for the container (typically localhost in most environments)
• environment.down(): Stops and removes all containers started by the environment

Documentation & References

Recommended Libraries & Tools

Recommended Stack

Use testcontainers@11.13.0 with DockerComposeEnvironment pointing at the project's docker-compose.yaml. Configure Jest jest.e2e.config.js with globalSetup and globalTeardown paths.

Patterns & Best Practices

Pattern 1: globalSetup + globalTeardown with DockerComposeEnvironment

When to use: E2E tests that require real infrastructure (Minio, databases) started once for the entire test suite.

Critical constraint: globalSetup runs in a completely separate Node.js process from the test files. Variables set in globalSetup are NOT accessible in tests via normal module scope. Use process.env to pass connection info to tests.

// test/e2e-global-setup.ts
import path from 'node:path'
import { DockerComposeEnvironment, Wait } from 'testcontainers'
import type { StartedDockerComposeEnvironment } from 'testcontainers'

let environment: StartedDockerComposeEnvironment

export async function setup(): Promise<void> {
  const composeFilePath = path.resolve(__dirname, '..')
  environment = await new DockerComposeEnvironment(composeFilePath, 'docker-compose.yaml')
    .withWaitStrategy('minio-1', Wait.forHealthCheck())
    .up(['minio'])  // Start only services needed for tests

  const minioContainer = environment.getContainer('minio-1')
  // Pass connection info to tests via process.env
  process.env.S3_ENDPOINT = `http://${minioContainer.getHost()}:${minioContainer.getMappedPort(9000)}`
  process.env.S3_ACCESS_KEY_ID = 'minioadmin'
  process.env.S3_SECRET_ACCESS_KEY = 'minioadmin'
  process.env.S3_BUCKET = 'analytics-data'
  process.env.S3_REGION = 'us-east-1'
}

export async function teardown(): Promise<void> {
  await environment?.down({ timeout: 10_000, removeVolumes: true })
}

Note on service container name: Docker Compose appends -1 (or the scale index) to the service name. A service named minio in docker-compose becomes minio-1 for getContainer('minio-1').

Pattern 2: Jest Config Integration

When to use: Configuring Jest e2e tests to use global setup.

// test/jest.e2e.config.js
const baseConfig = require('./jest.config.js')

module.exports = {
  ...baseConfig,
  testRegex: '\\.e2e-spec\\.ts$',
  globalSetup: '<rootDir>/test/e2e-global-setup.ts',
  globalTeardown: '<rootDir>/test/e2e-global-teardown.ts',
  setupFiles: [...(baseConfig.setupFiles ?? []), '<rootDir>/test/e2e-env-setup.ts'],
}

TypeScript globalSetup: Jest supports TypeScript globalSetup files via ts-jest transformer. Ensure ts-jest is configured in the base jest.config.js (it is in this project).

However, globalSetup / globalTeardown are loaded directly by Jest without the TypeScript transform. Options:

Option A: Separate setup and teardown files (simplest, avoids shared state):

// test/e2e-global-setup.ts - uses ts-node to run

Option B: Use ts-node for TypeScript globalSetup - configure ts-node in jest config or use @swc/jest:

// In jest.e2e.config.js - if ts-jest handles globalSetup
// Note: ts-jest does NOT transform globalSetup by default
// Use direct js compilation or add "transform" for globalSetup

Option C: Compile TS to JS first (most reliable for CI):

globalSetup: '<rootDir>/dist/test/e2e-global-setup.js',

Recommended for this project (ts-jest already configured): Use .ts files for globalSetup but ensure ts-node is registered or use the --require ts-node/register pattern. Alternatively, write globalSetup as a .js file wrapping a compiled .ts module.

Pattern 3: Wait Strategies

When to use: Services take time to initialize after docker start; without wait strategies tests may run before the service is ready.

new DockerComposeEnvironment(path, file)
  // Wait for a log message (reliable for services that log "ready"):
  .withWaitStrategy('minio-1', Wait.forLogMessage('API'))

  // Wait for docker-compose healthcheck to pass (requires healthcheck in compose file):
  .withWaitStrategy('minio-1', Wait.forHealthCheck())

  // Wait for HTTP endpoint to return 2xx:
  .withWaitStrategy('service-1', Wait.forHttp('/health', 8080).forStatusCode(200))

Pattern 4: Starting Only Specific Services

When to use: Full docker-compose has many services but e2e tests only need Minio.

const environment = await new DockerComposeEnvironment(path, 'docker-compose.yaml')
  .withWaitStrategy('minio-1', Wait.forHealthCheck())
  .up(['minio'])  // Only start minio service

Note: Also starts any services that minio depends on (via depends_on).

Pattern 5: Environment Variable Overrides

When to use: Override docker-compose environment variables for test-specific configuration.

const environment = await new DockerComposeEnvironment(path, 'docker-compose.yaml')
  .withEnvironment({ MINIO_ROOT_USER: 'testuser', MINIO_ROOT_PASSWORD: 'testpass' })
  .up(['minio'])

Similar Implementations

Example 1: Redis Global Setup (Vitest)

• Source: https://node.testcontainers.org/quickstart/global-setup/
• Approach: setup() starts container, stores in globalThis, teardown() stops it
• Applicability: Direct template for Minio setup; swap RedisContainer for DockerComposeEnvironment

Common Pitfalls & Solutions

Recommendations

1. Use Wait.forHealthCheck(): Requires a healthcheck in the docker-compose service definition. This is the most reliable wait strategy for Minio.
2. Pass connection info via process.env: This is the only way to share data from globalSetup to test files (they run in separate processes).
3. Start only needed services with .up(['service']): Avoid starting the full stack in e2e tests to reduce startup time.
4. Store environment in module-level variable: The globalSetup and globalTeardown can share state if exported from the same module - reference the environment instance for teardown.

Implementation Guidance

Jest e2e Config Update

// test/jest.e2e.config.js
const baseConfig = require('./jest.config.js')

module.exports = {
  ...baseConfig,
  testRegex: '\\.e2e-spec\\.ts$',
  globalSetup: '<rootDir>/test/e2e-global-setup.ts',
  setupFiles: [...(baseConfig.setupFiles ?? []), '<rootDir>/test/e2e-env-setup.ts'],
}

Integration Points

• globalSetup starts Minio before any test file runs
• process.env.S3_ENDPOINT (and other vars) set by globalSetup are read by e2e-env-setup.ts via configify
• teardown (exported from globalSetup module or separate file) stops containers after all tests
• NestJS app in tests reads config from process.env populated by the setup chain

Code Examples

Example 1: Complete e2e-global-setup.ts

import path from 'node:path'
import { DockerComposeEnvironment, Wait } from 'testcontainers'
import type { StartedDockerComposeEnvironment } from 'testcontainers'

let environment: StartedDockerComposeEnvironment | undefined

export async function setup(): Promise<void> {
  const composeFilePath = path.resolve(__dirname, '..')

  environment = await new DockerComposeEnvironment(composeFilePath, 'docker-compose.yaml')
    .withWaitStrategy('minio-1', Wait.forHealthCheck())
    .up(['minio', 'minio-init'])

  const minioContainer = environment.getContainer('minio-1')
  const minioHost = minioContainer.getHost()
  const minioPort = minioContainer.getMappedPort(9000)

  process.env.S3_ENDPOINT = `http://${minioHost}:${minioPort}`
  process.env.S3_ACCESS_KEY_ID = 'minioadmin'
  process.env.S3_SECRET_ACCESS_KEY = 'minioadmin'
  process.env.S3_BUCKET = 'analytics-data'
  process.env.S3_REGION = 'us-east-1'
}

export async function teardown(): Promise<void> {
  await environment?.down({ timeout: 10_000, removeVolumes: true })
}

Example 2: Using Container Info in Tests

// test/decision/evaluate-application.e2e-spec.ts
describe('AnalyticsInterceptor (e2e)', () => {
  it('persists analytics data to S3', async () => {
    // S3_ENDPOINT is set by globalSetup - use it to verify data was stored
    const s3Client = new S3Client({
      endpoint: process.env.S3_ENDPOINT,
      region: process.env.S3_REGION,
      credentials: {
        accessKeyId: process.env.S3_ACCESS_KEY_ID!,
        secretAccessKey: process.env.S3_SECRET_ACCESS_KEY!,
      },
      forcePathStyle: true,
    })
    // Query S3 to verify analytics data was stored
  })
})

Sources & Verification

Changelog