Polish contribution

See #1987, #2107

Author: sbrannen

documentation/src/docs/asciidoc/release-notes/release-notes-5.10.0-M1.adoc

@@ -32,14 +32,14 @@ repository on GitHub.
   which return a `Stream`.
 * New `tryToLoadClass(...)` variant in `ReflectionSupport` that accepts an explicit
   `ClassLoader`, allowing classes to be resolved with custom `ClassLoader` arrangements.
-* New overloaded constructors for `ClassSelector` and `MethodSelector` that take an
-  explicit `ClassLoader` as a parameter, allowing selectors to select classes in custom
-  `ClassLoader` arrangements like in OSGi.
 * `ReflectionSupport.findMethod(Class<?>, String, String)` now uses the `ClassLoader` of
   the supplied `Class` to load parameter types instead of using the _default_
   `ClassLoader`. This allows parameter types to be resolved with custom `ClassLoader`
   arrangements (such as OSGi). Consequently, `DiscoverySelectors.selectMethod(Class<?>,
   String, String)` also now works properly with custom `ClassLoader` arrangements.
+* New overloaded constructors for `ClassSelector` and `MethodSelector` that take an
+  explicit `ClassLoader` as a parameter, allowing selectors to select classes in custom
+  `ClassLoader` arrangements like in OSGi.
 * For consistency with JUnit Jupiter lifecycle callbacks, listener method pairs for
   started/finished and opened/closed events are now invoked using "wrapping" semantics.
   This means that finished/closed event methods are invoked in reverse order compared to

junit-platform-engine/src/main/java/org/junit/platform/engine/discovery/ClassSelector.java

@@ -10,6 +10,7 @@
 
 package org.junit.platform.engine.discovery;
 
+import static org.apiguardian.api.API.Status.EXPERIMENTAL;
 import static org.apiguardian.api.API.Status.STABLE;
 
 import java.util.Objects;
@@ -71,8 +72,10 @@ public String getClassName() {
 	}
 
 	/**
-	 * Get the class loader used to load the selected class.
+	 * Get the {@link ClassLoader} used to load the selected class.
+	 * @since 1.10
 	 */
+	@API(status = EXPERIMENTAL, since = "1.10")
 	public ClassLoader getClassLoader() {
 		return this.classLoader;
 	}
@@ -86,10 +89,13 @@ public ClassLoader getClassLoader() {
 	 */
 	public Class<?> getJavaClass() {
 		if (this.javaClass == null) {
-			final Try<Class<?>> clazz = this.classLoader == null ? ReflectionUtils.tryToLoadClass(this.className)
-					: ReflectionUtils.tryToLoadClass(className, this.classLoader);
-			this.javaClass = clazz.getOrThrow(cause -> new PreconditionViolationException(
-				"Could not load class with name: " + this.className, cause));
+			// @formatter:off
+			Try<Class<?>> tryToLoadClass = this.classLoader == null
+				? ReflectionUtils.tryToLoadClass(this.className)
+				: ReflectionUtils.tryToLoadClass(this.className, this.classLoader);
+			this.javaClass = tryToLoadClass.getOrThrow(cause ->
+				new PreconditionViolationException("Could not load class with name: " + this.className, cause));
+			// @formatter:on
 		}
 		return this.javaClass;
 	}
@@ -121,7 +127,12 @@ public int hashCode() {
 
 	@Override
 	public String toString() {
-		return new ToStringBuilder(this).append("className", this.className).toString();
+		// @formatter:off
+		return new ToStringBuilder(this)
+				.append("className", this.className)
+				.append("classLoader", this.classLoader)
+				.toString();
+		// @formatter:on
 	}
 
 }

junit-platform-engine/src/main/java/org/junit/platform/engine/discovery/DiscoverySelectors.java

@@ -384,25 +384,25 @@ public static ClassSelector selectClass(Class<?> clazz) {
 	/**
 	 * Create a {@code ClassSelector} for the supplied class name.
 	 *
-	 * @param className the fully qualified name of the class to select;
-	 * never {@code null} or blank
+	 * @param className the fully qualified name of the class to select; never
+	 * {@code null} or blank
 	 * @see ClassSelector
 	 */
 	public static ClassSelector selectClass(String className) {
-		Preconditions.notBlank(className, "Class name must not be null or blank");
-		return new ClassSelector(className);
+		return selectClass(className, null);
 	}
 
 	/**
-	 * Create a {@code ClassSelector} for the supplied class name using the
-	 * supplied class loader.
+	 * Create a {@code ClassSelector} for the supplied class name and class loader.
 	 *
-	 * @param className the fully qualified name of the class to select;
-	 * never {@code null} or blank
-	 * @param classLoader the class loader to use to try and load the
-	 * supplied class. If {@code null}, the default class loader will be used.
+	 * @param className the fully qualified name of the class to select; never
+	 * {@code null} or blank
+	 * @param classLoader the class loader to use to load the class, or {@code null}
+	 * to signal that the default {@code ClassLoader} should be used
+	 * @since 1.10
 	 * @see ClassSelector
 	 */
+	@API(status = EXPERIMENTAL, since = "1.10")
 	public static ClassSelector selectClass(String className, ClassLoader classLoader) {
 		Preconditions.notBlank(className, "Class name must not be null or blank");
 		return new ClassSelector(className, classLoader);
@@ -446,8 +446,8 @@ public static ClassSelector selectClass(String className, ClassLoader classLoade
 	 * <tr><td>{@code example.Service.process(String[][])}</td><td>{@code example.Service#process(java.lang.String[][])}</td></tr>
 	 * </table>
 	 *
-	 * @param fullyQualifiedMethodName the fully qualified name of the method to select; never
-	 * {@code null} or blank
+	 * @param fullyQualifiedMethodName the fully qualified name of the method to
+	 * select; never {@code null} or blank
 	 * @see MethodSelector
 	 */
 	public static MethodSelector selectMethod(String fullyQualifiedMethodName) throws PreconditionViolationException {
@@ -456,14 +456,21 @@ public static MethodSelector selectMethod(String fullyQualifiedMethodName) throw
 
 	/**
 	 * Create a {@code MethodSelector} for the supplied <em>fully qualified
-	 * method name</em> using the given classloader.
+	 * method name</em> and class loader.
 	 *
-	 * @param fullyQualifiedMethodName the fully qualified name of the method to select; never
-	 * {@code null} or blank (see {@link #selectMethod(String)} for the format of this string).
-	 * @param classLoader the class loader to use to try and load the
-	 * supplied class. If {@code null}, the default class loader will be used.
+	 * <p>See {@link #selectMethod(String)} for the supported formats for a
+	 * fully qualified method name.
+	 *
+	 * @param fullyQualifiedMethodName the fully qualified name of the method to
+	 * select; never {@code null} or blank
+	 * @param classLoader the class loader to use to load the method's declaring
+	 * class, or {@code null} to signal that the default {@code ClassLoader}
+	 * should be used
+	 * @since 1.10
 	 * @see #selectMethod(String)
+	 * @see MethodSelector
 	 */
+	@API(status = EXPERIMENTAL, since = "1.10")
 	public static MethodSelector selectMethod(String fullyQualifiedMethodName, ClassLoader classLoader)
 			throws PreconditionViolationException {
 		String[] methodParts = ReflectionUtils.parseFullyQualifiedMethodName(fullyQualifiedMethodName);
@@ -484,16 +491,18 @@ public static MethodSelector selectMethod(String className, String methodName) {
 	}
 
 	/**
-	 * Create a {@code MethodSelector} for the supplied class name and method name, using
-	 * the given class loader to find the class.
+	 * Create a {@code MethodSelector} for the supplied class name, method name,
+	 * and class loader.
 	 *
 	 * @param className the fully qualified name of the class in which the method
 	 * is declared, or a subclass thereof; never {@code null} or blank
 	 * @param methodName the name of the method to select; never {@code null} or blank
-	 * @param classLoader the class loader to use to try and load the
-	 * supplied class. If {@code null}, the default class loader will be used.
+	 * @param classLoader the class loader to use to load the class, or {@code null}
+	 * to signal that the default {@code ClassLoader} should be used
+	 * @since 1.10
 	 * @see MethodSelector
 	 */
+	@API(status = EXPERIMENTAL, since = "1.10")
 	public static MethodSelector selectMethod(String className, String methodName, ClassLoader classLoader) {
 		Preconditions.notBlank(className, "Class name must not be null or blank");
 		Preconditions.notBlank(methodName, "Method name must not be null or blank");
@@ -522,7 +531,7 @@ public static MethodSelector selectMethod(String className, String methodName, S
 
 	/**
 	 * Create a {@code MethodSelector} for the supplied class name, method name,
-	 * and method parameter types, using the specified class loader.
+	 * method parameter types, and class loader.
 	 *
 	 * <p>The parameter types {@code String} is typically a comma-separated list
 	 * of atomic types, fully qualified class names, or array types; however,
@@ -534,8 +543,12 @@ public static MethodSelector selectMethod(String className, String methodName, S
 	 * @param methodParameterTypes the method parameter types as a single string; never
 	 * {@code null} though potentially an empty string if the method does not accept
 	 * arguments
+	 * @param classLoader the class loader to use to load the class, or {@code null}
+	 * to signal that the default {@code ClassLoader} should be used
+	 * @since 1.10
 	 * @see MethodSelector
 	 */
+	@API(status = EXPERIMENTAL, since = "1.10")
 	public static MethodSelector selectMethod(String className, String methodName, String methodParameterTypes,
 			ClassLoader classLoader) {
 		Preconditions.notBlank(className, "Class name must not be null or blank");

junit-platform-engine/src/main/java/org/junit/platform/engine/discovery/MethodSelector.java

@@ -10,6 +10,7 @@
 
 package org.junit.platform.engine.discovery;
 
+import static org.apiguardian.api.API.Status.EXPERIMENTAL;
 import static org.apiguardian.api.API.Status.STABLE;
 
 import java.lang.reflect.Method;
@@ -63,15 +64,15 @@ public class MethodSelector implements DiscoverySelector {
 	private Method javaMethod;
 
 	MethodSelector(String className, String methodName) {
-		this(className, methodName, "", (ClassLoader) null);
+		this(className, methodName, (ClassLoader) null);
 	}
 
 	MethodSelector(String className, String methodName, ClassLoader classLoader) {
 		this(className, methodName, "", classLoader);
 	}
 
 	MethodSelector(String className, String methodName, String methodParameterTypes) {
-		this(className, methodName, methodParameterTypes, (ClassLoader) null);
+		this(className, methodName, methodParameterTypes, null);
 	}
 
 	MethodSelector(String className, String methodName, String methodParameterTypes, ClassLoader classLoader) {
@@ -110,8 +111,10 @@ public String getClassName() {
 	}
 
 	/**
-	 * Get the class loader used to load the specified class.
+	 * Get the {@link ClassLoader} used to load the specified class.
+	 * @since 1.10
 	 */
+	@API(status = EXPERIMENTAL, since = "1.10")
 	public ClassLoader getClassLoader() {
 		return this.classLoader;
 	}
@@ -173,10 +176,11 @@ public Method getJavaMethod() {
 	private void lazyLoadJavaClass() {
 		if (this.javaClass == null) {
 			// @formatter:off
-			final Try<Class<?>> clazz = this.classLoader == null ? ReflectionUtils.tryToLoadClass(this.className)
-					: ReflectionUtils.tryToLoadClass(className, this.classLoader);
-			this.javaClass = clazz.getOrThrow(
-				cause -> new PreconditionViolationException("Could not load class with name: " + this.className, cause));
+			Try<Class<?>> tryToLoadClass = this.classLoader == null
+				? ReflectionUtils.tryToLoadClass(this.className)
+				: ReflectionUtils.tryToLoadClass(this.className, this.classLoader);
+			this.javaClass = tryToLoadClass.getOrThrow(cause ->
+				new PreconditionViolationException("Could not load class with name: " + this.className, cause));
 			// @formatter:on
 		}
 	}
@@ -235,6 +239,7 @@ public String toString() {
 				.append("className", this.className)
 				.append("methodName", this.methodName)
 				.append("methodParameterTypes", this.methodParameterTypes)
+				.append("classLoader", this.classLoader)
 				.toString();
 		// @formatter:on
 	}

platform-tests/src/test/java/org/junit/platform/engine/discovery/ClassSelectorTests.java

@@ -45,9 +45,10 @@ void preservesOriginalExceptionWhenTryingToLoadClass() {
 	}
 
 	@Test
-	void useClassClassLoader() {
+	void usesClassClassLoader() {
 		var selector = new ClassSelector(getClass());
 
 		assertThat(selector.getClassLoader()).isNotNull().isSameAs(getClass().getClassLoader());
 	}
+
 }

platform-tests/src/test/java/org/junit/platform/engine/discovery/DiscoverySelectorsTests.java

@@ -33,7 +33,6 @@
 import java.io.File;
 import java.lang.reflect.Method;
 import java.net.URI;
-import java.net.URLClassLoader;
 import java.nio.file.Path;
 import java.nio.file.Paths;
 import java.util.List;
@@ -248,12 +247,12 @@ void selectClassByName() {
 
 	@Test
 	void selectClassByNameAndClassLoader() throws Exception {
-		try (TestClassLoader l = TestClassLoader.forClasses(getClass())) {
-			ClassSelector selector = selectClass(getClass().getName(), l);
-			assertEquals(getClass().getTypeName(), selector.getJavaClass().getTypeName());
+		try (var testClassLoader = TestClassLoader.forClasses(getClass())) {
+			ClassSelector selector = selectClass(getClass().getName(), testClassLoader);
+			assertEquals(getClass().getName(), selector.getJavaClass().getName());
 			assertNotEquals(getClass(), selector.getJavaClass());
-			assertSame(l, selector.getClassLoader());
-			assertSame(l, selector.getJavaClass().getClassLoader());
+			assertSame(testClassLoader, selector.getClassLoader());
+			assertSame(testClassLoader, selector.getJavaClass().getClassLoader());
 		}
 	}
 
@@ -337,12 +336,12 @@ void selectMethodByFullyQualifiedName() throws Exception {
 
 	@Test
 	void selectMethodByFullyQualifiedNameAndClassLoader() throws Exception {
-		try (URLClassLoader l = TestClassLoader.forClasses(getClass())) {
-			Class<?> clazz = l.loadClass(getClass().getTypeName());
+		try (var testClassLoader = TestClassLoader.forClasses(getClass())) {
+			Class<?> clazz = testClassLoader.loadClass(getClass().getName());
 			assertNotEquals(getClass(), clazz);
 
 			Method method = clazz.getDeclaredMethod("myTest");
-			MethodSelector selector = selectMethod(getClass().getName(), "myTest", l);
+			MethodSelector selector = selectMethod(getClass().getName(), "myTest", testClassLoader);
 			assertEquals(method, selector.getJavaMethod());
 			assertEquals(clazz, selector.getJavaClass());
 			assertEquals(clazz.getName(), selector.getClassName());

platform-tests/src/test/java/org/junit/platform/engine/discovery/MethodSelectorTests.java

@@ -52,7 +52,7 @@ void preservesOriginalExceptionWhenTryingToLoadClass() {
 	void usesClassClassLoader() {
 		var selector = new MethodSelector(getClass(), "usesClassClassLoader");
 
-		assertThat(selector.getClassLoader()).isNotNull().isEqualTo(getClass().getClassLoader());
+		assertThat(selector.getClassLoader()).isNotNull().isSameAs(getClass().getClassLoader());
 	}
 
 }

platform-tests/src/test/java/org/junit/platform/launcher/listeners/discovery/LoggingLauncherDiscoveryListenerTests.java

@@ -80,7 +80,7 @@ void logsErrorOnSelectorResolutionFailure(LogRecordListener log) {
 		assertThat(log.stream(LoggingLauncherDiscoveryListener.class, Level.SEVERE)) //
 				.extracting(LogRecord::getMessage) //
 				.containsExactly(
-					"Resolution of ClassSelector [className = 'java.lang.Object'] by [engine:some-engine] failed");
+					"Resolution of ClassSelector [className = 'java.lang.Object', classLoader = null] by [engine:some-engine] failed");
 	}
 
 	@Test