Support explicit ClassLoader in ClassSelector and MethodSelector

This commit introduces overloaded selectClass() and selectMethod() variants
in DiscoverySelectors that accept an explicit ClassLoader and also modifies
ClassSelector and MethodSelector accordingly.


Closes #1987
Closes #2107

Author: kriegfrj

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

@@ -32,6 +32,9 @@ 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`

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

@@ -16,6 +16,7 @@
 
 import org.apiguardian.api.API;
 import org.junit.platform.commons.PreconditionViolationException;
+import org.junit.platform.commons.function.Try;
 import org.junit.platform.commons.util.ReflectionUtils;
 import org.junit.platform.commons.util.ToStringBuilder;
 import org.junit.platform.engine.DiscoverySelector;
@@ -43,15 +44,22 @@
 public class ClassSelector implements DiscoverySelector {
 
 	private final String className;
+	private final ClassLoader classLoader;
 
 	private Class<?> javaClass;
 
 	ClassSelector(String className) {
+		this(className, null);
+	}
+
+	ClassSelector(String className, ClassLoader classLoader) {
 		this.className = className;
+		this.classLoader = classLoader;
 	}
 
 	ClassSelector(Class<?> javaClass) {
 		this.className = javaClass.getName();
+		this.classLoader = javaClass.getClassLoader();
 		this.javaClass = javaClass;
 	}
 
@@ -62,6 +70,13 @@ public String getClassName() {
 		return this.className;
 	}
 
+	/**
+	 * Get the class loader used to load the selected class.
+	 */
+	public ClassLoader getClassLoader() {
+		return this.classLoader;
+	}
+
 	/**
 	 * Get the selected {@link Class}.
 	 *
@@ -71,9 +86,10 @@ public String getClassName() {
 	 */
 	public Class<?> getJavaClass() {
 		if (this.javaClass == null) {
-			this.javaClass = ReflectionUtils.tryToLoadClass(this.className).getOrThrow(
-				cause -> new PreconditionViolationException("Could not load class with name: " + this.className,
-					cause));
+			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));
 		}
 		return this.javaClass;
 	}

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

@@ -393,6 +393,21 @@ public static ClassSelector selectClass(String className) {
 		return new ClassSelector(className);
 	}
 
+	/**
+	 * Create a {@code ClassSelector} for the supplied class name using the
+	 * supplied 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.
+	 * @see ClassSelector
+	 */
+	public static ClassSelector selectClass(String className, ClassLoader classLoader) {
+		Preconditions.notBlank(className, "Class name must not be null or blank");
+		return new ClassSelector(className, classLoader);
+	}
+
 	/**
 	 * Create a {@code MethodSelector} for the supplied <em>fully qualified
 	 * method name</em>.
@@ -436,22 +451,53 @@ public static ClassSelector selectClass(String className) {
 	 * @see MethodSelector
 	 */
 	public static MethodSelector selectMethod(String fullyQualifiedMethodName) throws PreconditionViolationException {
+		return selectMethod(fullyQualifiedMethodName, (ClassLoader) null);
+	}
+
+	/**
+	 * Create a {@code MethodSelector} for the supplied <em>fully qualified
+	 * method name</em> using the given classloader.
+	 *
+	 * @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.
+	 * @see #selectMethod(String)
+	 */
+	public static MethodSelector selectMethod(String fullyQualifiedMethodName, ClassLoader classLoader)
+			throws PreconditionViolationException {
 		String[] methodParts = ReflectionUtils.parseFullyQualifiedMethodName(fullyQualifiedMethodName);
-		return selectMethod(methodParts[0], methodParts[1], methodParts[2]);
+		return selectMethod(methodParts[0], methodParts[1], methodParts[2], classLoader);
 	}
 
 	/**
-	 * Create a {@code MethodSelector} for the supplied class name and method name.
+	 * Create a {@code MethodSelector} for the supplied class name and method name
+	 * using the default 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
 	 * @see MethodSelector
 	 */
 	public static MethodSelector selectMethod(String className, String methodName) {
+		return selectMethod(className, methodName, (ClassLoader) null);
+	}
+
+	/**
+	 * Create a {@code MethodSelector} for the supplied class name and method name, using
+	 * the given class loader to find the class.
+	 *
+	 * @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.
+	 * @see MethodSelector
+	 */
+	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");
-		return new MethodSelector(className, methodName);
+		return new MethodSelector(className, methodName, classLoader);
 	}
 
 	/**
@@ -471,10 +517,31 @@ public static MethodSelector selectMethod(String className, String methodName) {
 	 * @see MethodSelector
 	 */
 	public static MethodSelector selectMethod(String className, String methodName, String methodParameterTypes) {
+		return selectMethod(className, methodName, methodParameterTypes, null);
+	}
+
+	/**
+	 * Create a {@code MethodSelector} for the supplied class name, method name,
+	 * and method parameter types, using the specified 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,
+	 * the exact syntax depends on the underlying test engine.
+	 *
+	 * @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 methodParameterTypes the method parameter types as a single string; never
+	 * {@code null} though potentially an empty string if the method does not accept
+	 * arguments
+	 * @see MethodSelector
+	 */
+	public static MethodSelector selectMethod(String className, String methodName, String methodParameterTypes,
+			ClassLoader classLoader) {
 		Preconditions.notBlank(className, "Class name must not be null or blank");
 		Preconditions.notBlank(methodName, "Method name must not be null or blank");
 		Preconditions.notNull(methodParameterTypes, "Parameter types must not be null");
-		return new MethodSelector(className, methodName, methodParameterTypes.trim());
+		return new MethodSelector(className, methodName, methodParameterTypes.trim(), classLoader);
 	}
 
 	/**

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

@@ -17,6 +17,7 @@
 
 import org.apiguardian.api.API;
 import org.junit.platform.commons.PreconditionViolationException;
+import org.junit.platform.commons.function.Try;
 import org.junit.platform.commons.util.ClassUtils;
 import org.junit.platform.commons.util.ReflectionUtils;
 import org.junit.platform.commons.util.StringUtils;
@@ -53,6 +54,7 @@
 @API(status = STABLE, since = "1.0")
 public class MethodSelector implements DiscoverySelector {
 
+	private final ClassLoader classLoader;
 	private final String className;
 	private final String methodName;
 	private final String methodParameterTypes;
@@ -61,10 +63,19 @@ public class MethodSelector implements DiscoverySelector {
 	private Method javaMethod;
 
 	MethodSelector(String className, String methodName) {
-		this(className, methodName, "");
+		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);
+	}
+
+	MethodSelector(String className, String methodName, String methodParameterTypes, ClassLoader classLoader) {
+		this.classLoader = classLoader;
 		this.className = className;
 		this.methodName = methodName;
 		this.methodParameterTypes = methodParameterTypes;
@@ -75,13 +86,15 @@ public class MethodSelector implements DiscoverySelector {
 	}
 
 	MethodSelector(Class<?> javaClass, String methodName, String methodParameterTypes) {
+		this.classLoader = javaClass.getClassLoader();
 		this.javaClass = javaClass;
 		this.className = javaClass.getName();
 		this.methodName = methodName;
 		this.methodParameterTypes = methodParameterTypes;
 	}
 
 	MethodSelector(Class<?> javaClass, Method method) {
+		this.classLoader = javaClass.getClassLoader();
 		this.javaClass = javaClass;
 		this.className = javaClass.getName();
 		this.javaMethod = method;
@@ -96,6 +109,13 @@ public String getClassName() {
 		return this.className;
 	}
 
+	/**
+	 * Get the class loader used to load the specified class.
+	 */
+	public ClassLoader getClassLoader() {
+		return this.classLoader;
+	}
+
 	/**
 	 * Get the selected method name.
 	 */
@@ -153,7 +173,9 @@ public Method getJavaMethod() {
 	private void lazyLoadJavaClass() {
 		if (this.javaClass == null) {
 			// @formatter:off
-			this.javaClass = ReflectionUtils.tryToLoadClass(this.className).getOrThrow(
+			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:on
 		}

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

@@ -43,4 +43,11 @@ void preservesOriginalExceptionWhenTryingToLoadClass() {
 		assertThat(e).hasMessage("Could not load class with name: org.example.TestClass").hasCauseInstanceOf(
 			ClassNotFoundException.class);
 	}
+
+	@Test
+	void useClassClassLoader() {
+		var selector = new ClassSelector(getClass());
+
+		assertThat(selector.getClassLoader()).isNotNull().isSameAs(getClass().getClassLoader());
+	}
 }

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

@@ -13,6 +13,8 @@
 import static java.lang.String.join;
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotEquals;
+import static org.junit.jupiter.api.Assertions.assertSame;
 import static org.junit.jupiter.api.Assertions.assertThrows;
 import static org.junit.jupiter.params.provider.Arguments.arguments;
 import static org.junit.platform.engine.discovery.DiscoverySelectors.selectClass;
@@ -31,6 +33,7 @@
 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;
@@ -46,6 +49,7 @@
 import org.junit.jupiter.params.provider.Arguments;
 import org.junit.jupiter.params.provider.MethodSource;
 import org.junit.platform.commons.PreconditionViolationException;
+import org.junit.platform.commons.test.TestClassLoader;
 import org.junit.platform.commons.util.ReflectionUtils;
 
 /**
@@ -242,9 +246,20 @@ void selectClassByName() {
 		assertEquals(getClass(), selector.getJavaClass());
 	}
 
+	@Test
+	void selectClassByNameAndClassLoader() throws Exception {
+		try (TestClassLoader l = TestClassLoader.forClasses(getClass())) {
+			ClassSelector selector = selectClass(getClass().getName(), l);
+			assertEquals(getClass().getTypeName(), selector.getJavaClass().getTypeName());
+			assertNotEquals(getClass(), selector.getJavaClass());
+			assertSame(l, selector.getClassLoader());
+			assertSame(l, selector.getJavaClass().getClassLoader());
+		}
+	}
+
 	@Test
 	void selectMethodByClassNameAndMethodNamePreconditions() {
-		assertViolatesPrecondition(() -> selectMethod("TestClass", null));
+		assertViolatesPrecondition(() -> selectMethod("TestClass", (String) null));
 		assertViolatesPrecondition(() -> selectMethod("TestClass", ""));
 		assertViolatesPrecondition(() -> selectMethod("TestClass", "  "));
 		assertViolatesPrecondition(() -> selectMethod((String) null, "method"));
@@ -260,7 +275,7 @@ void selectMethodByClassNameMethodNameAndMethodParameterTypesPreconditions() {
 		assertViolatesPrecondition(() -> selectMethod((String) null, "method", "int"));
 		assertViolatesPrecondition(() -> selectMethod("", "method", "int"));
 		assertViolatesPrecondition(() -> selectMethod("   ", "method", "int"));
-		assertViolatesPrecondition(() -> selectMethod("TestClass", "method", null));
+		assertViolatesPrecondition(() -> selectMethod("TestClass", "method", (String) null));
 	}
 
 	@Test
@@ -320,6 +335,22 @@ void selectMethodByFullyQualifiedName() throws Exception {
 		assertSelectMethodByFullyQualifiedName(clazz, method);
 	}
 
+	@Test
+	void selectMethodByFullyQualifiedNameAndClassLoader() throws Exception {
+		try (URLClassLoader l = TestClassLoader.forClasses(getClass())) {
+			Class<?> clazz = l.loadClass(getClass().getTypeName());
+			assertNotEquals(getClass(), clazz);
+
+			Method method = clazz.getDeclaredMethod("myTest");
+			MethodSelector selector = selectMethod(getClass().getName(), "myTest", l);
+			assertEquals(method, selector.getJavaMethod());
+			assertEquals(clazz, selector.getJavaClass());
+			assertEquals(clazz.getName(), selector.getClassName());
+			assertEquals(method.getName(), selector.getMethodName());
+			assertEquals("", selector.getMethodParameterTypes());
+		}
+	}
+
 	@Test
 	void selectMethodByFullyQualifiedNameForDefaultMethodInInterface() throws Exception {
 		Class<?> clazz = TestCaseWithDefaultMethod.class;

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

@@ -27,25 +27,32 @@ class MethodSelectorTests extends AbstractEqualsAndHashCodeTests {
 
 	@Test
 	void equalsAndHashCode() {
-		var selector1 = new MethodSelector("TestClass", "method", "int, boolean");
-		var selector2 = new MethodSelector("TestClass", "method", "int, boolean");
+		var selector1 = new MethodSelector("TestClass", "method", "int, boolean", null);
+		var selector2 = new MethodSelector("TestClass", "method", "int, boolean", null);
 
 		assertEqualsAndHashCode(selector1, selector2, new MethodSelector("TestClass", "method", "int"));
-		assertEqualsAndHashCode(selector1, selector2, new MethodSelector("TestClass", "method"));
-		assertEqualsAndHashCode(selector1, selector2, new MethodSelector("TestClass", "X", "int, boolean"));
-		assertEqualsAndHashCode(selector1, selector2, new MethodSelector("TestClass", "X"));
-		assertEqualsAndHashCode(selector1, selector2, new MethodSelector("X", "method", "int, boolean"));
-		assertEqualsAndHashCode(selector1, selector2, new MethodSelector("X", "method"));
+		assertEqualsAndHashCode(selector1, selector2, new MethodSelector("TestClass", "method", (ClassLoader) null));
+		assertEqualsAndHashCode(selector1, selector2, new MethodSelector("TestClass", "X", "int, boolean", null));
+		assertEqualsAndHashCode(selector1, selector2, new MethodSelector("TestClass", "X", (ClassLoader) null));
+		assertEqualsAndHashCode(selector1, selector2, new MethodSelector("X", "method", "int, boolean", null));
+		assertEqualsAndHashCode(selector1, selector2, new MethodSelector("X", "method", (ClassLoader) null));
 	}
 
 	@Test
 	void preservesOriginalExceptionWhenTryingToLoadClass() {
-		var selector = new MethodSelector("TestClass", "method", "int, boolean");
+		var selector = new MethodSelector("TestClass", "method", "int, boolean", (ClassLoader) null);
 
 		var e = assertThrows(PreconditionViolationException.class, selector::getJavaClass);
 
 		assertThat(e).hasMessage("Could not load class with name: TestClass").hasCauseInstanceOf(
 			ClassNotFoundException.class);
 	}
 
+	@Test
+	void usesClassClassLoader() {
+		var selector = new MethodSelector(getClass(), "usesClassClassLoader");
+
+		assertThat(selector.getClassLoader()).isNotNull().isEqualTo(getClass().getClassLoader());
+	}
+
 }