Module
Core
Proposal
The gap
The "Singleton containers" section in Manual container lifecycle control shows the static-initialiser pattern, and the JUnit 5 page documents @Testcontainers / @Container. Neither explains the failure that makes the singleton pattern necessary under @SpringBootTest, and the symptom is misleading enough that it costs people real time.
The failure
Spring caches the application context across test classes. @Testcontainers ties container lifecycle to the test class. Those two facts conflict:
- Test class A runs. The container starts. Spring builds a context pointing at the container's mapped port.
- Class A finishes.
@Testcontainers stops the container.
- Class B runs. Spring reuses the cached context, still pointing at the container that was just shut down.
- Every test in class B fails with connection errors.
The misleading part is that class A passes and class B fails, and the error mentions nothing about containers. It reads like test pollution or an ordering problem, so that is where people go looking first.
Current documentation
Manual container lifecycle control says only: "Sometimes it might be useful to define a container that is only started once for several test classes." The JUnit 5 page does not mention Spring at all. So the pattern is documented, but the reason for it is not.
Proposal
Add a short note to the Singleton containers section: under @SpringBootTest, container lifecycle has to outlive Spring's context cache. That is why the containers are started in a static initialiser and deliberately never stopped — Ryuk reaps them at JVM exit, so nothing leaks.
I hit this building a Spring Boot project with Postgres and RabbitMQ containers and lost a while to it. Happy to open a PR if you would take it.
Module
Core
Proposal
The gap
The "Singleton containers" section in Manual container lifecycle control shows the static-initialiser pattern, and the JUnit 5 page documents
@Testcontainers/@Container. Neither explains the failure that makes the singleton pattern necessary under@SpringBootTest, and the symptom is misleading enough that it costs people real time.The failure
Spring caches the application context across test classes.
@Testcontainersties container lifecycle to the test class. Those two facts conflict:@Testcontainersstops the container.The misleading part is that class A passes and class B fails, and the error mentions nothing about containers. It reads like test pollution or an ordering problem, so that is where people go looking first.
Current documentation
Manual container lifecycle control says only: "Sometimes it might be useful to define a container that is only started once for several test classes." The JUnit 5 page does not mention Spring at all. So the pattern is documented, but the reason for it is not.
Proposal
Add a short note to the Singleton containers section: under
@SpringBootTest, container lifecycle has to outlive Spring's context cache. That is why the containers are started in a static initialiser and deliberately never stopped — Ryuk reaps them at JVM exit, so nothing leaks.I hit this building a Spring Boot project with Postgres and RabbitMQ containers and lost a while to it. Happy to open a PR if you would take it.