Mockito - difference between doReturn() and when()

Tap into doReturn() for Stubbing

Stubbing void methods & spies

In a case where you're stubbing void methods or working with Mockito spies, doReturn() is certainly your weapon of choice. It faithfully omits the actual method execution, a critical action when the actual method could possibly change the state or induce undesirable side effects on your test setup.

// Stubbing a void method with doReturn(), like a boss
doReturn().when(spyList).clear();

// This fella would start an UnnecessaryStubbingException party
// doNothing().when(spyList).clear();


Zero Side-effects

Utilizing doReturn() assures you zero unwanted side effects during stubbing, since the method being stubbed isn't executed. This is very important for methods that tinker with global state or interface with external systems.

// Just ensuring things don't blow up on us
doReturn("state-safe").when(mockObject).methodThatAltersState();


Overtaking past exceptions or stubs

You could take advantage of doReturn() to overrule past stubs that were initially set to throw exceptions, giving you room to adjust your mock's behaviour during your test.

// Masterfully overhauling an earlier exception stub
when(mockList.get(anyInt())).thenThrow(new RuntimeException());
doReturn("recovered").when(mockList).get(0);


when().thenReturn() for type-safety and readability

While doReturn() excels at averting side-effects, when().thenReturn() usually reigns supreme in terms of readability and type safety. This expressly indicates your stubbing intentions and ensures any test setup error is caught at compile time.

// Stubbing made sexy and safe
when(mockList.get(0)).thenReturn("type-safe");


Consistency and method chaining

Acing one syntax

For the sake of consistency and simplicity in your test code, it might pay dividends to master one syntax. If your test cases are candid and do not involve spies or methods that can morph state or return side-effects, when().thenReturn() might be the favoured approach due to its cleanliness and type safety.

// A demonstration of classic stubbing via when()
when(mockList.get(0)).thenReturn("consistent");


Handling exceptions & multiple calls

For methods that return distinct values on successive calls or throw exceptions, acing doReturn().when() could be quite beneficial.

// Stubbing a method to return different values on consecutive calls
doReturn("first-call").doReturn("second-call").when(mockList).get(anyInt());

// Stubbing a method to throw exceptions
doThrow(new RuntimeException()).when(mockList).clear();


Enhancing Clean code

Evading Code Smells

One should be wary of overriding stubs as it might hint at a code smell in your test structure. Instead, try to design your tests to be predictive and consistent thereby offering a pleasant testing experience.

Context is Key

In the method chaining order bake use of the one that aligns with your testing scenario. By selecting the correct stubbing method, you minimize your efforts, reduce prone-ness to errors, make testing seamless and enjoyable.