Introduction

Both when(...).thenReturn(...) and doReturn(...).when(...) stub behavior in Mockito, but they are not interchangeable in every situation. The big difference is whether the method call inside the stubbing expression is executed immediately, which matters a lot when you are working with spies or methods that have side effects.

The Common Case: when(...).thenReturn(...)

For ordinary mocks, the most readable form is usually when(...).thenReturn(...).

1import static org.mockito.Mockito.*;
2import java.util.List;
3
4List<String> mockedList = mock(List.class);
5when(mockedList.get(0)).thenReturn("first element");
6
7System.out.println(mockedList.get(0));

This is the idiomatic Mockito style for straightforward stubbing. It reads naturally and works well when the method invocation used in the stubbing expression is safe to evaluate.

Why doReturn(...).when(...) Exists

The doReturn family exists mainly for cases where calling the real method during stubbing is undesirable. This happens most often with spies.

1import static org.mockito.Mockito.*;
2import java.util.ArrayList;
3import java.util.List;
4
5List<String> spyList = spy(new ArrayList<>());
6doReturn("safe value").when(spyList).get(0);
7
8System.out.println(spyList.get(0));

If you wrote when(spyList.get(0)).thenReturn("safe value"), Mockito would call the real get(0) during stubbing. For an empty list, that means an IndexOutOfBoundsException before your test even starts exercising behavior.

That is the core practical difference: doReturn avoids calling the real method when setting up the stub.

Mocks Versus Spies

With a pure mock, there is usually no real behavior underneath, so when(...).thenReturn(...) is almost always fine.

With a spy, real methods exist and can run unless you stub around them carefully. That is why many Mockito discussions reduce to this rule:

• use when(...).thenReturn(...) for normal mocks
• use doReturn(...).when(...) when stubbing spies or otherwise unsafe real calls

It is not that doReturn is “more powerful” in general. It is that it is safer when the real method should not be touched during setup.

Related do... Methods

Mockito also has doThrow, doAnswer, and related forms for similar reasons. The whole do...when(...) family is about setting behavior without triggering the method call in the usual when(...) syntax.

That pattern is especially helpful when the target method is void, expensive, stateful, or dangerous to execute during test setup.

Which Style Should You Prefer

Prefer when(...).thenReturn(...) when it works, because it is clearer and more familiar to most Java developers. Reach for doReturn(...).when(...) when the act of stubbing would otherwise invoke real logic you do not want.

In other words, readability first, safety when needed.

Another useful way to think about it is that when describes expected behavior in the happy path, while doReturn is often the escape hatch for edge cases in test setup. That mental model helps keep most tests readable while still giving you a safe tool when spies or fragile methods are involved.

Common Pitfalls

• Using when(...).thenReturn(...) on a spy and accidentally calling the real method during stubbing.
• Treating doReturn as the default style even when plain when is clearer.
• Forgetting the difference between mocks and spies when reading Mockito examples.
• Stubbing methods with side effects in a way that mutates state before the test actually begins.
• Assuming the two forms are just stylistic variants rather than behaviorally different in spy scenarios.

Summary

• Both forms stub return values, but they differ in whether the method call is evaluated during setup.
• 'when(...).thenReturn(...) is the normal readable choice for ordinary mocks.'
• 'doReturn(...).when(...) is safer when stubbing spies or methods you do not want executed during setup.'
• The difference matters most when real method invocation would throw, mutate state, or be expensive.
• Choose the form based on whether the stubbing expression is safe to execute.