Document potential need to use `Mockito.doXxx()` to stub a `@MockitoSpyBean`

[ofir-popowski]

It seems that stubbing a function of a @MockitoSpyBean ends up calling the actual code during the stub. Is that intentional? Should this be documented maybe? I do think it might just be my misunderstanding of mockito spies and/or usage of this annotation, but I found this behavior very surprising

given:

@Service
public class MyService {
    public String mockThis() {
        System.out.println("this should not be printed");
        return "my value";
    }
}

and a simple test:

@SpringBootTest
public class AppTest {
    @MockitoSpyBean private MyService myService;
    
    @Test
    public void checkThis() {
        Mockito.when(myService.mockThis()).thenReturn("stubbed return value");
        System.out.println(myService.mockThis());
        System.out.println(myService.mockThis());
        verify(myService, times(2)).mockThis();
    }
}

The console would show output:

this should not be printed <-- this is printed during `Mockito.when`
stubbed return value
stubbed return value

(I could open a repo with this if required, but it seemed small enough to just post here)

Spring Boot version: 3.5.5

[sbrannen]

For such scenarios, you need to use Mockito.doReturn().

Changing your test as follows results in the desired behavior.

@Test
void checkThis() {
	Mockito.doReturn("stubbed return value").when(myService).mockThis();
	System.out.println(myService.mockThis());
	System.out.println(myService.mockThis());
	verify(myService, times(2)).mockThis();
}

The Javadoc for Mockito.doReturn() states the following.

Use doReturn() in those rare occasions when you cannot use Mockito.when(Object).

...

When spying real objects and calling real methods on a spy brings side effects...

I am therefore repurposing this issue to add a note to the documentation about the potential need to use Mockito.doReturn() instead of Mockito.when() when stubbing a @MockitoSpyBean.

Actually, we should mention the family of doXxx() methods: doThrow(), doAnswer(), doNothing(), and doReturn().

[ofir-popowski]

Thank you very much for the quick response. Yes I think documenting this on @MockitoSpyBean would be great, it was rather surprising behavior to find out

[github-actions]

Fixed via 33fe8d2