Introduce support for cancelling a running execution to the Launcher API

[marcphilipp]

Overview

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.

---

I hereby agree to the terms of the JUnit Contributor License Agreement.

---

Definition of Done

• There are no TODOs left in the code
• Method preconditions are checked and documented in the method's Javadoc
• Coding conventions (e.g. for logging) have been followed
• Change is covered by automated tests including corner cases, errors, and exception handling
• Public API has Javadoc and @API annotations
• Change is documented in the User Guide and Release Notes

[iloveeclipse]

@marcphilipp : could you please give a hint for IDE providers:

1. Which API is suggested
2. Starting from which JUnit version
3. Any side effects/behavior changes/incompatibilities related to that API that need to be considered by IDE providers
4. Give a link to the final document describing the usage of the new API?

Thanks.

[marcphilipp]

Sure!

Which API is suggested

The Launcher API will get a new execute(LauncherExecutionRequest) method and LauncherExecutionRequest.getCancellationToken() is checked by the JUnit Platform and registered test engines to determine whether cancellation has been requests.

Starting from which JUnit version

6.0.0-M2 (not released yet)

Any side effects/behavior changes/incompatibilities related to that API that need to be considered by IDE providers

To effectively cancel test execution, registered test engines will have to implement support cancellation. As you can see in the umbrella issue #4725, all engines provided by the JUnit team (Jupiter, Suites, Vintage, and TestNG) will do so and some third-party engines (most notably, Cucumber and Spock) will automatically receive support since they extend HierarchicalTestEngine. Other engines may be slower to adopt. Therefore, I think IDE providers should first try to cancel execution gracefully but have an option or timeout in place after which the forked JVM is terminated without waiting in case a user has requested test execution to be cancelled.

Give a link to the final document describing the usage of the new API?

I added a full example to the docs: https://docs.junit.org/snapshot/user-guide/#launcher-api-launcher-cancellation

Please let me know if you have any concerns or questions.