|
1 | | -[[spring-testing-beanoverriding]] |
| 1 | +[[testcontext-bean-overriding]] |
2 | 2 | = Bean Overriding in Tests |
3 | 3 |
|
4 | | -Bean Overriding in Tests refers to the ability to override specific beans in the Context |
5 | | -for a test class, by annotating one or more fields in said test class. |
| 4 | +Bean overriding in tests refers to the ability to override specific beans in the |
| 5 | +`ApplicationContext` for a test class, by annotating one or more fields in the test class. |
6 | 6 |
|
7 | | -NOTE: This is intended as a less risky alternative to the practice of registering a bean via |
8 | | -`@Bean` with the `DefaultListableBeanFactory` `setAllowBeanDefinitionOverriding` set to |
9 | | -`true`. |
| 7 | +NOTE: This feature is intended as a less risky alternative to the practice of registering |
| 8 | +a bean via `@Bean` with the `DefaultListableBeanFactory` |
| 9 | +`setAllowBeanDefinitionOverriding` flag set to `true`. |
10 | 10 |
|
11 | | -The Spring Testing Framework provides two sets of annotations: |
12 | | -xref:testing/annotations/integration-spring/annotation-testbean.adoc[`@TestBean`], |
13 | | -xref:testing/annotations/integration-spring/annotation-mockitobean.adoc[`@MockitoBean` and |
14 | | -`@MockitoSpyBean`]. The former relies purely on Spring, while the later set relies on |
15 | | -the https://site.mockito.org/[Mockito] third party library. |
| 11 | +The Spring TestContext framework provides two sets of annotations for bean overriding. |
16 | 12 |
|
17 | | -[[spring-testing-beanoverriding-extending]] |
18 | | -== Extending bean override with a custom annotation |
| 13 | +* xref:testing/annotations/integration-spring/annotation-testbean.adoc[`@TestBean`] |
| 14 | +* xref:testing/annotations/integration-spring/annotation-mockitobean.adoc[`@MockitoBean` and `@MockitoSpyBean`] |
19 | 15 |
|
20 | | -The three annotations mentioned above build upon the `@BeanOverride` meta-annotation |
21 | | -and associated infrastructure, which allows to define custom bean overriding variants. |
| 16 | +The former relies purely on Spring, while the latter set relies on the |
| 17 | +https://site.mockito.org/[Mockito] third-party library. |
22 | 18 |
|
23 | | -To create an extension, the following is needed: |
| 19 | +[[testcontext-bean-overriding-custom]] |
| 20 | +== Custom Bean Override Support |
24 | 21 |
|
25 | | -- An annotation meta-annotated with `@BeanOverride` that defines the |
26 | | -`BeanOverrideProcessor` to use. |
27 | | -- The `BeanOverrideProcessor` implementation itself. |
28 | | -- One or more concrete `OverrideMetadata` implementations provided by the processor. |
| 22 | +The three annotations mentioned above build upon the `@BeanOverride` meta-annotation and |
| 23 | +associated infrastructure, which allows one to define custom bean overriding variants. |
29 | 24 |
|
30 | | -The Spring TestContext Framework includes infrastructure classes that support bean |
31 | | -overriding: a `BeanFactoryPostProcessor`, a `TestExecutionListener` and a |
32 | | -`ContextCustomizerFactory`. |
33 | | -The later two are automatically registered via the Spring TestContext Framework |
34 | | -`spring.factories` file, and are responsible for setting up the rest of the infrastructure. |
| 25 | +To create custom bean override support, the following is needed: |
35 | 26 |
|
36 | | -The test classes are parsed looking for any field meta-annotated with `@BeanOverride`, |
37 | | -instantiating the relevant `BeanOverrideProcessor` in order to register an |
38 | | -`OverrideMetadata`. |
| 27 | +* An annotation meta-annotated with `@BeanOverride` that defines the |
| 28 | + `BeanOverrideProcessor` to use |
| 29 | +* A custom `BeanOverrideProcessor` implementation |
| 30 | +* One or more concrete `OverrideMetadata` implementations provided by the processor |
39 | 31 |
|
40 | | -Then the `BeanOverrideBeanFactoryPostProcessor` will use that information to alter the |
41 | | -context, registering and replacing bean definitions as defined by each metadata |
42 | | -`BeanOverrideStrategy`: |
| 32 | +The Spring TestContext framework includes implementations of the following APIs that |
| 33 | +support bean overriding and are responsible for setting up the rest of the infrastructure. |
43 | 34 |
|
44 | | -- `REPLACE_DEFINITION`: replaces the bean definition. If it is not present in the |
45 | | -context, an exception is thrown. |
46 | | -- `CREATE_OR_REPLACE_DEFINITION`: replaces the bean definition if the bean definition |
47 | | -does not exist, or create one if it is not. |
48 | | -- `WRAP_BEAN`: get the original instance early so that it can be wrapped. |
| 35 | +* a `BeanFactoryPostProcessor` |
| 36 | +* a `ContextCustomizerFactory` |
| 37 | +* a `TestExecutionListener` |
49 | 38 |
|
50 | | -NOTE: The Bean Overriding infrastructure does not include any bean resolution step, |
51 | | -unlike an `@Autowired`-annotated field for instance. As such, the name of the bean to |
52 | | -override must be somehow provided to or computed by the `BeanOverrideProcessor`. |
53 | | -Typically, the user provides the name one way or the other. |
| 39 | +The `spring-test` module registers implementations of the latter two |
| 40 | +(`BeanOverrideContextCustomizerFactory` and `BeanOverrideTestExecutionListener`) in its |
| 41 | +{spring-framework-code}/spring-test/src/main/resources/META-INF/spring.factories[`META-INF/spring.factories` |
| 42 | +properties file]. |
| 43 | + |
| 44 | +The bean overriding infrastructure searches in test classes for any field meta-annotated |
| 45 | +with `@BeanOverride` and instantiates the corresponding `BeanOverrideProcessor` which is |
| 46 | +responsible for registering appropriate `OverrideMetadata`. |
| 47 | + |
| 48 | +The internal `BeanOverrideBeanFactoryPostProcessor` then uses that information to alter |
| 49 | +the test's `ApplicationContext` by registering and replacing bean definitions as defined |
| 50 | +by the corresponding `BeanOverrideStrategy`: |
| 51 | + |
| 52 | +* `REPLACE_DEFINITION`: Replaces the bean definition. Throws an exception if a |
| 53 | + corresponding bean definition does not exist. |
| 54 | +* `REPLACE_OR_CREATE_DEFINITION`: Replaces the bean definition if it exists. Creates a |
| 55 | + new bean definition if a corresponding bean definition does not exist. |
| 56 | +* `WRAP_BEAN`: Retrieves the original bean instance and wraps it. |
| 57 | + |
| 58 | +[NOTE] |
| 59 | +==== |
| 60 | +In contrast to Spring's autowiring mechanism (for example, resolution of an `@Autowired` |
| 61 | +field), the bean overriding infrastructure in the TestContext framework does not perform |
| 62 | +any heuristics to locate a bean. Instead, the name of the bean to override must be |
| 63 | +explicitly provided to or computed by the `BeanOverrideProcessor`. |
| 64 | +
|
| 65 | +Typically, the user provides the bean name via a custom annotation, or the |
| 66 | +`BeanOverrideProcessor` determines the bean name based on some convention. |
| 67 | +==== |
0 commit comments