Support CharSequence argument for Fallback String-to-Object Conversion

Prior to this commit, the Fallback String-to-Object Conversion support
for parameterized tests supported factory constructors and methods that
accepted a single String argument.

This commit relaxes that restriction to support factory constructors
and methods that accept either a single String argument or a single
CharSequence argument, since the original source String can always be
supplied to an Executable that accepts a CharSequence.

Note that this change is available to third parties via
ConversionSupport in junit-platform-commons, which junit-jupiter-params
utilizes.

Closes #4815

Author: sbrannen

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

@@ -26,7 +26,9 @@ repository on GitHub.
 [[release-notes-6.0.0-RC1-junit-platform-new-features-and-improvements]]
 ==== New Features and Improvements
 
-* ❓
+* 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.
 
 
 [[release-notes-6.0.0-RC1-junit-jupiter]]
@@ -53,6 +55,10 @@ repository on GitHub.
   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.
+* <<../user-guide/index.adoc#writing-tests-parameterized-tests-argument-conversion-implicit-fallback,
+  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.
 
 
 [[release-notes-6.0.0-RC1-junit-vintage]]

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

@@ -2535,11 +2535,12 @@ table, JUnit Jupiter also provides a fallback mechanism for automatic conversion
 method_ or a _factory constructor_ as defined below.
 
 - __factory method__: a non-private, `static` method declared in the target type that
-  accepts a single `String` argument and returns an instance of the target type. The name
-  of the method can be arbitrary and need not follow any particular convention.
+  accepts either a single `String` argument or a single `CharSequence` argument and
+  returns an instance of the target type. The name of the method can be arbitrary and need
+  not follow any particular convention.
 - __factory constructor__: a non-private constructor in the target type that accepts a
-  single `String` argument. Note that the target type must be declared as either a
-  top-level class or as a `static` nested class.
+  either a single `String` argument or a single `CharSequence` argument. Note that the
+  target type must be declared as either a top-level class or as a `static` nested class.
 
 NOTE: If multiple _factory methods_ are discovered, they will be ignored. If a _factory
 method_ and a _factory constructor_ are discovered, the factory method will be used

junit-platform-commons/src/main/java/org/junit/platform/commons/support/conversion/ConversionSupport.java

@@ -75,10 +75,11 @@ private ConversionSupport() {
 	 *
 	 * <ol>
 	 * <li>Search for a single, non-private static factory method in the target
-	 * type that converts from a String to the target type. Use the factory method
-	 * if present.</li>
+	 * type that converts from a {@link String} or {@link CharSequence} to the
+	 * target type. Use the factory method if present.</li>
 	 * <li>Search for a single, non-private constructor in the target type that
-	 * accepts a String. Use the constructor if present.</li>
+	 * accepts a {@link String} or {@link CharSequence}. Use the constructor if
+	 * present.</li>
 	 * </ol>
 	 *
 	 * <p>If multiple suitable factory methods are discovered they will be ignored.

junit-platform-commons/src/main/java/org/junit/platform/commons/support/conversion/FallbackStringToObjectConverter.java

@@ -11,8 +11,8 @@
 package org.junit.platform.commons.support.conversion;
 
 import static org.junit.platform.commons.support.HierarchyTraversalMode.BOTTOM_UP;
-import static org.junit.platform.commons.support.ModifierSupport.isNotPrivate;
 import static org.junit.platform.commons.support.ModifierSupport.isNotStatic;
+import static org.junit.platform.commons.support.ModifierSupport.isPrivate;
 import static org.junit.platform.commons.support.ReflectionSupport.findMethods;
 import static org.junit.platform.commons.support.ReflectionSupport.invokeMethod;
 import static org.junit.platform.commons.util.ReflectionUtils.findConstructors;
@@ -38,11 +38,11 @@
  * <h2>Search Algorithm</h2>
  *
  * <ol>
- * <li>Search for a single, non-private static factory method in the target
- * type that converts from a String to the target type. Use the factory method
- * if present.</li>
- * <li>Search for a single, non-private constructor in the target type that
- * accepts a String. Use the constructor if present.</li>
+ * <li>Search for a single, non-private static factory method in the target type
+ * that converts from a {@link String} or {@link CharSequence} to the target type.
+ * Use the factory method if present.</li>
+ * <li>Search for a single, non-private constructor in the target type that accepts
+ * a {@link String} or {@link CharSequence}. Use the constructor if present.</li>
  * </ol>
  *
  * <p>If multiple suitable factory methods are discovered they will be ignored.
@@ -136,7 +136,7 @@ public boolean test(Method method) {
 			if (isNotStatic(method)) {
 				return false;
 			}
-			return isNotPrivateAndAcceptsSingleStringArgument(method);
+			return isFactoryCandidate(method);
 		}
 
 	}
@@ -160,15 +160,21 @@ public boolean test(Constructor<?> constructor) {
 			if (!constructor.getDeclaringClass().equals(this.targetType)) {
 				return false;
 			}
-			return isNotPrivateAndAcceptsSingleStringArgument(constructor);
+			return isFactoryCandidate(constructor);
 		}
 
 	}
 
-	private static boolean isNotPrivateAndAcceptsSingleStringArgument(Executable executable) {
-		return isNotPrivate(executable) //
-				&& (executable.getParameterCount() == 1) //
-				&& (executable.getParameterTypes()[0] == String.class);
+	/**
+	 * Determine if the supplied {@link Executable} is not private and accepts a
+	 * single {@link String} or {@link CharSequence} argument.
+	 */
+	private static boolean isFactoryCandidate(Executable executable) {
+		if (isPrivate(executable) || (executable.getParameterCount() != 1)) {
+			return false;
+		}
+		Object parameterType = executable.getParameterTypes()[0];
+		return (parameterType == String.class || parameterType == CharSequence.class);
 	}
 
 }

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

@@ -311,6 +311,17 @@ void executesWithImplicitGenericConverter() {
 					event(test(), displayName("[2] book = book 2"), finishedWithFailure(message("book 2"))));
 	}
 
+	/**
+	 * @since 6.0
+	 */
+	@Test
+	void executesWithImplicitGenericConverterWithCharSequenceConstructor() {
+		var results = execute("testWithImplicitGenericConverterWithCharSequenceConstructor", Record.class);
+		results.testEvents().assertThatEvents() //
+				.haveExactly(1, event(displayName("\"record 1\""), finishedWithFailure(message("record 1")))) //
+				.haveExactly(1, event(displayName("\"record 2\""), finishedWithFailure(message("record 2"))));
+	}
+
 	@Test
 	void legacyReportingNames() {
 		var results = execute("testWithCustomName", String.class, int.class);
@@ -1460,6 +1471,12 @@ void testWithImplicitGenericConverter(Book book) {
 			fail(book.title);
 		}
 
+		@ParameterizedTest(name = "{0}")
+		@ValueSource(strings = { "record 1", "record 2" })
+		void testWithImplicitGenericConverterWithCharSequenceConstructor(Record record) {
+			fail(record.title.toString());
+		}
+
 		@ParameterizedTest(quoteTextArguments = false)
 		@ValueSource(strings = { "O", "XXX" })
 		void testWithExplicitConverter(@ConvertWith(StringLengthConverter.class) int length) {
@@ -2673,6 +2690,9 @@ static Book factory(String title) {
 		}
 	}
 
+	record Record(CharSequence title) {
+	}
+
 	static class FailureInBeforeEachTestCase {
 
 		@BeforeEach

platform-tests/src/test/java/org/junit/platform/commons/support/conversion/FallbackStringToObjectConverterTests.java

@@ -38,6 +38,8 @@ class FallbackStringToObjectConverterTests {
 	@Test
 	void isNotFactoryMethodForWrongParameterType() {
 		assertThat(isBookFactoryMethod).rejects(bookMethod("factory", Object.class));
+		assertThat(isBookFactoryMethod).rejects(bookMethod("factory", Number.class));
+		assertThat(isBookFactoryMethod).rejects(bookMethod("factory", StringBuilder.class));
 	}
 
 	@Test
@@ -55,6 +57,7 @@ void isFactoryMethodForValidMethods() {
 		assertThat(isBookFactoryMethod).accepts(bookMethod("factory"));
 		assertThat(new IsFactoryMethod(Newspaper.class)).accepts(newspaperMethod("from"), newspaperMethod("of"));
 		assertThat(new IsFactoryMethod(Magazine.class)).accepts(magazineMethod("from"), magazineMethod("of"));
+		assertThat(new IsFactoryMethod(Record2.class)).accepts(record2Method("from"));
 	}
 
 	@Test
@@ -67,18 +70,30 @@ void isFactoryConstructorForValidConstructors() {
 		assertThat(new IsFactoryConstructor(Book.class)).accepts(constructor(Book.class));
 		assertThat(new IsFactoryConstructor(Journal.class)).accepts(constructor(Journal.class));
 		assertThat(new IsFactoryConstructor(Newspaper.class)).accepts(constructor(Newspaper.class));
+		assertThat(new IsFactoryConstructor(Record1.class)).accepts(Record1.class.getDeclaredConstructors()[0]);
+		assertThat(new IsFactoryConstructor(Record2.class)).accepts(Record2.class.getDeclaredConstructors()[0]);
 	}
 
 	@Test
 	void convertsStringToBookViaStaticFactoryMethod() throws Exception {
 		assertConverts("enigma", Book.class, Book.factory("enigma"));
 	}
 
+	@Test
+	void convertsStringToRecord2ViaStaticFactoryMethodAcceptingCharSequence() throws Exception {
+		assertConvertsRecord2("enigma", Record2.from(new StringBuffer("enigma")));
+	}
+
 	@Test
 	void convertsStringToJournalViaFactoryConstructor() throws Exception {
 		assertConverts("enigma", Journal.class, new Journal("enigma"));
 	}
 
+	@Test
+	void convertsStringToRecord1ViaFactoryConstructorAcceptingCharSequence() throws Exception {
+		assertConvertsRecord1("enigma", new Record1(new StringBuffer("enigma")));
+	}
+
 	@Test
 	void convertsStringToNewspaperViaConstructorIgnoringMultipleFactoryMethods() throws Exception {
 		assertConverts("enigma", Newspaper.class, new Newspaper("enigma"));
@@ -119,6 +134,10 @@ private static Method magazineMethod(String methodName) {
 		return findMethod(Magazine.class, methodName, String.class).orElseThrow();
 	}
 
+	private static Method record2Method(String methodName) {
+		return findMethod(Record2.class, methodName, CharSequence.class).orElseThrow();
+	}
+
 	private static void assertConverts(String input, Class<?> targetType, Object expectedOutput) throws Exception {
 		assertThat(converter.canConvertTo(targetType)).isTrue();
 
@@ -129,6 +148,27 @@ private static void assertConverts(String input, Class<?> targetType, Object exp
 				.isEqualTo(expectedOutput);
 	}
 
+	private static void assertConvertsRecord1(String input, Record1 expected) throws Exception {
+		Class<?> targetType = Record1.class;
+
+		assertThat(converter.canConvertTo(targetType)).isTrue();
+
+		Record1 result = (Record1) converter.convert(input, targetType);
+
+		assertThat(result).isNotNull();
+		assertThat(result.title.toString()).isEqualTo(expected.title.toString());
+	}
+
+	private static void assertConvertsRecord2(String input, Record2 expected) throws Exception {
+		Class<?> targetType = Record2.class;
+
+		assertThat(converter.canConvertTo(targetType)).isTrue();
+
+		Record2 result = (Record2) converter.convert(input, targetType);
+
+		assertThat(result).isEqualTo(expected);
+	}
+
 	static class Book {
 
 		private final String title;
@@ -144,7 +184,20 @@ static Book factory(String title) {
 
 		// wrong parameter type
 		static Book factory(Object obj) {
-			return new Book(String.valueOf(obj));
+			throw new UnsupportedOperationException();
+		}
+
+		// wrong parameter type
+		static Book factory(Number number) {
+			throw new UnsupportedOperationException();
+		}
+
+		/**
+		 * Wrong parameter type, intentionally a subtype of {@link CharSequence}
+		 * other than {@link String}.
+		 */
+		static Book factory(StringBuilder builder) {
+			throw new UnsupportedOperationException();
 		}
 
 		@SuppressWarnings("unused")
@@ -231,6 +284,16 @@ static Magazine of(String title) {
 
 	}
 
+	record Record1(CharSequence title) {
+	}
+
+	record Record2(String title) {
+
+		static Record2 from(CharSequence title) {
+			return new Record2(title.toString());
+		}
+	}
+
 	static class Diary {
 	}