[[spring-testing-annotation-beanoverriding-mockitobean]]
= `@MockitoBean` and `@MockitoSpyBean`

`@MockitoBean` and `@MockitoSpyBean` are used on fields in test classes to override beans
in the test's `ApplicationContext` with a Mockito _mock_ or _spy_, respectively. In the
latter case, an early instance of the original bean is captured and wrapped by the spy.

By default, the annotated field's type is used to search for candidate beans to override.
If multiple candidates match, `@Qualifier` can be provided to narrow the candidate to
override. Alternatively, a candidate whose bean name matches the name of the field will
match.

When using `@MockitoBean`, a new bean will be created if a corresponding bean does not
exist. However, if you would like for the test to fail when a corresponding bean does not
exist, you can set the `enforceOverride` attribute to `true` – for example,
`@MockitoBean(enforceOverride = true)`.

To use a by-name override rather than a by-type override, specify the `name` attribute
of the annotation.

[WARNING]
====
Qualifiers, including the name of the field, are used to determine if a separate
`ApplicationContext` needs to be created. If you are using this feature to mock or spy
the same bean in several tests, make sure to name the field consistently to avoid
creating unnecessary contexts.
====

Each annotation also defines Mockito-specific attributes to fine-tune the mocking details.

By default, the `@MockitoBean` annotation uses the `REPLACE_OR_CREATE`
xref:testing/testcontext-framework/bean-overriding.adoc#testcontext-bean-overriding-custom[strategy for test bean overriding].
If no existing bean matches, a new bean is created on the fly. As mentioned previously,
you can switch to the `REPLACE` strategy by setting the `enforceOverride` attribute to
`true`.

The `@MockitoSpyBean` annotation uses the `WRAP`
xref:testing/testcontext-framework/bean-overriding.adoc#testcontext-bean-overriding-custom[strategy],
and the original instance is wrapped in a Mockito spy. This strategy requires that
exactly one candidate bean exists.

NOTE: Only _singleton_ beans can be overridden. Any attempt to override a non-singleton
bean will result in an exception.

The following example shows how to use the default behavior of the `@MockitoBean` annotation:

[tabs]
======
Java::
+
[source,java,indent=0,subs="verbatim,quotes"]
----
	class OverrideBeanTests {
		@MockitoBean // <1>
		private CustomService customService;

		// test case body...
	}
----
<1> Replace the bean with type `CustomService` with a Mockito `mock`.
======

In the example above, we are creating a mock for `CustomService`. If more than one bean
of that type exists, the bean named `customService` is considered. Otherwise, the test
will fail, and you will need to provide a qualifier of some sort to identify which of the
`CustomService` beans you want to override. If no such bean exists, a bean definition
will be created with an auto-generated bean name.

The following example uses a by-name lookup, rather than a by-type lookup:

[tabs]
======
Java::
+
[source,java,indent=0,subs="verbatim,quotes"]
----
	class OverrideBeanTests {
		@MockitoBean("service") // <1>
		private CustomService customService;

		// test case body...

	}
----
<1> Replace the bean named `service` with a Mockito `mock`.
======

If no bean definition named `service` exists, one is created.

The following example shows how to use the default behavior of the `@MockitoSpyBean` annotation:

[tabs]
======
Java::
+
[source,java,indent=0,subs="verbatim,quotes"]
----
	class OverrideBeanTests {
		@MockitoSpyBean // <1>
		private CustomService customService;

		// test case body...
	}
----
<1> Wrap the bean with type `CustomService` with a Mockito `spy`.
======

In the example above, we are wrapping the bean with type `CustomService`. If more than
one bean of that type exists, the bean named `customService` is considered. Otherwise,
the test will fail, and you will need to provide a qualifier of some sort to identify
which of the `CustomService` beans you want to spy.

The following example uses a by-name lookup, rather than a by-type lookup:

[tabs]
======
Java::
+
[source,java,indent=0,subs="verbatim,quotes"]
----
	class OverrideBeanTests {
		@MockitoSpyBean("service") // <1>
		private CustomService customService;

		// test case body...

	}
----
<1> Wrap the bean named `service` with a Mockito `spy`.
======
