Merge branch 'issues/1771-testkit-loose-event-matching'

Author: mmerdes

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

@@ -36,7 +36,13 @@ on GitHub.
   execution of a submitted test via the returned `Future`.
 * Add `EngineExecutionListener.NOOP` and change all declared methods to have empty default
   implementations.
-
+* The TestKit now allows to match conditions with events loosely, i.e. an incomplete match
+  with or without a fixed order.
+* Add `Node.DynamicTestExecutor#execute(TestDescriptor, EngineExecutionListener)` for
+  engines that wish to pass a custom `EngineExecutionListener` and cancel or wait for the
+  execution of a submitted test via the returned `Future`.
+* Add `EngineExecutionListener.NOOP` and change all declared methods to have empty default
+  implementations.
 
 [[release-notes-5.7.0-M1-junit-jupiter]]
 === JUnit Jupiter

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

@@ -132,6 +132,10 @@ methods are executed, which in turn allows our `verifyAllJupiterEvents()` test t
 reliable.
 ====
 
+If you want to do a _partial_ match _with_ or _without_ ordering requirements, you can use
+the methods `assertEventsMatchLooselyInOrder()` and `assertEventsMatchLoosely()`,
+respectively.
+
 [source,java,indent=0]
 ----
 include::{testDir}/example/testkit/EngineTestKitAllEventsDemo.java[tags=user_guide]

junit-platform-testkit/src/main/java/org/junit/platform/testkit/engine/Events.java

@@ -10,6 +10,7 @@
 
 package org.junit.platform.testkit.engine;
 
+import static java.util.Collections.sort;
 import static java.util.function.Predicate.isEqual;
 import static java.util.stream.Collectors.toList;
 import static org.apiguardian.api.API.Status.EXPERIMENTAL;
@@ -20,8 +21,12 @@
 import java.io.OutputStream;
 import java.io.PrintWriter;
 import java.io.Writer;
+import java.util.ArrayList;
+import java.util.Arrays;
 import java.util.Collections;
 import java.util.List;
+import java.util.Objects;
+import java.util.Optional;
 import java.util.function.Consumer;
 import java.util.function.Function;
 import java.util.function.Predicate;
@@ -36,6 +41,7 @@
 import org.junit.platform.commons.util.Preconditions;
 import org.junit.platform.engine.TestExecutionResult;
 import org.junit.platform.engine.TestExecutionResult.Status;
+import org.opentest4j.AssertionFailedError;
 
 /**
  * {@code Events} is a facade that provides a fluent API for working with
@@ -259,6 +265,67 @@ public final void assertEventsMatchExactly(Condition<? super Event>... condition
 		assertEventsMatchExactly(this.events, conditions);
 	}
 
+	/**
+	 * Assert that all provided conditions are matched by an {@linkplain Event event}
+	 * contained in this {@code Events} object regardless of order.
+	 * Note that this method does a partial match, i.e. some events may not match any
+	 * of the provided conditions.
+	 *
+	 * <p>Conditions can be imported statically from {@link EventConditions}
+	 * and {@link TestExecutionResultConditions}.
+	 *
+	 * <h4>Example</h4>
+	 *
+	 * <pre class="code">
+	 * executionResults.testEvents().assertEventsMatchLoosely(
+	 *     event(test("exampleTestMethod"), started()),
+	 *     event(test("exampleTestMethod"), finishedSuccessfully())
+	 * );
+	 * </pre>
+	 *
+	 * @param conditions the conditions to match against; never {@code null}
+	 * @see EventConditions
+	 * @see TestExecutionResultConditions
+	 */
+	@SafeVarargs
+	@SuppressWarnings("varargs")
+	public final void assertEventsMatchLoosely(Condition<? super Event>... conditions) {
+		Preconditions.notNull(conditions, "conditions must not be null");
+		Preconditions.containsNoNullElements(conditions, "conditions must not contain null elements");
+		assertEventsMatchLoosely(this.events, conditions);
+	}
+
+	/**
+	 * Assert that all provided conditions are matched by an {@linkplain Event event}
+	 * contained in this {@code Events} object.
+	 * Note that this method does a partial match, i.e. some events may not match any
+	 * of the provided conditions.
+	 * However, the conditions provided must be in the correct order.
+	 *
+	 * <p>Conditions can be imported statically from {@link EventConditions}
+	 * and {@link TestExecutionResultConditions}.
+	 *
+	 * <h4>Example</h4>
+	 *
+	 * <pre class="code">
+	 * executionResults.testEvents().assertEventsMatchLooselyInOrder(
+	 *     event(test("exampleTestMethod"), started()),
+	 *     event(test("exampleTestMethod"), finishedSuccessfully())
+	 * );
+	 * </pre>
+	 *
+	 * @param conditions the conditions to match against; never {@code null}
+	 * @see EventConditions
+	 * @see TestExecutionResultConditions
+	 */
+	@SafeVarargs
+	@SuppressWarnings("varargs")
+	public final void assertEventsMatchLooselyInOrder(Condition<? super Event>... conditions) {
+		Preconditions.notNull(conditions, "conditions must not be null");
+		Preconditions.containsNoNullElements(conditions, "conditions must not contain null elements");
+		assertEventsMatchLooselyInOrder(this.events, conditions);
+	}
+
 	/**
 	 * Shortcut for {@code org.assertj.core.api.Assertions.assertThat(events.list())}.
 	 *
@@ -336,4 +403,63 @@ private static void assertEventsMatchExactly(List<Event> events, Condition<? sup
 		softly.assertAll();
 	}
 
+	@SafeVarargs
+	private static void assertEventsMatchLoosely(List<Event> events, Condition<? super Event>... conditions) {
+		SoftAssertions softly = new SoftAssertions();
+		for (Condition<? super Event> condition : conditions) {
+			checkCondition(events, softly, condition);
+		}
+		softly.assertAll();
+	}
+
+	@SafeVarargs
+	@SuppressWarnings("varargs")
+	private static void assertEventsMatchLooselyInOrder(List<Event> events, Condition<? super Event>... conditions) {
+		Assertions.assertThat(conditions).hasSizeLessThanOrEqualTo(events.size());
+		SoftAssertions softly = new SoftAssertions();
+
+		// @formatter:off
+		List<Integer> indices = Arrays.stream(conditions)
+				.map(condition -> findEvent(events, softly, condition))
+				.filter(Objects::nonNull)
+				.map(events::indexOf)
+				.collect(toList());
+		// @formatter:on
+
+		if (isNotInIncreasingOrder(indices)) {
+			throw new AssertionFailedError("Conditions are not in the correct order.");
+		}
+
+		softly.assertAll();
+	}
+
+	private static boolean isNotInIncreasingOrder(List<Integer> indices) {
+		List<Integer> copy = new ArrayList<>(indices);
+		sort(copy);
+
+		return !indices.equals(copy);
+	}
+
+	private static void checkCondition(List<Event> events, SoftAssertions softly, Condition<? super Event> condition) {
+		boolean matches = events.stream().anyMatch(condition::matches);
+
+		if (!matches) {
+			softly.fail("Condition did not match any event: " + condition);
+		}
+	}
+
+	private static Event findEvent(List<Event> events, SoftAssertions softly, Condition<? super Event> condition) {
+		// @formatter:off
+		Optional<Event> matchedEvent = events.stream()
+				.filter(condition::matches)
+				.findFirst();
+		// @formatter:on
+
+		if (!matchedEvent.isPresent()) {
+			softly.fail("Condition did not match any event: " + condition);
+		}
+
+		return matchedEvent.orElse(null);
+	}
+
 }