Mockito Cookbook: Over 65 recipes to get you up and running with unit testing using Mockito.

If you are using a dependency manager that connects to the Maven Central Repository, then you can get your dependencies as follows (examples of how to add mockito-all to your classpath for Maven and Gradle):

For Maven, use the following code:

        <dependency>
            <groupId>org.mockito</groupId>
            <artifactId>mockito-all</artifactId>
            <version>1.9.5</version>
            <scope>test</scope>
        </dependency>

For Gradle, use the following code:

testCompile "org.mockito:mockito-all:1.9.5"

If you are not using any of the dependency managers, you have to either download mockito-all.jar or mockito-core.jar and add it to your classpath manually (you can download the jars from https://code.google.com/p/mockito/downloads/list). To see more examples of adding Mockito to your classpath, please check the book, Instant Mockito, Marcin Grzejszczak, Packt Publishing, for more examples of adding Mockito to your classpath (it includes Ant, Buildr, Sbt, Ivy, Gradle, and Maven).

In order to add JUnit to your classpath, if you are using a dependency manager that connects to the Maven Central Repository, then you can get your dependencies as follows (examples for Maven and Gradle):

To add JUnit in Maven, use the following code:

<dependency>
  <groupId>junit</groupId>
  <artifactId>junit</artifactId>
  <version>4.11</version>
  <scope>test</scope>
</dependency>

To add JUnit in Gradle, use the following code:

testCompile('junit:junit:4.11')

If you are not using any of the dependency managers, you have to download the following jars:

Add the downloaded files to your classpath manually (you can download the jars from https://github.com/junit-team/junit/wiki/Download-and-Install).

For this recipe, our system under test will be a MeanTaxFactorCalculator class that will call an external service, TaxService, to get the current tax factor for the current user. It's a tax factor and not tax as such, since for simplicity, we will not be using BigDecimals but doubles, and I'd never suggest using doubles to anything related to money, as follows:

public class MeanTaxFactorCalculator {

    private final TaxService taxService;

    public MeanTaxFactorCalculator(TaxService taxService) {
        this.taxService = taxService;
    }

    public double calculateMeanTaxFactorFor(Person person) {
        double currentTaxFactor = taxService.getCurrentTaxFactorFor(person);
        double anotherTaxFactor = taxService.getCurrentTaxFactorFor(person);
        return (currentTaxFactor + anotherTaxFactor) / 2;
    }

}

To use Mockito's annotations, you have to perform the following steps:

The following snippet shows the JUnit and Mockito integration in a test class that verifies the SUT's behavior (remember that I'm using BDDMockito.given(...) and AssertJ's BDDAssertions.then(...) static methods; refer to Chapter 7, Verifying Behavior with Object Matchers, for how to work with AssertJ or how to do the same with Hamcrest's assertThat(...) method):

@RunWith(MockitoJUnitRunner.class)
public class MeanTaxFactorCalculatorTest {

    static final double TAX_FACTOR = 10;

    @Mock TaxService taxService;

    @InjectMocks MeanTaxFactorCalculator systemUnderTest;

    @Test
    public void should_calculate_mean_tax_factor() {
        // given
        given(taxService.getCurrentTaxFactorFor(any(Person.class))).willReturn(TAX_FACTOR);

        // when
        double meanTaxFactor = systemUnderTest.calculateMeanTaxFactorFor(new Person());

        // then
        then(meanTaxFactor).isEqualTo(TAX_FACTOR);
    }

}

The Mockito test runner will adapt its strategy depending on the version of JUnit. If there exists a org.junit.runners.BlockJUnit4ClassRunner class, it means that the codebase is using at least JUnit in Version 4.5.What eventually happens is that the MockitoAnnotations.initMocks(...) method is executed for the given test, which initializes all the Mockito annotations (for more information, check the subsequent There's more… section).

You may have a situation where your test class has already been annotated with a @RunWith annotation and, seemingly, you may not profit from Mockito's annotations. In order to achieve this, you have to call the MockitoAnnotations.initMocks method manually in the @Before annotated method of your test, as shown in the following code:

public class MeanTaxFactorCalculatorTest {

    static final double TAX_FACTOR = 10;

    @Mock TaxService taxService;

    @InjectMocks MeanTaxFactorCalculator systemUnderTest;

    @Before
    public void setup() {
        MockitoAnnotations.initMocks(this);
    }

    @Test
    public void should_calculate_mean_tax_factor() {
        // given
        given(taxService.getCurrentTaxFactorFor(Mockito.any(Person.class))).willReturn(TAX_FACTOR);

        // when
        double meanTaxFactor = systemUnderTest.calculateMeanTaxFactorFor(new Person());

        // then
        then(meanTaxFactor).isEqualTo(TAX_FACTOR);
    }

}

Mockito checks whether the user has overridden the global configuration of AnnotationEngine and, if this is not the case, the InjectingAnnotationEngine implementation is used to process annotations in tests. What is done internally is that the test class fields are scanned for annotations and proper test doubles are initialized and injected into the @InjectMocks annotated object (either by a constructor, property setter, or field injection, in that precise order).

When you take a look at Mockito's TestNG subproject on the Mockito GitHub repository, you will find that there are three classes in the org.mockito.testng package, as follows:

Unfortunately, until this project eventually gets released, you have to just copy and paste those classes to your codebase.

To integrate TestNG and Mockito, perform the following steps:

Now let's take a look at this snippet that, using TestNG, checks whether the mean tax factor value has been calculated properly (remember that I'm using the BDDMockito.given(...) and AssertJ's BDDAssertions.then(...) static methods—refer to Chapter 7, Verifying Behavior with Object Matchers, on how to work with Hamcrest assertThat(...) method):

@Listeners(MockitoTestNGListener.class)
public class MeanTaxFactorCalculatorTestNgTest {

    static final double TAX_FACTOR = 10;

    @Mock TaxService taxService;

    @InjectMocks MeanTaxFactorCalculator systemUnderTest;

    @Test
    public void should_calculate_mean_tax_factor() {
        // given
        given(taxService.getCurrentTaxFactorFor(any(Person.class))).willReturn(TAX_FACTOR);

        // when
        double meanTaxFactor = systemUnderTest.calculateMeanTaxFactorFor(new Person());

        // then
        then(meanTaxFactor).isEqualTo(TAX_FACTOR);
    }

}

TestNG allows you to register custom listeners (your listener class has to implement the IInvokedMethodListener interface). Once you do this, the logic inside the implemented methods will be executed before and after every configuration, and test methods get called. Mockito provides you with a listener whose responsibilities are as follows:

Let's assume that we have the following tax factor calculator that calculates a sum of two tax factors:

public class TaxFactorCalculator {

    public double calculateSum(double taxFactorOne, double taxFactorTwo) {
        return taxFactorOne + taxFactorTwo;
    }

}

After some time, it turned out that we read about a library that allows you to hide the implementation details of summing and you decided to rewrite your calculator to use this library. Now your code looks as follows:

public class TaxFactorCalculator {

    private final Calculator calculator;

    public TaxFactorCalculator(Calculator calculator) {
        this.calculator = calculator;
    }

    public double calculateSum(double taxFactorOne, double taxFactorTwo) {
        return calculator.add(taxFactorOne, taxFactorTwo);
    }

}

Since you want to test whether your system under test works fine, you should focus on the following points:

Let's take a look at a test of the first version of the class (I'm using the BDDMockito.given(...) and AssertJ's BDDAssertions.then(...) static methods—refer to Chapter 7, Verifying Behavior with Object Matchers, for how to work with AssertJ or how to do the same with Hamcrest's assertThat(...) method):

    @Test
    public void should_calculate_sum_of_factors() {
        // given
        TaxFactorCalculator systemUnderTest =new TaxFactorCalculator();
        double taxFactorOne = 1;
        double taxFactorTwo = 2;
        double expectedSum = 3;
        
        // when
        double sumOfFactors = systemUnderTest.calculateSum(taxFactorOne, taxFactorTwo);

        // then
        then(sumOfFactors).isEqualTo(expectedSum);
    }

As you can see, we are testing a class that should add two numbers and produce a result. We are not interested in how it is done—we want to check that the result is satisfactory. Now, assuming that our implementation changed—having a good test would require only to comply to the new way that our system under test is being initialized and the rest of the code remains untouched. In other words, change TaxFactorCalculator systemUnderTest = new TaxFactorCalculator() to TaxFactorCalculator systemUnderTest = new TaxFactorCalculator(new Calculator()). Moreover, since we are checking behavior and not the implementation, we don't have to refactor the test code at all.

For this recipe, let's assume that our system is the MeanTaxFactorCalculator class that calculates tax through TaxService, which has two methods—performAdditionalCalculation() and getCurrentTaxFactorFor(...). For the sake of this example, let's assume that only the latter is used to calculate the mean value:

public class MeanTaxFactorCalculator {

    private final TaxService taxService;

    public MeanTaxFactorCalculator(TaxService taxService) {
        this.taxService = taxService;
    }

    public double calculateMeanTaxFactorFor(Person person) {
        double currentTaxFactor = taxService.getCurrentTaxFactorFor(person);
        double anotherTaxFactor = taxService.getCurrentTaxFactorFor(person);
        return (currentTaxFactor + anotherTaxFactor) / 2;
    }

}

We wanted to check whether our system under test is calculating the proper result, so we wrote the following test but made a mistake and stubbed a wrong method (I'm using the BDDMockito.given(...) and AssertJ's BDDAssertions.then(...) static methods—refer Chapter 7, Verifying Behavior with Object Matchers, for how to work with AssertJ or how to do the same with Hamcrest's assertThat(...) method):

@RunWith(MockitoJUnitRunner.class)
public class MeanTaxFactorCalculatorTest {

    static final double UNUSED_VALUE = 10;

    @Test
    public void should_calculate_mean_tax_factor() {
        // given
        TaxService taxService = given(Mockito.mock(TaxService.class).performAdditionalCalculation()).willReturn(UNUSED_VALUE).getMock();
        MeanTaxFactorCalculator systemUnderTest =new MeanTaxFactorCalculator(taxService);

        // when
        double meanTaxFactor = systemUnderTest.calculateMeanTaxFactorFor(new Person());

        // then
        then(meanTaxFactor).isEqualTo(UNUSED_VALUE);
    }

}

The test fails and what we can see is the standard JUnit comparison failure being thrown (presenting only the most important part of the stack trace) as follows:

org.junit.ComparisonFailure:
Expected :10.0
Actual   :0.0

Now let's take a look at how to use Mockito's experimental features to get more Mockito related information appended to the error message.

If you want to have more information presented in your error message, you have to perform the following steps:

What happens next is that additional exception messages can be seen in the exception that is thrown as follows:

org.mockito.internal.exceptions.ExceptionIncludingMockitoWarnings:contains both: actual test failure *and* Mockito warnings.
This stubbing was never used   -> at ...MeanTaxFactorCalculatorTest.should_calculate_mean_tax_factor(MeanTaxFactorCalculatorTest.java:30)

 *** The actual failure is because of: ***

Expected :10.0
Actual   :0.0

When the test is run, VerboseMockitoJUnitRunner appends a listener. When the test is started, this listener finds all the stubs through WarningsCollector, including the unused stubs for given mocks.

As the Mockito developers state it in the code, they are indeed using a very hacky way to append a message to the thrown exception after the test fails. The JUnitFailureHacker class is instantiated and, by means of the Whitebox class, the internal state of a private field of the JUnit's Failure object is modified with additional Mockito messages.

If you want to have more information presented in your error message, you have to perform the following steps:

What happens then is that additional exception messages gets printed on the console after the exception that is thrown:

This stubbing was never used   -> at ....MeanTaxFactorCalculatorTest.should_calculate_mean_tax_factor(MeanTaxFactorCalculatorTest.java:25)

When the test is run, ConsoleSpammingMockitoJUnitRunner appends a listener that finds all the stubs through WarningsCollector, including the unused stubs for given mocks. When all of the warnings get collected, the ConsoleMockitoLogger class prints them to the console after the test has failed.