Improve Testkit Executions documentation (#5534)

* Deprecate Execution::started to avoid ambiguity. Executions are only
  ever skipped or finished.
* Document that executions are created from events.
* Document that execution either coincide with a skipped event or span
  started and finished event.
* Document that aborted, succeeded and failed executions are subsets of
  finished.

Author: mpkorstanje

documentation/modules/ROOT/partials/release-notes/release-notes-6.1.0-M2.adoc

@@ -25,7 +25,8 @@ repository on GitHub.
 [[v6.1.0-M2-junit-platform-deprecations-and-breaking-changes]]
 ==== Deprecations and Breaking Changes
 
-* ❓
+* Deprecate `Executions.started()` in favor of `Executions.finished()`. Started executions are
+  always finished.
 
 [[v6.1.0-M2-junit-platform-new-features-and-improvements]]
 ==== New Features and Improvements

junit-platform-testkit/src/main/java/org/junit/platform/testkit/engine/Events.java

@@ -38,6 +38,7 @@
 import org.assertj.core.data.Index;
 import org.jspecify.annotations.Nullable;
 import org.junit.platform.commons.util.Preconditions;
+import org.junit.platform.engine.TestDescriptor;
 import org.junit.platform.engine.TestExecutionResult;
 import org.junit.platform.engine.TestExecutionResult.Status;
 import org.opentest4j.AssertionFailedError;
@@ -121,6 +122,14 @@ public Stream<Event> filter(Predicate<? super Event> predicate) {
 
 	/**
 	 * Get the {@link Executions} for the current set of {@linkplain Event events}.
+	 * <p>
+	 * The set of executions is derived from the current set of events by
+	 * taking single {@linkplain  Event#executionSkipped(TestDescriptor, String)
+	 * execution skipped} events and pairs of {@linkplain Event#executionStarted(TestDescriptor)
+	 * execution started} and {@linkplain Event#executionFinished(TestDescriptor, TestExecutionResult)
+	 * execution finished} events. As a consequence, executions for which either
+	 * the started or finished event is not included in the current set of
+	 * events are not included.
 	 *
 	 * @return an instance of {@code Executions} for the current set of events;
 	 * never {@code null}

junit-platform-testkit/src/main/java/org/junit/platform/testkit/engine/Execution.java

@@ -18,12 +18,18 @@
 import org.apiguardian.api.API;
 import org.junit.platform.commons.util.Preconditions;
 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;
 
 /**
  * {@code Execution} encapsulates metadata for the execution of a single
  * {@link TestDescriptor}.
+ * <p>
+ * The execution either coincides with a single
+ * {@linkplain EngineExecutionListener#executionSkipped(TestDescriptor, String) skipped} event or spans a
+ * {@linkplain EngineExecutionListener#executionStarted(TestDescriptor) execution started} and
+ * {@linkplain EngineExecutionListener#executionFinished(TestDescriptor, TestExecutionResult) execution finished} event.
  *
  * @since 1.4
  */

junit-platform-testkit/src/main/java/org/junit/platform/testkit/engine/Executions.java

@@ -10,6 +10,7 @@
 
 package org.junit.platform.testkit.engine;
 
+import static org.apiguardian.api.API.Status.DEPRECATED;
 import static org.apiguardian.api.API.Status.MAINTAINED;
 
 import java.io.OutputStream;
@@ -45,6 +46,7 @@ public final class Executions {
 
 	private Executions(Stream<Execution> executions, String category) {
 		Preconditions.notNull(executions, "Execution stream must not be null");
+		Preconditions.notNull(category, "Category must not be null");
 
 		this.executions = executions.toList();
 		this.category = category;
@@ -53,6 +55,7 @@ private Executions(Stream<Execution> executions, String category) {
 	Executions(List<Event> events, String category) {
 		Preconditions.notNull(events, "Event list must not be null");
 		Preconditions.containsNoNullElements(events, "Event list must not contain null elements");
+		Preconditions.notNull(category, "Category must not be null");
 
 		this.executions = List.copyOf(createExecutions(events));
 		this.category = category;
@@ -122,6 +125,8 @@ public long count() {
 
 	/**
 	 * Get the skipped {@link Executions} contained in this {@code Executions} object.
+	 * <p>
+	 * Executions that are not skipped are {@linkplain #finished() finished}.
 	 *
 	 * @return the filtered {@code Executions}; never {@code null}
 	 */
@@ -131,15 +136,24 @@ public Executions skipped() {
 
 	/**
 	 * Get the started {@link Executions} contained in this {@code Executions} object.
+	 * <p>
+	 * Executions that are not started are {@linkplain #skipped() skipped}.
 	 *
 	 * @return the filtered {@code Executions}; never {@code null}
+	 *
+	 * @deprecated by definition, all started executions are also finished executions.
+	 * Use {@link #finished()} instead.
 	 */
+	@Deprecated(since = "6.1", forRemoval = true)
+	@API(status = DEPRECATED, since = "6.1")
 	public Executions started() {
 		return new Executions(executionsByTerminationInfo(TerminationInfo::notSkipped), this.category + " Started");
 	}
 
 	/**
 	 * Get the finished {@link Executions} contained in this {@code Executions} object.
+	 * <p>
+	 * Executions that are not finished are {@linkplain #skipped() skipped}.
 	 *
 	 * @return the filtered {@code Executions}; never {@code null}
 	 */
@@ -149,6 +163,8 @@ public Executions finished() {
 
 	/**
 	 * Get the aborted {@link Executions} contained in this {@code Executions} object.
+	 * <p>
+	 * The aborted executions are a subset of the {@linkplain #finished() finished} executions.
 	 *
 	 * @return the filtered {@code Executions}; never {@code null}
 	 */
@@ -158,6 +174,8 @@ public Executions aborted() {
 
 	/**
 	 * Get the succeeded {@link Executions} contained in this {@code Executions} object.
+	 * <p>
+	 * The succeeded executions are a subset of the {@linkplain #finished() finished} executions.
 	 *
 	 * @return the filtered {@code Executions}; never {@code null}
 	 */
@@ -167,6 +185,8 @@ public Executions succeeded() {
 
 	/**
 	 * Get the failed {@link Executions} contained in this {@code Executions} object.
+	 * <p>
+	 * The failed executions are a subset of the {@linkplain #finished() finished} executions.
 	 *
 	 * @return the filtered {@code Executions}; never {@code null}
 	 */

platform-tests/src/test/java/org/junit/platform/testkit/engine/ExecutionsIntegrationTests.java

@@ -37,6 +37,7 @@ void executionsFromSkippedTestEvents() {
 	}
 
 	@Test
+	@SuppressWarnings("removal")
 	void executionsFromStartedTestEvents() {
 		var testEvents = getTestEvents();