Testcontainers/Java/JUnit 5: Add missing support. Disambiguate docs.

Author: amotl

testing/testcontainers/java/README.rst

@@ -26,31 +26,25 @@ What's inside
 
 This directory includes different canonical examples how to use those
 components within test harnesses of custom applications using `CrateDB`_.
-Currently, all test cases are based on JUnit 4. This is an enumeration
+Currently, all test cases are based on JUnit. This is an enumeration
 of examples you can explore here:
 
-- ``TestClassScope``: Class-scoped testcontainer instance with JUnit 4 @Rule/@ClassRule integration.
-- ``TestFunctionScope``: Function-scoped testcontainer instance with JUnit 4 @Rule/@ClassRule integration.
+- ``TestClassScope``: Class-scoped testcontainer instance with automatic setup/teardown, see `Shared containers`_.
+- ``TestFunctionScope``: Function-scoped testcontainer instance with automatic setup/teardown, see `Restarted containers`_.
 - ``TestJdbcUrlScheme``: Database containers launched via Testcontainers "TC" JDBC URL scheme.
 - ``TestManual``: Function-scoped testcontainer instance with manual setup/teardown.
 - ``TestManualWithLegacyCrateJdbcDriver``:
   Function-scoped testcontainer instance with manual setup/teardown, using a custom
   ``CrateDBContainer``, which uses the `legacy CrateDB JDBC driver`_.
-- ``TestSharedSingleton`` [1]:
-  Testcontainer instance shared across multiple test classes, implemented using the Singleton pattern.
+- ``TestSharedSingleton``:
+  Testcontainer instance shared across multiple test classes, implemented using the Singleton pattern, see `Singleton containers`_.
 - ``TestSharedSingletonEnvironmentVersion``:
   Testcontainer instance honoring the ``CRATEDB_VERSION`` environment variable, suitable
   for running a test matrix on different versions of CrateDB, shared across multiple test
   classes.
 - ``TestSqlInitialization``: Demonstrate different ways how Testcontainers can run an init script after
   the database container is started, but before your code initiates a connection to it.
 
-[1]: Sometimes, it might be useful to define a container that is only started once for
-several test classes. There is no special support for this use case provided by
-the Testcontainers extension. Instead, this can be implemented using the Singleton
-pattern. See also `Testcontainers » Manual container lifecycle control » Singleton
-containers`_.
-
 
 *****
 Usage
@@ -89,6 +83,8 @@ Usage
 .. _CrateDB: https://github.com/crate/crate
 .. _CrateDB OCI image: https://hub.docker.com/_/crate
 .. _legacy CrateDB JDBC driver: https://crate.io/docs/jdbc/
+.. _Restarted containers: https://java.testcontainers.org/test_framework_integration/junit_5/#restarted-containers
+.. _Shared containers: https://java.testcontainers.org/test_framework_integration/junit_5/#shared-containers
+.. _Singleton containers: https://java.testcontainers.org/test_framework_integration/manual_lifecycle_control/#singleton-containers
 .. _Testcontainers for Java: https://github.com/testcontainers/testcontainers-java
 .. _Testcontainers CrateDB Module: https://www.testcontainers.org/modules/databases/cratedb/
-.. _Testcontainers » Manual container lifecycle control » Singleton containers: https://www.testcontainers.org/test_framework_integration/manual_lifecycle_control/#singleton-containers

testing/testcontainers/java/build.gradle

@@ -30,6 +30,7 @@ dependencies {
     testImplementation 'org.testcontainers:testcontainers:2.0.1'
     testImplementation 'org.testcontainers:testcontainers-cratedb:2.0.1'
     testImplementation 'org.testcontainers:testcontainers-postgresql:2.0.1'
+    testImplementation 'org.testcontainers:testcontainers-junit-jupiter:2.0.1'
 }
 
 java {

testing/testcontainers/java/src/test/java/io/crate/example/testing/TestClassScope.java

@@ -3,6 +3,8 @@
 import io.crate.example.testing.utils.TestingHelpers;
 import org.junit.jupiter.api.Test;
 import org.testcontainers.cratedb.CrateDBContainer;
+import org.testcontainers.junit.jupiter.Container;
+import org.testcontainers.junit.jupiter.Testcontainers;
 
 import java.io.IOException;
 import java.sql.SQLException;
@@ -11,19 +13,20 @@
 
 
 /**
- * Class-scoped testcontainer instance with JUnit 4 @Rule/@ClassRule integration.
+ * Class-scoped testcontainer instance with JUnit 5.
  * <p>
- * In case you can't use the URL support, or need to fine-tune the container, you can instantiate it yourself.
- * Note that if you use @Rule, you will be given an isolated container for each test method.
- * If you use @ClassRule, you will get on isolated container for all the methods in the test class.
+ * The extension finds all fields that are annotated with @Container and calls their container
+ * lifecycle methods (methods on the Startable interface).
+ * Containers declared as static fields will be shared between test methods.
  * </p>
  * <p>
- *   <a href="https://www.testcontainers.org/modules/databases/jdbc/#database-container-objects"/>
- *   <a href="https://www.testcontainers.org/test_framework_integration/junit_4/#ruleclassrule-integration"/>
+ *   <a href="https://java.testcontainers.org/test_framework_integration/junit_5/#shared-containers"/>
  * </p>
  */
+@Testcontainers
 public class TestClassScope {
 
+    @Container
     public static CrateDBContainer cratedb = new CrateDBContainer(TestingHelpers.nameFromLabel("5.10"));
 
     @Test

testing/testcontainers/java/src/test/java/io/crate/example/testing/TestFunctionScope.java

@@ -3,6 +3,8 @@
 import io.crate.example.testing.utils.TestingHelpers;
 import org.junit.jupiter.api.Test;
 import org.testcontainers.cratedb.CrateDBContainer;
+import org.testcontainers.junit.jupiter.Container;
+import org.testcontainers.junit.jupiter.Testcontainers;
 
 import java.io.IOException;
 import java.sql.SQLException;
@@ -11,19 +13,20 @@
 
 
 /**
- * Function-scoped testcontainer instance with JUnit 4 @Rule/@ClassRule integration.
+ * Function-scoped testcontainer instance with JUnit 5.
  * <p>
- * In case you can't use the URL support, or need to fine-tune the container, you can instantiate it yourself.
- * Note that if you use @Rule, you will be given an isolated container for each test method.
- * If you use @ClassRule, you will get on isolated container for all the methods in the test class.
+ * The extension finds all fields that are annotated with @Container and calls their container
+ * lifecycle methods (methods on the Startable interface).
+ * Containers declared as instance fields will be started and stopped for every test method.
  * </p>
  * <p>
- *   <a href="https://www.testcontainers.org/modules/databases/jdbc/#database-container-objects"/>
- *   <a href="https://www.testcontainers.org/test_framework_integration/junit_4/#ruleclassrule-integration" />
+ *   <a href="https://java.testcontainers.org/test_framework_integration/junit_5/#restarted-containers"/>
  * </p>
  */
+@Testcontainers
 public class TestFunctionScope {
 
+    @Container
     public CrateDBContainer cratedb = new CrateDBContainer(TestingHelpers.nameFromLabel("5.10"));
 
     @Test