Introduction

In Spring Boot 3.4, @MockBean and the container annotation @MockBeans were deprecated in favor of Spring Framework's new bean-override testing support. The replacement is @MockitoBean for mocks and @MockitoSpyBean for spies, both from Spring Framework 6.2.

What Changed In Spring Boot 3.4

Historically, Spring Boot provided Mockito test annotations in org.springframework.boot.test.mock.mockito, including:

• '@MockBean'
• '@MockBeans'
• '@SpyBean'

In Spring Boot 3.4, that package was deprecated for removal in favor of the new Spring Framework bean-override annotations.

The practical replacement for @MockBeans is not "find another container annotation in Boot." The normal replacement is to use one or more @MockitoBean declarations from Spring Framework.

Use @MockitoBean Instead

Field-level usage is the most direct migration path:

1import org.junit.jupiter.api.Test;
2import org.springframework.beans.factory.annotation.Autowired;
3import org.springframework.boot.test.context.SpringBootTest;
4import org.springframework.test.context.bean.override.mockito.MockitoBean;
5
6@SpringBootTest
7class OrderServiceTests {
8
9    @MockitoBean
10    private PaymentGateway paymentGateway;
11
12    @MockitoBean
13    private InventoryClient inventoryClient;
14
15    @Autowired
16    private OrderService orderService;
17
18    @Test
19    void createsOrder() {
20        orderService.placeOrder("sku-1");
21    }
22}

That covers the common use case where @MockBeans used to group several mock declarations on a test class.

The benefit is that the annotation now comes from Spring Framework's unified testing support instead of a Boot-specific layer.

Type-Level Replacement For Grouped Mocking

If you prefer type-level declarations, @MockitoBean also supports that style.

1import org.junit.jupiter.api.Test;
2import org.springframework.boot.test.context.SpringBootTest;
3import org.springframework.test.context.bean.override.mockito.MockitoBean;
4
5@SpringBootTest
6@MockitoBean(types = PaymentGateway.class)
7@MockitoBean(types = InventoryClient.class)
8class CheckoutTests {
9
10    @Test
11    void startsContext() {
12    }
13}

This is the closest conceptual replacement for @MockBeans: multiple repeatable mock annotations on the class.

In other words, the replacement is usually repeated @MockitoBean, not another one-off Boot container wrapper.

Use @MockitoSpyBean For Spies

If your old tests used @SpyBean, the matching replacement is @MockitoSpyBean.

1import org.springframework.test.context.bean.override.mockito.MockitoSpyBean;
2
3@MockitoSpyBean
4private AuditPublisher auditPublisher;

This is a separate concern from @MockBeans, but it is part of the same migration path away from Boot's deprecated Mockito test annotations.

Migration Example

Old style:

1import org.springframework.boot.test.mock.mockito.MockBean;
2import org.springframework.boot.test.mock.mockito.MockBeans;
3
4@MockBeans({
5    @MockBean(PaymentGateway.class),
6    @MockBean(InventoryClient.class)
7})
8class LegacyTest {
9}

New style:

1import org.springframework.test.context.bean.override.mockito.MockitoBean;
2
3@MockitoBean(types = PaymentGateway.class)
4@MockitoBean(types = InventoryClient.class)
5class ModernTest {
6}

Or field-based:

1@MockitoBean
2private PaymentGateway paymentGateway;
3
4@MockitoBean
5private InventoryClient inventoryClient;

Pick the style that best matches how your team writes tests.

Why The Change Happened

The move is part of a broader cleanup in which Spring Framework now owns the test bean-override abstraction directly. That reduces duplication between Boot and Framework testing features and gives the mocking model a more consistent home.

From a test author's perspective, the main consequence is import changes and annotation migration, not a completely different mental model.

You are still overriding beans in the application context with Mockito-managed test doubles. The package and annotation names changed, and the older Boot ones are on a removal path.

Common Pitfalls

The biggest mistake is replacing @MockBeans with repeated @MockBean and assuming the migration is complete. In Spring Boot 3.4, @MockBean itself is also deprecated.

Another mistake is forgetting to update the imports. The replacement annotations come from org.springframework.test.context.bean.override.mockito, not the old Boot package.

People also confuse mocks and spies during migration. @MockitoBean replaces mock semantics, while @MockitoSpyBean replaces spy semantics.

Finally, if you migrate type-level annotations, check the attribute names carefully. @MockitoBean uses attributes that differ from some older Boot examples.

Summary

• In Spring Boot 3.4, @MockBeans is deprecated along with @MockBean.
• The replacement is Spring Framework's @MockitoBean, usually repeated for multiple mocks.
• Use @MockitoSpyBean when the old test used spy behavior.
• The new annotations live in org.springframework.test.context.bean.override.mockito.
• The migration is mostly about changing imports and annotations, not about changing the underlying testing strategy.