Support named sources for DynamicTest.stream(…) (#2548)

Introduction of `DynamicTest.stream(Iterator<? extends Named<T>>, ThrowingConsumer<? super T>)` and `DynamicTest.stream(Stream<? extends Named<T>>, ThrowingConsumer<? super T>)`. Both methods use each name-value pair provided by the first parameter as the display name and value for each generated dynamic test.

Resolves #2375.

Author: juliette-derancourt

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

@@ -88,6 +88,10 @@ on GitHub.
 * In parameterized tests with `@MethodSource` or `@ArgumentSource`, arguments can now have
   optional names. When the argument is included in the display name of an iteration, this
   name will be used instead of the value.
+* `DynamicTests.stream()` can now consume `Named` input and will use each name-value
+  pair as the display name and value for each generated dynamic test (see
+  <<../user-guide/index.adoc#writing-tests-dynamic-tests-examples,User Guide>> for details).
+
 
 [[release-notes-5.8.0-M1-junit-vintage]]
 === JUnit Vintage

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

@@ -33,6 +33,7 @@
 
 import org.junit.jupiter.api.DynamicNode;
 import org.junit.jupiter.api.DynamicTest;
+import org.junit.jupiter.api.Named;
 import org.junit.jupiter.api.Tag;
 import org.junit.jupiter.api.TestFactory;
 import org.junit.jupiter.api.function.ThrowingConsumer;
@@ -151,6 +152,23 @@ Stream<DynamicTest> dynamicTestsFromStreamFactoryMethod() {
 		return DynamicTest.stream(inputStream, displayNameGenerator, testExecutor);
 	}
 
+	@TestFactory
+	Stream<DynamicTest> dynamicTestsFromStreamFactoryMethodWithNames() {
+		// Stream of palindromes to check
+		Stream<Named<String>> inputStream = Stream.of(
+				Named.of("racecar is a palindrome", "racecar"),
+				Named.of("radar is also a palindrome", "radar"),
+				Named.of("mom also seems to be a palindrome", "mom"),
+				Named.of("dad is yet another palindrome", "dad")
+		);
+
+		// Executes tests based on the current input value.
+		ThrowingConsumer<String> testExecutor = text -> assertTrue(isPalindrome(text));
+
+		// Returns a stream of dynamic tests.
+		return DynamicTest.stream(inputStream, testExecutor);
+	}
+
 	@TestFactory
 	Stream<DynamicNode> dynamicTestsWithContainers() {
 		return Stream.of("A", "B", "C")

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

@@ -155,6 +155,77 @@ public static <T> Stream<DynamicTest> stream(Stream<T> inputStream,
 				.map(input -> dynamicTest(displayNameGenerator.apply(input), () -> testExecutor.accept(input)));
 	}
 
+	/**
+	 * Generate a stream of dynamic tests based on the given generator and test
+	 * executor.
+	 *
+	 * <p>Use this method when the set of dynamic tests is nondeterministic in
+	 * nature or when the input comes from an existing {@link Iterator}. See
+	 * {@link #stream(Stream, ThrowingConsumer)} as an alternative.
+	 *
+	 * <p>The given {@code inputGenerator} is responsible for generating
+	 * input values and display names. A {@link DynamicTest} will be added to
+	 * the resulting stream for each dynamically generated input value,
+	 * using the given {@code testExecutor}.
+	 *
+	 * @param inputGenerator an {@code Iterator} with {@code Named} values
+	 * that serves as a dynamic <em>input generator</em>; never {@code null}
+	 * @param testExecutor a consumer that executes a test based on an input
+	 * value; never {@code null}
+	 * @param <T> the type of <em>input</em> generated by the {@code inputGenerator}
+	 * and used by the {@code testExecutor}
+	 * @return a stream of dynamic tests based on the given generator and
+	 * executor; never {@code null}
+	 * @since 5.8
+	 *
+	 * @see #dynamicTest(String, Executable)
+	 * @see #stream(Stream, ThrowingConsumer)
+	 * @see Named
+	 */
+	@API(status = MAINTAINED, since = "5.8")
+	public static <T> Stream<DynamicTest> stream(Iterator<? extends Named<T>> inputGenerator,
+			ThrowingConsumer<? super T> testExecutor) {
+		Preconditions.notNull(inputGenerator, "inputGenerator must not be null");
+
+		return stream(StreamSupport.stream(spliteratorUnknownSize(inputGenerator, ORDERED), false), testExecutor);
+	}
+
+	/**
+	 * Generate a stream of dynamic tests based on the given input stream and
+	 * test executor.
+	 *
+	 * <p>Use this method when the set of dynamic tests is nondeterministic in
+	 * nature or when the input comes from an existing {@link Stream}. See
+	 * {@link #stream(Iterator, ThrowingConsumer)} as an alternative.
+	 *
+	 * <p>The given {@code inputStream} is responsible for supplying input values
+	 * and display names. A {@link DynamicTest} will be added to the resulting stream for
+	 * each dynamically supplied input value, using the given {@code testExecutor}.
+	 *
+	 * @param inputStream a {@code Stream} that supplies dynamic {@code Named}
+	 * input values; never {@code null}
+	 * @param testExecutor a consumer that executes a test based on an input
+	 * value; never {@code null}
+	 * @param <T> the type of <em>input</em> supplied by the {@code inputStream}
+	 * and used by the {@code displayNameGenerator} and {@code testExecutor}
+	 * @return a stream of dynamic tests based on the given generator and
+	 * executor; never {@code null}
+	 * @since 5.8
+	 *
+	 * @see #dynamicTest(String, Executable)
+	 * @see #stream(Iterator, ThrowingConsumer)
+	 * @see Named
+	 */
+	@API(status = MAINTAINED, since = "5.8")
+	public static <T> Stream<DynamicTest> stream(Stream<? extends Named<T>> inputStream,
+			ThrowingConsumer<? super T> testExecutor) {
+		Preconditions.notNull(inputStream, "inputStream must not be null");
+		Preconditions.notNull(testExecutor, "testExecutor must not be null");
+
+		return inputStream //
+				.map(input -> dynamicTest(input.getName(), () -> testExecutor.accept(input.getPayload())));
+	}
+
 	private final Executable executable;
 
 	private DynamicTest(String displayName, URI testSourceUri, Executable executable) {

junit-jupiter-engine/src/test/java/org/junit/jupiter/api/DynamicTestTests.java

@@ -70,6 +70,26 @@ void streamFromIteratorPreconditions() {
 			() -> DynamicTest.stream(emptyIterator(), displayNameGenerator, null));
 	}
 
+	@Test
+	void streamFromStreamWithNamesPreconditions() {
+		ThrowingConsumer<Object> testExecutor = input -> {
+		};
+
+		assertThrows(PreconditionViolationException.class,
+			() -> DynamicTest.stream((Stream<? extends Named<Object>>) null, testExecutor));
+		assertThrows(PreconditionViolationException.class, () -> DynamicTest.stream(Stream.empty(), null));
+	}
+
+	@Test
+	void streamFromIteratorWithNamesPreconditions() {
+		ThrowingConsumer<Object> testExecutor = input -> {
+		};
+
+		assertThrows(PreconditionViolationException.class,
+			() -> DynamicTest.stream((Iterator<? extends Named<Object>>) null, testExecutor));
+		assertThrows(PreconditionViolationException.class, () -> DynamicTest.stream(emptyIterator(), null));
+	}
+
 	@Test
 	void streamFromStream() throws Throwable {
 		Stream<DynamicTest> stream = DynamicTest.stream(Stream.of("foo", "bar", "baz"), String::toUpperCase,
@@ -84,6 +104,21 @@ void streamFromIterator() throws Throwable {
 		assertStream(stream);
 	}
 
+	@Test
+	void streamFromStreamWithNames() throws Throwable {
+		Stream<DynamicTest> stream = DynamicTest.stream(
+			Stream.of(Named.of("FOO", "foo"), Named.of("BAR", "bar"), Named.of("BAZ", "baz")), this::throwingConsumer);
+		assertStream(stream);
+	}
+
+	@Test
+	void streamFromIteratorWithNames() throws Throwable {
+		Stream<DynamicTest> stream = DynamicTest.stream(
+			List.of(Named.of("FOO", "foo"), Named.of("BAR", "bar"), Named.of("BAZ", "baz")).iterator(),
+			this::throwingConsumer);
+		assertStream(stream);
+	}
+
 	private void assertStream(Stream<DynamicTest> stream) throws Throwable {
 		List<DynamicTest> dynamicTests = stream.collect(Collectors.toList());