Provide first-class support for Bean Overrides with @⁠ContextHierarchy

This commit provides first-class support for Bean Overrides
(@⁠MockitoBean, @⁠MockitoSpyBean, @⁠TestBean, etc.) with
@⁠ContextHierarchy.

Specifically, bean overrides can now specify which ApplicationContext
they target within the context hierarchy by configuring the
`contextName` attribute in the annotation. The `contextName` must match
a corresponding `name` configured via @⁠ContextConfiguration.

For example, the following test class configures the name of the second
hierarchy level to be "child" and simultaneously specifies that the
ExampleService should be wrapped in a Mockito spy in the context named
"child". Consequently, Spring will only attempt to create the spy in
the "child" context and will not attempt to create the spy in the
parent context.

@ExtendWith(SpringExtension.class)
@ContextHierarchy({
    @ContextConfiguration(classes = Config1.class),
    @ContextConfiguration(classes = Config2.class, name = "child")
})
class MockitoSpyBeanContextHierarchyTests {

    @MockitoSpyBean(contextName = "child")
    ExampleService service;

    // ...
}

See spring-projectsgh-33293
See spring-projectsgh-34597
See spring-projectsgh-34726

Signed-off-by: Sam Brannen <104798+sbrannen@users.noreply.github.com>

Author: sbrannen

spring-test/src/main/java/org/springframework/test/context/ContextConfiguration.java

@@ -292,13 +292,18 @@
 	 * <p>If not specified the name will be inferred based on the numerical level
 	 * within all declared contexts within the hierarchy.
 	 * <p>This attribute is only applicable when used within a test class hierarchy
-	 * or enclosing class hierarchy that is configured using
-	 * {@code @ContextHierarchy}, in which case the name can be used for
-	 * <em>merging</em> or <em>overriding</em> this configuration with configuration
-	 * of the same name in hierarchy levels defined in superclasses or enclosing
-	 * classes. See the Javadoc for {@link ContextHierarchy @ContextHierarchy} for
-	 * details.
+	 * or enclosing class hierarchy that is configured using {@code @ContextHierarchy},
+	 * in which case the name can be used for <em>merging</em> or <em>overriding</em>
+	 * this configuration with configuration of the same name in hierarchy levels
+	 * defined in superclasses or enclosing classes. As of Spring Framework 6.2.6,
+	 * the name can also be used to identify the configuration in which a
+	 * <em>Bean Override</em> should be applied &mdash; for example,
+	 * {@code @MockitoBean(contextName = "child")}. See the Javadoc for
+	 * {@link ContextHierarchy @ContextHierarchy} for details.
 	 * @since 3.2.2
+	 * @see org.springframework.test.context.bean.override.mockito.MockitoBean#contextName @MockitoBean(contextName = ...)
+	 * @see org.springframework.test.context.bean.override.mockito.MockitoSpyBean#contextName @MockitoSpyBean(contextName = ...)
+	 * @see org.springframework.test.context.bean.override.convention.TestBean#contextName @TestBean(contextName = ...)
 	 */
 	String name() default "";
 

spring-test/src/main/java/org/springframework/test/context/ContextHierarchy.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2024 the original author or authors.
+ * Copyright 2002-2025 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.
@@ -29,10 +29,12 @@
  * ApplicationContexts} for integration tests.
  *
  * <h3>Examples</h3>
+ *
  * <p>The following JUnit-based examples demonstrate common configuration
  * scenarios for integration tests that require the use of context hierarchies.
  *
  * <h4>Single Test Class with Context Hierarchy</h4>
+ *
  * <p>{@code ControllerIntegrationTests} represents a typical integration testing
  * scenario for a Spring MVC web application by declaring a context hierarchy
  * consisting of two levels, one for the <em>root</em> {@code WebApplicationContext}
@@ -57,6 +59,7 @@
  * }</pre>
  *
  * <h4>Class Hierarchy with Implicit Parent Context</h4>
+ *
  * <p>The following test classes define a context hierarchy within a test class
  * hierarchy. {@code AbstractWebTests} declares the configuration for a root
  * {@code WebApplicationContext} in a Spring-powered web application. Note,
@@ -83,12 +86,13 @@
  * public class RestWebServiceTests extends AbstractWebTests {}</pre>
  *
  * <h4>Class Hierarchy with Merged Context Hierarchy Configuration</h4>
+ *
  * <p>The following classes demonstrate the use of <em>named</em> hierarchy levels
  * in order to <em>merge</em> the configuration for specific levels in a context
- * hierarchy. {@code BaseTests} defines two levels in the hierarchy, {@code parent}
- * and {@code child}. {@code ExtendedTests} extends {@code BaseTests} and instructs
+ * hierarchy. {@code BaseTests} defines two levels in the hierarchy, {@code "parent"}
+ * and {@code "child"}. {@code ExtendedTests} extends {@code BaseTests} and instructs
  * the Spring TestContext Framework to merge the context configuration for the
- * {@code child} hierarchy level, simply by ensuring that the names declared via
+ * {@code "child"} hierarchy level, simply by ensuring that the names declared via
  * {@link ContextConfiguration#name} are both {@code "child"}. The result is that
  * three application contexts will be loaded: one for {@code "/app-config.xml"},
  * one for {@code "/user-config.xml"}, and one for <code>{"/user-config.xml",
@@ -111,6 +115,7 @@
  * public class ExtendedTests extends BaseTests {}</pre>
  *
  * <h4>Class Hierarchy with Overridden Context Hierarchy Configuration</h4>
+ *
  * <p>In contrast to the previous example, this example demonstrates how to
  * <em>override</em> the configuration for a given named level in a context hierarchy
  * by setting the {@link ContextConfiguration#inheritLocations} flag to {@code false}.
@@ -131,6 +136,38 @@
  * )
  * public class ExtendedTests extends BaseTests {}</pre>
  *
+ * <h4>Class Hierarchies with Bean Overrides</h4>
+ *
+ * <p>When {@code @ContextHierarchy} is used in conjunction with bean overrides such as
+ * {@link org.springframework.test.context.bean.override.convention.TestBean @TestBean},
+ * {@link org.springframework.test.context.bean.override.mockito.MockitoBean @MockitoBean}, or
+ * {@link org.springframework.test.context.bean.override.mockito.MockitoSpyBean @MockitoSpyBean},
+ * it may be desirable or necessary to have the override applied to a single level
+ * in the context hierarchy. To achieve that, the bean override must specify a
+ * context name that matches a name configured via {@link ContextConfiguration#name}.
+ *
+ * <p>The following test class configures the name of the second hierarchy level to be
+ * {@code "user-config"} and simultaneously specifies that the {@code UserService} should
+ * be wrapped in a Mockito spy in the context named {@code "user-config"}. Consequently,
+ * Spring will only attempt to create the spy in the {@code "user-config"} context and will
+ * not attempt to create the spy in the parent context.
+ *
+ * <pre class="code">
+ * &#064;ExtendWith(SpringExtension.class)
+ * &#064;ContextHierarchy({
+ *     &#064;ContextConfiguration(classes = AppConfig.class),
+ *     &#064;ContextConfiguration(classes = UserConfig.class, name = "user-config")
+ * })
+ * class IntegrationTests {
+ *
+ *     &#064;MockitoSpyBean(contextName = "user-config")
+ *     UserService userService;
+ *
+ *     // ...
+ * }</pre>
+ *
+ * <h4>Miscellaneous</h4>
+ *
  * <p>This annotation may be used as a <em>meta-annotation</em> to create custom
  * <em>composed annotations</em>.
  *

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

@@ -42,19 +42,25 @@ class BeanOverrideContextCustomizerFactory implements ContextCustomizerFactory {
 	public BeanOverrideContextCustomizer createContextCustomizer(Class<?> testClass,
 			List<ContextConfigurationAttributes> configAttributes) {
 
+		// Base the context name on the "closest" @ContextConfiguration declaration
+		// within the type and enclosing class hierarchies of the test class.
+		String contextName = configAttributes.get(0).getName();
 		Set<BeanOverrideHandler> handlers = new LinkedHashSet<>();
-		findBeanOverrideHandlers(testClass, handlers);
+		findBeanOverrideHandlers(testClass, contextName, handlers);
 		if (handlers.isEmpty()) {
 			return null;
 		}
 		return new BeanOverrideContextCustomizer(handlers);
 	}
 
-	private void findBeanOverrideHandlers(Class<?> testClass, Set<BeanOverrideHandler> handlers) {
-		BeanOverrideHandler.findAllHandlers(testClass).forEach(handler ->
-				Assert.state(handlers.add(handler), () ->
-						"Duplicate BeanOverrideHandler discovered in test class %s: %s"
-							.formatted(testClass.getName(), handler)));
+	private void findBeanOverrideHandlers(Class<?> testClass, @Nullable String contextName, Set<BeanOverrideHandler> handlers) {
+		BeanOverrideHandler.findAllHandlers(testClass).stream()
+				// If a handler does not specify a context name, it always gets applied.
+				// Otherwise, the handler's context name must match the current context name.
+				.filter(handler -> handler.getContextName().isEmpty() || handler.getContextName().equals(contextName))
+				.forEach(handler -> Assert.state(handlers.add(handler),
+						() -> "Duplicate BeanOverrideHandler discovered in test class %s: %s"
+								.formatted(testClass.getName(), handler)));
 	}
 
 }

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

@@ -87,11 +87,17 @@ public abstract class BeanOverrideHandler {
 	@Nullable
 	private final String beanName;
 
+	private final String contextName;
+
 	private final BeanOverrideStrategy strategy;
 
 
 	/**
 	 * Construct a new {@code BeanOverrideHandler} from the supplied values.
+	 * <p>To provide proper support for
+	 * {@link org.springframework.test.context.ContextHierarchy @ContextHierarchy},
+	 * invoke {@link #BeanOverrideHandler(Field, ResolvableType, String, String, BeanOverrideStrategy)}
+	 * instead.
 	 * @param field the {@link Field} annotated with {@link BeanOverride @BeanOverride},
 	 * or {@code null} if {@code @BeanOverride} was declared at the type level
 	 * @param beanType the {@linkplain ResolvableType type} of bean to override
@@ -102,11 +108,31 @@ public abstract class BeanOverrideHandler {
 	protected BeanOverrideHandler(@Nullable Field field, ResolvableType beanType, @Nullable String beanName,
 			BeanOverrideStrategy strategy) {
 
+		this(field, beanType, beanName, "", strategy);
+	}
+
+	/**
+	 * Construct a new {@code BeanOverrideHandler} from the supplied values.
+	 * @param field the {@link Field} annotated with {@link BeanOverride @BeanOverride},
+	 * or {@code null} if {@code @BeanOverride} was declared at the type level
+	 * @param beanType the {@linkplain ResolvableType type} of bean to override
+	 * @param beanName the name of the bean to override, or {@code null} to look
+	 * for a single matching bean by type
+	 * @param contextName the name of the context hierarchy level in which the
+	 * handler should be applied, or an empty string to indicate that the handler
+	 * should be applied to all application contexts within a context hierarchy
+	 * @param strategy the {@link BeanOverrideStrategy} to use
+	 * @since 6.2.6
+	 */
+	protected BeanOverrideHandler(@Nullable Field field, ResolvableType beanType, @Nullable String beanName,
+			String contextName, BeanOverrideStrategy strategy) {
+
 		this.field = field;
 		this.qualifierAnnotations = getQualifierAnnotations(field);
 		this.beanType = beanType;
 		this.beanName = beanName;
 		this.strategy = strategy;
+		this.contextName = contextName;
 	}
 
 	/**
@@ -247,6 +273,21 @@ public final String getBeanName() {
 		return this.beanName;
 	}
 
+	/**
+	 * Get the name of the context hierarchy level in which this handler should
+	 * be applied.
+	 * <p>An empty string indicates that this handler should be applied to all
+	 * application contexts.
+	 * <p>If a context name is configured for this handler, it must match a name
+	 * configured via {@code @ContextConfiguration(name=...)}.
+	 * @since 6.2.6
+	 * @see org.springframework.test.context.ContextHierarchy @ContextHierarchy
+	 * @see org.springframework.test.context.ContextConfiguration#name()
+	 */
+	public final String getContextName() {
+		return this.contextName;
+	}
+
 	/**
 	 * Get the {@link BeanOverrideStrategy} for this {@code BeanOverrideHandler},
 	 * which influences how and when the bean override instance should be created.
@@ -320,6 +361,7 @@ public boolean equals(Object other) {
 		BeanOverrideHandler that = (BeanOverrideHandler) other;
 		if (!Objects.equals(this.beanType.getType(), that.beanType.getType()) ||
 				!Objects.equals(this.beanName, that.beanName) ||
+				!Objects.equals(this.contextName, that.contextName) ||
 				!Objects.equals(this.strategy, that.strategy)) {
 			return false;
 		}
@@ -339,7 +381,7 @@ public boolean equals(Object other) {
 
 	@Override
 	public int hashCode() {
-		int hash = Objects.hash(getClass(), this.beanType.getType(), this.beanName, this.strategy);
+		int hash = Objects.hash(getClass(), this.beanType.getType(), this.beanName, this.contextName, this.strategy);
 		return (this.beanName != null ? hash : hash +
 				Objects.hash((this.field != null ? this.field.getName() : null), this.qualifierAnnotations));
 	}
@@ -350,6 +392,7 @@ public String toString() {
 				.append("field", this.field)
 				.append("beanType", this.beanType)
 				.append("beanName", this.beanName)
+				.append("contextName", this.contextName)
 				.append("strategy", this.strategy)
 				.toString();
 	}

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

@@ -24,15 +24,22 @@
 import org.apache.commons.logging.Log;
 import org.apache.commons.logging.LogFactory;
 
+import org.springframework.beans.factory.BeanFactory;
 import org.springframework.beans.factory.config.ConfigurableBeanFactory;
 import org.springframework.lang.Nullable;
 import org.springframework.util.Assert;
 
+import static org.springframework.test.context.bean.override.BeanOverrideContextCustomizer.REGISTRY_BEAN_NAME;
+
 /**
  * An internal class used to track {@link BeanOverrideHandler}-related state after
  * the bean factory has been processed and to provide lookup facilities to test
  * execution listeners.
  *
+ * <p>As of Spring Framework 6.2.6, {@code BeanOverrideRegistry} is hierarchical
+ * and has access to a potential parent in order to provide first-class support
+ * for {@link org.springframework.test.context.ContextHierarchy @ContextHierarchy}.
+ *
  * @author Simon Baslé
  * @author Sam Brannen
  * @since 6.2
@@ -48,10 +55,16 @@ class BeanOverrideRegistry {
 
 	private final ConfigurableBeanFactory beanFactory;
 
+	@Nullable
+	private final BeanOverrideRegistry parent;
+
 
 	BeanOverrideRegistry(ConfigurableBeanFactory beanFactory) {
 		Assert.notNull(beanFactory, "ConfigurableBeanFactory must not be null");
 		this.beanFactory = beanFactory;
+		BeanFactory parentBeanFactory = beanFactory.getParentBeanFactory();
+		this.parent = (parentBeanFactory != null && parentBeanFactory.containsBean(REGISTRY_BEAN_NAME) ?
+				parentBeanFactory.getBean(REGISTRY_BEAN_NAME, BeanOverrideRegistry.class) : null);
 	}
 
 	/**
@@ -110,7 +123,7 @@ Object wrapBeanIfNecessary(Object bean, String beanName) {
 	 * @param handler the {@code BeanOverrideHandler} that created the bean
 	 * @param requiredType the required bean type
 	 * @return the bean instance, or {@code null} if the provided handler is not
-	 * registered in this registry
+	 * registered in this registry or a parent registry
 	 * @since 6.2.6
 	 * @see #registerBeanOverrideHandler(BeanOverrideHandler, String)
 	 */
@@ -120,6 +133,9 @@ Object getBeanForHandler(BeanOverrideHandler handler, Class<?> requiredType) {
 		if (beanName != null) {
 			return this.beanFactory.getBean(beanName, requiredType);
 		}
+		if (this.parent != null) {
+			return this.parent.getBeanForHandler(handler, requiredType);
+		}
 		return null;
 	}
 

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

@@ -164,6 +164,19 @@
 	 */
 	String methodName() default "";
 
+	/**
+	 * The name of the context hierarchy level in which this {@code @TestBean}
+	 * should be applied.
+	 * <p>Defaults to an empty string which indicates that this {@code @TestBean}
+	 * should be applied to all application contexts.
+	 * <p>If a context name is configured, it must match a name configured via
+	 * {@code @ContextConfiguration(name=...)}.
+	 * @since 6.2.6
+	 * @see org.springframework.test.context.ContextHierarchy @ContextHierarchy
+	 * @see org.springframework.test.context.ContextConfiguration#name() @ContextConfiguration(name=...)
+	 */
+	String contextName() default "";
+
 	/**
 	 * Whether to require the existence of the bean being overridden.
 	 * <p>Defaults to {@code false} which means that a bean will be created if a

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

@@ -43,9 +43,9 @@ final class TestBeanOverrideHandler extends BeanOverrideHandler {
 
 
 	TestBeanOverrideHandler(Field field, ResolvableType beanType, @Nullable String beanName,
-			BeanOverrideStrategy strategy, Method factoryMethod) {
+			String contextName, BeanOverrideStrategy strategy, Method factoryMethod) {
 
-		super(field, beanType, beanName, strategy);
+		super(field, beanType, beanName, contextName, strategy);
 		this.factoryMethod = factoryMethod;
 	}
 
@@ -90,6 +90,7 @@ public String toString() {
 				.append("field", getField())
 				.append("beanType", getBeanType())
 				.append("beanName", getBeanName())
+				.append("contextName", getContextName())
 				.append("strategy", getStrategy())
 				.append("factoryMethod", this.factoryMethod)
 				.toString();

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

@@ -82,7 +82,7 @@ public TestBeanOverrideHandler createHandler(Annotation overrideAnnotation, Clas
 		}
 
 		return new TestBeanOverrideHandler(
-				field, ResolvableType.forField(field, testClass), beanName, strategy, factoryMethod);
+				field, ResolvableType.forField(field, testClass), beanName, testBean.contextName(), strategy, factoryMethod);
 	}
 
 	/**

spring-test/src/main/java/org/springframework/test/context/bean/override/mockito/AbstractMockitoBeanOverrideHandler.java

@@ -39,9 +39,10 @@ abstract class AbstractMockitoBeanOverrideHandler extends BeanOverrideHandler {
 
 
 	protected AbstractMockitoBeanOverrideHandler(@Nullable Field field, ResolvableType beanType,
-			@Nullable String beanName, BeanOverrideStrategy strategy, MockReset reset) {
+			@Nullable String beanName, String contextName, BeanOverrideStrategy strategy,
+			MockReset reset) {
 
-		super(field, beanType, beanName, strategy);
+		super(field, beanType, beanName, contextName, strategy);
 		this.reset = (reset != null ? reset : MockReset.AFTER);
 	}
 
@@ -92,6 +93,7 @@ public String toString() {
 				.append("field", getField())
 				.append("beanType", getBeanType())
 				.append("beanName", getBeanName())
+				.append("contextName", getContextName())
 				.append("strategy", getStrategy())
 				.append("reset", getReset())
 				.toString();

spring-test/src/main/java/org/springframework/test/context/bean/override/mockito/MockitoBean.java

@@ -144,6 +144,19 @@
 	 */
 	Class<?>[] types() default {};
 
+	/**
+	 * The name of the context hierarchy level in which this {@code @MockitoBean}
+	 * should be applied.
+	 * <p>Defaults to an empty string which indicates that this {@code @MockitoBean}
+	 * should be applied to all application contexts.
+	 * <p>If a context name is configured, it must match a name configured via
+	 * {@code @ContextConfiguration(name=...)}.
+	 * @since 6.2.6
+	 * @see org.springframework.test.context.ContextHierarchy @ContextHierarchy
+	 * @see org.springframework.test.context.ContextConfiguration#name() @ContextConfiguration(name=...)
+	 */
+	String contextName() default "";
+
 	/**
 	 * Extra interfaces that should also be declared by the mock.
 	 * <p>Defaults to none.