Testcontainers: Real Database Integration Testing for Node.js

Testcontainers is a Node.js library that spins up real Docker containers — PostgreSQL, Redis, MongoDB, Kafka, and more — for use inside your test suite. It solves the fundamental problem with mocked databases: the mock passes, but the real query fails in production. With Testcontainers, each test run uses a fresh, real container that starts before tests and stops when they finish.

Why Real Containers Beat Mocks

Mocks simulate a database by returning hardcoded values. They cannot catch: SQL syntax errors, constraint violations, index performance, serialization differences between pg-node and raw Postgres, or Redis EXPIRE behaviour. A mock-based test that passes can coexist with a production bug for months.

Testcontainers runs the same Docker image you use in production. Your queries, migrations, and ORM code run against the real engine. If the test passes, it works. If it fails, it fails now — not in production at 3am.

Installation

npm install --save-dev testcontainers

# Requires Docker to be running locally or in CI
docker --version  # verify Docker is available

PostgreSQL Container with Jest

// tests/user.integration.test.ts
import { PostgreSqlContainer } from 'testcontainers';
import { Pool } from 'pg';

let container: PostgreSqlContainer;
let pool: Pool;

beforeAll(async () => {
  container = await new PostgreSqlContainer('postgres:16')
    .withDatabase('testdb')
    .withUsername('testuser')
    .withPassword('testpass')
    .start();

  pool = new Pool({ connectionString: container.getConnectionUri() });
  await pool.query('CREATE TABLE users (id SERIAL, name TEXT)');
}, 60_000);  // allow 60s for image pull

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

it('inserts and retrieves a user', async () => {
  await pool.query("INSERT INTO users (name) VALUES ('Alice')");
  const result = await pool.query('SELECT name FROM users');
  expect(result.rows[0].name).toBe('Alice');
});

Redis Container for Cache Tests

import { RedisContainer } from 'testcontainers';
import { createClient } from 'redis';

let container: RedisContainer;
let client: ReturnType<typeof createClient>;

beforeAll(async () => {
  container = await new RedisContainer('redis:7').start();
  client = createClient({ url: container.getConnectionUrl() });
  await client.connect();
}, 30_000);

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

it('sets and gets a key with TTL', async () => {
  await client.set('session:abc', 'user123', { EX: 300 });
  const val = await client.get('session:abc');
  expect(val).toBe('user123');
  const ttl = await client.ttl('session:abc');
  expect(ttl).toBeGreaterThan(0);
});

Container Lifecycle and Parallel Isolation

// Start multiple containers in parallel:
const [pg, redis] = await Promise.all([
  new PostgreSqlContainer().start(),
  new RedisContainer().start(),
]);

// Each container gets a random host port — no conflicts
console.log(pg.getMappedPort(5432));   // e.g., 54321
console.log(redis.getMappedPort(6379)); // e.g., 63791

Using with Vitest

// vitest.config.ts
export default defineConfig({
  test: {
    testTimeout: 60_000,  // containers need startup time
    hookTimeout: 60_000,
    pool: 'forks',        // required for Docker socket access in Vitest
  }
});

Testcontainers vs docker-compose for Tests