Document why singleton containers are needed under Spring's test context cache - #11968

🏁 Script executed:

#!/bin/bash
printf '%s\n' '--- target document ---'
sed -n '35,70p' docs/test_framework_integration/manual_lifecycle_control.md
printf '%s\n' '--- relevant references ---'
rg -n -i 'Spring|Testcontainers|context cache|`@Container`|`@Testcontainers`|Ryuk|manual lifecycle' docs README.md .github 2>/dev/null | head -200
printf '%s\n' '--- version declarations ---'
rg -n -i 'spring-boot|springframework|testcontainers|junit.jupiter' --glob 'pom.xml' --glob 'build.gradle*' --glob 'gradle.properties' --glob '*.toml' --glob '*.yaml' --glob '*.yml' --glob '*.json' . 2>/dev/null | head -200

Repository: testcontainers/testcontainers-java

Length of output: 50392

🌐 Web query:

Spring Framework TestContext context cache same context cache key official documentation

💡 Result:

In the Spring TestContext Framework, an ApplicationContext is uniquely identified and cached based on a combination of specific configuration parameters used to load it [1][2]. The framework uses these parameters to generate a unique key under which the context is stored in a static cache [1][3]. The cache key is built using the following configuration parameters [1][4]: - Locations (from @ContextConfiguration) [1][5] - Classes (from @ContextConfiguration) [4][5] - Context Initializer Classes (from @ContextConfiguration) [4][5] - Context Customizers (from ContextCustomizerFactory): This category includes @DynamicPropertySource methods, bean overrides (such as @TestBean, @MockitoBean, @MockitoSpyBean), and various features from Spring Boot's testing support [1][4]. - Context Loader (from @ContextConfiguration) [1][2] - Parent Context (from @ContextHierarchy) [4][5] - Active Profiles (from @ActiveProfiles) [4][5] - Property Source Descriptors and Properties (from @TestPropertySource) [4][5] - Resource Base Path (from @WebAppConfiguration) [4][5] The ContextCache interface maintains these contexts, using MergedContextConfiguration instances as the actual keys for the cache [6]. If multiple test classes share the same configuration parameters—meaning they produce an identical cache key—they will share the same ApplicationContext, which avoids the overhead of reloading the context for each test class [1][3].

Citations:

• 1: https://docs.spring.io/spring/reference/testing/testcontext-framework/ctx-management/caching.html
• 2: https://docs.spring.io/spring-framework/reference/testing/testcontext-framework/ctx-management/caching.html
• 3: https://docs.spring.io/spring-framework/reference/6.2/testing/testcontext-framework/ctx-management/caching.html
• 4: https://github.com/spring-projects/spring-framework/blob/v7.0.8/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/caching.adoc
• 5: https://github.com/spring-projects/spring-framework/blob/v6.2.17/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/caching.adoc
• 6: https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/test/context/cache/ContextCache.html

🌐 Web query:

Testcontainers Java JUnit 5 @container static instance lifecycle non-static official documentation

💡 Result:

In the Testcontainers JUnit 5 integration, the lifecycle of a container annotated with @Container is determined by whether the field is declared as static or non-static [1][2]. This functionality is activated when the test class is annotated with @Testcontainers [1][3]. Static @Container Fields Containers declared as static fields are shared between all test methods within the same test class [1][2]. They are started once before any test method in that class executes and are stopped only after the last test method in that class has executed [1][2]. This is generally the preferred approach when multiple tests in a class require the same container, as it reduces resource overhead [3]. Non-static (Instance) @Container Fields Containers declared as instance fields (non-static) are managed for each individual test method [1][2]. They are started before each test method and stopped after each test method [1][2]. Because this cycle repeats for every test, it is more resource-intensive and is typically only used when isolation between tests is strictly required [3]. Important Considerations - Shared containers cannot be declared inside nested test classes, as those classes must be non-static and thus cannot hold static fields [1][4]. - The @Testcontainers extension is designed for sequential test execution; using it with parallel test execution is not supported and may lead to unintended side effects [1][2]. - If you need to share a container across multiple different test classes, you should use the singleton container pattern (often implemented with a static initializer in a base class) rather than the @Testcontainers/@container annotations [3][5][6]. Mixing these approaches can lead to configuration errors where containers are stopped prematurely [3][7].

Citations:

• 1: https://java.testcontainers.org/test_framework_integration/junit_5/
• 2: https://github.com/testcontainers/testcontainers-java/blob/main/modules/junit-jupiter/src/main/java/org/testcontainers/junit/jupiter/Testcontainers.java
• 3: https://docs.docker.com/guides/testcontainers-java-lifecycle/extension-annotations/
• 4: https://github.com/testcontainers/testcontainers-java/blob/master/docs/test_framework_integration/junit_5.md
• 5: https://docs.docker.com/guides/testcontainers-java-lifecycle/lifecycle-callbacks/
• 6: https://docs.docker.com/guides/testcontainers-java-lifecycle/
• 7: https://docs.spring.io/spring-boot/reference/testing/testcontainers.html

🏁 Script executed:

#!/bin/bash
set -eu
file="docs/test_framework_integration/manual_lifecycle_control.md"
printf '%s\n' '--- target document ---'
cat -n "$file"
printf '%s\n' '--- Testcontainers/Ryuk references ---'
rg -n -i 'Ryuk|TESTCONTAINERS_RYUK|`@Container`|static|lifecycle|Spring' . \
  -g '!node_modules' -g '!dist' -g '!build' | head -250
printf '%s\n' '--- dependency/version references ---'
rg -n -i 'testcontainers|spring boot|springframework' . \
  -g 'pom.xml' -g 'build.gradle*' -g 'gradle.properties' -g '*.md' -g '*.yml' -g '*.yaml' \
  | head -250

Repository: testcontainers/testcontainers-java

Length of output: 50392

🌐 Web query:

Testcontainers Ryuk enabled running JVM exits container cleanup official documentation

💡 Result:

In Testcontainers, Ryuk is a specialized sidecar container responsible for the fail-safe cleanup of Docker resources (containers, networks, volumes) created during a test session [1][2]. It ensures that resources are removed even if the JVM process terminates unexpectedly or crashes [1][3]. Key facts about Ryuk and JVM exits: 1. Functionality: When Testcontainers starts, it initiates the Ryuk container [1][3]. Throughout the test execution, Testcontainers connects to Ryuk and sends filters identifying the resources to be tracked. If the JVM exits normally or through a shutdown hook, Ryuk proceeds to remove the associated resources [1][3]. 2. JVM Shutdown Hooks: Testcontainers registers a JVM shutdown hook to manage the lifecycle of the Ryuk container itself [1][4]. If the JVM process is killed abruptly (e.g., via kill -9), the shutdown hook may not run, which can lead to "dangling" containers if Ryuk was not able to perform its cleanup tasks before the abrupt termination [1]. 3. Disabling Ryuk: Ryuk is enabled by default [1]. In specific environments (such as those where privileged containers are restricted or where external cleanup mechanisms are already in place), Ryuk can be disabled by setting the environment variable TESTCONTAINERS_RYUK_DISABLED to true [1][5][6]. Recent updates have also added support for a corresponding configuration property, ryuk.disabled=true, which can be set in the testcontainers.properties file [1][7]. 4. Important Considerations: - When Ryuk is disabled, Testcontainers will still attempt to perform cleanup at JVM shutdown, but this relies on the JVM's ability to execute its shutdown hooks [1]. - If you disable Ryuk in an environment without an alternative, automatic cleanup mechanism, you may accumulate orphaned Docker resources over time [1]. - Ryuk requires the ability to start a privileged container in many environments [1][8]. If this is not permitted, disabling it is often the required path [1][6]. Top results: [1][8][3][7]

Citations:

• 1: https://java.testcontainers.org/features/configuration/
• 2: https://github.com/testcontainers/moby-ryuk
• 3: https://docs.docker.com/guides/testcontainers-java-lifecycle/
• 4: [Bug]: Shutdown hook in RyukResourceReaper prevents a graceful shutdown with spring framework #8558
• 5: https://node.testcontainers.org/configuration/
• 6: https://golang.testcontainers.org/features/configuration/
• 7: Add property ryuk.disabled #11414
• 8: https://github.com/testcontainers/testcontainers-go/blob/6abb5710/docs/features/configuration.md

🏁 Script executed:

#!/bin/bash
set -eu
printf '%s\n' '--- Ryuk resource reaper implementation ---'
cat -n core/src/main/java/org/testcontainers/utility/RyukResourceReaper.java | sed -n '1,180p'
printf '%s\n' '--- resource registration and shutdown handling ---'
cat -n core/src/main/java/org/testcontainers/utility/ResourceReaper.java | sed -n '1,220p'
printf '%s\n' '--- relevant configuration documentation ---'
cat -n docs/features/configuration.md | sed -n '40,95p'
printf '%s\n' '--- resource reaper tests ---'
cat -n core/src/test/java/org/testcontainers/utility/ResourceReaperTest.java | sed -n '1,125p'

Repository: testcontainers/testcontainers-java

Length of output: 24293