Support `@MockitoBean` at the type level on test classes

[nmck257]

MockitoBean is designed to replace the now-deprecated MockBean annotation. MockBean could target either a field or a type. Currently, MockitoBean can only target a field. This issue proposes adding the support to target types to MockitoBean, similar to MockBean.

(pasting some prose from #29917 comments)

This feature is useful for test cases which want to stub out some set of beans (ie to avoid some side effect of regular instantiation), but didn't care about specifying behavior.

Suppose you have multiple @SpringBootTest classes, and want to stub out the same set of beans for each of them. With an annotation targeting the class itself, you could define a meta-annotation containing those repeated invocations of MockBean and reuse wherever needed. If we only have support for mocking beans as fields, then the next alternative would be a common superclass which declares those annotated fields. That pattern pushes you to (single) inheritance, whereas the class annotation pattern was composition-friendly.

Subjectively, I also think that if the test developer's intent is not to define any behavior for the mocked bean, then it's easier to read and maintain if we can avoid adding an unused field to the class scope.

Here's some Kotlin code to help demonstrate the point above:

@MockBeans(
    MockBean(MyServiceWithOutOfProcessSideEffectsOnBoot::class),
    MockBean(MyPreemptiveClientAuthTokenFetcher::class),
    MockBean(MyServiceWhichLoadsOneMillionThingsIntoMemoryOnBoot::class),
)
annotation class MockExpensiveDependencies

@SpringBootTest
@MockExpensiveDependencies
class BusinessLogicControllerTest {
    // ...
}

@SpringBootTest
@MockExpensiveDependencies
class SomeOtherTest {
    // ...
}

vs

open class MockExpensiveDependenciesBase {
    @MockBean
    private lateinit var foo: MyServiceWithOutOfProcessSideEffectsOnBoot
    @MockBean
    private lateinit var bar: MyPreemptiveClientAuthTokenFetcher
    @MockBean
    private lateinit var gav: MyServiceWhichLoadsOneMillionThingsIntoMemoryOnBoot
}

@SpringBootTest
class BusinessLogicControllerTest : MockExpensiveDependenciesBase() {
    // ...
}

@SpringBootTest
class SomeOtherTest : MockExpensiveDependenciesBase() {
    // ...
}

[OrangeDog]

Here's a couple of other cases that @MockBean allowed.

Including mocks via additional config (not just other annotations):

@TestConfiguration
@MockBean({
    MyServiceWithOutOfProcessSideEffectsOnBoot.class,
    MyPreemptiveClientAuthTokenFetcher.class
})
@EnableSomething
@Import(OtherStuff.class)
public class SharedTestConfiguration { }

@SpringTestAnnotation
@Import({SharedTestConfiguration.class, SomeOtherConfig.class})
public class SomeTests {

If one of these mocks were autowired, stub behaviour could then be specified.
This doesn't work when returning a mock from a @Bean method, depending on how beans are proxied:

@SpringTestAnnotation
@MockBean(MyServiceWithOutOfProcessSideEffectsOnBoot.class)  // actually declared elsewhere
public class SomeTests {
    @Autowired private MyServiceWithOutOfProcessSideEffectsOnBoot myService;

    @Test
    public void onlyThisTestSpecificallyWantsToStubIt() {
        doReturn(true).when(myService).isSomething();
    }

[jack5505]

Can I take this issue to work on this

[sbrannen]

Hi @jack5505,

The team has not yet made a decision regarding this issue, and it's highly unlikely that the implementation would be performed by anyone outside the core team.

Thanks for the offer anyway.

[sbrannen]

We appreciate the constructive feedback we have received here as well as in #33934, and in light of that we are considering introducing support for declaring @MockitoBean at the class level on test classes, with the driving impetus being the ability to reuse mock configuration across a test suite without having to extend a base test class.

If we choose to do so, that would allow @MockitoBean to be declared directly (or as a meta-annotation) on a test class (or on any superclass or interface in the type hierarchy of the test class). However, that does not mean that @MockitoBean would be supported on a @Configuration class.

In terms of declaring multiple types to mock (with different mock configurations), that could be supported by allowing @MockitoBean to be used as a repeatable annotation or introducing a dedicated, required container annotation such as @MockitoBeans.

In any case, @MockitoBean would need a new attribute to allow the developer to specify which type or types to mock, since the type could no longer be inferred from the annotated field's type.

The following demonstrates what such a programming model might look like.

@SpringJUnitConfig
// Register one or more types to mock
@MockitoBean(types = { ExampleService.class, AnotherService.class })
class MyIntegrationTests {

	// Optionally inject the mocks for stubbing and verification.
	//
	// @Autowired
	// ExampleService exampleService;
	//
	// @Autowired
	// AnotherService anotherService;

	@Test
	void test() {
		// ...
	}
}

For reuse of the mock configuration across the test suite, teams could introduce composed annotations such as the following.

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@MockitoBean(types = { ExampleService.class, AnotherService.class })
public @interface SharedMocks {
}

That would allow @SharedMocks to be declared on any test class (or on any superclass or interface in the type hierarchy of the test class) as follows.

@SpringJUnitConfig
// Reuse @MockitoBean declarations via a composed annotation:
@SharedMocks
class MyIntegrationTests {

	// Optionally inject the mocks for stubbing and verification.
	//
	// @Autowired
	// ExampleService exampleService;
	//
	// @Autowired
	// AnotherService anotherService;

	@Test
	void test() {
		// ...
	}
}

Another option would be to limit one type per @MockitoBean annotation, such as in the following example, where type can only supply a single Class reference to mock.

@SpringJUnitConfig
@MockitoBean(type = ExampleService.class)
@MockitoBean(type = AnotherService.class)
class MyIntegrationTests {

	// Optionally inject the mocks for stubbing and verification.
	//
	// @Autowired
	// ExampleService exampleService;
	//
	// @Autowired
	// AnotherService anotherService;

	@Test
	void test() {
		// ...
	}
}

NOTE: In contrast to Spring Boot's @MockBean annotation, the type or types to mock cannot be specified via an explicit or implicit value attribute since @MockitoBean already has a value attribute which is an alias for the name attribute.

---

As I mentioned previously, we are not yet committed to implementing this feature, but we are considering it.

Thus, if you are interested in this GitHub issue or #33934, we would appreciate your feedback on whether the above proposal would satisfy your needs to reuse @MockitoBean across your test suite.

As a side note, we would also be interested in knowing how many Spring Boot users have traditionally declared @SpyBean on a test class as opposed to on a field in a test class.

Thanks,

Sam

[cfredri4]

The composed annotation example would solve my cases.
We're not using @SpyBeanon a test class.

[nmck257]

Thanks for the update @sbrannen !

Here are some responses to topics raised in your comment:

• Targeting only test classes (and not Configuration classes) is suitable for my usage
• No preference on repeatable vs container annotations; I think I recall that the container pattern predates JDK support for repeatable annotations, and the repeatable pattern may be a bit simpler?
• I have not used @SpyBean on a test class; my intuition is that I would only use SpyBean for an element which I expect to reference directly in my test cases, and if I expect to reference a (stubbed) bean in my test cases, then declaring it as a field is less code anyway compared to declaring the stubbing at the class level and autowiring the resultant bean into a field
• Adding a type field makes sense, though it prompts a design decision about how to handle contexts which declare multiple beans of that same type. For the old MockBean, the name was required in that case, but it may also be useful to mock all beans of that type if the name is not specified