Updated Jun 30, 2026

Testcontainers, From Zero

You wrote a beautiful mock of your database, every test is green, and then production falls over on a query the mock happily accepted. The mock told you what you wanted to hear. Testcontainers fixes that by booting a real Postgres, a real Redis, a real Kafka in a throwaway Docker container for the duration of your test run, then deleting it the moment you're done. Your tests talk to the actual engine, not your guess about how it behaves. No shared staging database to fight over, no leftover state between runs.

How to read this

Read the three phases in order. Phase 1 builds the mental model: why mocks lie and what a "throwaway container" really is. Phase 2 is the everyday loop: start a container, get its real port, point your code at it, clean up. Phase 3 is where it gets real: the Docker requirement, slow first runs, port collisions, and CI. Type the commands as you go; the muscle memory matters more than the prose.

The phases

  1. Why mocks lie and what a container gives you
  2. The everyday loop: start, connect, tear down
  3. Production reality: Docker, speed, and CI

Phase 1: Why mocks lie and what a container gives you