This version is still in development and is not considered stable yet. For the latest stable version, please use Spring Framework 7.0.8!

Bean Overriding in Tests

Bean overriding in tests refers to the ability to override specific beans in the ApplicationContext for a test class, by annotating the test class, one or more non-static fields in the test class, or one or more parameters in the constructor for the test class.

This feature is intended as a less risky alternative to the practice of registering a bean via @Bean with the DefaultListableBeanFactory setAllowBeanDefinitionOverriding flag set to true.

The Spring TestContext framework provides two sets of annotations for bean overriding.

The former relies purely on Spring, while the latter set relies on the Mockito third-party library.

Custom Bean Override Support

The three annotations mentioned above build upon the @BeanOverride meta-annotation and associated infrastructure, which allows one to define custom bean overriding variants.

To implement custom bean override support, the following is needed:

  • An annotation meta-annotated with @BeanOverride that defines the BeanOverrideProcessor to use

  • A custom BeanOverrideProcessor implementation

  • One or more concrete BeanOverrideHandler implementations created by the processor

The Spring TestContext framework includes implementations of the following APIs that support bean overriding and are responsible for setting up the rest of the infrastructure.

  • a BeanFactoryPostProcessor

  • a ContextCustomizerFactory

  • a TestExecutionListener

The spring-test module registers implementations of the latter two (BeanOverrideContextCustomizerFactory and BeanOverrideTestExecutionListener) in its META-INF/spring.factories properties file.

The bean overriding infrastructure searches for annotations on test classes, non-static fields in test classes, and parameters in test class constructors that are meta-annotated with @BeanOverride, and instantiates the corresponding BeanOverrideProcessor which is responsible for creating an appropriate BeanOverrideHandler.

The internal BeanOverrideBeanFactoryPostProcessor then uses bean override handlers to alter the test’s ApplicationContext by creating, replacing, or wrapping beans as defined by the corresponding BeanOverrideStrategy:

REPLACE

Replaces the bean. Throws an exception if a corresponding bean does not exist.

REPLACE_OR_CREATE

Replaces the bean if it exists. Creates a new bean if a corresponding bean does not exist.

WRAP

Retrieves the original bean and wraps it.

When replacing a non-singleton bean, the non-singleton bean will be replaced with a singleton bean corresponding to bean override instance created by the applicable BeanOverrideHandler, and the corresponding bean definition will be converted to a singleton. Consequently, if a handler overrides a prototype or scoped bean, the overridden bean will be treated as a singleton.

When replacing a bean created by a FactoryBean, the FactoryBean itself will be replaced with a singleton bean corresponding to bean override instance created by the applicable BeanOverrideHandler.

When wrapping a bean created by a FactoryBean, the object created by the FactoryBean will be wrapped, not the FactoryBean itself.

In contrast to Spring’s autowiring mechanism (for example, resolution of an @Autowired field), the bean overriding infrastructure in the TestContext framework has limited heuristics it can perform to locate a bean. Either the BeanOverrideProcessor can compute the name of the bean to override, or it can be unambiguously selected given the type of the annotated field and its qualifying annotations.

Typically, the bean is selected "by type" by the BeanOverrideFactoryPostProcessor. Alternatively, the user can directly provide the bean name in the custom annotation.

BeanOverrideProcessor implementations may also internally compute a bean name based on a convention or some other method.

Bean Overrides and Spring AOP Proxies

Beans in a Spring ApplicationContext are frequently wrapped in an AOP proxy — for example, to support @Transactional, @Cacheable, or @Retryable semantics. Whether an overridden bean retains such a proxy depends on the BeanOverrideStrategy used to create the override.

  • Overrides that use the REPLACE or REPLACE_OR_CREATE strategy (such as @TestBean and @MockitoBean) register their override instance directly as a manual singleton, which bypasses the container’s normal bean post-processing. Consequently, the override instance is a bare object: none of the AOP advice that would otherwise apply to the original bean (@Transactional, @Cacheable, @Retryable, method security, and so on) is present.

  • Overrides that use the WRAP strategy (such as @MockitoSpyBean) capture an early reference to the original bean and wrap it before the rest of the container’s post-processors — including the one responsible for creating AOP proxies — have run. Consequently, if the original bean would have been proxied, that proxy is still created, but with the override instance as its target rather than the original bean. The bean that ends up in the ApplicationContext, and that is injected into collaborating beans and test classes, is therefore a proxy wrapping the override instance, not the bare override instance itself.

This distinction has practical consequences when combining bean overrides with Mockito’s stubbing and verification APIs. See @MockitoSpyBean and Spring AOP Proxies for details.