org.mockito
Class Mockito

This javadoc content is also available on the http://mockito.org web page.
All documentation is kept in javadocs because it guarantees consistency between what's on the web and what's in the source code.
Also, it makes possible to access documentation straight from the IDE even if you work offline.

Stubbing can be overridden: for example common stubbing can go to
fixture setup but the test methods can override it.
Please note that overridding stubbing is a potential code smell that points out too much stubbing

Once stubbed, the method will always return stubbed value regardless
of how many times it is called.

Last stubbing is more important - when you stubbed the same method with
the same arguments many times.

3. Argument matchers

Mockito verifies argument values in natural java style: by using an equals() method.
Sometimes, when extra flexibility is required then you might use argument matchers:

For information solely on custom argument matchers check out javadoc for ArgumentMatcher class.

Be reasonable with using complicated argument matching.
The natural matching style using equals() with occasional anyX() matchers tend to give clean & simple tests.
Sometimes it's just better to refactor the code to allow equals() matching or even implement equals() method to help out with testing.

If you are using argument matchers, all arguments have to be provided
by matchers.

E.g: (example shows verification but the same applies to stubbing):

verify(mock).someMethod(anyInt(), anyString(), eq("third argument"));
//above is correct - eq() is also an argument matcher
verify(mock).someMethod(anyInt(), anyString(), "third argument");
//above is incorrect - exception will be thrown because third argument is given without an argument matcher.

6. Verification in order

List firstMock = mock(List.class);
List secondMock = mock(List.class);
//using mocks
firstMock.add("was called first");
secondMock.add("was called second");
//create inOrder object passing any mocks that need to be verified in order
InOrder inOrder = inOrder(firstMock, secondMock);
//following will make sure that firstMock was called before secondMock
inOrder.verify(firstMock).add("was called first");
inOrder.verify(secondMock).add("was called second");

Verification in order is flexible - you don't have to verify all
interactions one-by-one but only those that you are interested in
testing in order.

Also, you can create InOrder object passing only mocks that are relevant for
in-order verification.

7. Making sure interaction(s) never happened on mock

//using mocks - only mockOne is interacted
mockOne.add("one");
//ordinary verification
verify(mockOne).add("one");
//verify that method was never called on a mock
verify(mockOne, never()).add("two");
//verify that other mocks were not interacted
verifyZeroInteractions(mockTwo, mockThree);

8. Finding redundant invocations

A word of warning:
Some users who did a lot of classic, expect-run-verify mocking tend to use verifyNoMoreInteractions() very often, even in every test method.
verifyNoMoreInteractions() is not recommended to use in every test method.
verifyNoMoreInteractions() is a handy assertion from the interaction testing toolkit. Use it only when it's relevant.
Abusing it leads to overspecified, less maintainable tests. You can find further reading
here.

See also never() - it is more explicit and
communicates the intent well.

9. Shorthand for mocks creation - @Mock annotation

Minimizes repetitive mock creation code.

Makes the test class more readable.

Makes the verification error easier to read because the field name
is used to identify the mock.

10. Stubbing consecutive calls (iterator-style stubbing)

Sometimes we need to stub with different return value/exception for the same
method call. Typical use case could be mocking iterators.
Original version of Mockito did not have this feature to promote simple mocking.
For example, instead of iterators one could use Iterable or simply
collections. Those offer natural ways of stubbing (e.g. using real
collections). In rare scenarios stubbing consecutive calls could be useful,
though:

11. Stubbing with callbacks

Yet another controversial feature which was not included in Mockito
originally. We recommend using simple stubbing with thenReturn() or
thenThrow() only. Those two should be just enough to test/test-drive
any clean & simple code.

13. Spying on real objects

You can create spies of real objects. When you use the spy then the real methods are called (unless a method was stubbed).

Real spies should be used carefully and occasionally, for example when dealing with legacy code.

Spying on real objects can be associated with "partial mocking" concept.
Before the release 1.8, Mockito spies were not real partial mocks.
The reason was we thought partial mock is a code smell.
At some point we found legitimate use cases for partial mocks
(3rd party interfaces, interim refactoring of legacy code, the full article is here)

Important gotcha on spying real objects!

List list = new LinkedList();
List spy = spy(list);
//Impossible: real method is called so spy.get(0) throws IndexOutOfBoundsException (the list is yet empty)
when(spy.get(0)).thenReturn("foo");
//You have to use doReturn() for stubbing
doReturn("foo").when(spy).get(0);

2. Watch out for final methods.
Mockito doesn't mock final methods so the bottom line is: when you spy on real objects + you try to stub a final method = trouble.
What will happen is the real method will be called *on mock* but *not on the real instance* you passed to the spy() method.
Typically you may get a NullPointerException because mock instances don't have fields initiated.

You can create a mock with specified strategy for its return values.
It's quite advanced feature and typically you don't need it to write decent tests.
However, it can be helpful for working with legacy systems.

It is the default answer so it will be used only when you don't stub the method call.

15. Capturing arguments for further assertions (Since 1.8.0)

Mockito verifies argument values in natural java style: by using an equals() method.
This is also the recommended way of matching arguments because it makes tests clean & simple.
In some situations though, it is helpful to assert on certain arguments after the actual verification.
For example:

Warning: it is recommended to use ArgumentCaptor with verification but not with stubbing.
Using ArgumentCaptor with stubbing may decrease test readability because captor is created outside of assert (aka verify or 'then') block.
Also it may reduce defect localization because if stubbed method was not called then no argument is captured.

In a way ArgumentCaptor is related to custom argument matchers (see javadoc for ArgumentMatcher class).
Both techniques can be used for making sure certain arguments where passed to mocks.
However, ArgumentCaptor may be a better fit if:

custom argument matcher is not likely to be reused

you just need it to assert on argument values to complete verification

Custom argument matchers via ArgumentMatcher are usually better for stubbing.

16. Real partial mocks (Since 1.8.0)

Finally, after many internal debates & discussions on the mailing list, partial mock support was added to Mockito.
Previously we considered partial mocks as code smells. However, we found a legitimate use case for partial mocks - more reading:
here

Before release 1.8 spy() was not producing real partial mocks and it was confusing for some users.
Read more about spying: here or in javadoc for spy(Object) method.

As usual you are going to read the partial mock warning:
Object oriented programming is more less tackling complexity by dividing the complexity into separate, specific, SRPy objects.
How does partial mock fit into this paradigm? Well, it just doesn't...
Partial mock usually means that the complexity has been moved to a different method on the same object.
In most cases, this is not the way you want to design your application.

However, there are rare cases when partial mocks come handy:
dealing with code you cannot change easily (3rd party interfaces, interim refactoring of legacy code etc.)
However, I wouldn't use partial mocks for new, test-driven & well-designed code.

17. Resetting mocks (Since 1.8.0)

Smart Mockito users hardly use this feature because they know it could be a sign of poor tests.
Normally, you don't need to reset your mocks, just create new mocks for each test method.

Instead of reset() please consider writing simple, small and focused test methods over lengthy, over-specified tests.
First potential code smell is reset() in the middle of the test method. This probably means you're testing too much.
Follow the whisper of your test methods: "Please keep us small & focused on single behavior".
There are several threads about it on mockito mailing list.

The only reason we added reset() method is to
make it possible to work with container-injected mocks.
See issue 55 (here)
or FAQ (here).

Don't harm yourself. reset() in the middle of the test method is a code smell (you're probably testing too much).

Next, you should know that Mockito validates if you use it correctly all the time.
However, there's a gotcha so please read the javadoc for validateMockitoUsage()

19. Aliases for behavior driven development (Since 1.8.0)

Behavior Driven Development style of writing tests uses //given //when //then comments as fundamental parts of your test methods.
This is exactly how we write our tests and we warmly encourage you to do so!

The problem is that current stubbing api with canonical role of when word does not integrate nicely with //given //when //then comments.
It's because stubbing belongs to given component of the test and not to the when component of the test.
Hence BDDMockito class introduces an alias so that you stub method calls with BDDMockito.given(Object) method.
Now it really nicely integrates with the given component of a BDD style test!

20. (**New**) Serializable mocks (Since 1.8.1)

Mocks can be made serializable. With this feature you can use a mock in a place that requires dependencies to be serializable.

WARNING: This should be rarely used in unit testing.

The behaviour was implemented for a specific use case of a BDD spec that had an unreliable external dependency. This
was in a web environment and the objects from the external dependency were being serialized to pass between layers.

Why it is deprecated? ReturnValues is being replaced by Answer
for better consistency & interoperability of the framework.
Answer interface has been in Mockito for a while and it has the same responsibility as ReturnValues.
There's no point in mainting exactly the same interfaces.

Creates mock with a specified strategy for its return values.
It's quite advanced feature and typically you don't need it to write decent tests.
However it can be helpful when working with legacy systems.

Obviously return values are used only when you don't stub the method call.

RETURNS_SMART_NULLS

Answer can be used to define the return values of unstubbed invocations.

This implementation can be helpful when working with legacy code.
Unstubbed methods often return null. If your code uses the object returned by an unstubbed call you get a NullPointerException.
This implementation of Answer returns SmartNull instead of null.
SmartNull gives nicer exception message than NPE because it points out the line where unstubbed method was called. You just click on the stack trace.

ReturnsSmartNulls first tries to return ordinary return values (see ReturnsMoreEmptyValues)
then it tries to return SmartNull. If the return type is final then plain null is returned.

ReturnsSmartNulls will be probably the default return values strategy in Mockito 2.0

Verification API does not support 'chaining' so deep stub doesn't change how you do verification.

WARNING:
This feature should rarely be required for regular clean code! Leave it for legacy code.
Mocking a mock to return a mock, to return a mock, (...), to return something meaningful
hints at violation of Law of Demeter or mocking a value object (a well known anti-pattern).

Good quote I've seen one day on the web: every time a mock returns a mock a fairy dies.

CALLS_REAL_METHODS

Answer can be used to define the return values of unstubbed invocations.

This implementation can be helpful when working with legacy code.
When this implementation is used, unstubbed methods will delegate to the real implementation.
This is a way to create a partial mock object that calls real methods by default.

As usual you are going to read the partial mock warning:
Object oriented programming is more less tackling complexity by dividing the complexity into separate, specific, SRPy objects.
How does partial mock fit into this paradigm? Well, it just doesn't...
Partial mock usually means that the complexity has been moved to a different method on the same object.
In most cases, this is not the way you want to design your application.

However, there are rare cases when partial mocks come handy:
dealing with code you cannot change easily (3rd party interfaces, interim refactoring of legacy code etc.)
However, I wouldn't use partial mocks for new, test-driven & well-designed code.

mock

Specifies mock name. Naming mocks can be helpful for debugging - the name is used in all verification errors.

Beware that naming mocks is not a solution for complex code which uses too many mocks or collaborators.
If you have too many mocks then refactor the code so that it's easy to test/debug without necessity of naming mocks.

If you use @Mock annotation then you've got naming mocks for free! @Mock uses field name as mock name. Read more.

mock

Why it is deprecated? ReturnValues is being replaced by Answer
for better consistency & interoperability of the framework.
Answer interface has been in Mockito for a while and it has the same responsibility as ReturnValues.
There's no point in mainting exactly the same interfaces.

Creates mock with a specified strategy for its return values.
It's quite advanced feature and typically you don't need it to write decent tests.
However it can be helpful when working with legacy systems.

Obviously return values are used only when you don't stub the method call.

mock

Creates mock with a specified strategy for its answers to interactions.
It's quite advanced feature and typically you don't need it to write decent tests.
However it can be helpful when working with legacy systems.

It is the default answer so it will be used only when you don't stub the method call.

Use it carefully and occasionally. What might be reason your test needs non-standard mocks?
Is the code under test so complicated that it requires non-standard mocks?
Wouldn't you prefer to refactor the code under test so it is testable in a simple way?

spy

Creates a spy of the real object. The spy calls real methods unless they are stubbed.

Real spies should be used carefully and occasionally, for example when dealing with legacy code.

As usual you are going to read the partial mock warning:
Object oriented programming is more less tackling complexity by dividing the complexity into separate, specific, SRPy objects.
How does partial mock fit into this paradigm? Well, it just doesn't...
Partial mock usually means that the complexity has been moved to a different method on the same object.
In most cases, this is not the way you want to design your application.

However, there are rare cases when partial mocks come handy:
dealing with code you cannot change easily (3rd party interfaces, interim refactoring of legacy code etc.)
However, I wouldn't use partial mocks for new, test-driven & well-designed code.

Important gotcha on spying real objects!

List list = new LinkedList();
List spy = spy(list);
//Impossible: real method is called so spy.get(0) throws IndexOutOfBoundsException (the list is yet empty)
when(spy.get(0)).thenReturn("foo");
//You have to use doReturn() for stubbing
doReturn("foo").when(spy).get(0);

2. Watch out for final methods.
Mockito doesn't mock final methods so the bottom line is: when you spy on real objects + you try to stub a final method = trouble.
What will happen is the real method will be called *on mock* but *not on the real instance* you passed to the spy() method.
Typically you may get a NullPointerException because mock instances don't have fields initiated.

Stubbing can be overridden: for example common stubbing can go to fixture
setup but the test methods can override it.
Please note that overridding stubbing is a potential code smell that points out too much stubbing.

Once stubbed, the method will always return stubbed value regardless
of how many times it is called.

Last stubbing is more important - when you stubbed the same method with
the same arguments many times.

Although it is possible to verify a stubbed invocation, usually it's just redundant.
Let's say you've stubbed foo.bar().
If your code cares what foo.bar() returns then something else breaks(often before even verify() gets executed).
If your code doesn't care what get(0) returns then it should not be stubbed.
Not convinced? See here.

Stubbing can be overridden: for example common stubbing can go to fixture
setup but the test methods can override it.
Please note that overridding stubbing is a potential code smell that points out too much stubbing.

Once stubbed, the method will always return stubbed value regardless
of how many times it is called.

Last stubbing is more important - when you stubbed the same method with
the same arguments many times.

Although it is possible to verify a stubbed invocation, usually it's just redundant.
Let's say you've stubbed foo.bar().
If your code cares what foo.bar() returns then something else breaks(often before even verify() gets executed).
If your code doesn't care what get(0) returns then it should not be stubbed.
Not convinced? See here.

Arguments passed are compared using equals() method.
Read about ArgumentCaptor or ArgumentMatcher to find out other ways of matching / asserting arguments passed.

Although it is possible to verify a stubbed invocation, usually it's just redundant.
Let's say you've stubbed foo.bar().
If your code cares what foo.bar() returns then something else breaks(often before even verify() gets executed).
If your code doesn't care what get(0) returns then it should not be stubbed.
Not convinced? See here.

verify

Verifies certain behavior happened at least once / exact number of times / never. E.g:

verify(mock, times(5)).someMethod("was called five times");
verify(mock, atLeast(2)).someMethod("was called at least two times");
//you can use flexible argument matchers, e.g:
verify(mock, atLeastOnce()).someMethod(anyString());

times(1) is the default and can be omitted

Arguments passed are compared using equals() method.
Read about ArgumentCaptor or ArgumentMatcher to find out other ways of matching / asserting arguments passed.

Parameters:

mock - to be verified

mode - times(x), atLeastOnce() or never()

Returns:

mock object itself

reset

public static <T> void reset(T... mocks)

Smart Mockito users hardly use this feature because they know it could be a sign of poor tests.
Normally, you don't need to reset your mocks, just create new mocks for each test method.

Instead of reset() please consider writing simple, small and focused test methods over lengthy, over-specified tests.
First potential code smell is reset() in the middle of the test method. This probably means you're testing too much.
Follow the whisper of your test methods: "Please keep us small & focused on single behavior".
There are several threads about it on mockito mailing list.

The only reason we added reset() method is to
make it possible to work with container-injected mocks.
See issue 55 (here)
or FAQ (here).

Don't harm yourself. reset() in the middle of the test method is a code smell (you're probably testing too much).

verifyNoMoreInteractions

You can use this method after you verified your mocks - to make sure that nothing
else was invoked on your mocks.

See also never() - it is more explicit and communicates the intent well.

Stubbed invocations (if called) are also treated as interactions.

A word of warning:
Some users who did a lot of classic, expect-run-verify mocking tend to use verifyNoMoreInteractions() very often, even in every test method.
verifyNoMoreInteractions() is not recommended to use in every test method.
verifyNoMoreInteractions() is a handy assertion from the interaction testing toolkit. Use it only when it's relevant.
Abusing it leads to overspecified, less maintainable tests. You can find further reading
here.

This method will also detect unverified invocations that occurred before the test method,
for example: in setUp(), @Before method or in constructor.
Consider writing nice code that makes interactions only in test methods.

verifyZeroInteractions

public static void verifyZeroInteractions(java.lang.Object... mocks)

Verifies that no interactions happened on given mocks.

verifyZeroInteractions(mockOne, mockTwo);

This method will also detect invocations
that occurred before the test method, for example: in setUp(), @Before method or in constructor.
Consider writing nice code that makes interactions only in test methods.

See also never() - it is more explicit and communicates the intent well.

doCallRealMethod

Use doCallRealMethod() when you want to call the real implementation of a method.

As usual you are going to read the partial mock warning:
Object oriented programming is more less tackling complexity by dividing the complexity into separate, specific, SRPy objects.
How does partial mock fit into this paradigm? Well, it just doesn't...
Partial mock usually means that the complexity has been moved to a different method on the same object.
In most cases, this is not the way you want to design your application.

However, there are rare cases when partial mocks come handy:
dealing with code you cannot change easily (3rd party interfaces, interim refactoring of legacy code etc.)
However, I wouldn't use partial mocks for new, test-driven & well-designed code.

See also javadoc spy(Object) to find out more about partial mocks.
Mockito.spy() is a recommended way of creating partial mocks.
The reason is it guarantees real methods are called against correctly constructed object because you're responsible for constructing the object passed to spy() method.

doReturn

Use doReturn() in those rare occasions when you cannot use when(Object).

Beware that when(Object) is always recommended for stubbing because it is argument type-safe
and more readable (especially when stubbing consecutive calls).

Here are those rare occasions when doReturn() comes handy:

1. When spying real objects and calling real methods on a spy brings side effects

List list = new LinkedList();
List spy = spy(list);
//Impossible: real method is called so spy.get(0) throws IndexOutOfBoundsException (the list is yet empty)
when(spy.get(0)).thenReturn("foo");
//You have to use doReturn() for stubbing:
doReturn("foo").when(spy).get(0);

2. Overriding a previous exception-stubbing:

when(mock.foo()).thenThrow(new RuntimeException());
//Impossible: the exception-stubbed foo() method is called so RuntimeException is thrown.
when(mock.foo()).thenReturn("bar");
//You have to use doReturn() for stubbing:
doReturn("bar").when(mock).foo();

Above scenarios shows a tradeoff of Mockito's ellegant syntax. Note that the scenarios are very rare, though.
Spying should be sporadic and overriding exception-stubbing is very rare. Not to mention that in general
overridding stubbing is a potential code smell that points out too much stubbing.

validateMockitoUsage() explicitly validates the framework state to detect invalid use of Mockito.
However, this feature is optional because Mockito validates the usage all the time... but there is a gotcha so read on.

Examples of incorrect use:

//Oups, someone forgot thenReturn() part:
when(mock.get());
//Oups, someone put the verified method call inside verify() where it should be outside:
verify(mock.execute());
//Oups, someone has used EasyMock for too long and forgot to specify the method to verify:
verify(mock);

Mockito throws exceptions if you misuse it so that you know if your tests are written correctly.
The gotcha is that Mockito does the validation next time you use the framework (e.g. next time you verify, stub, call mock etc.).
But even though the exception might be thrown in the next test,
the exception message contains a navigable stack trace element with location of the defect.
Hence you can click and find the place where Mockito was misused.

Sometimes though, you might want to validate the framework usage explicitly.
For example, one of the users wanted to put validateMockitoUsage() in his @After method
so that he knows immediately when he misused Mockito.
Without it, he would have known about it not sooner than next time he used the framework.
One more benefit of having validateMockitoUsage() in @After is that jUnit runner will always fail in the test method with defect
whereas ordinary 'next-time' validation might fail the next test method.
But even though JUnit might report next test as red, don't worry about it
and just click at navigable stack trace element in the exception message to instantly locate the place where you misused mockito.

Bear in mind that usually you don't have to validateMockitoUsage()
and framework validation triggered on next-time basis should be just enough,
mainly because of enhanced exception message with clickable location of defect.
However, I would recommend validateMockitoUsage() if you already have sufficient test infrastructure
(like your own runner or base class for all tests) because adding a special action to @After has zero cost.

MockSettings has been introduced for two reasons.
Firstly, to make it easy to add another mock settings when the demand comes.
Secondly, to enable combining different mock settings without introducing zillions of overloaded mock() methods.