Allow using DynamicTestExecutor with custom listener (#2238)

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

Resolves #2188.

Author: marcphilipp

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

@@ -31,6 +31,11 @@ on GitHub.
   one to specify a comma-separated list of patterns for deactivating
   `TestExecutionListener` implementations registered via the `ServiceLoader` mechanism.
 * The `@Testable` annotation may now be applied _directly_ to fields.
+* 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-platform-engine/src/main/java/org/junit/platform/engine/EngineExecutionListener.java

@@ -31,6 +31,12 @@
 @API(status = STABLE, since = "1.0")
 public interface EngineExecutionListener {
 
+	/**
+	 * No-op implementation of {@code EngineExecutionListener}
+	 */
+	EngineExecutionListener NOOP = new EngineExecutionListener() {
+	};
+
 	/**
 	 * Must be called when a new, dynamic {@link TestDescriptor} has been
 	 * registered.
@@ -41,7 +47,8 @@ public interface EngineExecutionListener {
 	 * @param testDescriptor the descriptor of the newly registered test
 	 * or container
 	 */
-	void dynamicTestRegistered(TestDescriptor testDescriptor);
+	default void dynamicTestRegistered(TestDescriptor testDescriptor) {
+	}
 
 	/**
 	 * Must be called when the execution of a leaf or subtree of the test tree
@@ -59,7 +66,8 @@ public interface EngineExecutionListener {
 	 * @param reason a human-readable message describing why the execution
 	 * has been skipped
 	 */
-	void executionSkipped(TestDescriptor testDescriptor, String reason);
+	default void executionSkipped(TestDescriptor testDescriptor, String reason) {
+	}
 
 	/**
 	 * Must be called when the execution of a leaf or subtree of the test tree
@@ -78,7 +86,8 @@ public interface EngineExecutionListener {
 	 *
 	 * @param testDescriptor the descriptor of the started test or container
 	 */
-	void executionStarted(TestDescriptor testDescriptor);
+	default void executionStarted(TestDescriptor testDescriptor) {
+	}
 
 	/**
 	 * Must be called when the execution of a leaf or subtree of the test tree
@@ -106,7 +115,8 @@ public interface EngineExecutionListener {
 	 *
 	 * @see TestExecutionResult
 	 */
-	void executionFinished(TestDescriptor testDescriptor, TestExecutionResult testExecutionResult);
+	default void executionFinished(TestDescriptor testDescriptor, TestExecutionResult testExecutionResult) {
+	}
 
 	/**
 	 * Can be called for any {@link TestDescriptor} in order to publish additional
@@ -124,6 +134,7 @@ public interface EngineExecutionListener {
 	 * the reporting entry belongs
 	 * @param entry a {@code ReportEntry} instance to be published
 	 */
-	void reportingEntryPublished(TestDescriptor testDescriptor, ReportEntry entry);
+	default void reportingEntryPublished(TestDescriptor testDescriptor, ReportEntry entry) {
+	}
 
 }

junit-platform-engine/src/main/java/org/junit/platform/engine/support/hierarchical/Node.java

@@ -16,9 +16,11 @@
 
 import java.util.Optional;
 import java.util.Set;
+import java.util.concurrent.Future;
 
 import org.apiguardian.api.API;
 import org.junit.platform.commons.util.ToStringBuilder;
+import org.junit.platform.engine.EngineExecutionListener;
 import org.junit.platform.engine.TestDescriptor;
 import org.junit.platform.engine.TestExecutionResult;
 
@@ -282,10 +284,26 @@ interface DynamicTestExecutor {
 		/**
 		 * Submit a dynamic test descriptor for immediate execution.
 		 *
-		 * @param testDescriptor the test descriptor to be executed
+		 * @param testDescriptor the test descriptor to be executed; never
+		 * {@code null}
 		 */
 		void execute(TestDescriptor testDescriptor);
 
+		/**
+		 * Submit a dynamic test descriptor for immediate execution with a
+		 * custom, potentially no-op, execution listener.
+		 *
+		 * @param testDescriptor the test descriptor to be executed; never
+		 * {@code null}
+		 * @param executionListener the executionListener to be notified; never
+		 * {@code null}
+		 * @return a future to cancel or wait for the execution
+		 * @see EngineExecutionListener#NOOP
+		 * @since 5.7
+		 */
+		@API(status = EXPERIMENTAL, since = "5.7")
+		Future<?> execute(TestDescriptor testDescriptor, EngineExecutionListener executionListener);
+
 		/**
 		 * Block until all dynamic test descriptors submitted to this executor
 		 * are finished.

junit-platform-engine/src/main/java/org/junit/platform/engine/support/hierarchical/NodeTestTask.java

@@ -10,12 +10,14 @@
 
 package org.junit.platform.engine.support.hierarchical;
 
+import static java.util.concurrent.CompletableFuture.completedFuture;
 import static java.util.stream.Collectors.toCollection;
 import static org.junit.platform.engine.TestExecutionResult.failed;
 
 import java.util.ArrayList;
 import java.util.List;
 import java.util.Set;
+import java.util.concurrent.CancellationException;
 import java.util.concurrent.ExecutionException;
 import java.util.concurrent.Future;
 
@@ -24,6 +26,8 @@
 import org.junit.platform.commons.logging.LoggerFactory;
 import org.junit.platform.commons.util.BlacklistedExceptions;
 import org.junit.platform.commons.util.ExceptionUtils;
+import org.junit.platform.commons.util.Preconditions;
+import org.junit.platform.engine.EngineExecutionListener;
 import org.junit.platform.engine.TestDescriptor;
 import org.junit.platform.engine.support.hierarchical.HierarchicalTestExecutorService.TestTask;
 import org.junit.platform.engine.support.hierarchical.Node.DynamicTestExecutor;
@@ -184,18 +188,30 @@ private class DefaultDynamicTestExecutor implements DynamicTestExecutor {
 		private final List<Future<?>> futures = new ArrayList<>();
 
 		@Override
-		public void execute(TestDescriptor dynamicTestDescriptor) {
-			taskContext.getListener().dynamicTestRegistered(dynamicTestDescriptor);
-			Set<ExclusiveResource> exclusiveResources = NodeUtils.asNode(dynamicTestDescriptor).getExclusiveResources();
+		public void execute(TestDescriptor testDescriptor) {
+			execute(testDescriptor, taskContext.getListener());
+		}
+
+		@Override
+		public Future<?> execute(TestDescriptor testDescriptor, EngineExecutionListener executionListener) {
+			Preconditions.notNull(testDescriptor, "testDescriptor must not be null");
+			Preconditions.notNull(executionListener, "executionListener must not be null");
+
+			executionListener.dynamicTestRegistered(testDescriptor);
+			Set<ExclusiveResource> exclusiveResources = NodeUtils.asNode(testDescriptor).getExclusiveResources();
 			if (!exclusiveResources.isEmpty()) {
-				taskContext.getListener().executionStarted(dynamicTestDescriptor);
+				executionListener.executionStarted(testDescriptor);
 				String message = "Dynamic test descriptors must not declare exclusive resources: " + exclusiveResources;
-				taskContext.getListener().executionFinished(dynamicTestDescriptor, failed(new JUnitException(message)));
+				executionListener.executionFinished(testDescriptor, failed(new JUnitException(message)));
+				return completedFuture(null);
 			}
 			else {
-				NodeTestTask<C> nodeTestTask = new NodeTestTask<>(taskContext, dynamicTestDescriptor);
+				NodeTestTask<C> nodeTestTask = new NodeTestTask<>(taskContext.withListener(executionListener),
+					testDescriptor);
 				nodeTestTask.setParentContext(context);
-				futures.add(taskContext.getExecutorService().submit(nodeTestTask));
+				Future<?> future = taskContext.getExecutorService().submit(nodeTestTask);
+				futures.add(future);
+				return future;
 			}
 		}
 
@@ -205,6 +221,9 @@ public void awaitFinished() throws InterruptedException {
 				try {
 					future.get();
 				}
+				catch (CancellationException ignore) {
+					// Futures returned by execute() may have been cancelled
+				}
 				catch (ExecutionException e) {
 					ExceptionUtils.throwAsUncheckedException(e.getCause());
 				}

junit-platform-engine/src/main/java/org/junit/platform/engine/support/hierarchical/NodeTestTaskContext.java

@@ -30,6 +30,13 @@ public NodeTestTaskContext(EngineExecutionListener listener, HierarchicalTestExe
 		this.executionAdvisor = executionAdvisor;
 	}
 
+	NodeTestTaskContext withListener(EngineExecutionListener listener) {
+		if (this.listener == listener) {
+			return this;
+		}
+		return new NodeTestTaskContext(listener, executorService, throwableCollectorFactory, executionAdvisor);
+	}
+
 	EngineExecutionListener getListener() {
 		return listener;
 	}

junit-platform-launcher/src/testFixtures/java/org/junit/platform/launcher/core/ConfigurationParametersFactoryForTests.java

@@ -0,0 +1,25 @@
+/*
+ * Copyright 2015-2020 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.platform.launcher.core;
+
+import java.util.Map;
+
+import org.junit.platform.engine.ConfigurationParameters;
+
+public class ConfigurationParametersFactoryForTests {
+
+	private ConfigurationParametersFactoryForTests() {
+	}
+
+	public static ConfigurationParameters create(Map<String, String> configParams) {
+		return new LauncherConfigurationParameters(configParams, "/dev/null");
+	}
+}