Support fully-qualified factory method names in @⁠TestBean

Prior to this commit, @⁠TestBean factory methods had to be defined in
the test class, one of its superclasses, or in an implemented
interface. However, users may wish to define common factory methods in
external classes that can be shared easily across multiple test classes
simply by referencing an external method via a fully-qualified method
name.

To address that, this commit introduces support for referencing a
@⁠TestBean factory method via its fully-qualified method name following
the syntax <fully-qualified class name>#<method name>.

Closes gh-33125

Author: sbrannen

framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-testbean.adoc

@@ -78,5 +78,12 @@ Java::
 <2> The result of this static method will be used as the instance and injected into the field.
 ======
 
-NOTE: Spring searches for the factory method to invoke in the test class, in the test
-class hierarchy, and in the enclosing class hierarchy for a `@Nested` test class.
+[NOTE]
+====
+Spring searches for the factory method to invoke in the test class, in the test class
+hierarchy, and in the enclosing class hierarchy for a `@Nested` test class.
+
+Alternatively, a factory method in an external class can be referenced via its
+fully-qualified method name following the syntax `<fully-qualified class name>#<method name>`
+– for example, `methodName = "org.example.TestUtils#createCustomService"`.
+====

spring-test/src/main/java/org/springframework/test/context/bean/override/convention/TestBean.java

@@ -40,8 +40,12 @@
  * test class whose return type is compatible with the annotated field. In the
  * case of a nested test class, the enclosing class hierarchy is also searched.
  * Similarly, if the test class extends from a base class or implements any
- * interfaces, the entire type hierarchy is searched. The method is deduced as
- * follows.
+ * interfaces, the entire type hierarchy is searched. Alternatively, a factory
+ * method in an external class can be referenced via its fully-qualified method
+ * name following the syntax {@code <fully-qualified class name>#<method name>}
+ * &mdash; for example, {@code "org.example.TestUtils#createCustomerRepository"}.
+ *
+ * <p>The factory method is deduced as follows.
  *
  * <ul>
  * <li>If the {@link #methodName()} is specified, look for a static method with
@@ -125,6 +129,10 @@
 	 * <p>A search will be performed to find the factory method in the test class,
 	 * in one of its superclasses, or in any implemented interfaces. In the case
 	 * of a nested test class, the enclosing class hierarchy will also be searched.
+	 * <p>Alternatively, a factory method in an external class can be referenced
+	 * via its fully-qualified method name following the syntax
+	 * {@code <fully-qualified class name>#<method name>} &mdash; for example,
+	 * {@code "org.example.TestUtils#createCustomerRepository"}.
 	 * <p>If left unspecified, the name of the factory method will be detected
 	 * based either on the name of the annotated field or the name of the bean.
 	 */

spring-test/src/main/java/org/springframework/test/context/bean/override/convention/TestBeanOverrideProcessor.java

@@ -32,6 +32,8 @@
 import org.springframework.test.context.TestContextAnnotationUtils;
 import org.springframework.test.context.bean.override.BeanOverrideProcessor;
 import org.springframework.util.Assert;
+import org.springframework.util.ClassUtils;
+import org.springframework.util.ReflectionUtils;
 import org.springframework.util.ReflectionUtils.MethodFilter;
 import org.springframework.util.StringUtils;
 
@@ -109,12 +111,40 @@ Method findTestBeanFactoryMethod(Class<?> clazz, Class<?> methodReturnType, Stri
 	 */
 	Method findTestBeanFactoryMethod(Class<?> clazz, Class<?> methodReturnType, Collection<String> methodNames) {
 		Assert.notEmpty(methodNames, "At least one candidate method name is required");
-		Set<String> supportedNames = new LinkedHashSet<>(methodNames);
+		Set<Method> methods = new LinkedHashSet<>();
+		Set<String> originalNames = new LinkedHashSet<>(methodNames);
+
+		// Process fully-qualified method names first.
+		for (String methodName : methodNames) {
+			int indexOfHash = methodName.lastIndexOf('#');
+			if (indexOfHash != -1) {
+				String className = methodName.substring(0, indexOfHash).trim();
+				Assert.hasText(className, () -> "No class name present in fully-qualified method name: " + methodName);
+				String methodNameToUse = methodName.substring(indexOfHash + 1).trim();
+				Assert.hasText(methodNameToUse, () -> "No method name present in fully-qualified method name: " + methodName);
+				Class<?> declaringClass;
+				try {
+					declaringClass = ClassUtils.forName(className, getClass().getClassLoader());
+				}
+				catch (ClassNotFoundException | LinkageError ex) {
+					throw new IllegalStateException(
+							"Failed to load class for fully-qualified method name: " + methodName, ex);
+				}
+				Method externalMethod = ReflectionUtils.findMethod(declaringClass, methodNameToUse);
+				Assert.state(externalMethod != null && Modifier.isStatic(externalMethod.getModifiers()) &&
+						methodReturnType.isAssignableFrom(externalMethod.getReturnType()), () ->
+								"No static method found named %s in %s with return type %s".formatted(
+										methodNameToUse, className, methodReturnType.getName()));
+				methods.add(externalMethod);
+				originalNames.remove(methodName);
+			}
+		}
+
+		Set<String> supportedNames = new LinkedHashSet<>(originalNames);
 		MethodFilter methodFilter = method -> (Modifier.isStatic(method.getModifiers()) &&
 				supportedNames.contains(method.getName()) &&
 				methodReturnType.isAssignableFrom(method.getReturnType()));
-
-		Set<Method> methods = findMethods(clazz, methodFilter);
+		findMethods(methods, clazz, methodFilter);
 
 		String methodNamesDescription = supportedNames.stream()
 				.map(name -> name + "()").collect(Collectors.joining(" or "));
@@ -130,10 +160,10 @@ Method findTestBeanFactoryMethod(Class<?> clazz, Class<?> methodReturnType, Coll
 		return methods.iterator().next();
 	}
 
-	private static Set<Method> findMethods(Class<?> clazz, MethodFilter methodFilter) {
-		Set<Method> methods = MethodIntrospector.selectMethods(clazz, methodFilter);
+	private static Set<Method> findMethods(Set<Method> methods, Class<?> clazz, MethodFilter methodFilter) {
+		methods.addAll(MethodIntrospector.selectMethods(clazz, methodFilter));
 		if (methods.isEmpty() && TestContextAnnotationUtils.searchEnclosingClass(clazz)) {
-			methods = findMethods(clazz.getEnclosingClass(), methodFilter);
+			findMethods(methods, clazz.getEnclosingClass(), methodFilter);
 		}
 		return methods;
 	}

spring-test/src/test/java/org/springframework/test/context/bean/override/convention/TestBeanForExternalFactoryMethodIntegrationTests.java

@@ -0,0 +1,56 @@
+/*
+ * Copyright 2002-2024 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.test.context.bean.override.convention;
+
+import org.junit.jupiter.api.Test;
+
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.test.context.junit.jupiter.SpringJUnitConfig;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+/**
+ * Integration tests for {@link TestBean} that use bean factory methods defined
+ * in external classes.
+ *
+ * @author Sam Brannen
+ * @since 6.2
+ */
+@SpringJUnitConfig
+class TestBeanForExternalFactoryMethodIntegrationTests {
+
+	@TestBean(methodName = "org.springframework.test.context.bean.override.example.TestBeanFactory#createTestMessage")
+	String message;
+
+
+	@Test
+	void test() {
+		assertThat(message).isEqualTo("test");
+	}
+
+
+	@Configuration
+	static class Config {
+
+		@Bean
+		String message() {
+			return "prod";
+		}
+	}
+
+}

spring-test/src/test/java/org/springframework/test/context/bean/override/convention/TestBeanOverrideProcessorTests.java

@@ -24,6 +24,7 @@
 import org.springframework.core.annotation.AnnotationUtils;
 import org.springframework.lang.NonNull;
 import org.springframework.test.context.bean.override.example.ExampleService;
+import org.springframework.test.context.bean.override.example.TestBeanFactory;
 import org.springframework.util.ReflectionUtils;
 
 import static org.assertj.core.api.Assertions.assertThat;
@@ -91,6 +92,64 @@ void findTestBeanFactoryMethodNoNameProvided() {
 				.withMessage("At least one candidate method name is required");
 	}
 
+	@Test
+	void findTestBeanFactoryMethodByFullyQualifiedName() {
+		Class<?> clazz = getClass();
+		Class<?> returnType = String.class;
+		String methodName = TestBeanFactory.class.getName() + "#createTestMessage";
+
+		Method method = this.processor.findTestBeanFactoryMethod(clazz, returnType, methodName);
+
+		assertThat(method).isEqualTo(ReflectionUtils.findMethod(TestBeanFactory.class, "createTestMessage"));
+	}
+
+	@Test
+	void findTestBeanFactoryMethodByFullyQualifiedNameWithNonexistentMethod() {
+		Class<?> clazz = getClass();
+		Class<?> returnType = String.class;
+		String factoryClassName = TestBeanFactory.class.getName();
+		String methodName = factoryClassName + "#bogus";
+
+		assertThatIllegalStateException()
+				.isThrownBy(() -> this.processor.findTestBeanFactoryMethod(clazz, returnType, methodName))
+				.withMessage("No static method found named %s in %s with return type %s",
+						"bogus", factoryClassName, returnType.getName());
+	}
+
+	@Test
+	void findTestBeanFactoryMethodByFullyQualifiedNameWithNonexistentClass() {
+		Class<?> clazz = getClass();
+		Class<?> returnType = String.class;
+		String methodName = "org.example.Bogus#createTestBean";
+
+		assertThatIllegalStateException()
+				.isThrownBy(() -> this.processor.findTestBeanFactoryMethod(clazz, returnType, methodName))
+				.withMessage("Failed to load class for fully-qualified method name: %s", methodName)
+				.withCauseInstanceOf(ClassNotFoundException.class);
+	}
+
+	@Test
+	void findTestBeanFactoryMethodByFullyQualifiedNameWithMissingMethodName() {
+		Class<?> clazz = getClass();
+		Class<?> returnType = String.class;
+		String methodName = TestBeanFactory.class.getName() + "#";
+
+		assertThatIllegalArgumentException()
+				.isThrownBy(() -> this.processor.findTestBeanFactoryMethod(clazz, returnType, methodName))
+				.withMessage("No method name present in fully-qualified method name: %s", methodName);
+	}
+
+	@Test
+	void findTestBeanFactoryMethodByFullyQualifiedNameWithMissingClassName() {
+		Class<?> clazz = getClass();
+		Class<?> returnType = String.class;
+		String methodName = "#createTestBean";
+
+		assertThatIllegalArgumentException()
+				.isThrownBy(() -> this.processor.findTestBeanFactoryMethod(clazz, returnType, methodName))
+				.withMessage("No class name present in fully-qualified method name: %s", methodName);
+	}
+
 	@Test
 	void createMetaDataForUnknownExplicitMethod() throws Exception {
 		Class<?> clazz = ExplicitMethodNameTestCase.class;
@@ -176,7 +235,6 @@ static ExampleService explicit2() {
 
 	static class BaseTestCase {
 
-		@TestBean(methodName = "factory")
 		public String field;
 
 		static String factory() {