Mockito doReturn Method

The doReturn method in Mockito is used to stub methods in cases where the when method cannot be used. This is typically needed when dealing with methods that are final, private, or when you need to set consecutive return values. This guide covers the basics of using the doReturn method, including its syntax and examples.

Table of Contents

1. Introduction
2. doReturn Method Syntax
3. Examples
   • Basic Usage
   • Setting Consecutive Return Values
4. Real-World Use Case
5. Conclusion

Introduction

Mockito is a popular library in Java for creating mock objects. While the when method is commonly used for stubbing, there are situations where it cannot be used directly. The doReturn method provides an alternative way to stub methods, especially when dealing with certain constraints.

doReturn Method Syntax

Basic Usage

static Stubber doReturn(Object toBeReturned)

Sets a return value for a method when it is called.

Setting Consecutive Return Values

static Stubber doReturn(Object toBeReturned, Object... toBeReturnedNext)

Sets consecutive return values for a method when it is called multiple times.

Examples

Basic Usage

Stub a method to return a specific value using doReturn.

import static org.mockito.Mockito.mock;
import static org.mockito.Mockito.doReturn;
import static org.mockito.Mockito.when;
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.assertEquals;

public class BasicDoReturnTest {
   @Test
   void testDoReturn() {
      UserService mockUserService = mock(UserService.class);
      // Stub the getUserDetails method to return "Mock user details" using doReturn
      doReturn("Mock user details").when(mockUserService).getUserDetails("123");
      String details = mockUserService.getUserDetails("123");
      assertEquals("Mock user details", details);
   }
}

class UserService {
   public String getUserDetails(String userId) {
      return "Real user details for " + userId;
   }
}

Setting Consecutive Return Values

Stub a method to return different values on consecutive calls using doReturn.

import static org.mockito.Mockito.mock;
import static org.mockito.Mockito.doReturn;
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.assertEquals;

public class ConsecutiveDoReturnTest {
   @Test
   void testDoReturnConsecutiveValues() {
      UserService mockUserService = mock(UserService.class);
      // Stub the getUserDetails method to return different values on consecutive calls
      doReturn("First call", "Second call").when(mockUserService).getUserDetails("123");
      assertEquals("First call", mockUserService.getUserDetails("123"));
      assertEquals("Second call", mockUserService.getUserDetails("123"));
   }
}

class UserService {
   public String getUserDetails(String userId) {
      return "Real user details for " + userId;
   }
}

Real-World Use Case

Stubbing a Final Method

In a real-world scenario, you might need to stub a final method in a class. The doReturn method is useful in this case because the when method cannot be used with final methods.

import static org.mockito.Mockito.mock;
import static org.mockito.Mockito.doReturn;
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.assertEquals;

class UserService {
   public final String getUserDetails(String userId) {
      return "Real user details for " + userId;
   }
}

public class FinalMethodTest {
   @Test
   void testFinalMethodStubbing() {
       
       // Given
      UserService mockUserService = mock(UserService.class);
      // Stub the final getUserDetails method using doReturn
      doReturn("Mock user details").when(mockUserService).getUserDetails("123");
      
      // When
      String details = mockUserService.getUserDetails("123");
      
      // Then
      assertEquals("Mock user details", details);
   }
}

In this example, the FinalMethodTest class uses Mockito’s doReturn method to stub a final method in the UserService class. The test verifies that the stubbed method returns the expected value.

Output

Conclusion

The doReturn method in Mockito is used for stubbing methods when the when method cannot be used. By using doReturn, you can set return values and handle consecutive calls for methods that are final, private, or otherwise constrained. This helps ensure that your tests are flexible and can handle a wide range of scenarios.