Introduce LauncherExecutionRequest (#4724)

The new `Launcher.execute(LauncherExecutionRequest)` method paves the
road for adding additional parameters to test execution without having
to add additional overloads of `execute()`. For example, for #1880
we will likely need to introduce a `CancellationToken` (as drafted
in #4709). Instead of having to add two new overloads, such changes will
then be easy because only `LauncherExecutionRequest` will need to be
changed.

`LauncherExecutionRequestBuilder` provides a fluent API for constructing
execution requests starting either with a `TestPlan` or a
`LauncherDiscoveryRequest`. In addition,
`LauncherDiscoveryRequestBuilder.forExecution()` is a convenience method
to create an execution request from a discovery request.

Author: marcphilipp

documentation/src/docs/asciidoc/release-notes/release-notes-6.0.0-M2.adoc

@@ -23,10 +23,19 @@ repository on GitHub.
 
 * Discontinue `junit-platform-suite-commons` which is now integrated into
   `junit-platform-suite`.
+* Deprecate `Launcher.execute(TestPlan, TestExecutionListener[])` and
+  `Launcher.execute(LauncherDiscoveryRequest, TestExecutionListener[])` in favor of
+  `Launcher.execute(LauncherExecutionRequest)`
 
 [[release-notes-6.0.0-M2-junit-platform-new-features-and-improvements]]
 ==== New Features and Improvements
 
+* Introduce new `Launcher.execute(LauncherExecutionRequest)` API with corresponding
+  `LauncherExecutionRequestBuilder` to enable the addition of parameters to test
+  executions without additional overloads of `execute`.
+* Introduce `LauncherDiscoveryRequestBuilder.forExecution()` method as a convenience
+  method for constructing a `LauncherExecutionRequest` that contains a
+  `LauncherDiscoveryRequest`.
 * Introduce `TestTask.getTestDescriptor()` method for use in
   `HierarchicalTestExecutorService` implementations.
 

documentation/src/test/java/example/UsingTheLauncherDemo.java

@@ -23,13 +23,15 @@
 import org.junit.platform.launcher.Launcher;
 import org.junit.platform.launcher.LauncherDiscoveryListener;
 import org.junit.platform.launcher.LauncherDiscoveryRequest;
+import org.junit.platform.launcher.LauncherExecutionRequest;
 import org.junit.platform.launcher.LauncherSession;
 import org.junit.platform.launcher.LauncherSessionListener;
 import org.junit.platform.launcher.PostDiscoveryFilter;
 import org.junit.platform.launcher.TestExecutionListener;
 import org.junit.platform.launcher.TestPlan;
 import org.junit.platform.launcher.core.LauncherConfig;
 import org.junit.platform.launcher.core.LauncherDiscoveryRequestBuilder;
+import org.junit.platform.launcher.core.LauncherExecutionRequestBuilder;
 import org.junit.platform.launcher.core.LauncherFactory;
 import org.junit.platform.launcher.listeners.SummaryGeneratingListener;
 import org.junit.platform.launcher.listeners.TestExecutionSummary;
@@ -74,7 +76,7 @@ void discovery() {
 	void execution() {
 		// @formatter:off
 		// tag::execution[]
-		LauncherDiscoveryRequest request = LauncherDiscoveryRequestBuilder.request()
+		LauncherDiscoveryRequest discoveryRequest = LauncherDiscoveryRequestBuilder.request()
 			.selectors(
 				selectPackage("com.example.mytests"),
 				selectClass(MyTestClass.class)
@@ -94,11 +96,11 @@ void execution() {
 			// Register a listener of your choice
 			launcher.registerTestExecutionListeners(listener);
 			// Discover tests and build a test plan
-			TestPlan testPlan = launcher.discover(request);
+			TestPlan testPlan = launcher.discover(discoveryRequest);
 			// Execute test plan
-			launcher.execute(testPlan);
-			// Alternatively, execute the request directly
-			launcher.execute(request);
+			launcher.execute(LauncherExecutionRequestBuilder.request(testPlan).build());
+			// Alternatively, execute the discoveryRequest request directly
+			launcher.execute(LauncherExecutionRequestBuilder.request(discoveryRequest).build());
 		}
 
 		TestExecutionSummary summary = listener.getSummary();
@@ -128,8 +130,9 @@ void launcherConfig() {
 			.addTestExecutionListeners(new CustomTestExecutionListener())
 			.build();
 
-		LauncherDiscoveryRequest request = LauncherDiscoveryRequestBuilder.request()
+		LauncherExecutionRequest request = LauncherDiscoveryRequestBuilder.request()
 			.selectors(selectPackage("com.example.mytests"))
+			.forExecution()
 			.build();
 
 		try (LauncherSession session = LauncherFactory.openSession(launcherConfig)) {

documentation/src/test/java/example/sharedresources/SharedResourceDemo.java

@@ -39,7 +39,7 @@ void runBothCustomEnginesTest() {
 				// tag::custom_line_break[]
 				.build());
 
-		launcher.execute(request().build());
+		launcher.execute(request().forExecution().build());
 
 		assertSame(firstCustomEngine.socket, secondCustomEngine.socket);
 		assertTrue(firstCustomEngine.socket.isClosed(), "socket should be closed");

junit-platform-console/src/main/java/org/junit/platform/console/tasks/ConsoleTestExecutor.java

@@ -143,7 +143,7 @@ private void launchTests(Launcher launcher, Optional<Path> reportsDir) {
 		LauncherDiscoveryRequestBuilder discoveryRequestBuilder = toDiscoveryRequestBuilder(discoveryOptions);
 		reportsDir.ifPresent(dir -> discoveryRequestBuilder.configurationParameter(OUTPUT_DIR_PROPERTY_NAME,
 			dir.toAbsolutePath().toString()));
-		launcher.execute(discoveryRequestBuilder.build());
+		launcher.execute(discoveryRequestBuilder.forExecution().build());
 	}
 
 	private Optional<ClassLoader> createCustomClassLoader() {

junit-platform-launcher/src/main/java/org/junit/platform/launcher/Launcher.java

@@ -10,9 +10,12 @@
 
 package org.junit.platform.launcher;
 
+import static org.apiguardian.api.API.Status.DEPRECATED;
+import static org.apiguardian.api.API.Status.MAINTAINED;
 import static org.apiguardian.api.API.Status.STABLE;
 
 import org.apiguardian.api.API;
+import org.junit.platform.launcher.core.LauncherExecutionRequestBuilder;
 
 /**
  * The {@code Launcher} API is the main entry point for client code that
@@ -105,8 +108,16 @@ public interface Launcher {
 	 *
 	 * @param launcherDiscoveryRequest the launcher discovery request; never {@code null}
 	 * @param listeners additional test execution listeners; never {@code null}
+	 * @deprecated Please use {@link #execute(LauncherExecutionRequest)} instead.
 	 */
-	void execute(LauncherDiscoveryRequest launcherDiscoveryRequest, TestExecutionListener... listeners);
+	@Deprecated
+	@API(status = DEPRECATED, since = "6.0")
+	default void execute(LauncherDiscoveryRequest launcherDiscoveryRequest, TestExecutionListener... listeners) {
+		var executionRequest = LauncherExecutionRequestBuilder.request(launcherDiscoveryRequest) //
+				.listeners(listeners) //
+				.build();
+		execute(executionRequest);
+	}
 
 	/**
 	 * Execute the supplied {@link TestPlan} and notify
@@ -123,8 +134,44 @@ public interface Launcher {
 	 * @param testPlan the test plan to execute; never {@code null}
 	 * @param listeners additional test execution listeners; never {@code null}
 	 * @since 1.4
+	 * @deprecated Please use {@link #execute(LauncherExecutionRequest)} instead.
 	 */
-	@API(status = STABLE, since = "1.4")
-	void execute(TestPlan testPlan, TestExecutionListener... listeners);
+	@Deprecated
+	@API(status = DEPRECATED, since = "6.0")
+	default void execute(TestPlan testPlan, TestExecutionListener... listeners) {
+		var executionRequest = LauncherExecutionRequestBuilder.request(testPlan) //
+				.listeners(listeners) //
+				.build();
+		execute(executionRequest);
+	}
+
+	/**
+	 * Execute tests according to the supplied {@link LauncherExecutionRequest}
+	 * {@linkplain #registerTestExecutionListeners registered listeners} about
+	 * the progress and results of the execution.
+	 *
+	 * <p>Test execution listeners supplied
+	 * {@linkplain LauncherExecutionRequest#getAdditionalTestExecutionListeners()
+	 * as part of the request} are registered in addition to already registered
+	 * listeners but only for the supplied execution request.
+	 *
+	 * @apiNote If the execution request contains a {@link TestPlan} rather than
+	 * a {@link LauncherDiscoveryRequest}, it must not have been executed
+	 * previously.
+	 *
+	 * <p>If the execution request contains a {@link LauncherDiscoveryRequest},
+	 * calling this method will cause test discovery to be executed for all
+	 * registered engines. If the same {@link LauncherDiscoveryRequest} was
+	 * previously passed to {@link #discover(LauncherDiscoveryRequest)}, you
+	 * should instead provide the resulting {@link TestPlan} as part of the
+	 * supplied execution request to avoid the potential performance degradation
+	 * (e.g., classpath scanning) of running test discovery twice.
+	 *
+	 * @param launcherExecutionRequest the launcher execution request; never
+	 * {@code null}
+	 * @since 6.0
+	 */
+	@API(status = MAINTAINED, since = "6.0")
+	void execute(LauncherExecutionRequest launcherExecutionRequest);
 
 }

junit-platform-launcher/src/main/java/org/junit/platform/launcher/LauncherConstants.java

@@ -257,8 +257,7 @@ public class LauncherConstants {
 	 * <p>If not specified, the {@code Launcher} will report discovery issues
 	 * during the discovery phase if
 	 * {@link Launcher#discover(LauncherDiscoveryRequest)} is called, and during
-	 * the execution phase if
-	 * {@link Launcher#execute(LauncherDiscoveryRequest, TestExecutionListener...)}
+	 * the execution phase if {@link Launcher#execute(LauncherExecutionRequest)}
 	 * is called.
 	 *
 	 * @since 1.13

junit-platform-launcher/src/main/java/org/junit/platform/launcher/LauncherDiscoveryRequest.java

@@ -43,6 +43,8 @@
  * in the test plan.</li>
  * </ul>
  *
+ * <p>This interface is not intended to be implemented by clients.
+ *
  * @since 1.0
  * @see org.junit.platform.launcher.core.LauncherDiscoveryRequestBuilder
  * @see EngineDiscoveryRequest

junit-platform-launcher/src/main/java/org/junit/platform/launcher/LauncherExecutionRequest.java

@@ -0,0 +1,64 @@
+/*
+ * Copyright 2015-2025 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;
+
+import static org.apiguardian.api.API.Status.MAINTAINED;
+
+import java.util.Collection;
+import java.util.Optional;
+
+import org.apiguardian.api.API;
+
+/**
+ * {@code LauncherExecutionRequest} encapsulates a request for test execution
+ * passed to the {@link Launcher}.
+ *
+ * <p>Most importantly, a {@code LauncherExecutionRequest} contains either a
+ * {@link LauncherDiscoveryRequest} for on-the-fly test discovery or a
+ * {@link TestPlan} that has previously been discovered.
+ *
+ * <p>Moreover, a {@code LauncherExecutionRequest} may contain the following:
+ *
+ * <ul>
+ * <li>Additional {@linkplain TestExecutionListener Test Execution Listeners}
+ * that should be notified of events pertaining to this execution request.</li>
+ * </ul>
+ *
+ * <p>This interface is not intended to be implemented by clients.
+ *
+ * @since 6.0
+ * @see org.junit.platform.launcher.core.LauncherExecutionRequestBuilder
+ * @see Launcher#execute(LauncherExecutionRequest)
+ */
+@API(status = MAINTAINED, since = "6.0")
+public interface LauncherExecutionRequest {
+
+	/**
+	 * {@return the test plan for this execution request}
+	 *
+	 * <p>If absent, a {@link TestPlan} will be present.
+	 */
+	Optional<TestPlan> getTestPlan();
+
+	/**
+	 * {@return the discovery request for this execution request}
+	 *
+	 * <p>If absent, a {@link TestPlan} will be present.
+	 */
+	Optional<LauncherDiscoveryRequest> getDiscoveryRequest();
+
+	/**
+	 * {@return the collection of additional test execution listeners that
+	 * should be notified about events pertaining to this execution request}
+	 */
+	Collection<? extends TestExecutionListener> getAdditionalTestExecutionListeners();
+
+}

junit-platform-launcher/src/main/java/org/junit/platform/launcher/LauncherInterceptor.java

@@ -32,8 +32,9 @@
  *     </li>
  *     <li>
  *         calls to {@link Launcher#discover(LauncherDiscoveryRequest)},
- *         {@link Launcher#execute(TestPlan, TestExecutionListener...)}, and
- *         {@link Launcher#execute(LauncherDiscoveryRequest, TestExecutionListener...)}
+ *         {@link Launcher#execute(TestPlan, TestExecutionListener...)},
+ *         {@link Launcher#execute(LauncherDiscoveryRequest, TestExecutionListener...)},
+ *         and {@link Launcher#execute(LauncherExecutionRequest)},
  *     </li>
  * </ul>
  *

junit-platform-launcher/src/main/java/org/junit/platform/launcher/TestExecutionListener.java

@@ -22,7 +22,8 @@
 
 /**
  * Register a concrete implementation of this interface with a {@link Launcher}
- * to be notified of events that occur during test execution.
+ * or {@link LauncherExecutionRequest} to be notified of events that occur
+ * during test execution.
  *
  * <p>All methods in this interface have empty <em>default</em> implementations.
  * Concrete implementations may therefore override one or more of these methods