Quote text-based arguments in display names for parameterized tests

This commit introduces quoteTextArguments attributes in
@⁠ParameterizedClass and @⁠ParameterizedTest which default to true.

This new feature automatically encloses any CharSequence (such as a
String) in double quotes (") and any Character in single quotes (').
Special characters will be escaped within quoted text. For example,
'\n', '\r', will be escaped as "\\r" and "\\n", respectively. In
addition, any ISO control character will be represented as a question
mark (?) in the quoted text.

For example, given a String argument "line 1\nline 2", the
representation in the display name would be "\"line 1\\nline 2\""
(visually "line 1\nline 2") with the newline character escaped as
"\\n". Similarly, given a String argument "\t", the representation in
the display name would be "\"\\t\"" (visually "\t") instead of a blank
string or invisible tab character. The same applies for a character
argument '\t', whose representation in the display name would be
"'\\t'" (visually '\t').

Closes #4716

Author: sbrannen

documentation/src/docs/asciidoc/release-notes/release-notes-6.0.0-RC1.adoc

@@ -45,7 +45,10 @@ repository on GitHub.
 [[release-notes-6.0.0-RC1-junit-jupiter-new-features-and-improvements]]
 ==== New Features and Improvements
 
-* ❓
+* Text-based arguments in display names for parameterized tests are now quoted by default.
+  In addition, special characters are escaped within quoted text. Please refer to the
+  <<../user-guide/index.adoc#writing-tests-parameterized-tests-display-names-quoted-text,
+  User Guide>> for details.
 
 
 [[release-notes-6.0.0-RC1-junit-vintage]]

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

@@ -1242,26 +1242,26 @@ Executing the above test class yields the following output:
 
 ....
 FruitTests ✔
-├─ [1] fruit = apple ✔
+├─ [1] fruit = "apple" ✔
 │  └─ QuantityTests ✔
 │     ├─ [1] quantity = 23 ✔
 │     │  └─ test(Duration) ✔
-│     │     ├─ [1] duration = PT1H ✔
-│     │     └─ [2] duration = PT2H ✔
+│     │     ├─ [1] duration = "PT1H" ✔
+│     │     └─ [2] duration = "PT2H" ✔
 │     └─ [2] quantity = 42 ✔
 │        └─ test(Duration) ✔
-│           ├─ [1] duration = PT1H ✔
-│           └─ [2] duration = PT2H ✔
-└─ [2] fruit = banana ✔
+│           ├─ [1] duration = "PT1H" ✔
+│           └─ [2] duration = "PT2H" ✔
+└─ [2] fruit = "banana" ✔
    └─ QuantityTests ✔
       ├─ [1] quantity = 23 ✔
       │  └─ test(Duration) ✔
-      │     ├─ [1] duration = PT1H ✔
-      │     └─ [2] duration = PT2H ✔
+      │     ├─ [1] duration = "PT1H" ✔
+      │     └─ [2] duration = "PT2H" ✔
       └─ [2] quantity = 42 ✔
          └─ test(Duration) ✔
-            ├─ [1] duration = PT1H ✔
-            └─ [2] duration = PT2H ✔
+            ├─ [1] duration = "PT1H" ✔
+            └─ [2] duration = "PT2H" ✔
 ....
 
 [[writing-tests-dependency-injection]]
@@ -1649,9 +1649,9 @@ following.
 
 ....
 palindromes(String) ✔
-├─ [1] candidate = racecar ✔
-├─ [2] candidate = radar ✔
-└─ [3] candidate = able was I ere I saw elba ✔
+├─ [1] candidate = "racecar" ✔
+├─ [2] candidate = "radar" ✔
+└─ [3] candidate = "able was I ere I saw elba" ✔
 ....
 
 The same `@ValueSource` annotation can be used to specify the source of arguments for a
@@ -1668,13 +1668,13 @@ following.
 
 ....
 PalindromeTests ✔
-├─ [1] candidate = racecar ✔
+├─ [1] candidate = "racecar" ✔
 │  ├─ palindrome() ✔
 │  └─ reversePalindrome() ✔
-├─ [2] candidate = radar ✔
+├─ [2] candidate = "radar" ✔
 │  ├─ palindrome() ✔
 │  └─ reversePalindrome() ✔
-└─ [3] candidate = able was I ere I saw elba ✔
+└─ [3] candidate = "able was I ere I saw elba" ✔
    ├─ palindrome() ✔
    └─ reversePalindrome() ✔
 ....
@@ -2139,7 +2139,7 @@ It is also possible to provide a `Stream`, `DoubleStream`, `IntStream`, `LongStr
 iterator is wrapped in a `java.util.function.Supplier`. The following example demonstrates
 how to provide a `Supplier` of a `Stream` of named arguments. This parameterized test
 method will be invoked twice: with the values `"apple"` and `"banana"` and with display
-names `Apple` and `Banana`, respectively.
+names `"Apple"` and `"Banana"`, respectively.
 
 [source,java,indent=0]
 ----
@@ -2252,10 +2252,10 @@ void testWithCsvSource(String fruit, int rank) {
 The generated display names for the previous example include the CSV header names.
 
 ----
-[1] FRUIT = apple, RANK = 1
-[2] FRUIT = banana, RANK = 2
-[3] FRUIT = lemon, lime, RANK = 0xF1
-[4] FRUIT = strawberry, RANK = 700_000
+[1] FRUIT = "apple", RANK = "1"
+[2] FRUIT = "banana", RANK = "2"
+[3] FRUIT = "lemon, lime", RANK = "0xF1"
+[4] FRUIT = "strawberry", RANK = "700_000"
 ----
 
 In contrast to CSV records supplied via the `value` attribute, a text block can contain
@@ -2332,20 +2332,20 @@ The following listing shows the generated display names for the first two parame
 test methods above.
 
 ----
-[1] country = Sweden, reference = 1
-[2] country = Poland, reference = 2
-[3] country = United States of America, reference = 3
-[4] country = France, reference = 700_000
+[1] country = "Sweden", reference = "1"
+[2] country = "Poland", reference = "2"
+[3] country = "United States of America", reference = "3"
+[4] country = "France", reference = "700_000"
 ----
 
 The following listing shows the generated display names for the last parameterized test
 method above that uses CSV header names.
 
 ----
-[1] COUNTRY = Sweden, REFERENCE = 1
-[2] COUNTRY = Poland, REFERENCE = 2
-[3] COUNTRY = United States of America, REFERENCE = 3
-[4] COUNTRY = France, REFERENCE = 700_000
+[1] COUNTRY = "Sweden", REFERENCE = "1"
+[2] COUNTRY = "Poland", REFERENCE = "2"
+[3] COUNTRY = "United States of America", REFERENCE = "3"
+[4] COUNTRY = "France", REFERENCE = "700_000"
 ----
 
 In contrast to the default syntax used in `@CsvSource`, `@CsvFileSource` uses a double
@@ -2668,11 +2668,18 @@ include::{testDir}/example/ParameterizedTestDemo.java[tags=ArgumentsAggregator_w
 ==== Customizing Display Names
 
 By default, the display name of a parameterized class or test invocation contains the
-invocation index and the `String` representation of all arguments for that specific
-invocation. Each argument is preceded by its parameter name (unless the argument is only
-available via an `ArgumentsAccessor` or `ArgumentAggregator`), if the parameter name is
-present in the bytecode (for Java, test code must be compiled with the `-parameters`
-compiler flag; for Kotlin, with `-java-parameters`).
+invocation index and a comma-separated list of the `String` representations of all
+arguments for that specific invocation. If parameter names are present in the bytecode,
+each argument will be preceded by its parameter name and an equals sign (unless the
+argument is only available via an `ArgumentsAccessor` or `ArgumentAggregator`) – for
+example, `firstName = "Jane"`.
+
+[TIP]
+====
+To ensure that parameter names are present in the bytecode, test code must be compiled
+with the `-parameters` compiler flag for Java or with the `-java-parameters` compiler flag
+for Kotlin.
+====
 
 However, you can customize invocation display names via the `name` attribute of the
 `@ParameterizedClass` or `@ParameterizedTest` annotation as in the following example.
@@ -2688,9 +2695,9 @@ the following.
 
 ....
 Display name of container ✔
-├─ 1 ==> the rank of 'apple' is 1 ✔
-├─ 2 ==> the rank of 'banana' is 2 ✔
-└─ 3 ==> the rank of 'lemon, lime' is 3 ✔
+├─ 1 ==> the rank of "apple" is "1" ✔
+├─ 2 ==> the rank of "banana" is "2" ✔
+└─ 3 ==> the rank of "lemon, lime" is "3" ✔
 ....
 ======
 
@@ -2777,6 +2784,70 @@ Note that `argumentSet(String, Object...)` is a static factory method defined in
 `org.junit.jupiter.params.provider.Arguments` interface.
 ====
 
+[[writing-tests-parameterized-tests-display-names-quoted-text]]
+===== Quoted Text-based Arguments
+
+As of JUnit Jupiter 6.0, text-based arguments in display names for parameterized tests are
+quoted by default. In this context, any `CharSequence` (such as a `String`) or `Character`
+is considered text. A `CharSequence` is wrapped in double quotes (`"`), and a `Character`
+is wrapped in single quotes (`'`).
+
+Special characters will be escaped in the quoted text. For example, carriage returns and
+line feeds will be escaped as `\\r` and `\\n`, respectively. In addition, any ISO control
+character will be represented as a question mark (`?`) in the quoted text.
+
+[TIP]
+====
+This feature can be disabled by setting the `quoteTextArguments` attributes in
+`@ParameterizedClass` and `@ParameterizedTest` to `false`.
+====
+
+For example, given a string argument `"line 1\nline 2"`, the physical representation in
+the display name will be `"\"line 1\\nline 2\""` which is printed as `"line 1\nline 2"`.
+Similarly, given a string argument `"\t"`, the physical representation in the display name
+will be `"\"\\t\""` which is printed as `"\t"` instead of a blank string or invisible tab
+character. The same applies for a character argument `'\t'`, whose physical representation
+in the display name would be `"'\\t'"` which is printed as `'\t'`.
+
+For a concrete example, if you run the first `nullEmptyAndBlankStrings(String text)`
+parameterized test method from the
+<<writing-tests-parameterized-tests-sources-null-and-empty>> section above, the following
+display names are generated.
+
+----
+[1] text = null
+[2] text = ""
+[3] text = " "
+[4] text = "   "
+[5] text = "\t"
+[6] text = "\n"
+----
+
+If you run the first `testWithCsvSource(String fruit, int rank)` parameterized test method
+from the <<writing-tests-parameterized-tests-sources-CsvSource>> section above, the
+following display names are generated.
+
+----
+[1] fruit = "apple", rank = "1"
+[2] fruit = "banana", rank = "2"
+[3] fruit = "lemon, lime", rank = "0xF1"
+[4] fruit = "strawberry", rank = "700_000"
+----
+
+[NOTE]
+====
+The original source arguments are quoted when generating a display name, and this occurs
+before any implicit or explicit argument conversion is performed.
+
+For example, if a parameterized test accepts `3.14` as a `float` argument that was
+converted from `"3.14"` as an input string, `"3.14"` will be present in the display name
+instead of `3.14`. You can see the effect of this with the `rank` values in the above
+example.
+====
+
+[[writing-tests-parameterized-tests-display-names-default-pattern]]
+===== Default Display Name Pattern
+
 If you'd like to set a default name pattern for all parameterized classes and tests in
 your project, you can declare the `junit.jupiter.params.displayname.default` configuration
 parameter in the `junit-platform.properties` file as demonstrated in the following example (see
@@ -2787,6 +2858,9 @@ parameter in the `junit-platform.properties` file as demonstrated in the followi
 junit.jupiter.params.displayname.default = {index}
 ----
 
+[[writing-tests-parameterized-tests-display-names-precedence-rules]]
+===== Precedence Rules
+
 The display name for a parameterized class or test is determined according to the
 following precedence rules:
 

documentation/src/test/java/example/ParameterizedTestDemo.java

@@ -582,7 +582,7 @@ void testWithCustomAggregatorAnnotation(@CsvToPerson Person person) {
 
 	// tag::custom_display_names[]
 	@DisplayName("Display name of container")
-	@ParameterizedTest(name = "{index} ==> the rank of ''{0}'' is {1}")
+	@ParameterizedTest(name = "{index} ==> the rank of {0} is {1}")
 	@CsvSource({ "apple, 1", "banana, 2", "'lemon, lime', 3" })
 	void testWithCustomDisplayNames(String fruit, int rank) {
 	}

junit-jupiter-params/src/jmh/java/org/junit/jupiter/params/ParameterizedInvocationNameFormatterBenchmarks.java

@@ -56,7 +56,7 @@ public void formatTestNames(Blackhole blackhole) throws Exception {
 			512);
 		for (int i = 0; i < argumentsList.size(); i++) {
 			Arguments arguments = argumentsList.get(i);
-			blackhole.consume(formatter.format(i, EvaluatedArgumentSet.allOf(arguments)));
+			blackhole.consume(formatter.format(i, EvaluatedArgumentSet.allOf(arguments), false));
 		}
 	}
 

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

@@ -75,8 +75,8 @@ int getConsumedLength() {
 	}
 
 	@Nullable
-	Object[] getConsumedNames() {
-		return extractFromNamed(this.consumed, Named::getName);
+	Object[] getConsumedArguments() {
+		return this.consumed;
 	}
 
 	@Nullable

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

@@ -198,9 +198,50 @@
 	 * a flag rather than a placeholder.
 	 *
 	 * @see java.text.MessageFormat
+	 * @see #quoteTextArguments()
 	 */
 	String name() default ParameterizedInvocationNameFormatter.DEFAULT_DISPLAY_NAME;
 
+	/**
+	 * Configure whether to enclose text-based argument values in quotes within
+	 * display names.
+	 *
+	 * <p>Defaults to {@code true}.
+	 *
+	 * <p>In this context, any {@link CharSequence} (such as a {@link String})
+	 * or {@link Character} is considered text. A {@code CharSequence} is wrapped
+	 * in double quotes ("), and a {@code Character} is wrapped in single quotes
+	 * (').
+	 *
+	 * <p>Special characters in Java strings and characters will be escaped in the
+	 * quoted text &mdash; for example, carriage returns and line feeds will be
+	 * escaped as {@code \\r} and {@code \\n}, respectively. In addition, any
+	 * {@linkplain Character#isISOControl(char) ISO control character} will be
+	 * represented as a question mark (?) in the quoted text.
+	 *
+	 * <p>For example, given a string argument {@code "line 1\nline 2"}, the
+	 * representation in the display name would be {@code "\"line 1\\nline 2\""}
+	 * (printed as {@code "line 1\nline 2"}) with the newline character escaped as
+	 * {@code "\\n"}. Similarly, given a string argument {@code "\t"}, the
+	 * representation in the display name would be {@code "\"\\t\""} (printed as
+	 * {@code "\t"}) instead of a blank string or invisible tab
+	 * character. The same applies for a character argument {@code '\t'}, whose
+	 * representation in the display name would be {@code "'\\t'"} (printed as
+	 * {@code '\t'}).
+	 *
+	 * <p>Please note that original source arguments are quoted when generating
+	 * a display name, before any implicit or explicit argument conversion is
+	 * performed. For example, if a parameterized class accepts {@code 3.14} as a
+	 * {@code float} argument that was converted from {@code "3.14"} as an input
+	 * string, {@code "3.14"} will be present in the display name instead of
+	 * {@code 3.14}.
+	 *
+	 * @since 6.0
+	 * @see #name()
+	 */
+	@API(status = EXPERIMENTAL, since = "6.0")
+	boolean quoteTextArguments() default true;
+
 	/**
 	 * Configure whether all arguments of the parameterized class that implement
 	 * {@link AutoCloseable} will be closed after their corresponding

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

@@ -102,6 +102,11 @@ public String getDisplayNamePattern() {
 		return this.annotation.name();
 	}
 
+	@Override
+	public boolean quoteTextArguments() {
+		return this.annotation.quoteTextArguments();
+	}
+
 	@Override
 	public boolean isAutoClosingArguments() {
 		return this.annotation.autoCloseArguments();

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

@@ -28,6 +28,8 @@ interface ParameterizedDeclarationContext<C> {
 
 	String getDisplayNamePattern();
 
+	boolean quoteTextArguments();
+
 	boolean isAutoClosingArguments();
 
 	boolean isAllowingZeroInvocations();

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

@@ -43,7 +43,7 @@ class ParameterizedInvocationContext<T extends ParameterizedDeclarationContext<?
 	}
 
 	public String getDisplayName(int invocationIndex) {
-		return this.formatter.format(invocationIndex, this.arguments);
+		return this.formatter.format(invocationIndex, this.arguments, this.declarationContext.quoteTextArguments());
 	}
 
 	public void prepareInvocation(ExtensionContext context) {