Polish "Bean Overriding in Tests" support
This commit is contained in:
Sam Brannen
@@ -134,13 +134,13 @@
|
||||
**** xref:testing/testcontext-framework/ctx-management/failure-threshold.adoc[]
|
||||
**** xref:testing/testcontext-framework/ctx-management/hierarchies.adoc[]
|
||||
*** xref:testing/testcontext-framework/fixture-di.adoc[]
|
||||
*** xref:testing/testcontext-framework/bean-overriding.adoc[]
|
||||
*** xref:testing/testcontext-framework/web-scoped-beans.adoc[]
|
||||
*** xref:testing/testcontext-framework/tx.adoc[]
|
||||
*** xref:testing/testcontext-framework/executing-sql.adoc[]
|
||||
*** xref:testing/testcontext-framework/parallel-test-execution.adoc[]
|
||||
*** xref:testing/testcontext-framework/support-classes.adoc[]
|
||||
*** xref:testing/testcontext-framework/aot.adoc[]
|
||||
*** xref:testing/testcontext-framework/bean-overriding.adoc[]
|
||||
** xref:testing/webtestclient.adoc[]
|
||||
** xref:testing/spring-mvc-test-framework.adoc[]
|
||||
*** xref:testing/spring-mvc-test-framework/server.adoc[]
|
||||
@@ -172,6 +172,8 @@
|
||||
***** xref:testing/annotations/integration-spring/annotation-activeprofiles.adoc[]
|
||||
***** xref:testing/annotations/integration-spring/annotation-testpropertysource.adoc[]
|
||||
***** xref:testing/annotations/integration-spring/annotation-dynamicpropertysource.adoc[]
|
||||
***** xref:testing/annotations/integration-spring/annotation-testbean.adoc[]
|
||||
***** xref:testing/annotations/integration-spring/annotation-mockitobean.adoc[]
|
||||
***** xref:testing/annotations/integration-spring/annotation-dirtiescontext.adoc[]
|
||||
***** xref:testing/annotations/integration-spring/annotation-testexecutionlisteners.adoc[]
|
||||
***** xref:testing/annotations/integration-spring/annotation-recordapplicationevents.adoc[]
|
||||
@@ -184,8 +186,6 @@
|
||||
***** xref:testing/annotations/integration-spring/annotation-sqlmergemode.adoc[]
|
||||
***** xref:testing/annotations/integration-spring/annotation-sqlgroup.adoc[]
|
||||
***** xref:testing/annotations/integration-spring/annotation-disabledinaotmode.adoc[]
|
||||
***** xref:testing/annotations/integration-spring/annotation-testbean.adoc[]
|
||||
***** xref:testing/annotations/integration-spring/annotation-mockitobean.adoc[]
|
||||
**** xref:testing/annotations/integration-junit4.adoc[]
|
||||
**** xref:testing/annotations/integration-junit-jupiter.adoc[]
|
||||
**** xref:testing/annotations/integration-meta.adoc[]
|
||||
|
||||
@@ -16,6 +16,8 @@ Spring's testing annotations include the following:
|
||||
* xref:testing/annotations/integration-spring/annotation-activeprofiles.adoc[`@ActiveProfiles`]
|
||||
* xref:testing/annotations/integration-spring/annotation-testpropertysource.adoc[`@TestPropertySource`]
|
||||
* xref:testing/annotations/integration-spring/annotation-dynamicpropertysource.adoc[`@DynamicPropertySource`]
|
||||
* xref:testing/annotations/integration-spring/annotation-testbean.adoc[`@TestBean`]
|
||||
* xref:testing/annotations/integration-spring/annotation-mockitobean.adoc[`@MockitoBean` and `@MockitoSpyBean`]
|
||||
* xref:testing/annotations/integration-spring/annotation-dirtiescontext.adoc[`@DirtiesContext`]
|
||||
* xref:testing/annotations/integration-spring/annotation-testexecutionlisteners.adoc[`@TestExecutionListeners`]
|
||||
* xref:testing/annotations/integration-spring/annotation-recordapplicationevents.adoc[`@RecordApplicationEvents`]
|
||||
@@ -28,6 +30,4 @@ Spring's testing annotations include the following:
|
||||
* xref:testing/annotations/integration-spring/annotation-sqlmergemode.adoc[`@SqlMergeMode`]
|
||||
* xref:testing/annotations/integration-spring/annotation-sqlgroup.adoc[`@SqlGroup`]
|
||||
* xref:testing/annotations/integration-spring/annotation-disabledinaotmode.adoc[`@DisabledInAotMode`]
|
||||
* xref:testing/annotations/integration-spring/annotation-testbean.adoc[`@TestBean`]
|
||||
* xref:testing/annotations/integration-spring/annotation-mockitobean.adoc[`@MockitoBean` and `@MockitoSpyBean`]
|
||||
|
||||
|
||||
@@ -1,24 +1,24 @@
|
||||
[[spring-testing-annotation-beanoverriding-mockitobean]]
|
||||
= `@MockitoBean` and `@MockitoSpyBean`
|
||||
|
||||
`@MockitoBean` and `@MockitoSpyBean` are used on a test class field to override a bean
|
||||
with a mocking and spying instance, respectively. In the later case, the original bean
|
||||
definition is not replaced but instead an early instance is captured and wrapped by the
|
||||
spy.
|
||||
`@MockitoBean` and `@MockitoSpyBean` are used on test class fields to override beans in
|
||||
the test's `ApplicationContext` with a Mockito mock or spy, respectively. In the latter
|
||||
case, the original bean definition is not replaced, but instead an early instance of the
|
||||
bean is captured and wrapped by the spy.
|
||||
|
||||
By default, the name of the bean to override is derived from the annotated field's name,
|
||||
but both annotations allows for a specific `name` to be provided. Each annotation also
|
||||
but both annotations allow for a specific `name` to be provided. Each annotation also
|
||||
defines Mockito-specific attributes to fine-tune the mocking details.
|
||||
|
||||
The `@MockitoBean` annotation uses the `CREATE_OR_REPLACE_DEFINITION`
|
||||
The `@MockitoBean` annotation uses the `REPLACE_OR_CREATE_DEFINITION`
|
||||
xref:testing/testcontext-framework/bean-overriding.adoc#spring-testing-beanoverriding-extending[strategy for test bean overriding].
|
||||
|
||||
The `@MockitoSpyBean` annotation uses the `WRAP_EARLY_BEAN`
|
||||
xref:testing/testcontext-framework/bean-overriding.adoc#spring-testing-beanoverriding-extending[strategy]
|
||||
The `@MockitoSpyBean` annotation uses the `WRAP_BEAN`
|
||||
xref:testing/testcontext-framework/bean-overriding.adoc#spring-testing-beanoverriding-extending[strategy],
|
||||
and the original instance is wrapped in a Mockito spy.
|
||||
|
||||
The following example shows how to configure the bean name for both `@MockitoBean` and
|
||||
`@MockitoSpyBean` annotations:
|
||||
The following example shows how to configure the bean name via `@MockitoBean` and
|
||||
`@MockitoSpyBean`:
|
||||
|
||||
[tabs]
|
||||
======
|
||||
@@ -27,6 +27,7 @@ Java::
|
||||
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
|
||||
----
|
||||
class OverrideBeanTests {
|
||||
|
||||
@MockitoBean(name = "service1") // <1>
|
||||
private CustomService mockService;
|
||||
|
||||
@@ -36,7 +37,7 @@ Java::
|
||||
// test case body...
|
||||
}
|
||||
----
|
||||
<1> Mark `mockService` as a Mockito mock override of bean `service1` in this test class
|
||||
<2> Mark `spyService` as a Mockito spy override of bean `service2` in this test class
|
||||
<3> Both fields will be injected with the Mockito values (the mock and the spy respectively)
|
||||
======
|
||||
<1> Mark `mockService` as a Mockito mock override of bean `service1` in this test class.
|
||||
<2> Mark `spyService` as a Mockito spy override of bean `service2` in this test class.
|
||||
<3> The fields will be injected with the Mockito mock and spy, respectively.
|
||||
======
|
||||
|
||||
@@ -1,17 +1,18 @@
|
||||
[[spring-testing-annotation-beanoverriding-testbean]]
|
||||
= `@TestBean`
|
||||
|
||||
`@TestBean` is used on a test class field to override a specific bean with an instance
|
||||
provided by a conventionally named static factory method.
|
||||
`@TestBean` is used on a test class field to override a specific bean in the test's
|
||||
`ApplicationContext` with an instance provided by a conventionally named static factory
|
||||
method.
|
||||
|
||||
By default, the bean name and the associated factory method name are derived from the
|
||||
annotated field's name but the annotation allows for specific values to be provided.
|
||||
annotated field's name, but the annotation allows for specific values to be provided.
|
||||
|
||||
The `@TestBean` annotation uses the `REPLACE_DEFINITION`
|
||||
xref:testing/testcontext-framework/bean-overriding.adoc#spring-testing-beanoverriding-extending[strategy for test bean overriding].
|
||||
|
||||
The following example shows how to fully configure the `@TestBean` annotation, with
|
||||
explicit values equivalent to the default:
|
||||
explicit values equivalent to the defaults:
|
||||
|
||||
[tabs]
|
||||
======
|
||||
@@ -30,10 +31,9 @@ Java::
|
||||
}
|
||||
}
|
||||
----
|
||||
<1> Mark a field for bean overriding in this test class
|
||||
<2> The result of this static method will be used as the instance and injected into the field
|
||||
<1> Mark a field for bean overriding in this test class.
|
||||
<2> The result of this static method will be used as the instance and injected into the field.
|
||||
======
|
||||
|
||||
NOTE: The method to invoke is searched in the test class and any enclosing class it might
|
||||
have, as well as its hierarchy. This typically allows nested test class to rely on the
|
||||
factory method in the root 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.
|
||||
|
||||
@@ -1,53 +1,67 @@
|
||||
[[spring-testing-beanoverriding]]
|
||||
[[testcontext-bean-overriding]]
|
||||
= Bean Overriding in Tests
|
||||
|
||||
Bean Overriding in Tests refers to the ability to override specific beans in the Context
|
||||
for a test class, by annotating one or more fields in said test class.
|
||||
Bean overriding in tests refers to the ability to override specific beans in the
|
||||
`ApplicationContext` for a test class, by annotating one or more fields in the test class.
|
||||
|
||||
NOTE: This is intended as a less risky alternative to the practice of registering a bean via
|
||||
`@Bean` with the `DefaultListableBeanFactory` `setAllowBeanDefinitionOverriding` set to
|
||||
`true`.
|
||||
NOTE: 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 Testing Framework provides two sets of annotations:
|
||||
xref:testing/annotations/integration-spring/annotation-testbean.adoc[`@TestBean`],
|
||||
xref:testing/annotations/integration-spring/annotation-mockitobean.adoc[`@MockitoBean` and
|
||||
`@MockitoSpyBean`]. The former relies purely on Spring, while the later set relies on
|
||||
the https://site.mockito.org/[Mockito] third party library.
|
||||
The Spring TestContext framework provides two sets of annotations for bean overriding.
|
||||
|
||||
[[spring-testing-beanoverriding-extending]]
|
||||
== Extending bean override with a custom annotation
|
||||
* xref:testing/annotations/integration-spring/annotation-testbean.adoc[`@TestBean`]
|
||||
* xref:testing/annotations/integration-spring/annotation-mockitobean.adoc[`@MockitoBean` and `@MockitoSpyBean`]
|
||||
|
||||
The three annotations mentioned above build upon the `@BeanOverride` meta-annotation
|
||||
and associated infrastructure, which allows to define custom bean overriding variants.
|
||||
The former relies purely on Spring, while the latter set relies on the
|
||||
https://site.mockito.org/[Mockito] third-party library.
|
||||
|
||||
To create an extension, the following is needed:
|
||||
[[testcontext-bean-overriding-custom]]
|
||||
== Custom Bean Override Support
|
||||
|
||||
- An annotation meta-annotated with `@BeanOverride` that defines the
|
||||
`BeanOverrideProcessor` to use.
|
||||
- The `BeanOverrideProcessor` implementation itself.
|
||||
- One or more concrete `OverrideMetadata` implementations provided by the processor.
|
||||
The three annotations mentioned above build upon the `@BeanOverride` meta-annotation and
|
||||
associated infrastructure, which allows one to define custom bean overriding variants.
|
||||
|
||||
The Spring TestContext Framework includes infrastructure classes that support bean
|
||||
overriding: a `BeanFactoryPostProcessor`, a `TestExecutionListener` and a
|
||||
`ContextCustomizerFactory`.
|
||||
The later two are automatically registered via the Spring TestContext Framework
|
||||
`spring.factories` file, and are responsible for setting up the rest of the infrastructure.
|
||||
To create custom bean override support, the following is needed:
|
||||
|
||||
The test classes are parsed looking for any field meta-annotated with `@BeanOverride`,
|
||||
instantiating the relevant `BeanOverrideProcessor` in order to register an
|
||||
`OverrideMetadata`.
|
||||
* An annotation meta-annotated with `@BeanOverride` that defines the
|
||||
`BeanOverrideProcessor` to use
|
||||
* A custom `BeanOverrideProcessor` implementation
|
||||
* One or more concrete `OverrideMetadata` implementations provided by the processor
|
||||
|
||||
Then the `BeanOverrideBeanFactoryPostProcessor` will use that information to alter the
|
||||
context, registering and replacing bean definitions as defined by each metadata
|
||||
`BeanOverrideStrategy`:
|
||||
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.
|
||||
|
||||
- `REPLACE_DEFINITION`: replaces the bean definition. If it is not present in the
|
||||
context, an exception is thrown.
|
||||
- `CREATE_OR_REPLACE_DEFINITION`: replaces the bean definition if the bean definition
|
||||
does not exist, or create one if it is not.
|
||||
- `WRAP_BEAN`: get the original instance early so that it can be wrapped.
|
||||
* a `BeanFactoryPostProcessor`
|
||||
* a `ContextCustomizerFactory`
|
||||
* a `TestExecutionListener`
|
||||
|
||||
NOTE: The Bean Overriding infrastructure does not include any bean resolution step,
|
||||
unlike an `@Autowired`-annotated field for instance. As such, the name of the bean to
|
||||
override must be somehow provided to or computed by the `BeanOverrideProcessor`.
|
||||
Typically, the user provides the name one way or the other.
|
||||
The `spring-test` module registers implementations of the latter two
|
||||
(`BeanOverrideContextCustomizerFactory` and `BeanOverrideTestExecutionListener`) in its
|
||||
{spring-framework-code}/spring-test/src/main/resources/META-INF/spring.factories[`META-INF/spring.factories`
|
||||
properties file].
|
||||
|
||||
The bean overriding infrastructure searches in test classes for any field meta-annotated
|
||||
with `@BeanOverride` and instantiates the corresponding `BeanOverrideProcessor` which is
|
||||
responsible for registering appropriate `OverrideMetadata`.
|
||||
|
||||
The internal `BeanOverrideBeanFactoryPostProcessor` then uses that information to alter
|
||||
the test's `ApplicationContext` by registering and replacing bean definitions as defined
|
||||
by the corresponding `BeanOverrideStrategy`:
|
||||
|
||||
* `REPLACE_DEFINITION`: Replaces the bean definition. Throws an exception if a
|
||||
corresponding bean definition does not exist.
|
||||
* `REPLACE_OR_CREATE_DEFINITION`: Replaces the bean definition if it exists. Creates a
|
||||
new bean definition if a corresponding bean definition does not exist.
|
||||
* `WRAP_BEAN`: Retrieves the original bean instance and wraps it.
|
||||
|
||||
[NOTE]
|
||||
====
|
||||
In contrast to Spring's autowiring mechanism (for example, resolution of an `@Autowired`
|
||||
field), the bean overriding infrastructure in the TestContext framework does not perform
|
||||
any heuristics to locate a bean. Instead, the name of the bean to override must be
|
||||
explicitly provided to or computed by the `BeanOverrideProcessor`.
|
||||
|
||||
Typically, the user provides the bean name via a custom annotation, or the
|
||||
`BeanOverrideProcessor` determines the bean name based on some convention.
|
||||
====
|
||||
|
||||
Reference in New Issue
Block a user