Document in User Guide and Release Notes

Author: marcphilipp

documentation/src/docs/asciidoc/release-notes/release-notes-6.1.0.adoc

@@ -45,7 +45,12 @@ repository on GitHub.
 [[release-notes-6.1.0-M1-junit-jupiter-new-features-and-improvements]]
 ==== New Features and Improvements
 
-* ❓
+* Introduce new `dynamicTest(Consumer<? super Configuration>)` factory method for dynamic
+  tests. It allows configuring the `ExecutionMode` of the dynamic test in addition to its
+  display name, test source URI, and executable.
+* Introduce new `dynamicContainer(Consumer<? super Configuration>)` factory method for
+  dynamic containers. It allows configuring the `ExecutionMode` of the dynamic container
+  and/or its children in addition to its display name, test source URI, and children.
 
 
 [[release-notes-6.1.0-M1-junit-vintage]]

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

@@ -3106,6 +3106,29 @@ implementations.
 `UriSource` ::
   If none of the above `TestSource` implementations are applicable.
 
+[[writing-tests-dynamic-tests-parallel-execution]]
+==== Parallel Execution
+
+Dynamic tests and containers support
+<<writing-tests-parallel-execution, parallel execution>>. You can configure their
+`ExecutionMode` by using the `dynamicTest(Consumer)` and `dynamicContainer(Consumer)`
+factory methods as illustrated by the following example.
+
+[source,java,indent=0]
+----
+include::{testDir}/example/DynamicTestsDemo.java[tags=execution_mode]
+----
+
+Executing the above test factory method results in the following test tree and execution
+modes:
+
+* dynamicTestsWithConfiguredExecutionMode() -- `CONCURRENT` (from `@Execution` annotation)
+** Container A -- `CONCURRENT` (from `@Execution` annotation)
+*** not null -- `SAME_THREAD` (from `executionMode(...)` call)
+*** properties -- `CONCURRENT` (from `@Execution` annotation)
+**** length > 0 -- `CONCURRENT` (from `executionMode(...)` call)
+**** not empty -- `SAME_THREAD` (from `childExecutionMode(...)` call)
+** ... (same for "Container B" and "Container C")
 
 [[writing-tests-declarative-timeouts]]
 === Timeouts

documentation/src/test/java/example/DynamicTestsDemo.java

@@ -18,6 +18,8 @@
 import static org.junit.jupiter.api.Assertions.assertTrue;
 import static org.junit.jupiter.api.DynamicContainer.dynamicContainer;
 import static org.junit.jupiter.api.DynamicTest.dynamicTest;
+import static org.junit.jupiter.api.parallel.ExecutionMode.CONCURRENT;
+import static org.junit.jupiter.api.parallel.ExecutionMode.SAME_THREAD;
 
 import java.util.Arrays;
 import java.util.Collection;
@@ -35,6 +37,7 @@
 import org.junit.jupiter.api.Tag;
 import org.junit.jupiter.api.TestFactory;
 import org.junit.jupiter.api.function.ThrowingConsumer;
+import org.junit.jupiter.api.parallel.Execution;
 
 // end::user_guide[]
 // @formatter:off
@@ -163,6 +166,44 @@ Stream<DynamicNode> dynamicTestsWithContainers() {
 			)));
 	}
 
+	// end::user_guide[]
+	// tag::execution_mode[]
+	@TestFactory
+	@Execution(CONCURRENT) // <1>
+	Stream<DynamicNode> dynamicTestsWithConfiguredExecutionMode() {
+		return Stream.of("A", "B", "C")
+				.map(input ->
+					dynamicContainer(outer -> outer
+						.displayName("Container " + input)
+						.children(
+							dynamicTest(config -> config
+								.displayName("not null")
+								.executionMode(SAME_THREAD) // <2>
+								.executable(() -> assertNotNull(input))
+							),
+							dynamicContainer(inner -> inner
+								.displayName("properties")
+								.executionMode(CONCURRENT) // <3>
+								.childExecutionMode(SAME_THREAD) // <4>
+								.children(
+									dynamicTest(config -> config
+										.displayName("length > 0")
+										.executionMode(CONCURRENT) // <5>
+										.executable(() -> assertTrue(input.length() > 0))
+									),
+									dynamicTest(config -> config
+										.displayName("not empty")
+										.executable(() -> assertFalse(input.isEmpty()))
+									)
+								)
+							)
+						)
+					)
+				);
+	}
+	// end::execution_mode[]
+
+	// tag::user_guide[]
 	@TestFactory
 	DynamicNode dynamicNodeSingleTest() {
 		return dynamicTest("'pop' is a palindrome", () -> assertTrue(isPalindrome("pop")));