Replace ISO control characters in display names

Prior to this commit, display names were "sanitized" before they were
printed via the ConsoleLauncher (#1713), and text-based arguments in
display names for parameterized tests were quoted and escaped (#4716).
However, there was still the chance that display names could contain
control characters such as CR or LF.

To address that, this commit introduces support for automatically
replacing ISO control characters in any display name passed to one of
the constructors for AbstractTestDescriptor. Doing so automatically
covers all display names in JUnit Jupiter, @⁠SuiteDisplayName, and any
other test engines that subclass AbstractTestDescriptor, which should
cover most common use cases.

Specifically, the following replacements are performed.

- \r -> <CR>
- \n -> <LF>
- ISO control character -> � (Unicode replacement character)

This commit also removes the special handling of ISO control characters
from QuoteUtils, since this is now handled in AbstractTestDescriptor.

See #1713
See #4716
Closes #4714

Author: sbrannen

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

@@ -32,6 +32,11 @@ repository on GitHub.
 * Convention-based conversion in `ConversionSupport` now supports factory methods and
   factory constructors that accept a single `CharSequence` argument in addition to the
   existing support for factories that accept a single `String` argument.
+* Non-printable control characters in display names are now replaced with alternative
+  representations. For example, `\n` is replaced with `<LF>`. This applies to all display
+  names in JUnit Jupiter, `@SuiteDisplayName`, and any other test engines that subclass
+  `AbstractTestDescriptor`. Please refer to the
+  <<../user-guide/index.adoc#writing-tests-display-names, User Guide>> for details.
 
 
 [[release-notes-6.0.0-RC1-junit-jupiter]]
@@ -64,6 +69,9 @@ repository on GitHub.
   Fallback String-to-Object Conversion>> for parameterized tests now supports factory
   methods and factory constructors that accept a single `CharSequence` argument in
   addition to the existing support for factories that accept a single `String` argument.
+* Non-printable control characters in display names are now replaced with alternative
+  representations. Please refer to the
+  <<../user-guide/index.adoc#writing-tests-display-names, User Guide>> for details.
 
 
 [[release-notes-6.0.0-RC1-junit-vintage]]

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

@@ -307,6 +307,32 @@ by test runners and IDEs.
 include::{testDir}/example/DisplayNameDemo.java[tags=user_guide]
 ----
 
+[NOTE]
+====
+Control characters in text-based arguments in display names for parameterized tests are
+escaped by default. See <<writing-tests-parameterized-tests-display-names-quoted-text>>
+for details.
+
+Any remaining ISO control characters in a display name will be replaced as follows.
+
+[cols="25%,15%,60%"]
+|===
+| Original | Replacement | Description
+
+| ```\r```
+| ```<CR>```
+| Textual representation of a carriage return
+
+| ```\n```
+| ```<LF>```
+| Textual representation of a line feed
+
+| Other control character
+| ```�```
+| Unicode replacement character (U+FFFD)
+|===
+====
+
 [[writing-tests-display-name-generator]]
 ==== Display Name Generators
 
@@ -2778,8 +2804,7 @@ is considered text. A `CharSequence` is wrapped in double quotes (`"`), and a `C
 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.
+line feeds will be escaped as `\\r` and `\\n`, respectively.
 
 [TIP]
 ====

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

@@ -48,7 +48,7 @@ private static String escape(char ch, boolean withinString) {
 			case '\t' -> "\\t";
 			case '\r' -> "\\r";
 			case '\n' -> "\\n";
-			default -> Character.isISOControl(ch) ? "?" : String.valueOf(ch);
+			default -> String.valueOf(ch);
 		};
 	}
 

junit-platform-engine/src/main/java/org/junit/platform/engine/support/descriptor/AbstractTestDescriptor.java

@@ -41,6 +41,12 @@
 @API(status = STABLE, since = "1.0")
 public abstract class AbstractTestDescriptor implements TestDescriptor {
 
+	/**
+	 * The Unicode replacement character, often displayed as a black diamond with
+	 * a white question mark in it: {@value}
+	 */
+	private static final String UNICODE_REPLACEMENT_CHARACTER = "\uFFFD";
+
 	private final UniqueId uniqueId;
 
 	private final String displayName;
@@ -66,6 +72,10 @@ public abstract class AbstractTestDescriptor implements TestDescriptor {
 	 * Create a new {@code AbstractTestDescriptor} with the supplied
 	 * {@link UniqueId} and display name.
 	 *
+	 * <p>As of JUnit 6.0, ISO control characters in the provided display name
+	 * will be replaced. See {@link #AbstractTestDescriptor(UniqueId, String, TestSource)}
+	 * for details.
+	 *
 	 * @param uniqueId the unique ID of this {@code TestDescriptor}; never
 	 * {@code null}
 	 * @param displayName the display name for this {@code TestDescriptor};
@@ -80,6 +90,17 @@ protected AbstractTestDescriptor(UniqueId uniqueId, String displayName) {
 	 * Create a new {@code AbstractTestDescriptor} with the supplied
 	 * {@link UniqueId}, display name, and source.
 	 *
+	 * <p>As of JUnit 6.0, ISO control characters in the provided display name
+	 * will be replaced according to the following table.
+	 *
+	 * <table class="plain">
+	 * <caption>Control Character Replacement</caption>
+	 * <tr><th> Original                </th><th> Replacement  </th><th> Description                                 </th></tr>
+	 * <tr><td> {@code \r}              </td><td> {@code <CR>} </td><td> Textual representation of a carriage return </td></tr>
+	 * <tr><td> {@code \n}              </td><td> {@code <LF>} </td><td> Textual representation of a line feed       </td></tr>
+	 * <tr><td> Other control character </td><td> &#xFFFD;     </td><td> Unicode replacement character (U+FFFD)      </td></tr>
+	 * </table>
+	 *
 	 * @param uniqueId the unique ID of this {@code TestDescriptor}; never
 	 * {@code null}
 	 * @param displayName the display name for this {@code TestDescriptor};
@@ -90,7 +111,8 @@ protected AbstractTestDescriptor(UniqueId uniqueId, String displayName) {
 	 */
 	protected AbstractTestDescriptor(UniqueId uniqueId, String displayName, @Nullable TestSource source) {
 		this.uniqueId = Preconditions.notNull(uniqueId, "UniqueId must not be null");
-		this.displayName = Preconditions.notBlank(displayName, "displayName must not be null or blank");
+		this.displayName = replaceControlCharacters(
+			Preconditions.notBlank(displayName, "displayName must not be null or blank"));
 		this.source = source;
 	}
 
@@ -207,4 +229,20 @@ public String toString() {
 		return getClass().getSimpleName() + ": " + getUniqueId();
 	}
 
+	private static String replaceControlCharacters(String text) {
+		StringBuilder builder = new StringBuilder();
+		for (int i = 0; i < text.length(); i++) {
+			builder.append(replaceControlCharacter(text.charAt(i)));
+		}
+		return builder.toString();
+	}
+
+	private static String replaceControlCharacter(char ch) {
+		return switch (ch) {
+			case '\r' -> "<CR>";
+			case '\n' -> "<LF>";
+			default -> Character.isISOControl(ch) ? UNICODE_REPLACEMENT_CHARACTER : String.valueOf(ch);
+		};
+	}
+
 }

jupiter-tests/src/test/java/org/junit/jupiter/params/ParameterizedInvocationNameFormatterTests.java

@@ -342,7 +342,7 @@ class QuotedTextTests {
 				'   \t   '   -> '   \\t   '
 				'\b'         -> \\b
 				'\f'         -> \\f
-				'\u0007'     -> ?
+				'\u0007'     -> '\u0007'
 				""")
 		void quotedStrings(String argument, String expected) {
 			var formatter = formatter(DEFAULT_DISPLAY_NAME, "IGNORED");
@@ -364,7 +364,7 @@ void quotedStrings(String argument, String expected) {
 				"\t"     -> \\t
 				"\b"     -> \\b
 				"\f"     -> \\f
-				"\u0007" -> ?
+				"\u0007" -> "\u0007"
 				""")
 		void quotedCharacters(char argument, String expected) {
 			var formatter = formatter(DEFAULT_DISPLAY_NAME, "IGNORED");

jupiter-tests/src/test/java/org/junit/jupiter/params/ParameterizedTestIntegrationTests.java

@@ -270,6 +270,30 @@ void executesWithCsvSource() {
 				.haveExactly(1, event(test(), displayName("[2] argument = bar"), finishedWithFailure(message("bar"))));
 	}
 
+	/**
+	 * @since 6.0
+	 */
+	@Test
+	void executesWithCsvSourceAndSpecialCharacters() {
+		// @formatter:off
+		execute("testWithCsvSourceAndSpecialCharacters", String.class)
+				.testEvents()
+				.started()
+				.assertEventsMatchExactly(
+					displayName(quoted("üñåé")),
+					displayName(quoted("\\n")),
+					displayName(quoted("\\r")),
+					displayName(quoted("\uFFFD")),
+					displayName(quoted("😱")),
+					displayName(quoted("Zero\u200BWidth\u200BSpaces"))
+				);
+		// @formatter:on
+	}
+
+	private static String quoted(String text) {
+		return '"' + text + '"';
+	}
+
 	@Test
 	void executesWithCustomName() {
 		var results = execute("testWithCustomName", String.class, int.class);
@@ -1453,6 +1477,11 @@ void testWithCsvSource(String argument) {
 			fail(argument);
 		}
 
+		@ParameterizedTest(name = "{0}")
+		@CsvSource({ "'üñåé'", "'\n'", "'\r'", "'\u0007'", "😱", "'Zero\u200BWidth\u200BSpaces'" })
+		void testWithCsvSourceAndSpecialCharacters(String argument) {
+		}
+
 		@ParameterizedTest(quoteTextArguments = false, name = "{0} and {1}")
 		@CsvSource({ "foo, 23", "bar, 42" })
 		void testWithCustomName(String argument, int i) {

platform-tests/src/test/java/org/junit/platform/engine/support/descriptor/AbstractTestDescriptorTests.java

@@ -16,13 +16,16 @@
 import static org.junit.jupiter.api.Assertions.assertSame;
 import static org.junit.jupiter.api.Assertions.assertThrows;
 import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.mockito.Mockito.mock;
 
 import java.util.ArrayList;
 import java.util.List;
 import java.util.concurrent.atomic.AtomicInteger;
 
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.CsvSource;
 import org.junit.platform.commons.JUnitException;
 import org.junit.platform.engine.TestDescriptor;
 import org.junit.platform.engine.UniqueId;
@@ -166,6 +169,29 @@ private List<UniqueId> getAncestorsUniqueIds(TestDescriptor descriptor) {
 		return descriptor.getAncestors().stream().map(TestDescriptor::getUniqueId).toList();
 	}
 
+	@ParameterizedTest(name = "{0} \u27A1 {1}")
+	// NOTE: "\uFFFD" is the Unicode replacement character: �
+	@CsvSource(delimiterString = "->", textBlock = """
+			'carriage \r return'           -> 'carriage <CR> return'
+			'line \n feed'                 -> 'line <LF> feed'
+			'form \f feed'                 -> 'form \uFFFD feed'
+			'back \b space'                -> 'back \uFFFD space'
+			'tab \t tab'                   -> 'tab \uFFFD tab'
+			# Latin-1
+			'üñåé'                         -> 'üñåé'
+			# "hello" in Japanese
+			'こんにちは'                     -> 'こんにちは'
+			# 'hello world' in Thai
+			'สวัสดีชาวโลก'                   -> 'สวัสดีชาวโลก'
+			# bell sound/character
+			'ding \u0007 dong'             -> 'ding \uFFFD dong'
+			'Munch 😱 emoji'               -> 'Munch 😱 emoji'
+			'Zero\u200BWidth\u200BSpaces'  -> 'Zero\u200BWidth\u200BSpaces'
+			""")
+	void specialCharactersInDisplayNamesAreEscaped(String input, String expected) {
+		assertThat(new DemoDescriptor(input).getDisplayName()).isEqualTo(expected);
+	}
+
 }
 
 class GroupDescriptor extends AbstractTestDescriptor {
@@ -193,3 +219,16 @@ public Type getType() {
 	}
 
 }
+
+class DemoDescriptor extends AbstractTestDescriptor {
+
+	DemoDescriptor(String displayName) {
+		super(mock(), displayName);
+	}
+
+	@Override
+	public Type getType() {
+		return Type.CONTAINER;
+	}
+
+}