Allow configuring execution mode of dynamic tests and containers (#4621)

* 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.

Resolves #2497.

Author: marcphilipp

documentation/src/docs/asciidoc/release-notes/release-notes-6.1.0-M1.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")));

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

@@ -10,14 +10,19 @@
 
 package org.junit.jupiter.api;
 
+import static org.apiguardian.api.API.Status.EXPERIMENTAL;
 import static org.apiguardian.api.API.Status.MAINTAINED;
 
 import java.net.URI;
+import java.util.List;
+import java.util.Optional;
+import java.util.function.Consumer;
 import java.util.stream.Stream;
 import java.util.stream.StreamSupport;
 
 import org.apiguardian.api.API;
 import org.jspecify.annotations.Nullable;
+import org.junit.jupiter.api.parallel.ExecutionMode;
 import org.junit.platform.commons.util.Preconditions;
 
 /**
@@ -38,6 +43,8 @@
 @API(status = MAINTAINED, since = "5.3")
 public class DynamicContainer extends DynamicNode {
 
+	private final @Nullable ExecutionMode childExecutionMode;
+
 	/**
 	 * Factory for creating a new {@code DynamicContainer} for the supplied display
 	 * name and collection of dynamic nodes.
@@ -51,7 +58,7 @@ public class DynamicContainer extends DynamicNode {
 	 * @see #dynamicContainer(String, Stream)
 	 */
 	public static DynamicContainer dynamicContainer(String displayName, Iterable<? extends DynamicNode> dynamicNodes) {
-		return dynamicContainer(displayName, null, StreamSupport.stream(dynamicNodes.spliterator(), false));
+		return dynamicContainer(config -> config.displayName(displayName).children(dynamicNodes));
 	}
 
 	/**
@@ -67,7 +74,7 @@ public static DynamicContainer dynamicContainer(String displayName, Iterable<? e
 	 * @see #dynamicContainer(String, Iterable)
 	 */
 	public static DynamicContainer dynamicContainer(String displayName, Stream<? extends DynamicNode> dynamicNodes) {
-		return dynamicContainer(displayName, null, dynamicNodes);
+		return dynamicContainer(config -> config.displayName(displayName).children(dynamicNodes));
 	}
 
 	/**
@@ -88,15 +95,32 @@ public static DynamicContainer dynamicContainer(String displayName, Stream<? ext
 	public static DynamicContainer dynamicContainer(String displayName, @Nullable URI testSourceUri,
 			Stream<? extends DynamicNode> dynamicNodes) {
 
-		return new DynamicContainer(displayName, testSourceUri, dynamicNodes);
+		return dynamicContainer(
+			config -> config.displayName(displayName).testSourceUri(testSourceUri).children(dynamicNodes));
+	}
+
+	/**
+	 * Factory for creating a new {@code DynamicTest} that is configured via the
+	 * supplied {@link Consumer} of {@link DynamicTest.Configuration}.
+	 *
+	 * @param configurer callback for configuring the resulting
+	 * {@code DynamicTest}; never {@code null}.
+	 *
+	 * @since 6.1
+	 */
+	@API(status = EXPERIMENTAL, since = "6.1")
+	public static DynamicContainer dynamicContainer(Consumer<? super Configuration> configurer) {
+		var configuration = new DefaultConfiguration();
+		configurer.accept(configuration);
+		return new DynamicContainer(configuration);
 	}
 
 	private final Stream<? extends DynamicNode> children;
 
-	private DynamicContainer(String displayName, @Nullable URI testSourceUri, Stream<? extends DynamicNode> children) {
-		super(displayName, testSourceUri);
-		Preconditions.notNull(children, "children must not be null");
-		this.children = children;
+	private DynamicContainer(DefaultConfiguration configuration) {
+		super(configuration);
+		this.children = Preconditions.notNull(configuration.children, "children must not be null");
+		this.childExecutionMode = configuration.childExecutionMode;
 	}
 
 	/**
@@ -107,4 +131,105 @@ public Stream<? extends DynamicNode> getChildren() {
 		return children;
 	}
 
+	/**
+	 * {@return the {@link ExecutionMode} for
+	 * {@linkplain #getChildren() children} of this {@code DynamicContainer}
+	 * that is used unless they are
+	 * {@linkplain DynamicTest#getExecutionMode() configured} differently}.
+	 *
+	 * @since 6.1
+	 * @see DynamicTest#getExecutionMode()
+	 */
+	@API(status = EXPERIMENTAL, since = "6.1")
+	public Optional<ExecutionMode> getChildExecutionMode() {
+		return Optional.ofNullable(childExecutionMode);
+	}
+
+	/**
+	 * {@code Configuration} of a {@link DynamicContainer}.
+	 *
+	 * @since 6.1
+	 * @see DynamicContainer#dynamicContainer(Consumer)
+	 */
+	@API(status = EXPERIMENTAL, since = "6.1")
+	public sealed interface Configuration extends DynamicNode.Configuration<Configuration> {
+
+		/**
+		 * Set the
+		 * {@linkplain DynamicContainer#getChildExecutionMode() child execution mode}
+		 * to use for the configured {@link DynamicContainer}.
+		 *
+		 * @return this configuration for method chaining
+		 */
+		Configuration childExecutionMode(ExecutionMode executionMode);
+
+		/**
+		 * Set the {@linkplain DynamicContainer#getChildren() children} of the
+		 * configured {@link DynamicContainer}.
+		 *
+		 * <p>Any previously configured value is overridden.
+		 *
+		 * @param children the children; never {@code null} or containing
+		 * {@code null} elements
+		 * @return this configuration for method chaining
+		 */
+		default Configuration children(Iterable<? extends DynamicNode> children) {
+			Preconditions.notNull(children, "children must not be null");
+			return children(StreamSupport.stream(children.spliterator(), false));
+		}
+
+		/**
+		 * Set the {@linkplain DynamicContainer#getChildren() children} of the
+		 * configured {@link DynamicContainer}.
+		 *
+		 * <p>Any previously configured value is overridden.
+		 *
+		 * @param children the children; never {@code null} or containing
+		 * {@code null} elements
+		 * @return this configuration for method chaining
+		 */
+		default Configuration children(DynamicNode... children) {
+			Preconditions.notNull(children, "children must not be null");
+			Preconditions.containsNoNullElements(children, "children must not contain null elements");
+			return children(List.of(children));
+		}
+
+		/**
+		 * Set the {@linkplain DynamicContainer#getChildren() children} of the
+		 * configured {@link DynamicContainer}.
+		 *
+		 * <p>Any previously configured value is overridden.
+		 *
+		 * @param children the children; never {@code null} or containing
+		 * {@code null} elements
+		 * @return this configuration for method chaining
+		 */
+		Configuration children(Stream<? extends DynamicNode> children);
+
+	}
+
+	static final class DefaultConfiguration extends AbstractConfiguration<Configuration> implements Configuration {
+
+		private @Nullable Stream<? extends DynamicNode> children;
+		private @Nullable ExecutionMode childExecutionMode;
+
+		@Override
+		public Configuration childExecutionMode(ExecutionMode executionMode) {
+			this.childExecutionMode = Preconditions.notNull(executionMode, "executionMode must not be null");
+			return this;
+		}
+
+		@Override
+		public Configuration children(Stream<? extends DynamicNode> children) {
+			Preconditions.notNull(children, "children must not be null");
+			Preconditions.condition(this.children == null, "children can only be set once");
+			this.children = children;
+			return this;
+		}
+
+		@Override
+		protected Configuration self() {
+			return this;
+		}
+	}
 }