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