Document that Streams returned from argument sources closed automatically

... in Javadoc and User Guide

Author: vdmitrienko

Diff for: documentation/src/docs/asciidoc/user-guide/writing-tests.adoc

@@ -1954,6 +1954,10 @@ an array of primitives. The "arguments" within the stream can be supplied as an
 of `Arguments`, an array of objects (e.g., `Object[]`), or a single value if the
 parameterized class or test method accepts a single argument.
 
+If the return type is `Stream` or one of the primitive streams,
+JUnit will properly close it by calling `BaseStream.close()`,
+making it safe to use a resource such as `Files.lines()`.
+
 If you only need a single parameter, you can return a `Stream` of instances of the
 parameter type as demonstrated in the following example.
 
@@ -2049,6 +2053,10 @@ are _consumed_ the first time they are processed. However, if you wish to use on
 these types, you can wrap it in a `Supplier` — for example, `Supplier<IntStream>`.
 ====
 
+If the `Supplier` return type is `Stream` or one of the primitive streams,
+JUnit will properly close it by calling `BaseStream.close()`,
+making it safe to use a resource such as `Files.lines()`.
+
 Please note that a one-dimensional array of objects supplied as a set of "arguments" will
 be handled differently than other types of arguments. Specifically, all the elements of a
 one-dimensional array of objects will be passed as individual physical arguments to the

Diff for: junit-jupiter-params/src/main/java/org/junit/jupiter/params/provider/AnnotationBasedArgumentsProvider.java

@@ -76,6 +76,13 @@ protected Stream<? extends Arguments> provideArguments(ExtensionContext context,
 			getClass().getName()));
 	}
 
+	/**
+	 * The returned {@code Stream} will be {@link Stream#close() properly closed}
+	 * by the default implementation of
+	 * {@link #provideArguments(ParameterDeclarations, ExtensionContext)},
+	 * making it safe to use a resource such as
+	 * {@link java.nio.file.Files#lines(java.nio.file.Path) Files.lines()}.
+	 */
 	protected Stream<? extends Arguments> provideArguments(ParameterDeclarations parameters, ExtensionContext context,
 			A annotation) {
 		return provideArguments(context, annotation);

Diff for: junit-jupiter-params/src/main/java/org/junit/jupiter/params/provider/FieldSource.java

@@ -61,6 +61,12 @@
  * use one of these types, you can wrap it in a {@code Supplier} — for
  * example, {@code Supplier<IntStream>}.
  *
+ * <p>If the {@code Supplier} return type is {@code Stream} or
+ * one of the primitive streams, JUnit will properly close it by calling
+ * {@link java.util.stream.BaseStream#close() BaseStream.close()},
+ * making it safe to use a resource such as
+ * {@link java.nio.file.Files#lines(java.nio.file.Path) Files.lines()}.
+ *
  * <p>Please note that a one-dimensional array of objects supplied as a set of
  * "arguments" will be handled differently than other types of arguments.
  * Specifically, all of the elements of a one-dimensional array of objects will

Diff for: junit-jupiter-params/src/main/java/org/junit/jupiter/params/provider/MethodSource.java

@@ -50,6 +50,12 @@
  * {@code String[]}, etc.), or a single <em>value</em> if the parameterized test
  * method accepts a single argument.
  *
+ * <p>If the return type is {@code Stream} or
+ * one of the primitive streams, JUnit will properly close it by calling
+ * {@link java.util.stream.BaseStream#close() BaseStream.close()},
+ * making it safe to use a resource such as
+ * {@link java.nio.file.Files#lines(java.nio.file.Path) Files.lines()}.
+ *
  * <p>Please note that a one-dimensional array of objects supplied as a set of
  * "arguments" will be handled differently than other types of arguments.
  * Specifically, all of the elements of a one-dimensional array of objects will