Docker Testcontainers

Docker Testcontainers

This skill makes an AI agent write integration tests that spin up real databases, caches, and message brokers in disposable Docker containers via the testcontainers Node.js library - instead of mocking them or depending on a shared dev server. Trigger it when tests need a real Postgres, Redis, Kafka, or any service with Docker image, when a repo already imports testcontainers, or when the user complains that mocked repositories keep hiding SQL and serialization bugs.

Core Principles

1. Test against the real engine, not a lookalike. SQLite in place of Postgres misses JSONB operators, transaction isolation behavior, and case-sensitivity rules. Run the exact image and major version production uses (postgres:16-alpine, not latest).
2. Always use mapped ports. Containers bind to random free host ports. Read them with container.getMappedPort(5432) and container.getHost(); hardcoding localhost:5432 collides with local services and parallel CI jobs.
3. Wait strategies, not sleeps. A started container is not a ready service. Use Wait.forLogMessage, Wait.forListeningPorts, Wait.forHttp, or Wait.forHealthCheck so tests begin exactly when the dependency is usable.
4. One container per suite, clean state per test. Container startup costs seconds; start in beforeAll, then reset state between tests with TRUNCATE, FLUSHALL, or transaction rollbacks - not by restarting the container.
5. Cleanup must survive failures. Stop containers in afterAll; Testcontainers' Ryuk sidecar reaps anything left behind if the process dies, so never disable it in CI.
6. Pin image tags. redis:latest changing under you turns a green suite red with zero code changes. Pin to a major-minor tag and upgrade deliberately.

Setup

npm install --save-dev testcontainers @testcontainers/postgresql
# Requires a running Docker daemon (Docker Desktop, Colima, or CI's dockerd)
docker info

Patterns

1. GenericContainer: Redis with a wait strategy

// tests/cache.integration.test.ts
import { GenericContainer, StartedTestContainer, Wait } from 'testcontainers';
import { createClient, RedisClientType } from 'redis';

describe('rate limiter backed by Redis', () => {
  let container: StartedTestContainer;
  let client: RedisClientType;

  beforeAll(async () => {
    container = await new GenericContainer('redis:7.4-alpine')
      .withExposedPorts(6379)
      .withWaitStrategy(Wait.forLogMessage('Ready to accept connections'))
      .withStartupTimeout(30_000)
      .start();

    client = createClient({
      url: `redis://${container.getHost()}:${container.getMappedPort(6379)}`,
    });
    await client.connect();
  }, 60_000);

  afterEach(async () => {
    await client.flushAll();
  });

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

  it('blocks the 6th request within a window', async () => {
    for (let i = 0; i < 5; i++) {
      expect(await isAllowed(client, 'user-1')).toBe(true);
    }
    expect(await isAllowed(client, 'user-1')).toBe(false);
  });
});

async function isAllowed(client: RedisClientType, key: string): Promise<boolean> {
  const count = await client.incr(`rl:${key}`);
  if (count === 1) await client.expire(`rl:${key}`, 60);
  return count <= 5;
}

2. Module container: Postgres with real migrations

// tests/orders.repository.integration.test.ts
import { PostgreSqlContainer, StartedPostgreSqlContainer } from '@testcontainers/postgresql';
import { Pool } from 'pg';
import { runMigrations } from '../src/db/migrate';
import { OrdersRepository } from '../src/db/orders-repository';

let pg: StartedPostgreSqlContainer;
let pool: Pool;
let repo: OrdersRepository;

beforeAll(async () => {
  pg = await new PostgreSqlContainer('postgres:16-alpine')
    .withDatabase('shop_test')
    .withUsername('shop')
    .withPassword('shop')
    .start();

  pool = new Pool({ connectionString: pg.getConnectionUri() });
  await runMigrations(pool); // the SAME migrations production runs
  repo = new OrdersRepository(pool);
}, 90_000);

beforeEach(async () => {
  await pool.query('TRUNCATE orders RESTART IDENTITY CASCADE');
});

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

it('persists JSONB line items and filters with the @> operator', async () => {
  await repo.create({ customerId: 'c1', items: [{ sku: 'SKU-1', qty: 2 }] });
  await repo.create({ customerId: 'c2', items: [{ sku: 'SKU-9', qty: 1 }] });

  const matches = await repo.findByItemSku('SKU-1'); // uses items @> '[{"sku":"SKU-1"}]'
  expect(matches).toHaveLength(1);
  expect(matches[0].customerId).toBe('c1');
});

3. Docker Compose environment for multi-service tests

// tests/api.e2e.integration.test.ts
import { DockerComposeEnvironment, StartedDockerComposeEnvironment, Wait } from 'testcontainers';

let environment: StartedDockerComposeEnvironment;
let apiBaseUrl: string;

beforeAll(async () => {
  environment = await new DockerComposeEnvironment('.', 'docker-compose.test.yml')
    .withWaitStrategy('api-1', Wait.forHttp('/health', 3000).forStatusCode(200))
    .withWaitStrategy('postgres-1', Wait.forListeningPorts())
    .up(['api', 'postgres']);

  const api = environment.getContainer('api-1');
  apiBaseUrl = `http://${api.getHost()}:${api.getMappedPort(3000)}`;
}, 120_000);

afterAll(async () => {
  await environment.down({ timeout: 10_000 });
});

it('serves orders through the full stack', async () => {
  const created = await fetch(`${apiBaseUrl}/orders`, {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify({ sku: 'SKU-1', qty: 1 }),
  });
  expect(created.status).toBe(201);

  const list = await fetch(`${apiBaseUrl}/orders`);
  const orders = (await list.json()) as Array<{ sku: string }>;
  expect(orders.map((o) => o.sku)).toContain('SKU-1');
});

4. Faster local loops: container reuse and env wiring

// Opt-in reuse keeps the container alive between test runs locally.
// Requires testcontainers.reuse.enable=true in ~/.testcontainers.properties
const pg = await new PostgreSqlContainer('postgres:16-alpine')
  .withDatabase('shop_test')
  .withReuse()
  .start();

// Hand the dynamic URL to the code under test the same way prod config does
process.env.DATABASE_URL = pg.getConnectionUri();

// Copying fixtures and running one-off commands inside a container
const container = await new GenericContainer('postgres:16-alpine')
  .withEnvironment({ POSTGRES_PASSWORD: 'shop' })
  .withCopyFilesToContainer([
    { source: './tests/fixtures/seed.sql', target: '/docker-entrypoint-initdb.d/seed.sql' },
  ])
  .withExposedPorts(5432)
  .start();

const { exitCode, output } = await container.exec(['psql', '-U', 'postgres', '-c', 'SELECT 1']);
expect(exitCode).toBe(0);
expect(output).toContain('1 row');

Best Practices

• Raise the test framework timeout for beforeAll hooks that pull images (60-120 seconds); the first CI run downloads layers.
• Use module packages (@testcontainers/postgresql, @testcontainers/kafka, @testcontainers/elasticsearch) before reaching for GenericContainer; they encode correct wait strategies and credentials.
• In CI, pre-pull hot images (docker pull postgres:16-alpine) in a cached step to cut suite time.
• Keep integration tests in a separate script ("test:integration": "vitest run --config vitest.integration.config.ts") so unit tests stay Docker-free and fast.
• Pass connection details via the same env vars production reads (DATABASE_URL, REDIS_URL); never add test-only config paths to the app.
• Log container output on failure with container.logs() streamed to the test reporter when diagnosing startup issues.

Anti-Patterns

• await sleep(3000) after start() instead of a wait strategy - slow on good days, flaky on loaded CI runners.
• One shared, long-lived "test database" server that every developer and CI job mutates; state leaks make failures non-reproducible.
• Restarting the container between tests for isolation; truncate tables or roll back transactions instead and save minutes per suite.
• Mocking the repository layer in "integration" tests - the SQL is exactly the thing that needs testing.
• Using :latest tags or a different database engine than production.
• Disabling Ryuk (TESTCONTAINERS_RYUK_DISABLED=true) in CI to "fix" a permissions issue, then leaking containers until the runner dies; fix the Docker socket permissions instead.

When to Trigger This Skill

• The user asks for integration tests against a real Postgres, MySQL, MongoDB, Redis, Kafka, RabbitMQ, Elasticsearch, or LocalStack instance.
• A repository imports testcontainers or @testcontainers/*, or contains a docker-compose.test.yml.
• Mock-heavy tests keep missing SQL syntax errors, migration drift, or serialization bugs that only a real engine catches.
• CI needs hermetic, parallel-safe integration tests without a provisioned shared database.
• Repository, DAO, or ORM code (Drizzle, Prisma, Knex, TypeORM) needs verification against the production database engine and real migrations.