Create Testcontainers Rule

Author: kcooney

core/build.gradle

@@ -113,6 +113,7 @@ dependencies {
     testImplementation 'redis.clients:jedis:5.1.5'
     testImplementation 'com.rabbitmq:amqp-client:5.22.0'
     testImplementation 'org.mongodb:mongo-java-driver:3.12.14'
+    testImplementation project(':junit-vintage')
 
     testImplementation ('org.mockito:mockito-core:4.11.0') {
         exclude(module: 'hamcrest-core')

core/src/test/java/org/testcontainers/containers/NetworkTest.java

@@ -6,6 +6,8 @@
 import org.junit.runner.RunWith;
 import org.testcontainers.DockerClientFactory;
 import org.testcontainers.TestImages;
+import org.testcontainers.junit.vintage.Container;
+import org.testcontainers.junit.vintage.Testcontainers;
 
 import static org.assertj.core.api.Assertions.assertThat;
 
@@ -18,12 +20,15 @@ public static class WithRules {
         public Network network = Network.newNetwork();
 
         @Rule
+        public Testcontainers containers = new Testcontainers(this);
+
+        @Container
         public GenericContainer<?> foo = new GenericContainer<>(TestImages.TINY_IMAGE)
             .withNetwork(network)
             .withNetworkAliases("foo")
             .withCommand("/bin/sh", "-c", "while true ; do printf 'HTTP/1.1 200 OK\\n\\nyay' | nc -l -p 8080; done");
 
-        @Rule
+        @Container
         public GenericContainer<?> bar = new GenericContainer<>(TestImages.TINY_IMAGE)
             .withNetwork(network)
             .withCommand("top");

core/src/test/java/org/testcontainers/junit/ComposeContainerPortViaEnvTest.java

@@ -2,12 +2,17 @@
 
 import org.junit.Rule;
 import org.testcontainers.containers.ComposeContainer;
+import org.testcontainers.junit.vintage.Container;
+import org.testcontainers.junit.vintage.Testcontainers;
 
 import java.io.File;
 
 public class ComposeContainerPortViaEnvTest extends BaseComposeTest {
 
     @Rule
+    public final Testcontainers containers = new Testcontainers(this);
+
+    @Container
     public ComposeContainer environment = new ComposeContainer(
         new File("src/test/resources/v2-compose-test-port-via-env.yml")
     )

docs/examples/junit4/redis/build.gradle

@@ -5,5 +5,6 @@ dependencies {
 
     testImplementation "junit:junit:4.13.2"
     testImplementation project(":testcontainers")
+    testImplementation project(":junit-vintage")
     testImplementation 'org.assertj:assertj-core:3.26.3'
 }

docs/examples/junit4/redis/src/test/java/quickstart/RedisBackedCacheIntTest.java

@@ -4,6 +4,8 @@
 import org.junit.Rule;
 import org.junit.Test;
 import org.testcontainers.containers.GenericContainer;
+import org.testcontainers.junit.vintage.Container;
+import org.testcontainers.junit.vintage.Testcontainers;
 import org.testcontainers.utility.DockerImageName;
 
 import static org.assertj.core.api.Assertions.assertThat;
@@ -14,13 +16,19 @@ public class RedisBackedCacheIntTest {
 
     // rule {
     @Rule
+    public Testcontainers containers = new Testcontainers(this);
+
+    // }
+
+    // container {
+    @Container
     public GenericContainer redis = new GenericContainer(DockerImageName.parse("redis:6-alpine"))
         .withExposedPorts(6379);
 
     // }
 
     @Before
-    public void setUp() {
+    public void createCache() {
         String address = redis.getHost();
         Integer port = redis.getFirstMappedPort();
 
@@ -29,7 +37,7 @@ public void setUp() {
     }
 
     @Test
-    public void testSimplePutAndGet() {
+    public void simplePutAndGet() {
         underTest.put("test", "example");
 
         String retrieved = underTest.get("test");

docs/examples/junit4/redis/src/test/java/quickstart/RedisBackedCacheIntTestStep0.java

@@ -12,13 +12,13 @@ public class RedisBackedCacheIntTestStep0 {
     private RedisBackedCache underTest;
 
     @Before
-    public void setUp() {
+    public void createCache() {
         // Assume that we have Redis running locally?
         underTest = new RedisBackedCache("localhost", 6379);
     }
 
     @Test
-    public void testSimplePutAndGet() {
+    public void simplePutAndGet() {
         underTest.put("test", "example");
 
         String retrieved = underTest.get("test");

docs/quickstart/junit_4_quickstart.md

@@ -1,10 +1,13 @@
 # JUnit 4 Quickstart
 
-It's easy to add Testcontainers to your project - let's walk through a quick example to see how.
+This example shows the way you could use Testcontainers with JUnit 4.
+
+!!! note
+    JUnit 4 is in [maintenance mode since 2025-05-31](https://github.com/junit-team/junit4), so we recommend using JUnit 5 or newer versions instead.
 
 Let's imagine we have a simple program that has a dependency on Redis, and we want to add some tests for it.
 In our imaginary program, there is a `RedisBackedCache` class which stores data in Redis.
- 
+
 You can see an example test that could have been written for it (without using Testcontainers):
 
 <!--codeinclude-->
@@ -15,15 +18,16 @@ Notice that the existing test has a problem - it's relying on a local installati
 This may work if we were sure that every developer and CI machine had Redis installed, but would fail otherwise.
 We might also have problems if we attempted to run tests in parallel, such as state bleeding between tests, or port clashes.
 
-Let's start from here, and see how to improve the test with Testcontainers:  
+Let's start from here, and see how to improve the test with Testcontainers:
 
 ## 1. Add Testcontainers as a test-scoped dependency
 
 First, add Testcontainers as a dependency as follows:
 
 === "Gradle"
     ```groovy
-    testImplementation "org.testcontainers:testcontainers:{{latest_version}}"
+    testImplementation("org.testcontainers:testcontainers:{{latest_version}}")
+    testImplementation("org.testcontainers:junit-vintage:{{latest_version}}")
     ```
 === "Maven"
     ```xml
@@ -33,18 +37,26 @@ First, add Testcontainers as a dependency as follows:
         <version>{{latest_version}}</version>
         <scope>test</scope>
     </dependency>
+    <dependency>
+        <groupId>org.testcontainers</groupId>
+        <artifactId>junit-vintage</artifactId>
+        <version>{{latest_version}}</version>
+        <scope>test</scope>
+    </dependency>
     ```
 
 ## 2. Get Testcontainers to run a Redis container during our tests
 
-Simply add the following to the body of our test class:
+Add the following to the body of our test class:
 
 <!--codeinclude-->
 [JUnit 4 Rule](../examples/junit4/redis/src/test/java/quickstart/RedisBackedCacheIntTest.java) inside_block:rule
 <!--/codeinclude-->
 
 The `@Rule` annotation tells JUnit to notify this field about various events in the test lifecycle.
-In this case, our rule object is a Testcontainers `GenericContainer`, configured to use a specific Redis image from Docker Hub, and configured to expose a port.
+Wrap the containers with `new TestContainersRule(...)` so the containers start and stop, according to the test lifecycle.
+In this case, our rule object is not `static`, so the container will start and stop with every test.
+The test configures `GenericContainer` to use a specific Redis image from Docker Hub, and to expose a port.
 
 If we run our test as-is, then regardless of the actual test outcome, we'll see logs showing us that Testcontainers:
 
@@ -66,9 +78,9 @@ We can do this in our test `setUp` method, to set up our component under test:
 <!--/codeinclude-->
 
 !!! tip
-    Notice that we also ask Testcontainers for the container's actual address with `redis.getHost();`, 
+    Notice that we also ask Testcontainers for the container's actual address with `redis.getHost();`,
     rather than hard-coding `localhost`. `localhost` may work in some environments but not others - for example it may
-    not work on your current or future CI environment. As such, **avoid hard-coding** the address, and use 
+    not work on your current or future CI environment. As such, **avoid hard-coding** the address, and use
     `getHost()` instead.
 
 ## 4. Run the tests!
@@ -80,4 +92,3 @@ Let's look at our complete test class to see how little we had to add to get up
 <!--codeinclude-->
 [RedisBackedCacheIntTest](../examples/junit4/redis/src/test/java/quickstart/RedisBackedCacheIntTest.java) block:RedisBackedCacheIntTest
 <!--/codeinclude-->
-

modules/junit-vintage/build.gradle

@@ -0,0 +1,11 @@
+description = "Testcontainers :: JUnit4 Rule"
+
+dependencies {
+    api project(":testcontainers")
+    api 'junit:junit:4.13.2'
+    implementation platform('org.junit:junit-bom:5.10.3')
+    implementation 'org.junit.jupiter:junit-jupiter-api'
+
+    testImplementation 'com.datastax.oss:java-driver-core:4.17.0'
+    testImplementation 'org.assertj:assertj-core:3.26.3'
+}

modules/junit-vintage/src/main/java/org/testcontainers/junit/vintage/Container.java

@@ -0,0 +1,15 @@
+package org.testcontainers.junit.vintage;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * The {@code @Container} annotation marks containers that should be managed by the
+ * {@code Testcontainers} rule.
+ */
+@Target(ElementType.FIELD)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface Container {
+}

modules/junit-vintage/src/main/java/org/testcontainers/junit/vintage/FailureDetectingExternalResource.java

@@ -0,0 +1,65 @@
+package org.testcontainers.junit.vintage;
+
+import org.junit.rules.TestRule;
+import org.junit.runner.Description;
+import org.junit.runners.model.MultipleFailureException;
+import org.junit.runners.model.Statement;
+import org.testcontainers.lifecycle.TestDescription;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * {@link TestRule} which is called before and after each test, and also is notified on success/failure.
+ *
+ * This mimics the behaviour of TestWatcher to some degree, but failures occurring in this rule do not
+ * contribute to the overall failure count (which can otherwise cause strange negative test success
+ * figures).
+ */
+class FailureDetectingExternalResource implements TestRule {
+
+    @Override
+    public final Statement apply(Statement base, Description description) {
+        return new Statement() {
+            @Override
+            public void evaluate() throws Throwable {
+                List<Throwable> errors = new ArrayList<Throwable>();
+
+                try {
+                    starting(description);
+                    base.evaluate();
+                    succeeded(description);
+                } catch (Throwable e) {
+                    errors.add(e);
+                    failed(e, description);
+                } finally {
+                    finished(description, errors);
+                }
+
+                MultipleFailureException.assertEmpty(errors);
+            }
+        };
+    }
+
+    protected void starting(Description description) throws Throwable {}
+
+    protected void succeeded(Description description) throws Throwable {}
+
+    protected void failed(Throwable e, Description description) {}
+
+    protected void finished(Description description, List<Throwable> errors) {}
+
+    protected static final TestDescription toTestDescription(Description description) {
+        return new TestDescription() {
+            @Override
+            public String getTestId() {
+                return description.getDisplayName();
+            }
+
+            @Override
+            public String getFilesystemFriendlyName() {
+                return description.getClassName() + "-" + description.getMethodName();
+            }
+        };
+    }
+}