Testcontainers: A Real Database During Your Tests

The team has three options, and all three have problems. A shared PostgreSQL database on an integration server: two simultaneous runs step on each other, one test leaves a row behind and breaks its neighbor, and nobody dares reset it. A local database installed on each workstation: everyone has their own version, extensions, and a slightly drifted schema, and onboarding a new developer costs half a day. An in-memory database like H2: fast, uniform, and blind to anything specific to PostgreSQL, as we saw in the first lesson.

Testcontainers offers a fourth way: the test suite itself starts a PostgreSQL Docker container, applies the schema, runs the tests, then destroys the container. The version is the one declared in the code, so it's identical everywhere. Isolation is total, so parallel execution is possible. And because it's a real PostgreSQL, jsonb, ILIKE, GIN indexes, and exclusion constraints behave exactly as they do in production. The price to pay is real — Docker becomes a dependency of the suite, and startup costs time — and most of this lesson is precisely about how to contain that price.