[Feature]: Stabilize Reusable Containers feature and make it GA

Bắt đầu bằng cách xem xét entry point hiện có của các container có thể tái sử dụng, .withReuse(true), và cấu hình testcontainers.reuse.enable=true, sau đó đọc các issue liên quan #3081 và #7097. Để được coi là hoàn tất, cần giải quyết hoặc ghi lại rõ ràng về networking, việc dọn dẹp tài nguyên, hành vi opt-in và khả năng tương thích với CI trước khi tuyên bố feature là GA.

Module

Core

Problem

The reusable containers feature (.withReuse(true)) has been available as an experimental/alpha feature since its introduction in 2019 via PR #1781. Despite its clear value and widespread adoption by the community, it remains in this unstable state.

Several critical issues prevent its safe and reliable use in production-grade CI/CD pipelines, as explicitly stated in the official documentation:

"Reusable containers are not suited for CI usage and as an experimental feature not all Testcontainers features are fully working (e.g., resource cleanup or networking)."

The most significant unresolved problems include:

1. Networking support — The documentation still lists networking as an area that is not fully working with reusable containers. There has been an issue discussing reusable networks, but its current status is unclear. Even if some fixes have been merged, it's not evident whether the feature now fully supports custom networks or whether there are still edge cases that break reuse.

2. Resource cleanup — The documentation also states that resource cleanup is not fully reliable with reusable containers. A related bug report has been closed, but the comments indicate that the underlying problem may not be completely resolved. Users still report containers not being cleaned up properly between test runs, leading to errors and flooded logs.

3. Explicit opt-in friction — The feature requires both .withReuse(true) in code and testcontainers.reuse.enable=true in ~/.testcontainers.properties (classpath properties are intentionally not supported). While this explicit opt-in is appropriate for an experimental feature, it adds unnecessary friction for users who want to safely adopt reuse in appropriate environments.

4. CI incompatibility — The documentation explicitly states that reusable containers are not suited for CI usage. This is a significant limitation given that many teams would benefit from faster test execution in CI environments (especially on self-hosted runners with persistent Docker daemons).

Solution

We propose that the Testcontainers team prioritize making the Reusable Containers feature Generally Available (GA) by addressing the blockers above. Specifically:

1. Clarify and complete networking support — We request that the team clarify the current status of networking support for reusable containers. If the feature is not yet fully implemented (e.g., custom networks still cause hash mismatches), we ask that it be completed. If it is already implemented, we ask that the documentation be updated to reflect that and remove the warning about networking limitations.

2. Clarify and complete resource cleanup support — Similarly, we ask that the team confirm whether resource cleanup issues are fully resolved. If not, we request that the remaining problems be fixed. If they are resolved, the documentation should be updated to remove the caveat about resource cleanup.

3. Re-evaluate the opt-in mechanism — Consider whether classpath properties could be supported for environments where reuse is always desired (e.g., local development), while keeping the explicit opt-in for safety.

4. Re-evaluate CI compatibility — Investigate whether reuse could be made safe for CI environments, or at least provide clear guidance and workarounds for teams that want to use it in CI.

Benefit

Stabilizing this feature would deliver significant value to the entire Testcontainers ecosystem:

• Massive performance improvements — Reusing containers shaves off container start times, dramatically speeding up test suites. This is especially valuable for large integration test suites with many containers.

• Better local development experience — Developers can run tests faster and with less resource consumption, improving productivity.

• Reduced CI costs — Faster test execution means shorter CI build times and lower infrastructure costs.

• Increased adoption — Many users are hesitant to use the feature because of its experimental status. Making it GA would encourage broader adoption and unlock its benefits for more projects.

• Cleaner code — The current workarounds (e.g., manual Docker client checks, reflection to modify internal objects) are fragile and error-prone. A stable, well-documented feature would eliminate the need for these hacks.

Alternatives

Users currently have several workarounds, but none are ideal:

1. Singleton containers in test suites — Define a container once and reuse it across tests within the same JVM instance. This works but does not persist across separate test runs or builds.

2. Manual Docker management — Use the Docker client directly to check if a container exists and reuse it manually. This is fragile, requires extensive boilerplate, and often involves reflection to modify internal Testcontainers objects.

3. External container orchestration — Run containers outside of Testcontainers (e.g., via Docker Compose or a separate service) and connect tests to them. This loses many of Testcontainers' benefits (automatic port mapping, lifecycle management, etc.) and complicates the test setup.

None of these alternatives provide the seamless, reliable experience that a stable, GA implementation would offer.

Thank you for maintaining this excellent project! We believe that stabilizing the Reusable Containers feature would be a significant milestone and would greatly benefit the community. We're happy to help with testing, documentation, or even contributing PRs if given guidance on the preferred approach.

Would you like to help contributing this feature?

Yes