Home > Software > Understanding the Difference Between when() and doXxx() Methods in Mockito

Understanding the Difference Between when() and doXxx() Methods in Mockito

Anastasios Antoniadis

Explore the key differences between Mockito’s when() and doXxx() methods for stubbing in Java unit tests. Learn when to use each method for effective mocking, including scenarios for return methods, void methods, and handling exceptions, to enhance your unit testing practices and improve software quality.


Mockito is a popular mocking framework for unit tests in Java, known for its clean API and ease of use. Among its functionalities, the methods when() and the doXxx() family (such as doReturn(), doThrow(), etc.) are frequently used for stubbing void methods and methods that return a value. Despite their similar purposes, these methods have distinct characteristics and use cases. This article explores the difference between when() and doXxx() methods in Mockito, providing insights into their optimal usage scenarios.

The when() Method

The when() method is perhaps the most commonly used method for stubbing in Mockito. It is primarily used with methods that return a value. The typical syntax for when() looks like this:


Here, mock is an instance of a mocked class, someMethod() is the method being stubbed, and someValue is the value that someMethod() should return when it is called. The when() method allows for a readable and straightforward way to define how mocks should behave when invoked certain methods.

Usage Example:

List<String> mockList = mock(List.class);
String result = mockList.get(0);

assertEquals("Mockito", result);

In this example, we stub the get() method of a mocked List to return “Mockito” when it is called with an index of 0.

The doXxx() Methods

The doXxx() family of methods in Mockito includes doReturn(), doThrow(), doAnswer(), and doNothing(), among others. These methods are used for stubbing void methods or for stubbing methods in specific scenarios where when() might not be suitable. The syntax for doReturn() looks like this:


Compared to when(), the method to be stubbed is called after the when() method in this syntax.

Usage Scenarios:

Stubbing Void Methods:


This syntax is particularly useful for stubbing void methods, as thenReturn() cannot be used with methods that don’t return a value.

Stubbing Methods That Throw Exceptions When Called:

doThrow(new RuntimeException()).when(mock).methodThatThrows();

This is useful for stubbing methods that, due to their implementation, throw an exception when called on a mock instance.

Usage Example:

List<String> mockList = mock(List.class);
doThrow(new RuntimeException()).when(mockList).clear();

assertThrows(RuntimeException.class, () -> mockList.clear());

In this example, we stub the clear() method of a mocked List to throw a RuntimeException when it is called.

Key Differences

The primary difference between when() and doXxx() methods lies in their applicability and the order of invocation. Here are the main points:

  1. Usage with Return Methods vs. Void Methods: when() is typically used with methods that return a value, while doXxx() methods are versatile enough to be used with both void methods and return methods.
  2. Order of Invocation: With when(), the method call is inside the parentheses and precedes the stubbing action (thenReturn(), thenThrow(), etc.). In contrast, with doXxx() methods, the action (doReturn(), doThrow(), etc.) precedes the method call, which is encapsulated inside a subsequent when() call.
  3. Handling of Real Method Invocations: when() actually calls the method on the mock and is therefore not suitable for methods that throw exceptions. doXxx() methods, however, do not call the method when setting up the stub, making them safer for methods that throw exceptions or have side effects.


Both when() and doXxx() methods serve crucial roles in the Mockito framework, facilitating the stubbing of methods under different conditions. Choosing between them depends on the specific requirements of the method being stubbed—such as whether it returns a value or is void—and the desired behavior of the stub in terms of exception handling and side effects. Understanding the nuances of each approach allows developers to write more precise and robust unit tests, enhancing test coverage and software quality.

Anastasios Antoniadis
Follow me
Latest posts by Anastasios Antoniadis (see all)
0 0 votes
Article Rating
Notify of
Inline Feedbacks
View all comments
Would love your thoughts, please comment.x