Quick Guide to BDDMockito

1. Overview

The BDD term was coined first by Dan North – back in 2006.

BDD encourages writing tests in a natural, human-readable language that focuses on the behavior of the application.

It defines a clearly structured way of writing tests following three sections (Arrange, Act, Assert):

• given some preconditions (Arrange)
• when an action occurs (Act)
• then verify the output (Assert)

The Mockito library is shipped with a BDDMockito class which introduces BDD-friendly APIs. This API allows us to take a more BDD friendly approach arranging our tests using given() and making assertions using then().

In this article, we’re going to explain how to setup our BDD-based Mockito tests. We’ll also talk about differences between Mockito and BDDMockito APIs, to eventually focus on the BDDMockito API.

2. Setup

2.1. Maven Dependencies

The BDD flavor of Mockito is part of the mockito-core library, in order to get started we just need to include the artifact:

<dependency>
    <groupId>org.mockito</groupId>
    <artifactId>mockito-core</artifactId>
    <version>5.11.0</version>
</dependency>

For the latest version of Mockito please check Maven Central.

2.2. Imports

Our tests can become more readable if we include the following static import:

import static org.mockito.BDDMockito.*;

Notice that BDDMockito extends Mockito, so we won’t miss any feature provided by the traditional Mockito API.

3. Mockito vs. BDDMockito

The traditional mocking in Mockito is performed using when(obj).then*() in the Arrange step.

Later, interaction with our mock can be validated using verify() in the Assert step.

BDDMockito provides BDD aliases for various Mockito methods, so we can write our Arrange step using given (instead of when), likewise, we could write our Assert step using then (instead of verify).

Let’s look at an example of a test body using traditional Mockito:

when(phoneBookRepository.contains(momContactName))
  .thenReturn(false);
 
phoneBookService.register(momContactName, momPhoneNumber);
 
verify(phoneBookRepository)
  .insert(momContactName, momPhoneNumber);

Let’s see how that compares to BDDMockito:

given(phoneBookRepository.contains(momContactName))
  .willReturn(false);
 
phoneBookService.register(momContactName, momPhoneNumber);
 
then(phoneBookRepository)
  .should()
  .insert(momContactName, momPhoneNumber);

4. Mocking With BDDMockito

Let’s try to test the PhoneBookService where we’ll need to mock the PhoneBookRepository:

public class PhoneBookService {
    private PhoneBookRepository phoneBookRepository;

    public void register(String name, String phone) {
        if(!name.isEmpty() && !phone.isEmpty()
          && !phoneBookRepository.contains(name)) {
            phoneBookRepository.insert(name, phone);
        }
    }

    public String search(String name) {
        if(!name.isEmpty() && phoneBookRepository.contains(name)) {
            return phoneBookRepository.getPhoneNumberByContactName(name);
        }
        return null;
    }
}

BDDMockito as Mockito allows us to return a value that may be fixed or dynamic. It’d also allow us to throw an exception:

4.1. Returning a Fixed Value

Using BDDMockito, we could easily configure Mockito to return a fixed result whenever our mock object target method is invoked:

given(phoneBookRepository.contains(momContactName))
  .willReturn(false);
 
phoneBookService.register(xContactName, "");
 
then(phoneBookRepository)
  .should(never())
  .insert(momContactName, momPhoneNumber);

4.2. Returning a Dynamic Value

BDDMockito allows us to provide a more sophisticated way to return values. We could return a dynamic result based on the input:

given(phoneBookRepository.contains(momContactName))
  .willReturn(true);
given(phoneBookRepository.getPhoneNumberByContactName(momContactName))
  .will((InvocationOnMock invocation) ->
    invocation.getArgument(0).equals(momContactName) 
      ? momPhoneNumber 
      : null);
phoneBookService.search(momContactName);
then(phoneBookRepository)
  .should()
  .getPhoneNumberByContactName(momContactName);

4.3. Throwing an Exception

Telling Mockito to throw an exception is pretty straightforward:

given(phoneBookRepository.contains(xContactName))
  .willReturn(false);
willThrow(new RuntimeException())
  .given(phoneBookRepository)
  .insert(any(String.class), eq(tooLongPhoneNumber));

try {
    phoneBookService.register(xContactName, tooLongPhoneNumber);
    fail("Should throw exception");
} catch (RuntimeException ex) { }

then(phoneBookRepository)
  .should(never())
  .insert(momContactName, tooLongPhoneNumber);

Notice how we exchanged the positions of given and will*, that’s mandatory in case we’re mocking a method that has no return value.

Also notice that we used argument matchers like (any, eq) to provide a more generic way of mocking based on criteria rather than depending on a fixed value.

5. Conclusion

In this quick tutorial, we discussed how BDDMockito tries to bring a BDD resemblance to our Mockito tests, and we discussed some of the differences between Mockito and BDDMockito.