Testcontainers review: tutorial, pros and cons

Testcontainers talks to a container engine through the Docker API, the same API the docker command uses. On first use it looks for an engine through DOCKER_HOST, the default socket, Docker Desktop or its own configuration file, runs a few startup checks, pulls the image if needed and creates the container. Ports you ask it to expose are published on random free ports on the host, and the test asks for the real address with getHost and getMappedPort. That indirection is deliberate: it is what lets two builds on one machine run the same tests at once, and it is why any test that hardcodes localhost:5432 breaks.

A running container is not necessarily a ready service. Every container has a wait strategy that start() blocks on: by default it waits for the first exposed port to accept connections, and modules ship strategies suited to their service. For your own images, the Wait class offers strategies based on an HTTP endpoint, a log message or the image’s own Docker health check. Getting this right is most of the work of writing a reliable custom container, because a strategy that fires too early produces exactly the intermittent connection failures the library is meant to remove.

Alongside your containers, Testcontainers starts a small container called Ryuk, the resource reaper. Ryuk keeps a connection to the test process and, when that connection ends, removes the containers, networks and volumes created in that session. That is why a run interrupted by a crash or a killed IDE does not leave databases running for days. Ryuk needs access to the Docker socket and, in some environments, privileged mode. Where that is not allowed, as with rootless Podman, TESTCONTAINERS_RYUK_DISABLED=true turns it off, and cleanup then relies on the process exiting normally.

How long a container lives is the main lever on speed and isolation. With the JUnit 5 extension, an instance field annotated with @Container starts and stops for every test method; a static field starts once per test class. The singleton pattern goes further: a container started in a static block of a shared base class lives for the whole test run, and Ryuk removes it at the end. Reusable containers, which survive between runs, are documented as experimental and unsuitable for CI. Most suites settle on singletons for expensive services, with test data isolated per test.

Starting a database per test class is fine for ten classes and painful for two hundred. The singleton pattern from the Testcontainers docs starts the container once, in a static block of an abstract base class, and every test class that extends it reuses the same instance; Ryuk removes it when the run ends. The trade is isolation, which you get back at the data level: run each test in a transaction that rolls back, truncate the tables a test touches in a before-each hook, or give each test class its own schema. Because start() is called explicitly, do not also annotate the field with @Container, or the extension will stop it after the first class.

In a Spring Boot application, @ServiceConnection removes the property plumbing that older examples did with @DynamicPropertySource. Spring reads the container’s connection details and uses them for the data source, overriding any spring.datasource settings, so the test configuration contains nothing environment-specific. Add spring-boot-testcontainers alongside the Testcontainers modules. The static field gives one container per test class; combine it with the singleton base class above when several classes share the database. Spring caches application contexts between test classes with identical configuration, so keeping container definitions consistent across classes also avoids rebuilding the context.

GitHub-hosted Ubuntu runners have Docker, so a Testcontainers suite needs no special setup: check out, set up the JDK and run the build. Hosted macOS and Windows runners do not provide Docker for Linux containers, so keep these jobs on Linux. Sign in to Docker Hub or set TESTCONTAINERS_HUB_IMAGE_NAME_PREFIX to pull from a mirror, since shared runner IP addresses hit the anonymous pull limit. If the build itself runs inside a container, for example on a self-hosted Jenkins agent, the documented pattern is to mount the Docker socket and the project directory at the same path inside the build container, so Testcontainers starts sibling containers on the host engine.

Speed problems usually come from the number of container starts, not from the containers themselves, so count them before optimising anything else. Pin image tags so CI caches stay valid, and prefer small official images. Group tests that need the same set of services, and use singletons for anything slow to boot, such as Kafka or a search engine. Reusable containers, enabled with withReuse(true) plus testcontainers.reuse.enable=true in the user’s ~/.testcontainers.properties, keep a container alive between local runs and can cut the edit-run loop to almost nothing, but the docs mark them experimental and unsuited to CI, so keep them a local convenience. Once the environment is stable, checks.disable=true skips the startup checks.

The other implementations follow the same ideas with each language’s conventions: a generic container class, modules for common services, random host ports, a wait strategy and Ryuk. In Node.js, containers are started in beforeAll and stopped in afterAll, and modules are separate packages such as @testcontainers/postgresql or @testcontainers/redis. In Python, containers are context managers, so a with block guarantees the stop. Feature coverage differs between languages, and only the Java and Go libraries are sponsored by Docker, so check that the modules you need exist in your language before standardising on it.