Development & Testing

Testcontainers

Run real databases, message brokers, and services in Docker containers for reliable integration tests.

Claude Code Codex Cursor Gemini CLI

Overview

Testcontainers provides a programmatic API to spin up Docker containers for integration testing. Instead of mocking your database or external services, you run the real thing in a container that is created before each test suite and destroyed after. This gives you confidence that your code works with actual infrastructure, not just mocked interfaces.

Your AI agent can write test setups that start PostgreSQL, Redis, Kafka, Elasticsearch, or any Dockerized service. The Testcontainers library handles container lifecycle management, port mapping, and readiness detection automatically. For Node.js projects, the testcontainers package provides a fluent API, while Python projects use the testcontainers-python package.

The key advantage of Testcontainers is test reliability. Your integration tests run against real databases with real query execution, real connection handling, and real data serialization. Your AI agent can configure container reuse between test suites for faster execution, set up database migrations inside containers, and seed test data for consistent test scenarios.

Who Is This For?

Backend developers testing database queries against real PostgreSQL or MySQL instances
Teams testing message queue consumers with real Kafka or RabbitMQ brokers
Engineers validating Redis caching logic with actual Redis containers
CI/CD pipelines running integration tests with Docker-based dependencies

Installation

Setup for Claude Code

npm install -D testcontainers
Docker must be running locally
Claude Code writes test setups with container lifecycle management

Configuration

// tests/db.integration.test.ts
import { PostgreSqlContainer } from "@testcontainers/postgresql";

let container;
beforeAll(async () => {
  container = await new PostgreSqlContainer("postgres:16")
    .withDatabase("testdb")
    .start();
  process.env.DATABASE_URL = container.getConnectionUri();
}, 60000);

afterAll(async () => {
  await container.stop();
});