How to Choose a Wait Strategy in Testcontainers for CI
A container being started is not the same as being ready; a wait strategy blocks the test until a port, log line, or health check confirms readiness.
Choose Wait.forListeningPort() for a simple port, Wait.forLogMessage() when a startup log signals readiness, or Wait.forHealthcheck() when the image defines a HEALTHCHECK. Set a timeout to fail fast in CI.
Options
| Strategy | Use when |
|---|---|
| Wait.forListeningPort() | The service is ready as soon as a TCP port accepts connections |
| Wait.forLogMessage(regex, n) | A specific log line marks readiness (n occurrences) |
| Wait.forHttp(path) | An HTTP endpoint returns a ready status |
| Wait.forHealthcheck() | The image defines a Docker HEALTHCHECK |
Java example
ApiIT.java
new GenericContainer<>("my-api:latest")
.withExposedPorts(8080)
.waitingFor(
Wait.forLogMessage(".*Started Application.*", 1)
.withStartupTimeout(Duration.ofMinutes(2)));Gotchas
- A too-short timeout on a slow CI pull surfaces as "Timed out waiting for container".
- A port opening early does not always mean the app finished booting; a log or HTTP wait is stricter.
Related guides
How to Use GenericContainer for a Custom Image in TestcontainersRun any Docker image in tests with GenericContainer, setting exposed ports, env vars, and a wait strategy, th…
How to Speed Up Testcontainers Runs in CICut Testcontainers CI time by sharing containers per class, running tests in parallel, caching images, and av…