Gem databasesdocker

Testcontainers

Spin up real databases and services in Docker from inside your tests.

Would you recommend Testcontainers?

No votes yet. Tried it? Be the first to say.

One vote per person. No account needed.

Overview

Testcontainers libraries start throwaway containers (Postgres, Redis, Kafka and more) for a test run and clean them up afterwards. Your integration tests hit the real thing instead of mocks.

Instead of

Mocked database layers, shared test databases, hand-written docker-compose setup

Reach for it when

Bugs slip through because your tests mock the database or message broker.

Key features

  • Real dependencies in tests

    Start Postgres, MySQL, Redis, Kafka, MongoDB, LocalStack and many more in Docker, straight from test code.

  • Ready-made modules

    Pre-configured modules give you a typed container with helpers like connection strings and credentials.

  • Wait strategies

    Tests only start once the service is actually ready (log message, port, HTTP health check), not just when the container starts.

  • Automatic clean-up

    A small "reaper" container removes everything after the run, even if your test process crashes.

  • Compose support

    Spin up an existing docker-compose file for a test run when you need several services together.

  • Many languages

    The same model and module names across Java, Go, .NET, Node.js, Python, Rust and others.

In depth

How it works

Testcontainers talks to the Docker API from inside your test process. When a test asks for, say, a Postgres container, the library pulls the image if needed, starts it on a random free port, waits until the database is genuinely accepting connections, and hands you the connection details. A small companion container watches your test session and removes everything when it ends, so crashed runs don't leave containers behind.

A Node.js example with Vitest

ts
import { PostgreSqlContainer, type StartedPostgreSqlContainer } from '@testcontainers/postgresql';
import { afterAll, beforeAll, expect, test } from 'vitest';
import pg from 'pg';

let container: StartedPostgreSqlContainer;
let client: pg.Client;

beforeAll(async () => {
  container = await new PostgreSqlContainer('postgres:16-alpine').start();
  client = new pg.Client({ connectionString: container.getConnectionUri() });
  await client.connect();
  // run your migrations here
}, 60_000);

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

test('stores and reads a user', async () => {
  await client.query('CREATE TABLE users (id serial PRIMARY KEY, name text)');
  await client.query("INSERT INTO users (name) VALUES ('Ada')");
  const { rows } = await client.query('SELECT name FROM users');
  expect(rows[0].name).toBe('Ada');
});

Tips

  • Pin image versions (postgres:16-alpine, not postgres:latest) so tests are reproducible.
  • Run migrations once per container, then wrap each test in a transaction you roll back, which is much faster than recreating tables.
  • In GitHub Actions, Docker is available on Ubuntu runners out of the box.

Strengths

  • Integration tests hit the same database engine and version you run in production, which catches SQL, migration and driver bugs that mocks hide.
  • Every test run gets a fresh, isolated environment, so there's no shared test database to drift or clash.
  • Works the same on laptops and CI as long as Docker is available.
  • Removes hand-written setup scripts and "start the DB first" instructions from READMEs.

Watch out for

  • Needs a Docker-compatible runtime in CI and locally, and Docker-in-Docker setups can take some configuring.
  • Container start-up adds seconds per suite; share one container per test file or suite rather than per test.
  • First runs pull images, so cache them in CI to keep pipelines fast.
  • It's still slower than unit tests, so keep it for the integration layer.

Try it in a few minutes

Terminal
npm i -D testcontainers @testcontainers/postgresql
// in a test:
// const pg = await new PostgreSqlContainer("postgres:16").start();

Alternatives

docker compose test environment

Start services before the test run. Simpler, but shared state and manual lifecycle.

In-memory fakes (pg-mem, H2, SQLite)

Very fast, but behave differently from the real engine in subtle ways.

Mocking the data layer

Fast and isolated, but tests the mock rather than your SQL.

Related tools

Other tools that share topics with Testcontainers.

Mailpit

mailpit.axllent.org
Gem

A local SMTP server and web inbox for testing the emails your app sends.

Instead of MailHog (unmaintained), sending test emails to your own address

Bun

bun.sh
Gem

A fast JavaScript runtime, package manager, bundler and test runner in one binary.

Instead of Node.js + npm + ts-node + Jest + a bundler

Kiri

runkiri.com
New

A small, fast container runtime for macOS, Windows and Linux that replaces Docker Desktop.

Instead of Docker Desktop