Document & enforce preconditions in Events & Executions in Test Kit

Issue: #1621

Author: sbrannen

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

@@ -90,6 +90,8 @@ public Stream<Event> stream() {
 	/**
 	 * Shortcut for {@code events.stream().map(mapper)}.
 	 *
+	 * @param mapper a {@code Function} to apply to each event; never {@code null}
+	 * @return the mapped stream of events; never {@code null}
 	 * @see #stream()
 	 * @see Stream#map(Function)
 	 */
@@ -101,6 +103,9 @@ public <R> Stream<R> map(Function<? super Event, ? extends R> mapper) {
 	/**
 	 * Shortcut for {@code events.stream().filter(predicate)}.
 	 *
+	 * @param predicate a {@code Predicate} to apply to each event to decide if
+	 * it should be included in the filtered stream; never {@code null}
+	 * @return the filtered stream of events; never {@code null}
 	 * @see #stream()
 	 * @see Stream#filter(Predicate)
 	 */
@@ -216,10 +221,12 @@ public Events dynamicallyRegistered() {
 	 *
 	 * <p>{@code events.assertStatistics(stats -> stats.started(1).succeeded(1).failed(0));}
 	 *
-	 * @param statisticsConsumer a consumer of {@link EventStatistics}
+	 * @param statisticsConsumer a {@link Consumer} of {@link EventStatistics};
+	 * never {@code null}
 	 * @return this {@code Events} object for method chaining; never {@code null}
 	 */
 	public Events assertStatistics(Consumer<EventStatistics> statisticsConsumer) {
+		Preconditions.notNull(statisticsConsumer, "Consumer must not be null");
 		EventStatistics eventStatistics = new EventStatistics(this, this.category);
 		statisticsConsumer.accept(eventStatistics);
 		eventStatistics.assertAll();
@@ -242,20 +249,20 @@ public Events assertStatistics(Consumer<EventStatistics> statisticsConsumer) {
 	 * );
 	 * </pre>
 	 *
-	 * @param conditions the conditions to match against
+	 * @param conditions the conditions to match against; never {@code null}
 	 * @see EventConditions
 	 * @see TestExecutionResultConditions
 	 */
 	@SafeVarargs
 	public final void assertEventsMatchExactly(Condition<? super Event>... conditions) {
+		Preconditions.notNull(conditions, "conditions must not be null");
 		assertEventsMatchExactly(this.events, conditions);
 	}
 
 	/**
 	 * Shortcut for {@code org.assertj.core.api.Assertions.assertThat(events.list())}.
 	 *
-	 * @return an instance of {@link ListAssert} for events; never
-	 * {@code null}
+	 * @return an instance of {@link ListAssert} for events; never {@code null}
 	 * @see org.assertj.core.api.Assertions#assertThat(List)
 	 * @see org.assertj.core.api.ListAssert
 	 */
@@ -278,19 +285,23 @@ public Events debug() {
 	/**
 	 * Print all events to the supplied {@link OutputStream}.
 	 *
+	 * @param out the {@code OutputStream} to print to; never {@code null}
 	 * @return this {@code Events} object for method chaining; never {@code null}
 	 */
 	public Events debug(OutputStream out) {
+		Preconditions.notNull(out, "OutputStream must not be null");
 		debug(new PrintWriter(out, true));
 		return this;
 	}
 
 	/**
 	 * Print all events to the supplied {@link Writer}.
 	 *
+	 * @param writer the {@code Writer} to print to; never {@code null}
 	 * @return this {@code Events} object for method chaining; never {@code null}
 	 */
 	public Events debug(Writer writer) {
+		Preconditions.notNull(writer, "Writer must not be null");
 		debug(new PrintWriter(writer, true));
 		return this;
 	}

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

@@ -85,6 +85,9 @@ public Stream<Execution> stream() {
 	/**
 	 * Shortcut for {@code executions.stream().map(mapper)}.
 	 *
+	 * @param mapper a {@code Function} to apply to each execution;
+	 * never {@code null}
+	 * @return the mapped stream of executions; never {@code null}
 	 * @see #stream()
 	 * @see Stream#map(Function)
 	 */
@@ -96,6 +99,9 @@ public <R> Stream<R> map(Function<? super Execution, ? extends R> mapper) {
 	/**
 	 * Shortcut for {@code executions.stream().filter(predicate)}.
 	 *
+	 * @param predicate a {@code Predicate} to apply to each execution to decide
+	 * if it should be included in the filtered stream; never {@code null}
+	 * @return the filtered stream of executions; never {@code null}
 	 * @see #stream()
 	 * @see Stream#filter(Predicate)
 	 */
@@ -198,26 +204,30 @@ public Executions debug() {
 	/**
 	 * Print all executions to the supplied {@link OutputStream}.
 	 *
+	 * @param out the {@code OutputStream} to print to; never {@code null}
 	 * @return this {@code Executions} object for method chaining; never {@code null}
 	 */
 	public Executions debug(OutputStream out) {
+		Preconditions.notNull(out, "OutputStream must not be null");
 		debug(new PrintWriter(out, true));
 		return this;
 	}
 
 	/**
 	 * Print all executions to the supplied {@link Writer}.
 	 *
+	 * @param writer the {@code Writer} to print to; never {@code null}
 	 * @return this {@code Executions} object for method chaining; never {@code null}
 	 */
 	public Executions debug(Writer writer) {
+		Preconditions.notNull(writer, "Writer must not be null");
 		debug(new PrintWriter(writer, true));
 		return this;
 	}
 
 	private Executions debug(PrintWriter printWriter) {
 		printWriter.println(this.category + " Executions:");
-		this.executions.forEach(event -> printWriter.printf("\t%s%n", event));
+		this.executions.forEach(execution -> printWriter.printf("\t%s%n", execution));
 		return this;
 	}