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

@MockitoBean and @MockitoSpyBean

@MockitoBean and @MockitoSpyBean are used on non-static 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.

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 test classes, make sure to name the field consistently to avoid creating unnecessary contexts.

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

The @MockitoBean annotation uses the REPLACE_OR_CREATE strategy for test bean overriding. If no existing bean matches, a new bean is created on the fly. However, you can switch to the REPLACE strategy by setting the enforceOverride attribute to true. See the following section for an example.

The @MockitoSpyBean annotation uses the WRAP strategy, and the original instance is wrapped in a Mockito spy. This strategy requires that exactly one candidate bean exists.

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

When using @MockitoBean to mock a bean created by a FactoryBean, the FactoryBean will be replaced with a singleton mock of the type of object created by the FactoryBean.

When using @MockitoSpyBean to create a spy for a FactoryBean, a spy will be created for the object created by the FactoryBean, not for the FactoryBean itself.

There are no restrictions on the visibility of @MockitoBean and @MockitoSpyBean fields.

Such fields can therefore be public, protected, package-private (default visibility), or private depending on the needs or coding practices of the project.

@MockitoBean Examples

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 (or value) attribute of the annotation.

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

  • Java

@SpringJUnitConfig(TestConfig.class)
class BeanOverrideTests {

	@MockitoBean (1)
	CustomService customService;

	// tests...
}
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 will be created with an auto-generated bean name.

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

  • Java

@SpringJUnitConfig(TestConfig.class)
class BeanOverrideTests {

	@MockitoBean("service") (1)
	CustomService customService;

	// tests...

}
1 Replace the bean named service with a Mockito mock.

If no bean named service exists, one is created.

@MockitoBean can also be used at the type level:

  • on a test class or any superclass or implemented interface in the type hierarchy above the test class

  • on an enclosing class for a @Nested test class or on any class or interface in the type hierarchy or enclosing class hierarchy above the @Nested test class

When @MockitoBean is declared at the type level, the type of bean (or beans) to mock must be supplied via the types attribute – for example, @MockitoBean(types = {OrderService.class, UserService.class}). If multiple candidates exist in the application context, you can explicitly specify a bean name to mock by setting the name attribute. Note, however, that the types attribute must contain a single type if an explicit bean name is configured – for example, @MockitoBean(name = "ps1", types = PrintingService.class).

To support reuse of mock configuration, @MockitoBean may be used as a meta-annotation to create custom composed annotations — for example, to define common mock configuration in a single annotation that can be reused across a test suite. @MockitoBean can also be used as a repeatable annotation at the type level — for example, to mock several beans by name.

The following @SharedMocks annotation registers two mocks by-type and one mock by-name.

  • Java

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@MockitoBean(types = {OrderService.class, UserService.class}) (1)
@MockitoBean(name = "ps1", types = PrintingService.class) (2)
public @interface SharedMocks {
}
1 Register OrderService and UserService mocks by-type.
2 Register PrintingService mock by-name.

The following demonstrates how @SharedMocks can be used on a test class.

  • Java

@SpringJUnitConfig(TestConfig.class)
@SharedMocks (1)
class BeanOverrideTests {

	@Autowired OrderService orderService; (2)

	@Autowired UserService userService; (2)

	@Autowired PrintingService ps1; (2)

	// Inject other components that rely on the mocks.

	@Test
	void testThatDependsOnMocks() {
		// ...
	}
}
1 Register common mocks via the custom @SharedMocks annotation.
2 Optionally inject mocks to stub or verify them.
The mocks can also be injected into @Configuration classes or other test-related components in the ApplicationContext in order to configure them with Mockito’s stubbing APIs.

@MockitoSpyBean Examples

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

  • Java

@SpringJUnitConfig(TestConfig.class)
class BeanOverrideTests {

	@MockitoSpyBean (1)
	CustomService customService;

	// tests...
}
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:

  • Java

@SpringJUnitConfig(TestConfig.class)
class BeanOverrideTests {

	@MockitoSpyBean("service") (1)
	CustomService customService;

	// tests...
}
1 Wrap the bean named service with a Mockito spy.