Improve documentation of LauncherExecutionRequestBuilder (#5224)

Based on feedback received in #4728

Author: marcphilipp

documentation/modules/ROOT/pages/advanced-topics/launcher-api.adoc

@@ -363,7 +363,7 @@ failed can be achieved as follows.
 
 [source,java,indent=0]
 ----
-include::example$java/example/UsingTheLauncherDemo.java[tags=cancellation]
+include::example$java/example/UsingTheLauncherDemo.java[tags=cancellation-direct]
 ----
 <1> Create a `{CancellationToken}`
 <2> Implement a `{TestExecutionListener}` that calls `cancel()` when a test fails
@@ -387,3 +387,37 @@ At the time of writing, the following test engines support cancellation:
 * `{junit-platform-suite-engine}`
 * Any `{TestEngine}` extending `{HierarchicalTestEngine}` such as Spock and Cucumber
 ====
+
+[[launcher-cancellation-execution-request-from-discovery-request]]
+=== Building a LauncherExecutionRequest from a LauncherDiscoveryRequest
+
+Rather than building a `{LauncherExecutionRequest}` by starting with a
+`{LauncherDiscoveryRequestBuilder}` and calling `forExecution()`, you can create a
+`{LauncherExecutionRequestBuilder}` from a previously built `{LauncherDiscoveryRequest}`.
+
+[source,java,indent=0]
+----
+include::example$java/example/UsingTheLauncherDemo.java[tags=cancellation-discovery-request]
+----
+<1> Build a `{LauncherDiscoveryRequest}`
+<2> Create a `{LauncherExecutionRequestBuilder}` with it
+<3> Register the cancellation token
+<4> Register the listener
+<5> Pass the `{LauncherExecutionRequest}` to `Launcher.execute`
+
+[[launcher-cancellation-execution-request-from-test-plan]]
+=== Building a LauncherExecutionRequest from a TestPlan
+
+Alternatively, a `{LauncherExecutionRequestBuilder}` can be created from a previously
+discovered `{TestPlan}`.
+
+[source,java,indent=0]
+----
+include::example$java/example/UsingTheLauncherDemo.java[tags=cancellation-test-plan]
+----
+<1> Build a `{LauncherDiscoveryRequest}`
+<2> Discover a `{TestPlan}` via `Launcher.discover`
+<3> Create a `{LauncherExecutionRequestBuilder}` with it
+<4> Register the cancellation token
+<5> Register the listener
+<6> Pass the `{LauncherExecutionRequest}` to `Launcher.execute`

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

@@ -36,6 +36,7 @@
 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;
@@ -119,8 +120,8 @@ void launcherConfig() {
 
 	@Test
 	@SuppressWarnings("unused")
-	void cancellation() {
-		// tag::cancellation[]
+	void cancellationDirect() {
+		// tag::cancellation-direct[]
 		CancellationToken cancellationToken = CancellationToken.create(); // <1>
 
 		TestExecutionListener failFastListener = new TestExecutionListener() {
@@ -132,24 +133,92 @@ public void executionFinished(TestIdentifier identifier, TestExecutionResult res
 			}
 		};
 
-		// end::cancellation[]
+		// end::cancellation-direct[]
 		// @formatter:off
-		// tag::cancellation[]
+		// tag::cancellation-direct[]
 		LauncherExecutionRequest executionRequest = LauncherDiscoveryRequestBuilder.request()
 				.selectors(selectClass(MyTestClass.class))
 				.forExecution()
+				// end::cancellation-direct[]
+				// @formatter:on
+				// tag::cancellation-direct[]
 				.cancellationToken(cancellationToken) // <3>
 				.listeners(failFastListener) // <4>
 				.build();
-		// end::cancellation[]
+
+		try (LauncherSession session = LauncherFactory.openSession()) {
+			session.getLauncher().execute(executionRequest); // <5>
+		}
+		// end::cancellation-direct[]
+	}
+
+	@Test
+	@SuppressWarnings("unused")
+	void cancellationFromDiscoveryRequest() {
+		CancellationToken cancellationToken = CancellationToken.create();
+
+		TestExecutionListener failFastListener = new TestExecutionListener() {
+			@Override
+			public void executionFinished(TestIdentifier identifier, TestExecutionResult result) {
+				if (result.getStatus() == FAILED) {
+					cancellationToken.cancel();
+				}
+			}
+		};
+
 		// @formatter:off
-		// tag::cancellation[]
+		// tag::cancellation-discovery-request[]
+		LauncherDiscoveryRequest discoveryRequest = LauncherDiscoveryRequestBuilder.request()
+				.selectors(selectClass(MyTestClass.class))
+				.build(); // <1>
+		// end::cancellation-discovery-request[]
+		// @formatter:on
+		// tag::cancellation-discovery-request[]
+
+		LauncherExecutionRequest executionRequest = LauncherExecutionRequestBuilder.request(discoveryRequest) // <2>
+				.cancellationToken(cancellationToken) // <3>
+				.listeners(failFastListener) // <4>
+				.build();
 
 		try (LauncherSession session = LauncherFactory.openSession()) {
 			session.getLauncher().execute(executionRequest); // <5>
 		}
-		// end::cancellation[]
+		// end::cancellation-discovery-request[]
+	}
+
+	@Test
+	@SuppressWarnings("unused")
+	void cancellationFromTestPlan() {
+		CancellationToken cancellationToken = CancellationToken.create();
+
+		TestExecutionListener failFastListener = new TestExecutionListener() {
+			@Override
+			public void executionFinished(TestIdentifier identifier, TestExecutionResult result) {
+				if (result.getStatus() == FAILED) {
+					cancellationToken.cancel();
+				}
+			}
+		};
+
+		// @formatter:off
+		// tag::cancellation-test-plan[]
+		LauncherDiscoveryRequest discoveryRequest = LauncherDiscoveryRequestBuilder.request()
+				.selectors(selectClass(MyTestClass.class))
+				.build(); // <1>
+		// end::cancellation-test-plan[]
 		// @formatter:on
+		// tag::cancellation-test-plan[]
+
+		try (LauncherSession session = LauncherFactory.openSession()) {
+			var launcher = session.getLauncher();
+			TestPlan testPlan = launcher.discover(discoveryRequest); // <2>
+			LauncherExecutionRequest executionRequest = LauncherExecutionRequestBuilder.request(testPlan) // <3>
+					.cancellationToken(cancellationToken) // <4>
+					.listeners(failFastListener) // <5>
+					.build();
+			launcher.execute(executionRequest); // <6>
+		}
+		// end::cancellation-test-plan[]
 	}
 
 }