Introduce extension API for container templates (#4315)

Analogous to `@TestTemplate` on the method level, this commit introduces
a class-level `@ContainerTemplate` annotation with an accompanying 
`ContainerTemplateInvocationContextProvider` extension API.

Resolves #871.

Author: marcphilipp

documentation/src/docs/asciidoc/link-attributes.adoc

@@ -111,6 +111,7 @@ endif::[]
 :ClassOrderer_OrderAnnotation:               {javadoc-root}/org.junit.jupiter.api/org/junit/jupiter/api/ClassOrderer.OrderAnnotation.html[ClassOrderer.OrderAnnotation]
 :ClassOrderer_Random:                        {javadoc-root}/org.junit.jupiter.api/org/junit/jupiter/api/ClassOrderer.Random.html[ClassOrderer.Random]
 :ClassOrderer:                               {javadoc-root}/org.junit.jupiter.api/org/junit/jupiter/api/ClassOrderer.html[ClassOrderer]
+:ContainerTemplate:                          {javadoc-root}/org.junit.jupiter.api/org/junit/jupiter/api/ContainerTemplate.html[@ContainerTemplate]
 :Disabled:                                   {javadoc-root}/org.junit.jupiter.api/org/junit/jupiter/api/Disabled.html[@Disabled]
 :MethodOrderer_Alphanumeric:                 {javadoc-root}/org.junit.jupiter.api/org/junit/jupiter/api/MethodOrderer.Alphanumeric.html[MethodOrderer.Alphanumeric]
 :MethodOrderer_DisplayName:                  {javadoc-root}/org.junit.jupiter.api/org/junit/jupiter/api/MethodOrderer.DisplayName.html[MethodOrderer.DisplayName]
@@ -142,6 +143,8 @@ endif::[]
 :BeforeAllCallback:                          {javadoc-root}/org.junit.jupiter.api/org/junit/jupiter/api/extension/BeforeAllCallback.html[BeforeAllCallback]
 :BeforeEachCallback:                         {javadoc-root}/org.junit.jupiter.api/org/junit/jupiter/api/extension/BeforeEachCallback.html[BeforeEachCallback]
 :BeforeTestExecutionCallback:                {javadoc-root}/org.junit.jupiter.api/org/junit/jupiter/api/extension/BeforeTestExecutionCallback.html[BeforeTestExecutionCallback]
+:ContainerTemplateInvocationContext:         {javadoc-root}/org.junit.jupiter.api/org/junit/jupiter/api/extension/ContainerTemplateInvocationContext.html[ContainerTemplateInvocationContext]
+:ContainerTemplateInvocationContextProvider: {javadoc-root}/org.junit.jupiter.api/org/junit/jupiter/api/extension/ContainerTemplateInvocationContextProvider.html[ContainerTemplateInvocationContextProvider]
 :ExecutableInvoker:                          {javadoc-root}/org.junit.jupiter.api/org/junit/jupiter/api/extension/ExecutableInvoker.html[ExecutableInvoker]
 :ExecutionCondition:                         {javadoc-root}/org.junit.jupiter.api/org/junit/jupiter/api/extension/ExecutionCondition.html[ExecutionCondition]
 :ExtendWith:                                 {javadoc-root}/org.junit.jupiter.api/org/junit/jupiter/api/extension/ExtendWith.html[@ExtendWith]

documentation/src/docs/asciidoc/release-notes/release-notes-5.13.0-M1.adoc

@@ -45,7 +45,11 @@ repository on GitHub.
 [[release-notes-5.13.0-M1-junit-jupiter-new-features-and-improvements]]
 ==== New Features and Improvements
 
-* ❓
+* Introduce `@ContainerTemplate` and `ContainerTemplateInvocationContextProvider` that
+  allow declaring a top-level or `@Nested` test class as a template to be invoked multiple
+  times. This may be used, for example, to inject different parameters to be used by all
+  tests in the container template class or to set up each invocation of the container
+  template differently.
 
 
 [[release-notes-5.13.0-M1-junit-vintage]]

documentation/src/docs/asciidoc/user-guide/extensions.adoc

@@ -765,6 +765,46 @@ You may override the `getTestInstantiationExtensionContextScope(...)` method to
 on the test method level.
 ====
 
+[[extensions-container-templates]]
+=== Providing Invocation Contexts for Container Templates
+
+A `{ContainerTemplate}` class can only be executed when at least one
+`{ContainerTemplateInvocationContextProvider}` is registered. Each such provider is
+responsible for providing a `Stream` of `{ContainerTemplateInvocationContext}` instances.
+Each context may specify a custom display name and a list of additional extensions that
+will only be used for the next invocation of the `{ContainerTemplate}` class.
+
+The following example shows how to write a container template as well as how to register
+and implement a `{ContainerTemplateInvocationContextProvider}`.
+
+[source,java,indent=0]
+.A container template with accompanying extension
+----
+include::{testDir}/example/ContainerTemplateDemo.java[tags=user_guide]
+----
+
+In this example, the container template will be invoked twice, meaning all test methods in
+the container template class will be executed twice. The display names of the container
+invocations will be `apple` and `banana` as specified by the invocation context. Each
+invocation registers a custom `{TestInstancePostProcessor}` which is used to inject a
+value into a field. The output when using the `ConsoleLauncher` is as follows.
+
+....
+└─ ContainerTemplateDemo ✔
+   ├─ apple ✔
+   │  ├─ notNull() ✔
+   │  └─ wellKnown() ✔
+   └─ banana ✔
+      ├─ notNull() ✔
+      └─ wellKnown() ✔
+....
+
+The `{ContainerTemplateInvocationContextProvider}` extension API is primarily intended for
+implementing different kinds of tests that rely on repetitive invocation of _all_ test
+methods in a test class albeit in different contexts — for example, with different
+parameters, by preparing the test class instance differently, or multiple times without
+modifying the context.
+
 [[extensions-test-templates]]
 === Providing Invocation Contexts for Test Templates
 

documentation/src/docs/asciidoc/user-guide/writing-tests.adoc

@@ -32,7 +32,7 @@ in the `junit-jupiter-api` module.
 | `@ParameterizedTest`     | Denotes that a method is a <<writing-tests-parameterized-tests, parameterized test>>. Such methods are inherited unless they are overridden.
 | `@RepeatedTest`          | Denotes that a method is a test template for a <<writing-tests-repeated-tests, repeated test>>. Such methods are inherited unless they are overridden.
 | `@TestFactory`           | Denotes that a method is a test factory for <<writing-tests-dynamic-tests, dynamic tests>>. Such methods are inherited unless they are overridden.
-| `@TestTemplate`          | Denotes that a method is a <<writing-tests-test-templates, template for test cases>> designed to be invoked multiple times depending on the number of invocation contexts returned by the registered <<extensions-test-templates, providers>>. Such methods are inherited unless they are overridden.
+| `@TestTemplate`          | Denotes that a method is a <<writing-tests-test-templates, template for a test case>> designed to be invoked multiple times depending on the number of invocation contexts returned by the registered <<extensions-test-templates, providers>>. Such methods are inherited unless they are overridden.
 | `@TestClassOrder`        | Used to configure the <<writing-tests-test-execution-order-classes, test class execution order>> for `@Nested` test classes in the annotated test class. Such annotations are inherited.
 | `@TestMethodOrder`       | Used to configure the <<writing-tests-test-execution-order-methods, test method execution order>> for the annotated test class; similar to JUnit 4's `@FixMethodOrder`. Such annotations are inherited.
 | `@TestInstance`          | Used to configure the <<writing-tests-test-instance-lifecycle, test instance lifecycle>> for the annotated test class. Such annotations are inherited.
@@ -42,6 +42,7 @@ in the `junit-jupiter-api` module.
 | `@AfterEach`             | Denotes that the annotated method should be executed _after_ *each* `@Test`, `@RepeatedTest`, `@ParameterizedTest`, or `@TestFactory` method in the current class; analogous to JUnit 4's `@After`. Such methods are inherited unless they are overridden.
 | `@BeforeAll`             | Denotes that the annotated method should be executed _before_ *all* `@Test`, `@RepeatedTest`, `@ParameterizedTest`, and `@TestFactory` methods in the current class; analogous to JUnit 4's `@BeforeClass`. Such methods are inherited unless they are overridden and must be `static` unless the "per-class" <<writing-tests-test-instance-lifecycle, test instance lifecycle>> is used.
 | `@AfterAll`              | Denotes that the annotated method should be executed _after_ *all* `@Test`, `@RepeatedTest`, `@ParameterizedTest`, and `@TestFactory` methods in the current class; analogous to JUnit 4's `@AfterClass`. Such methods are inherited unless they are overridden and must be `static` unless the "per-class" <<writing-tests-test-instance-lifecycle, test instance lifecycle>> is used.
+| `@ContainerTemplate`     | Denotes that the annotated class is a <<writing-tests-container-templates, template for a set of test cases>> designed to be executed multiple times depending on the number of invocation contexts returned by the registered <<extensions-container-templates, providers>>.
 | `@Nested`                | Denotes that the annotated class is a non-static <<writing-tests-nested,nested test class>>. On Java 8 through Java 15, `@BeforeAll` and `@AfterAll` methods cannot be used directly in a `@Nested` test class unless the "per-class" <<writing-tests-test-instance-lifecycle, test instance lifecycle>> is used. Beginning with Java 16, `@BeforeAll` and `@AfterAll` methods can be declared as `static` in a `@Nested` test class with either test instance lifecycle mode. Such annotations are not inherited.
 | `@Tag`                   | Used to declare <<writing-tests-tagging-and-filtering,tags for filtering tests>>, either at the class or method level; analogous to test groups in TestNG or Categories in JUnit 4. Such annotations are inherited at the class level but not at the method level.
 | `@Disabled`              | Used to <<writing-tests-disabling,disable>> a test class or test method; analogous to JUnit 4's `@Ignore`. Such annotations are not inherited.
@@ -2448,12 +2449,22 @@ lifecycle methods (e.g. `@BeforeEach`) and test class constructors.
 include::{testDir}/example/ParameterizedTestDemo.java[tags=ParameterResolver_example]
 ----
 
+[[writing-tests-container-templates]]
+=== Container Templates
+
+A `{ContainerTemplate}` class is not a regular test class but rather a template for the
+contained test cases. As such, it is designed to be invoked multiple times depending on
+invocation contexts returned by the registered providers. Thus, it must be used in
+conjunction with a registered `{ContainerTemplateInvocationContextProvider}` extension.
+Each invocation of a container template class behaves like the execution of a regular test
+class with full support for the same lifecycle callbacks and extensions. Please refer to
+<<extensions-container-templates>> for usage examples.
 
 [[writing-tests-test-templates]]
 === Test Templates
 
-A `{TestTemplate}` method is not a regular test case but rather a template for test
-cases. As such, it is designed to be invoked multiple times depending on the number of
+A `{TestTemplate}` method is not a regular test case but rather a template for a test
+case. As such, it is designed to be invoked multiple times depending on the number of
 invocation contexts returned by the registered providers. Thus, it must be used in
 conjunction with a registered `{TestTemplateInvocationContextProvider}` extension. Each
 invocation of a test template method behaves like the execution of a regular `@Test`

documentation/src/test/java/example/ContainerTemplateDemo.java

@@ -0,0 +1,99 @@
+/*
+ * Copyright 2015-2025 the original author or authors.
+ *
+ * All rights reserved. This program and the accompanying materials are
+ * made available under the terms of the Eclipse Public License v2.0 which
+ * accompanies this distribution and is available at
+ *
+ * https://www.eclipse.org/legal/epl-v20.html
+ */
+
+package example;
+
+import static java.util.Collections.singletonList;
+import static java.util.Collections.unmodifiableList;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.util.Arrays;
+import java.util.List;
+import java.util.stream.Stream;
+
+import example.ContainerTemplateDemo.MyContainerTemplateInvocationContextProvider;
+
+import org.junit.jupiter.api.ContainerTemplate;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ContainerTemplateInvocationContext;
+import org.junit.jupiter.api.extension.ContainerTemplateInvocationContextProvider;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.junit.jupiter.api.extension.Extension;
+import org.junit.jupiter.api.extension.ExtensionContext;
+import org.junit.jupiter.api.extension.TestInstancePostProcessor;
+
+// tag::user_guide[]
+@ContainerTemplate
+@ExtendWith(MyContainerTemplateInvocationContextProvider.class)
+class ContainerTemplateDemo {
+
+	static final List<String> WELL_KNOWN_FRUITS
+	// tag::custom_line_break[]
+		= unmodifiableList(Arrays.asList("apple", "banana", "lemon"));
+
+	private String fruit;
+
+	@Test
+	void notNull() {
+		assertNotNull(fruit);
+	}
+
+	@Test
+	void wellKnown() {
+		assertTrue(WELL_KNOWN_FRUITS.contains(fruit));
+	}
+
+	// end::user_guide[]
+	static
+	// tag::user_guide[]
+	public class MyContainerTemplateInvocationContextProvider
+			// tag::custom_line_break[]
+			implements ContainerTemplateInvocationContextProvider {
+
+		@Override
+		public boolean supportsContainerTemplate(ExtensionContext context) {
+			return true;
+		}
+
+		@Override
+		public Stream<ContainerTemplateInvocationContext>
+				// tag::custom_line_break[]
+				provideContainerTemplateInvocationContexts(ExtensionContext context) {
+
+			return Stream.of(invocationContext("apple"), invocationContext("banana"));
+		}
+
+		private ContainerTemplateInvocationContext invocationContext(String parameter) {
+			return new ContainerTemplateInvocationContext() {
+				@Override
+				public String getDisplayName(int invocationIndex) {
+					return parameter;
+				}
+
+				// end::user_guide[]
+				@SuppressWarnings("Convert2Lambda")
+				// tag::user_guide[]
+				@Override
+				public List<Extension> getAdditionalExtensions() {
+					return singletonList(new TestInstancePostProcessor() {
+						@Override
+						public void postProcessTestInstance(
+								// tag::custom_line_break[]
+								Object testInstance, ExtensionContext context) {
+							((ContainerTemplateDemo) testInstance).fruit = parameter;
+						}
+					});
+				}
+			};
+		}
+	}
+}
+// end::user_guide[]

junit-jupiter-api/src/main/java/org/junit/jupiter/api/AfterAll.java

@@ -25,7 +25,13 @@
  * executed <em>after</em> <strong>all</strong> tests in the current test class.
  *
  * <p>In contrast to {@link AfterEach @AfterEach} methods, {@code @AfterAll}
- * methods are only executed once for a given test class.
+ * methods are only executed once per execution of a given test class. If the
+ * test class is annotated with {@link ContainerTemplate @ContainerTemplate},
+ * the {@code @AfterAll} methods are executed once after the last invocation of
+ * the container template. If a {@link Nested @Nested} test class is declared in
+ * a {@link ContainerTemplate @ContainerTemplate} class, its {@code @AfterAll}
+ * methods are called once per execution of the nested test class, namely, once
+ * per invocation of the outer container template.
  *
  * <h2>Method Signatures</h2>
  *

junit-jupiter-api/src/main/java/org/junit/jupiter/api/BeforeAll.java

@@ -25,7 +25,13 @@
  * executed <em>before</em> <strong>all</strong> tests in the current test class.
  *
  * <p>In contrast to {@link BeforeEach @BeforeEach} methods, {@code @BeforeAll}
- * methods are only executed once for a given test class.
+ * methods are only executed once per execution of a given test class. If the
+ * test class is annotated with {@link ContainerTemplate @ContainerTemplate},
+ * the {@code @BeforeAll} methods are executed once before the first invocation
+ * of the container template. If a {@link Nested @Nested} test class is declared
+ * in a {@link ContainerTemplate @ContainerTemplate} class, its
+ * {@code @BeforeAll} methods are called once per execution of the nested test
+ * class, namely, once per invocation of the outer container template.
  *
  * <h2>Method Signatures</h2>
  *

junit-jupiter-api/src/main/java/org/junit/jupiter/api/ContainerTemplate.java

@@ -0,0 +1,65 @@
+/*
+ * Copyright 2015-2025 the original author or authors.
+ *
+ * All rights reserved. This program and the accompanying materials are
+ * made available under the terms of the Eclipse Public License v2.0 which
+ * accompanies this distribution and is available at
+ *
+ * https://www.eclipse.org/legal/epl-v20.html
+ */
+
+package org.junit.jupiter.api;
+
+import static org.apiguardian.api.API.Status.EXPERIMENTAL;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import org.apiguardian.api.API;
+import org.junit.platform.commons.annotation.Testable;
+
+/**
+ * {@code @ContainerTemplate} is used to signal that the annotated class is a
+ * <em>container template</em>.
+ *
+ * <p>In contrast to regular test classes, a container template is not directly
+ * a test class but rather a template for a set of test cases. As such, it is
+ * designed to be invoked multiple times depending on the number of {@linkplain
+ * org.junit.jupiter.api.extension.ContainerTemplateInvocationContext invocation
+ * contexts} returned by the registered {@linkplain
+ * org.junit.jupiter.api.extension.ContainerTemplateInvocationContextProvider
+ * providers}. Must be used together with at least one provider. Otherwise,
+ * execution will fail.
+ *
+ * <p>Each invocation of a container template method behaves like the execution
+ * of a regular test class with full support for the same lifecycle callbacks
+ * and extensions.
+ *
+ * <p>{@code @ContainerTemplate} may be combined with {@link Nested @Nested} and
+ * a container template may contain regular nested test classes or nested
+ * container templates.
+ *
+ * <p>{@code @ContainerTemplate} may also be used as a meta-annotation in order
+ * to create a custom <em>composed annotation</em> that inherits the semantics
+ * of {@code @ContainerTemplate}.
+ *
+ * <h2>Inheritance</h2>
+ *
+ * <p>The {@code @ContainerTemplate} annotation is not inherited to subclasses
+ * but needs to be declared on each container template class individually.
+ *
+ * @since 5.13
+ * @see TestTemplate
+ * @see org.junit.jupiter.api.extension.ContainerTemplateInvocationContext
+ * @see org.junit.jupiter.api.extension.ContainerTemplateInvocationContextProvider
+ */
+@Target({ ElementType.ANNOTATION_TYPE, ElementType.TYPE })
+@Retention(RetentionPolicy.RUNTIME)
+@Documented
+@API(status = EXPERIMENTAL, since = "5.13")
+@Testable
+public @interface ContainerTemplate {
+}

junit-jupiter-api/src/main/java/org/junit/jupiter/api/Nested.java

@@ -31,6 +31,9 @@
  * <p>{@code @Nested} test classes may be ordered via
  * {@link TestClassOrder @TestClassOrder} or a global {@link ClassOrderer}.
  *
+ * <p>{@code @Nested} may be combined with
+ * {@link ContainerTemplate @ContainerTemplate}.
+ *
  * <h2>Test Instance Lifecycle</h2>
  *
  * <ul>
@@ -42,6 +45,7 @@
  * </ul>
  *
  * @since 5.0
+ * @see ContainerTemplate
  * @see Test
  * @see TestInstance
  * @see TestClassOrder

junit-jupiter-api/src/main/java/org/junit/jupiter/api/TestInstance.java

@@ -86,7 +86,12 @@ enum Lifecycle {
 
 		/**
 		 * When using this mode, a new test instance will be created once per
-		 * test class.
+		 * test or container template class.
+		 *
+		 * <p>For {@link Nested @Nested}</p> test classes declared inside an
+		 * enclosing {@link ContainerTemplate @ContainerTemplate} test class, an
+		 * instance of the {@code @Nested} class will be created for each
+		 * invocation of the {@code @ContainerTemplate} test class.
 		 *
 		 * @see #PER_METHOD
 		 */

junit-jupiter-api/src/main/java/org/junit/jupiter/api/TestTemplate.java

@@ -79,6 +79,7 @@
  *
  * @since 5.0
  * @see Test
+ * @see ContainerTemplate
  * @see org.junit.jupiter.api.extension.TestTemplateInvocationContext
  * @see org.junit.jupiter.api.extension.TestTemplateInvocationContextProvider
  */