awesome-copilot/skills/spring-boot-testing/references/mockitobean.md

@MockitoBean

Mocking dependencies in Spring Boot tests (replaces deprecated @MockBean in Spring Boot 4+).

Overview

@MockitoBean replaces the deprecated @MockBean annotation in Spring Boot 4.0+. It creates a Mockito mock and registers it in the Spring context, replacing any existing bean of the same type.

Basic Usage

@WebMvcTest(OrderController.class)
class OrderControllerTest {
  
  @MockitoBean
  private OrderService orderService;
  
  @MockitoBean
  private UserService userService;
}

Supported Test Slices

• @WebMvcTest - Mock service/repository dependencies
• @WebFluxTest - Mock reactive service dependencies
• @SpringBootTest - Replace real beans with mocks

Stubbing Methods

Basic Stub

@Test
void shouldReturnOrder() {
  Order order = new Order(1L, "PENDING");
  given(orderService.findById(1L)).willReturn(order);
  
  // Test code
}

Multiple Returns

given(orderService.findById(anyLong()))
  .willReturn(new Order(1L, "PENDING"))
  .willReturn(new Order(2L, "COMPLETED"));

Throwing Exceptions

given(orderService.findById(999L))
  .willThrow(new OrderNotFoundException(999L));

Argument Matching

given(orderService.create(argThat(req -> req.getQuantity() > 0)))
  .willReturn(1L);

given(orderService.findByStatus(eq("PENDING")))
  .willReturn(List.of(new Order()));

Verifying Interactions

Verify Method Called

verify(orderService).findById(1L);

Verify Never Called

verify(orderService, never()).delete(any());

Verify Count

verify(orderService, times(2)).findById(anyLong());
verify(orderService, atLeastOnce()).findByStatus(anyString());

Verify Order

InOrder inOrder = inOrder(orderService, userService);
inOrder.verify(orderService).findById(1L);
inOrder.verify(userService).getUser(any());

Resetting Mocks

Mocks are reset between tests automatically. To reset mid-test:

Mockito.reset(orderService);

@MockitoSpyBean for Partial Mocking

Use @MockitoSpyBean to wrap a real bean with Mockito.

@SpringBootTest
class OrderServiceIntegrationTest {
  
  @MockitoSpyBean
  private PaymentGatewayClient paymentClient;
  
  @Test
  void shouldProcessOrder() {
    doReturn(true).when(paymentClient).processPayment(any());
    
    // Test with real service but mocked payment client
  }
}

@TestBean for Custom Test Beans

Register a custom bean instance in the test context:

@SpringBootTest
class OrderServiceTest {
  
  @TestBean
  private PaymentGatewayClient paymentClient() {
    return new FakePaymentClient();
  }
}

Scoping: Singleton vs Prototype

Spring Framework 7+ (Spring Boot 4+) supports mocking non-singleton beans:

@Component
@Scope("prototype")
public class OrderProcessor {
  public String process() { return "real"; }
}

@SpringBootTest
class OrderServiceTest {
  @MockitoBean
  private OrderProcessor orderProcessor;
  
  @Test
  void shouldWorkWithPrototype() {
    given(orderProcessor.process()).willReturn("mocked");
    // Test code
  }
}

Common Patterns

Mocking Repository in Service Test

@SpringBootTest
class OrderServiceTest {
  @MockitoBean
  private OrderRepository orderRepository;
  
  @Autowired
  private OrderService orderService;
  
  @Test
  void shouldCreateOrder() {
    given(orderRepository.save(any())).willReturn(new Order(1L));
    
    Long id = orderService.createOrder(new OrderRequest());
    
    assertThat(id).isEqualTo(1L);
    verify(orderRepository).save(any(Order.class));
  }
}

Multiple Mocks of Same Type

Use bean names:

@MockitoBean(name = "primaryDataSource")
private DataSource primaryDataSource;

@MockitoBean(name = "secondaryDataSource")
private DataSource secondaryDataSource;

Migration from @MockBean

Before (Deprecated)

@MockBean
private OrderService orderService;

After (Spring Boot 4+)

@MockitoBean
private OrderService orderService;

Key Differences from Mockito @Mock

Feature	@MockitoBean	@Mock
Context integration	Yes	No
Spring lifecycle	Participates	None
Works with @Autowired	Yes	No
Test slice support	Yes	Limited

Best Practices

1. Use @MockitoBean only when Spring context is involved
2. For pure unit tests, use Mockito's @Mock or Mockito.mock()
3. Always verify interactions that have side effects
4. Don't verify simple queries (stubbing is enough)
5. Reset mocks if test modifies shared mock state