Introduce support for cancelling a running execution to the Launcher API

This commit introduces `CancellationToken` that can be created and
passed to the `Launcher` as part of a `LauncherExecutionRequest`. The
`Launcher` checks whether cancellation has been requested on the token
prior to asking each test engine to execute tests. If cancellation has
been requested, the `Launcher` reports all direct children of engine
descriptors as skipped. Moreover, it passes the `CancellationToken` to
each engine so they can check and respond to cancellation as well which
will be implemented separately as indicated by TODO comments.

`EngineTestKit` also supports passing a `CancellationToken` to the
engine under test.

The documentation now contains an example for implementing a fail-fast
listener and documents the additional requirement for test engines that
wish to support cancellation.

Resolves #1880.

Author: marcphilipp

documentation/src/docs/asciidoc/link-attributes.adoc

@@ -22,6 +22,7 @@ endif::[]
 // Platform Engine
 :junit-platform-engine:                      {javadoc-root}/org.junit.platform.engine/org/junit/platform/engine/package-summary.html[junit-platform-engine]
 :junit-platform-engine-support-discovery:    {javadoc-root}/org.junit.platform.engine/org/junit/platform/engine/support/discovery/package-summary.html[org.junit.platform.engine.support.discovery]
+:CancellationToken:                          {javadoc-root}/org.junit.platform.engine/org/junit/platform/engine/CancellationToken.html[CancellationToken]
 :ClasspathResourceSelector:                  {javadoc-root}/org.junit.platform.engine/org/junit/platform/engine/discovery/ClasspathResourceSelector.html[ClasspathResourceSelector]
 :ClasspathRootSelector:                      {javadoc-root}/org.junit.platform.engine/org/junit/platform/engine/discovery/ClasspathRootSelector.html[ClasspathRootSelector]
 :ClassSelector:                              {javadoc-root}/org.junit.platform.engine/org/junit/platform/engine/discovery/ClassSelector.html[ClassSelector]
@@ -66,6 +67,7 @@ endif::[]
 :LauncherDiscoveryListener:                  {javadoc-root}/org.junit.platform.launcher/org/junit/platform/launcher/LauncherDiscoveryListener.html[LauncherDiscoveryListener]
 :LauncherDiscoveryRequest:                   {javadoc-root}/org.junit.platform.launcher/org/junit/platform/launcher/LauncherDiscoveryRequest.html[LauncherDiscoveryRequest]
 :LauncherDiscoveryRequestBuilder:            {javadoc-root}/org.junit.platform.launcher/org/junit/platform/launcher/core/LauncherDiscoveryRequestBuilder.html[LauncherDiscoveryRequestBuilder]
+:LauncherExecutionRequest:                   {javadoc-root}/org.junit.platform.launcher/org/junit/platform/launcher/LauncherExecutionRequest.html[LauncherExecutionRequest]
 :LauncherFactory:                            {javadoc-root}/org.junit.platform.launcher/org/junit/platform/launcher/core/LauncherFactory.html[LauncherFactory]
 :LauncherInterceptor:                        {javadoc-root}/org.junit.platform.launcher/org/junit/platform/launcher/LauncherInterceptor.html[LauncherInterceptor]
 :LauncherSession:                            {javadoc-root}/org.junit.platform.launcher/org/junit/platform/launcher/LauncherSession.html[LauncherSession]

documentation/src/docs/asciidoc/user-guide/advanced-topics/engines.adoc

@@ -120,6 +120,13 @@ compatibility with build tools and IDEs:
   siblings or other nodes that are required for the execution of the selected tests.
 * `TestEngines` _should_ support <<running-tests-tags, tagging>> tests and containers so
   that tag filters can be applied when discovering tests.
+* [[test-engines-requirements-cancellation]] A `TestEngine` _should_ cancel its execution
+  when the `{CancellationToken}` it is passed as part of the `ExecutionRequest` indicates
+  that cancellation has been requested. In this case, it _should_ report any remaining
+  `TestDescriptors` as skipped but not report any events for their descendants. It _may_
+  report already started `TestDescriptors` as aborted in case they have not been executed
+  completely. If a `TestEngine` supports cancellation, it should clean up any resources
+  that it has created just like if execution had finished regularly.
 
 [[test-engines-discovery-issues]]
 ==== Reporting Discovery Issues

documentation/src/docs/asciidoc/user-guide/advanced-topics/launcher-api.adoc

@@ -30,12 +30,12 @@ Usage Example:
 
 [source,java,indent=0]
 ----
-include::{testDir}/example/UsingTheLauncherDemo.java[tags=imports]
+include::{testDir}/example/UsingTheLauncherForDiscoveryDemo.java[tags=imports]
 ----
 
 [source,java,indent=0]
 ----
-include::{testDir}/example/UsingTheLauncherDemo.java[tags=discovery]
+include::{testDir}/example/UsingTheLauncherForDiscoveryDemo.java[tags=discovery]
 ----
 
 You can select classes, methods, and all classes in a package or even search for all tests
@@ -353,3 +353,31 @@ between them.
 
 Alternatively, it's possible to inject resources into test engines by
 <<launcher-api-launcher-session-listeners-custom, registering a `LauncherSessionListener`>>.
+
+[[launcher-api-launcher-cancellation]]
+==== Cancelling a Running Test Execution
+
+The launcher API provides the ability to cancel a running test execution mid-flight while
+allowing engines to clean up resources. To request an execution to be cancelled, you need
+to call `cancel()` on the `{CancellationToken}` that is passed to `Launcher.execute` as
+part of the `{LauncherExecutionRequest}`.
+
+For example, implementing a listener that cancels test execution after the first test
+failed can be achieved as follows.
+
+[source,java,indent=0]
+----
+include::{testDir}/example/UsingTheLauncherDemo.java[tags=cancellation]
+----
+<1> Create a `{CancellationToken}`
+<2> Implement a `{TestExecutionListener}` that calls `cancel()` when a test fails
+<3> Register the cancellation token
+<4> Register the listener
+<5> Pass the `{LauncherExecutionRequest}` to `Launcher.execute`
+
+WARNING: Cancelling tests relies on <<test-engines>> checking and responding to the
+`{CancellationToken}` appropriately (see
+<<test-engines-requirements-cancellation, Test Engine Requirements>> for details). The
+`Launcher` will also check the token and cancel test execution when multiple test engines
+are present at runtime.
+// TODO #4725 List engines that are known to support cancellation here

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

@@ -11,15 +11,18 @@
 package example;
 
 // tag::imports[]
+import static org.junit.platform.engine.TestExecutionResult.Status.FAILED;
 import static org.junit.platform.engine.discovery.ClassNameFilter.includeClassNamePatterns;
 import static org.junit.platform.engine.discovery.DiscoverySelectors.selectClass;
 import static org.junit.platform.engine.discovery.DiscoverySelectors.selectPackage;
 
 import java.io.PrintWriter;
 import java.nio.file.Path;
 
+import org.junit.platform.engine.CancellationToken;
 import org.junit.platform.engine.FilterResult;
 import org.junit.platform.engine.TestDescriptor;
+import org.junit.platform.engine.TestExecutionResult;
 import org.junit.platform.launcher.Launcher;
 import org.junit.platform.launcher.LauncherDiscoveryListener;
 import org.junit.platform.launcher.LauncherDiscoveryRequest;
@@ -28,6 +31,7 @@
 import org.junit.platform.launcher.LauncherSessionListener;
 import org.junit.platform.launcher.PostDiscoveryFilter;
 import org.junit.platform.launcher.TestExecutionListener;
+import org.junit.platform.launcher.TestIdentifier;
 import org.junit.platform.launcher.TestPlan;
 import org.junit.platform.launcher.core.LauncherConfig;
 import org.junit.platform.launcher.core.LauncherDiscoveryRequestBuilder;
@@ -43,33 +47,6 @@
  */
 class UsingTheLauncherDemo {
 
-	@org.junit.jupiter.api.Test
-	@SuppressWarnings("unused")
-	void discovery() {
-		// @formatter:off
-		// tag::discovery[]
-		LauncherDiscoveryRequest request = LauncherDiscoveryRequestBuilder.request()
-			.selectors(
-				selectPackage("com.example.mytests"),
-				selectClass(MyTestClass.class)
-			)
-			.filters(
-				includeClassNamePatterns(".*Tests")
-			)
-			// end::discovery[]
-			.configurationParameter("enableHttpServer", "false")
-			// tag::discovery[]
-			.build();
-
-		try (LauncherSession session = LauncherFactory.openSession()) {
-			TestPlan testPlan = session.getLauncher().discover(request);
-
-			// ... discover additional test plans or execute tests
-		}
-		// end::discovery[]
-		// @formatter:on
-	}
-
 	@org.junit.jupiter.api.Tag("exclude")
 	@org.junit.jupiter.api.Test
 	@SuppressWarnings("unused")
@@ -142,6 +119,41 @@ void launcherConfig() {
 		// @formatter:on
 	}
 
+	@org.junit.jupiter.api.Test
+	@SuppressWarnings("unused")
+	void cancellation() {
+		// tag::cancellation[]
+		CancellationToken cancellationToken = CancellationToken.create(); // <1>
+
+		TestExecutionListener failFastListener = new TestExecutionListener() {
+			@Override
+			public void executionFinished(TestIdentifier identifier, TestExecutionResult result) {
+				if (result.getStatus() == FAILED) {
+					cancellationToken.cancel(); // <2>
+				}
+			}
+		};
+
+		// end::cancellation[]
+		// @formatter:off
+		// tag::cancellation[]
+		LauncherExecutionRequest executionRequest = LauncherDiscoveryRequestBuilder.request()
+				.selectors(selectClass(MyTestClass.class))
+				.forExecution()
+				.cancellationToken(cancellationToken) // <3>
+				.listeners(failFastListener) // <4>
+				.build();
+		// end::cancellation[]
+		// @formatter:off
+		// tag::cancellation[]
+
+		try (LauncherSession session = LauncherFactory.openSession()) {
+			session.getLauncher().execute(executionRequest); // <5>
+		}
+		// end::cancellation[]
+		// @formatter:on
+	}
+
 }
 
 class MyTestClass {

documentation/src/test/java/example/UsingTheLauncherForDiscoveryDemo.java

@@ -0,0 +1,57 @@
+/*
+ * 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 example;
+
+// tag::imports[]
+import static org.junit.platform.engine.discovery.ClassNameFilter.includeClassNamePatterns;
+import static org.junit.platform.engine.discovery.DiscoverySelectors.selectClass;
+import static org.junit.platform.engine.discovery.DiscoverySelectors.selectPackage;
+
+import org.junit.platform.launcher.LauncherDiscoveryRequest;
+import org.junit.platform.launcher.LauncherSession;
+import org.junit.platform.launcher.TestPlan;
+import org.junit.platform.launcher.core.LauncherDiscoveryRequestBuilder;
+import org.junit.platform.launcher.core.LauncherFactory;
+// end::imports[]
+
+/**
+ * @since 6.0
+ */
+class UsingTheLauncherForDiscoveryDemo {
+
+	@org.junit.jupiter.api.Test
+	@SuppressWarnings("unused")
+	void discovery() {
+		// @formatter:off
+		// tag::discovery[]
+		LauncherDiscoveryRequest request = LauncherDiscoveryRequestBuilder.request()
+			.selectors(
+				selectPackage("com.example.mytests"),
+				selectClass(MyTestClass.class)
+			)
+			.filters(
+				includeClassNamePatterns(".*Tests")
+			)
+			.build();
+
+		try (LauncherSession session = LauncherFactory.openSession()) {
+			TestPlan testPlan = session.getLauncher().discover(request);
+
+			// ... discover additional test plans or execute tests
+		}
+		// end::discovery[]
+		// @formatter:on
+	}
+
+	static class MyTestClass {
+	}
+
+}

junit-platform-engine/src/main/java/org/junit/platform/engine/CancellationToken.java

@@ -0,0 +1,68 @@
+/*
+ * 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.engine;
+
+import static org.apiguardian.api.API.Status.EXPERIMENTAL;
+
+import org.apiguardian.api.API;
+
+/**
+ * Token that should be checked to determine whether an operation was requested
+ * to be cancelled.
+ *
+ * <p>For example, this is used by the
+ * {@link org.junit.platform.launcher.Launcher} and
+ * {@link org.junit.platform.engine.TestEngine} implementations to determine
+ * whether the current test execution should be cancelled.
+ *
+ * <p>This interface is not intended to be implemented by clients.
+ *
+ * @since 6.0
+ * @see org.junit.platform.launcher.LauncherExecutionRequest#getCancellationToken()
+ * @see ExecutionRequest#getCancellationToken()
+ */
+@API(status = EXPERIMENTAL, since = "6.0")
+public sealed interface CancellationToken permits RegularCancellationToken, DisabledCancellationToken {
+
+	/**
+	 * Create a new, uncancelled cancellation token.
+	 */
+	static CancellationToken create() {
+		return new RegularCancellationToken();
+	}
+
+	/**
+	 * Get a new cancellation token that cannot be cancelled.
+	 *
+	 * <p>This is only useful for cases when a cancellation token is required
+	 * but is not supported or irrelevant, for example, in tests.
+	 */
+	static CancellationToken disabled() {
+		return DisabledCancellationToken.INSTANCE;
+	}
+
+	/**
+	 * {@return whether cancellation has been requested}
+	 *
+	 * <p>Once this method returns {@code true}, it will never return
+	 * {@code false} in a subsequent call.
+	 */
+	boolean isCancellationRequested();
+
+	/**
+	 * Request cancellation.
+	 *
+	 * <p>This will call subsequent calls to {@link #isCancellationRequested()}
+	 * to return {@code true}.
+	 */
+	void cancel();
+
+}

junit-platform-engine/src/main/java/org/junit/platform/engine/DisabledCancellationToken.java

@@ -0,0 +1,31 @@
+/*
+ * 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.engine;
+
+/**
+ * @since 6.0
+ */
+final class DisabledCancellationToken implements CancellationToken {
+
+	static final DisabledCancellationToken INSTANCE = new DisabledCancellationToken();
+
+	private DisabledCancellationToken() {
+	}
+
+	@Override
+	public boolean isCancellationRequested() {
+		return false;
+	}
+
+	@Override
+	public void cancel() {
+	}
+}