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 gh-33293
See gh-34597
See gh-34726

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

Author: sbrannen

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 within a context hierarchy.
+	 * <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 within a context hierarchy.
+	 * <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()
+	 */
+	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 within a context hierarchy.
+	 * <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()
+	 */
+	String contextName() default "";
+
 	/**
 	 * Extra interfaces that should also be declared by the mock.
 	 * <p>Defaults to none.

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

@@ -63,15 +63,15 @@ class MockitoBeanOverrideHandler extends AbstractMockitoBeanOverrideHandler {
 
 	MockitoBeanOverrideHandler(@Nullable Field field, ResolvableType typeToMock, MockitoBean mockitoBean) {
 		this(field, typeToMock, (!mockitoBean.name().isBlank() ? mockitoBean.name() : null),
-			(mockitoBean.enforceOverride() ? REPLACE : REPLACE_OR_CREATE),
-			mockitoBean.reset(), mockitoBean.extraInterfaces(), mockitoBean.answers(), mockitoBean.serializable());
+				mockitoBean.contextName(), (mockitoBean.enforceOverride() ? REPLACE : REPLACE_OR_CREATE),
+				mockitoBean.reset(), mockitoBean.extraInterfaces(), mockitoBean.answers(), mockitoBean.serializable());
 	}
 
 	private MockitoBeanOverrideHandler(@Nullable Field field, ResolvableType typeToMock, @Nullable String beanName,
-			BeanOverrideStrategy strategy, MockReset reset, Class<?>[] extraInterfaces, Answers answers,
-			boolean serializable) {
+			String contextName, BeanOverrideStrategy strategy, MockReset reset, Class<?>[] extraInterfaces,
+			Answers answers, boolean serializable) {
 
-		super(field, typeToMock, beanName, strategy, reset);
+		super(field, typeToMock, beanName, contextName, strategy, reset);
 		Assert.notNull(typeToMock, "'typeToMock' must not be null");
 		this.extraInterfaces = asClassSet(extraInterfaces);
 		this.answers = answers;
@@ -160,6 +160,7 @@ public String toString() {
 				.append("field", getField())
 				.append("beanType", getBeanType())
 				.append("beanName", getBeanName())
+				.append("contextName", getContextName())
 				.append("strategy", getStrategy())
 				.append("reset", getReset())
 				.append("extraInterfaces", getExtraInterfaces())

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

@@ -136,6 +136,19 @@
 	 */
 	Class<?>[] types() default {};
 
+	/**
+	 * The name of the context hierarchy level in which this {@code @MockitoSpyBean}
+	 * should be applied.
+	 * <p>Defaults to an empty string which indicates that this {@code @MockitoSpyBean}
+	 * should be applied to all application contexts within a context hierarchy.
+	 * <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()
+	 */
+	String contextName() default "";
+
 	/**
 	 * The reset mode to apply to the spied bean.
 	 * <p>The default is {@link MockReset#AFTER} meaning that spies are automatically

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

@@ -54,7 +54,7 @@ class MockitoSpyBeanOverrideHandler extends AbstractMockitoBeanOverrideHandler {
 
 	MockitoSpyBeanOverrideHandler(@Nullable Field field, ResolvableType typeToSpy, MockitoSpyBean spyBean) {
 		super(field, typeToSpy, (StringUtils.hasText(spyBean.name()) ? spyBean.name() : null),
-				BeanOverrideStrategy.WRAP, spyBean.reset());
+				spyBean.contextName(), BeanOverrideStrategy.WRAP, spyBean.reset());
 		Assert.notNull(typeToSpy, "typeToSpy must not be null");
 	}
 

spring-test/src/test/java/org/springframework/test/context/bean/override/BeanOverrideContextCustomizerFactoryTests.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.
@@ -16,12 +16,13 @@
 
 package org.springframework.test.context.bean.override;
 
-import java.util.Collections;
+import java.util.List;
 import java.util.function.Consumer;
 
 import org.junit.jupiter.api.Test;
 
 import org.springframework.lang.Nullable;
+import org.springframework.test.context.ContextConfigurationAttributes;
 import org.springframework.test.context.bean.override.DummyBean.DummyBeanOverrideProcessor.DummyBeanOverrideHandler;
 
 import static org.assertj.core.api.Assertions.assertThat;
@@ -92,7 +93,7 @@ private Consumer<BeanOverrideHandler> dummyHandler(@Nullable String beanName, Cl
 
 	@Nullable
 	private BeanOverrideContextCustomizer createContextCustomizer(Class<?> testClass) {
-		return this.factory.createContextCustomizer(testClass, Collections.emptyList());
+		return this.factory.createContextCustomizer(testClass, List.of(new ContextConfigurationAttributes(testClass)));
 	}
 
 

spring-test/src/test/java/org/springframework/test/context/bean/override/BeanOverrideContextCustomizerTestUtils.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.
@@ -16,10 +16,11 @@
 
 package org.springframework.test.context.bean.override;
 
-import java.util.Collections;
+import java.util.List;
 
 import org.springframework.context.ConfigurableApplicationContext;
 import org.springframework.lang.Nullable;
+import org.springframework.test.context.ContextConfigurationAttributes;
 import org.springframework.test.context.ContextCustomizer;
 import org.springframework.test.context.MergedContextConfiguration;
 
@@ -44,7 +45,7 @@ public abstract class BeanOverrideContextCustomizerTestUtils {
 	 */
 	@Nullable
 	public static ContextCustomizer createContextCustomizer(Class<?> testClass) {
-		return factory.createContextCustomizer(testClass, Collections.emptyList());
+		return factory.createContextCustomizer(testClass, List.of(new ContextConfigurationAttributes(testClass)));
 	}
 
 	/**