When to Use a Spy

Direct Answer

Use a spy when you deliberately want a real object's methods to run by default while stubbing or verifying a small, specific part of its behavior. A mock starts with Mockito defaults instead. A spy is useful around legacy code or for observing a real collaborator, but real methods can have side effects. doReturn(...).when(spy)... avoids calling a risky real method during setup; ordinary when(...) can still be used when that setup call is safe.

Code Example

@ExtendWith(MockitoExtension.class)
class PaymentServiceTest {
    @Mock
    private PaymentGateway mockGateway; // All methods return null/defaults
    
    @Spy
    private PaymentValidator spyValidator = new PaymentValidator(); // Real object
    
    @Test
    void testMockBehavior() {
        when(mockGateway.charge(100)).thenReturn("SUCCESS");
        var result = mockGateway.charge(100); // Returns "SUCCESS"
        var other = mockGateway.refund(50); // Returns null (no stub)
    }
    
    @Test
    void testSpyBehavior() {
        // Real validateAmount() runs unless we stub it
        var realResult = spyValidator.validateAmount(100); // Runs actual code
        
        doReturn(false).when(spyValidator).validateAmount(0); // Override one method
        var stubbedResult = spyValidator.validateAmount(0); // Returns false
        
        verify(spyValidator, times(2)).validateAmount(anyInt());
    }
}

Common Mistakes & Pitfalls

• Forgetting real behavior: every unstubbed spy method can execute production logic and side effects.
• Eager setup call: when(spy.read()).thenReturn(value) calls read() while configuring the stub; use doReturn when that is unsafe.
• Treating doReturn as mandatory: it is an escape hatch for risky setup calls, not a rule for every spy.
• Assuming @Spy always needs an initializer: Mockito can construct a suitable type, but explicit construction is clearer when the object needs chosen state or constructor arguments.
• Hiding a design problem: heavy partial stubbing may mean a responsibility should be moved behind an injectable collaborator.