Document that autoCloseArguments in @ParameterizedTest is a potentially breaking change

Closes #2706

Author: sbrannen

documentation/src/docs/asciidoc/release-notes/release-notes-5.8.0.adoc

@@ -120,6 +120,12 @@ on GitHub.
 
 ==== Deprecations and Breaking Changes
 
+* The new `autoCloseArguments` feature in `@ParameterizedTest` may potentially be a
+  breaking change for existing parameterized test methods if an argument that implements
+  `java.lang.AutoCloseable` is reused for multiple invocations of the same parameterized
+  test method. If your parameterized test methods start to fail when you upgrade to JUnit
+  Jupiter 5.8, you can disable this feature by declaring
+  `@ParameterizedTest(autoCloseArguments = false)`.
 * `InvocationInterceptor.interceptDynamicTest(Invocation<Void>, ExtensionContext)` has
   been deprecated in favor of
   `InvocationInterceptor.interceptDynamicTest(Invocation<Void>, DynamicTestInvocationContext, ExtensionContext)`
@@ -165,8 +171,9 @@ on GitHub.
   the information available in a `StackTraceElement`.
 * Dynamic tests now require less memory thanks to a number of improvements to internal
   data structures.
-* New `autoCloseArguments` attribute in `@ParameterizedTest` to close `AutoCloseable`
-  arguments at the end of the test. This attribute defaults to true.
+* New `autoCloseArguments` attribute in `@ParameterizedTest` to close
+  `java.lang.AutoCloseable` arguments after each invocation of the parameterized test
+  method. This attribute defaults to `true`.
 * Numeric literals used with `@CsvSource` or `CsvFileSource` can now be expressed using
   underscores as in some JVM languages, to improve readability of long numbers like
   `700_000_000`.

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

@@ -1118,9 +1118,20 @@ parameterized method at the same index in the method's formal parameter list. An
 _aggregator_ is any parameter of type `ArgumentsAccessor` or any parameter annotated with
 `@AggregateWith`.
 
-NOTE: Arguments of type `AutoCloseable` will be closed once `@AfterEach` methods and
-`AfterEachCallback` implementations have been called. To prevent this from happening, set
-the `autoCloseArguments` attribute in `@ParameterizedTest` to `false`.
+[NOTE]
+.AutoCloseable arguments
+====
+Arguments that implement `java.lang.AutoCloseable` (or `java.io.Closeable` which extends
+`java.lang.AutoCloseable`) will be automatically closed after `@AfterEach` methods and
+`AfterEachCallback` extensions have been called for the current parameterized test
+invocation.
+
+To prevent this from happening, set the `autoCloseArguments` attribute in
+`@ParameterizedTest` to `false`. Specifically, if an argument that implements
+`AutoCloseable` is reused for multiple invocations of the same parameterized test method,
+you must annotate the method with `@ParameterizedTest(autoCloseArguments = false)` to
+ensure that the argument is not closed between invocations.
+====
 
 [[writing-tests-parameterized-tests-sources]]
 ==== Sources of Arguments

junit-jupiter-params/src/main/java/org/junit/jupiter/params/ParameterizedTest.java

@@ -209,9 +209,17 @@
 	String name() default "{default_display_name}";
 
 	/**
-	 * If true, all arguments of the parameterized test implementing {@link AutoCloseable}
-	 * will be closed after {@code @AfterEach} methods and {@code AfterEachCallbacks}
-	 * have been called.
+	 * Configure whether all arguments of the parameterized test that implement {@link AutoCloseable}
+	 * will be closed after {@link org.junit.jupiter.api.AfterEach @AfterEach} methods
+	 * and {@link org.junit.jupiter.api.extension.AfterEachCallback AfterEachCallback}
+	 * extensions have been called for the current parameterized test invocation.
+	 *
+	 * <p>Defaults to {@code true}.
+	 *
+	 * <p><strong>WARNING</strong>: if an argument that implements {@code AutoCloseable}
+	 * is reused for multiple invocations of the same parameterized test method,
+	 * you must set {@code autoCloseArguments} to {@code false} to ensure that
+	 * the argument is not closed between invocations.
 	 *
 	 * @since 5.8
 	 * @see java.lang.AutoCloseable