@SpyBean vs @MockBean in Spring Boot

Direct Answer

The older Spring Boot @MockBean replaces a bean in the test ApplicationContext with a Mockito mock; @SpyBean wraps an existing bean with a spy so unstubbed calls use real behavior. Since Spring Boot 3.4 these annotations are deprecated for removal in 4.0 in favor of Spring Framework's @MockitoBean and @MockitoSpyBean. A bean override changes the context cache key, but it does not automatically mark every context dirty or force a reload for every test class; classes with the same configuration can reuse a cached context.

Code Example

@WebMvcTest(OrderController.class)
class OrderControllerTest {
    @MockitoBean OrderRepository repository; // mock bean in the context
    @MockitoSpyBean AuditService audit;       // wraps the real bean

    @Test
    void recordsTheRead() {
        when(repository.findById(1L)).thenReturn(Optional.of(new Order(1L)));
        // Exercise the controller before verification.
        verify(audit).record(any());
    }
}

Common Mistakes & Pitfalls

• Using context overrides for plain unit tests: direct constructor wiring is enough when Spring behavior is irrelevant.
• Spying an unsafe bean: unstubbed methods can perform real external work.
• Using normal when on a risky spy call: it executes the real method during setup; use a do...when form when needed.
• Calling every cache difference invalidation: override metadata can create a different cache key, but does not automatically mark a context dirty.
• Using legacy annotations in new code: current Spring uses @MockitoBean and @MockitoSpyBean.