public class Mockito extends ArgumentMatchers
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. It allows access to documentation straight from the IDE even if you work offline. It motivates Mockito developers to keep documentation up-to-date with the code that they write, every day, with every commit.
@Mock
annotation doReturn()
|doThrow()
|doAnswer()
|doNothing()
|doCallRealMethod()
family of methods@Captor
, @Spy
, @InjectMocks
(Since 1.8.3) @Spies
, @InjectMocks
and constructor injection goodness (Since 1.9.0)MockMaker
API (Since 1.9.5)MockitoSession
is usable by testing frameworks (Since 2.15.+)org.mockito.plugins.InstantiatorProvider
as it was leaking internal API. it was replaced by org.mockito.plugins.InstantiatorProvider2 (Since 2.15.4)
Mockito.lenient()
and MockSettings.lenient()
methods (Since 2.20.0)
repositories {
jcenter()
}
dependencies {
testCompile "org.mockito:mockito-core:+"
androidTestCompile "org.mockito:mockito-android:+"
}
You can continue to run the same unit tests on a regular VM by using the `mockito-core` artifact in your "testCompile" scope as shown
above. Be aware that you cannot use the inline mock maker on Android due to limitations in the Android VM.
If you encounter issues with mocking on Android, please open an issue
on the official issue tracker.
Do provide the version of Android you are working on and dependencies of your project.
repositories {
jcenter()
}
dependencies {
testCompile "org.mockito:mockito-inline:+"
}
Be aware that this artifact may be abolished when the inline mock making feature is integrated into the default mock maker.
For more information about inline mock making, see section 39.
add()
, get()
, clear()
methods).
//Let's import Mockito statically so that the code looks clearer
import static org.mockito.Mockito.*;
//mock creation
List mockedList = mock(List.class);
//using mock object
mockedList.add("one");
mockedList.clear();
//verification
verify(mockedList).add("one");
verify(mockedList).clear();
Once created, a mock will remember all interactions. Then you can selectively verify whatever interactions you are interested in.
//You can mock concrete classes, not just interfaces
LinkedList mockedList = mock(LinkedList.class);
//stubbing
when(mockedList.get(0)).thenReturn("first");
when(mockedList.get(1)).thenThrow(new RuntimeException());
//following prints "first"
System.out.println(mockedList.get(0));
//following throws runtime exception
System.out.println(mockedList.get(1));
//following prints "null" because get(999) was not stubbed
System.out.println(mockedList.get(999));
//Although it is possible to verify a stubbed invocation, usually it's just redundant
//If your code cares what get(0) returns, then something else breaks (often even before verify() gets executed).
//If your code doesn't care what get(0) returns, then it should not be stubbed.
verify(mockedList).get(0);
equals()
method.
Sometimes, when extra flexibility is required then you might use argument matchers:
//stubbing using built-in anyInt() argument matcher
when(mockedList.get(anyInt())).thenReturn("element");
//stubbing using custom matcher (let's say isValid() returns your own matcher implementation):
when(mockedList.contains(argThat(isValid()))).thenReturn(true);
//following prints "element"
System.out.println(mockedList.get(999));
//you can also verify using an argument matcher
verify(mockedList).get(anyInt());
//argument matchers can also be written as Java 8 Lambdas
verify(mockedList).add(argThat(someString -> someString.length() > 5));
Argument matchers allow flexible verification or stubbing.
Click here
or here
to see more built-in matchers
and examples of custom argument matchers / hamcrest 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.
Also, read section 15 or javadoc for ArgumentCaptor
class.
ArgumentCaptor
is a special implementation of an argument matcher that captures argument values for further assertions.
Warning on argument matchers:
If you are using argument matchers, all arguments have to be provided by matchers.
The following 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.
Matcher methods like anyObject()
, eq()
do not return matchers.
Internally, they record a matcher on a stack and return a dummy value (usually null).
This implementation is due to static type safety imposed by the java compiler.
The consequence is that you cannot use anyObject()
, eq()
methods outside of verified/stubbed method.
//using mock
mockedList.add("once");
mockedList.add("twice");
mockedList.add("twice");
mockedList.add("three times");
mockedList.add("three times");
mockedList.add("three times");
//following two verifications work exactly the same - times(1) is used by default
verify(mockedList).add("once");
verify(mockedList, times(1)).add("once");
//exact number of invocations verification
verify(mockedList, times(2)).add("twice");
verify(mockedList, times(3)).add("three times");
//verification using never(). never() is an alias to times(0)
verify(mockedList, never()).add("never happened");
//verification using atLeast()/atMost()
verify(mockedList, atMostOnce()).add("once");
verify(mockedList, atLeastOnce()).add("three times");
verify(mockedList, atLeast(2)).add("three times");
verify(mockedList, atMost(5)).add("three times");
times(1) is the default. Therefore using times(1) explicitly can be omitted.
doThrow(new RuntimeException()).when(mockedList).clear();
//following throws RuntimeException:
mockedList.clear();
Read more about doThrow()
|doAnswer()
family of methods in section 12.
// A. Single mock whose methods must be invoked in a particular order
List singleMock = mock(List.class);
//using a single mock
singleMock.add("was added first");
singleMock.add("was added second");
//create an inOrder verifier for a single mock
InOrder inOrder = inOrder(singleMock);
//following will make sure that add is first called with "was added first", then with "was added second"
inOrder.verify(singleMock).add("was added first");
inOrder.verify(singleMock).add("was added second");
// B. Multiple mocks that must be used in a particular 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");
// Oh, and A + B can be mixed together at will
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 an InOrder object passing only the mocks that are relevant for in-order verification.
//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);
//using mocks
mockedList.add("one");
mockedList.add("two");
verify(mockedList).add("one");
//following verification will fail
verifyNoMoreInteractions(mockedList);
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.
See also never()
- it is more explicit and
communicates the intent well.
@Mock
annotation
public class ArticleManagerTest {
@Mock private ArticleCalculator calculator;
@Mock private ArticleDatabase database;
@Mock private UserProvider userProvider;
private ArticleManager manager;
Modifier and Type | Field and Description |
---|---|
static Answer<Object> |
CALLS_REAL_METHODS
Optional
Answer to be used with mock(Class, Answer) |
static Answer<Object> |
RETURNS_DEEP_STUBS
Optional
Answer to be used with mock(Class, Answer) . |
static Answer<Object> |
RETURNS_DEFAULTS
The default
Answer of every mock if the mock was not stubbed. |
static Answer<Object> |
RETURNS_MOCKS
Optional
Answer to be used with mock(Class, Answer) |
static Answer<Object> |
RETURNS_SELF
Optional
Answer to be used with mock(Class, Answer) . |
static Answer<Object> |
RETURNS_SMART_NULLS
Optional
Answer to be used with mock(Class, Answer) . |
Constructor and Description |
---|
Mockito() |
Modifier and Type | Method and Description |
---|---|
static VerificationAfterDelay |
after(long millis)
Verification will be triggered after given amount of millis, allowing testing of async code.
|
static VerificationMode |
atLeast(int minNumberOfInvocations)
Allows at-least-x verification.
|
static VerificationMode |
atLeastOnce()
Allows at-least-once verification.
|
static VerificationMode |
atMost(int maxNumberOfInvocations)
Allows at-most-x verification.
|
static VerificationMode |
atMostOnce()
Allows at-most-once verification.
|
static VerificationMode |
calls(int wantedNumberOfInvocations)
Allows non-greedy verification in order.
|
static <T> void |
clearInvocations(T... mocks)
Use this method in order to only clear invocations, when stubbing is non-trivial.
|
static VerificationMode |
description(String description)
Adds a description to be printed if verification fails.
|
static Stubber |
doAnswer(Answer answer)
Use
doAnswer() when you want to stub a void method with generic Answer . |
static Stubber |
doCallRealMethod()
Use
doCallRealMethod() when you want to call the real implementation of a method. |
static Stubber |
doNothing()
Use
doNothing() for setting void methods to do nothing. |
static Stubber |
doReturn(Object toBeReturned)
Use
doReturn() in those rare occasions when you cannot use when(Object) . |
static Stubber |
doReturn(Object toBeReturned,
Object... toBeReturnedNext)
Same as
doReturn(Object) but sets consecutive values to be returned. |
static Stubber |
doThrow(Class<? extends Throwable> toBeThrown)
Use
doThrow() when you want to stub the void method with an exception. |
static Stubber |
doThrow(Class<? extends Throwable> toBeThrown,
Class<? extends Throwable>... toBeThrownNext)
Same as
doThrow(Class) but sets consecutive exception classes to be thrown. |
static Stubber |
doThrow(Throwable... toBeThrown)
Use
doThrow() when you want to stub the void method with an exception. |
static MockitoFramework |
framework()
For advanced users or framework integrators.
|
static Object[] |
ignoreStubs(Object... mocks)
Ignores stubbed methods of given mocks for the sake of verification.
|
static InOrder |
inOrder(Object... mocks)
Creates
InOrder object that allows verifying mocks in order. |
static LenientStubber |
lenient()
Lenient stubs bypass "strict stubbing" validation (see
Strictness.STRICT_STUBS ). |
static <T> T |
mock(Class<T> classToMock)
Creates mock object of given class or interface.
|
static <T> T |
mock(Class<T> classToMock,
Answer defaultAnswer)
Creates mock with a specified strategy for its answers to interactions.
|
static <T> T |
mock(Class<T> classToMock,
MockSettings mockSettings)
Creates a mock with some non-standard settings.
|
static <T> T |
mock(Class<T> classToMock,
String name)
Specifies mock name.
|
static MockingDetails |
mockingDetails(Object toInspect)
Returns a MockingDetails instance that enables inspecting a particular object for Mockito related information.
|
static MockitoSessionBuilder |
mockitoSession()
MockitoSession is an optional, highly recommended feature
that helps driving cleaner tests by eliminating boilerplate code and adding extra validation. |
static <T> MockedStatic<T> |
mockStatic(Class<T> classToMock)
Creates a thread-local mock controller for all static methods of the given class or interface.
|
static <T> MockedStatic<T> |
mockStatic(Class<T> classToMock,
Answer defaultAnswer)
Creates a thread-local mock controller for all static methods of the given class or interface.
|
static <T> MockedStatic<T> |
mockStatic(Class<T> classToMock,
MockSettings mockSettings)
Creates a thread-local mock controller for all static methods of the given class or interface.
|
static <T> MockedStatic<T> |
mockStatic(Class<T> classToMock,
String name)
Creates a thread-local mock controller for all static methods of the given class or interface.
|
static VerificationMode |
never()
Alias to
times(0) , see times(int) |
static VerificationMode |
only()
Allows checking if given method was the only one invoked.
|
static <T> void |
reset(T... mocks)
Smart Mockito users hardly use this feature because they know it could be a sign of poor tests.
|
static <T> T |
spy(Class<T> classToSpy)
Please refer to the documentation of
spy(Object) . |
static <T> T |
spy(T object)
Creates a spy of the real object.
|
static VerificationWithTimeout |
timeout(long millis)
Verification will be triggered over and over until the given amount of millis, allowing testing of async code.
|
static VerificationMode |
times(int wantedNumberOfInvocations)
Allows verifying exact number of invocations.
|
static void |
validateMockitoUsage()
First of all, in case of any trouble, I encourage you to read the Mockito FAQ: https://github.com/mockito/mockito/wiki/FAQ
|
static <T> T |
verify(T mock)
Verifies certain behavior happened once.
|
static <T> T |
verify(T mock,
VerificationMode mode)
Verifies certain behavior happened at least once / exact number of times / never.
|
static void |
verifyNoInteractions(Object... mocks)
Verifies that no interactions happened on given mocks.
|
static void |
verifyNoMoreInteractions(Object... mocks)
Checks if any of given mocks has any unverified interaction.
|
static void |
verifyZeroInteractions(Object... mocks)
Deprecated.
Since 3.0.1. Please migrate your code to
verifyNoInteractions(Object...) |
static <T> OngoingStubbing<T> |
when(T methodCall)
Enables stubbing methods.
|
static MockSettings |
withSettings()
Allows mock creation with additional mock settings.
|
any, any, anyBoolean, anyByte, anyChar, anyCollection, anyCollectionOf, anyDouble, anyFloat, anyInt, anyIterable, anyIterableOf, anyList, anyListOf, anyLong, anyMap, anyMapOf, anyObject, anySet, anySetOf, anyShort, anyString, anyVararg, argThat, booleanThat, byteThat, charThat, contains, doubleThat, endsWith, eq, eq, eq, eq, eq, eq, eq, eq, eq, floatThat, intThat, isA, isNotNull, isNotNull, isNull, isNull, longThat, matches, matches, notNull, notNull, nullable, refEq, same, shortThat, startsWith
public static final Answer<Object> RETURNS_DEFAULTS
Answer
of every mock if the mock was not stubbed.
Typically it just returns some empty value.
Answer
can be used to define the return values of unstubbed invocations.
This implementation first tries the global configuration and if there is no global configuration then it will use a default answer that returns zeros, empty collections, nulls, etc.
public static final Answer<Object> RETURNS_SMART_NULLS
Answer
to be used with mock(Class, Answer)
.
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 values (zeros, empty collections, empty string, etc.)
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 4.0.0
Example:
Foo mock = mock(Foo.class, RETURNS_SMART_NULLS);
//calling unstubbed method here:
Stuff stuff = mock.getStuff();
//using object returned by unstubbed call:
stuff.doSomething();
//Above doesn't yield NullPointerException this time!
//Instead, SmartNullPointerException is thrown.
//Exception's cause links to unstubbed mock.getStuff() - just click on the stack trace.
public static final Answer<Object> RETURNS_MOCKS
Answer
to be used with mock(Class, Answer)
Answer
can be used to define the return values of unstubbed invocations.
This implementation can be helpful when working with legacy code.
ReturnsMocks first tries to return ordinary values (zeros, empty collections, empty string, etc.)
then it tries to return mocks. If the return type cannot be mocked (e.g. is final) then plain null
is returned.
public static final Answer<Object> RETURNS_DEEP_STUBS
Answer
to be used with mock(Class, Answer)
.
Example that shows how deep stub works:
Foo mock = mock(Foo.class, RETURNS_DEEP_STUBS);
// note that we're stubbing a chain of methods here: getBar().getName()
when(mock.getBar().getName()).thenReturn("deep");
// note that we're chaining method calls: getBar().getName()
assertEquals("deep", mock.getBar().getName());
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.
Please note that this answer will return existing mocks that matches the stub. This behavior is ok with deep stubs and allows verification to work on the last mock of the chain.
when(mock.getBar(anyString()).getThingy().getName()).thenReturn("deep");
mock.getBar("candy bar").getThingy().getName();
assertSame(mock.getBar(anyString()).getThingy().getName(), mock.getBar(anyString()).getThingy().getName());
verify(mock.getBar("candy bar").getThingy()).getName();
verify(mock.getBar(anyString()).getThingy()).getName();
Verification only works with the last mock in the chain. You can use verification modes.
when(person.getAddress(anyString()).getStreet().getName()).thenReturn("deep");
when(person.getAddress(anyString()).getStreet(Locale.ITALIAN).getName()).thenReturn("deep");
when(person.getAddress(anyString()).getStreet(Locale.CHINESE).getName()).thenReturn("deep");
person.getAddress("the docks").getStreet().getName();
person.getAddress("the docks").getStreet().getLongName();
person.getAddress("the docks").getStreet(Locale.ITALIAN).getName();
person.getAddress("the docks").getStreet(Locale.CHINESE).getName();
// note that we are actually referring to the very last mock in the stubbing chain.
InOrder inOrder = inOrder(
person.getAddress("the docks").getStreet(),
person.getAddress("the docks").getStreet(Locale.CHINESE),
person.getAddress("the docks").getStreet(Locale.ITALIAN)
);
inOrder.verify(person.getAddress("the docks").getStreet(), times(1)).getName();
inOrder.verify(person.getAddress("the docks").getStreet()).getLongName();
inOrder.verify(person.getAddress("the docks").getStreet(Locale.ITALIAN), atLeast(1)).getName();
inOrder.verify(person.getAddress("the docks").getStreet(Locale.CHINESE)).getName();
How deep stub work internally?
//this:
Foo mock = mock(Foo.class, RETURNS_DEEP_STUBS);
when(mock.getBar().getName(), "deep");
//is equivalent of
Foo foo = mock(Foo.class);
Bar bar = mock(Bar.class);
when(foo.getBar()).thenReturn(bar);
when(bar.getName()).thenReturn("deep");
This feature will not work when any return type of methods included in the chain cannot be mocked (for example: is a primitive or a final class). This is because of java type system.
public static final Answer<Object> CALLS_REAL_METHODS
Answer
to be used with mock(Class, Answer)
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.
Example:
Foo mock = mock(Foo.class, CALLS_REAL_METHODS);
// this calls the real implementation of Foo.getSomething()
value = mock.getSomething();
doReturn(fakeValue).when(mock).getSomething();
// now fakeValue is returned
value = mock.getSomething();
Note 1: Stubbing partial mocks using when(mock.getSomething()).thenReturn(fakeValue)
syntax will call the real method. For partial mock it's recommended to use doReturn
syntax.
Note 2: If the mock is serialized then deserialized, then this answer will not be able to understand generics metadata.
public static final Answer<Object> RETURNS_SELF
Answer
to be used with mock(Class, Answer)
.
Allows Builder mocks to return itself whenever a method is invoked that returns a Type equal
to the class or a superclass.
Keep in mind this answer uses the return type of a method.
If this type is assignable to the class of the mock, it will return the mock.
Therefore if you have a method returning a superclass (for example Object
) it will match and return the mock.
public class HttpRequesterWithHeaders {
private HttpBuilder builder;
public HttpRequesterWithHeaders(HttpBuilder builder) {
this.builder = builder;
}
public String request(String uri) {
return builder.withUrl(uri)
.withHeader("Content-type: application/json")
.withHeader("Authorization: Bearer")
.request();
}
}
private static class HttpBuilder {
private String uri;
private List<String> headers;
public HttpBuilder() {
this.headers = new ArrayList<String>();
}
public HttpBuilder withUrl(String uri) {
this.uri = uri;
return this;
}
public HttpBuilder withHeader(String header) {
this.headers.add(header);
return this;
}
public String request() {
return uri + headers.toString();
}
}
The following test will succeed
@Test
public void use_full_builder_with_terminating_method() {
HttpBuilder builder = mock(HttpBuilder.class, RETURNS_SELF);
HttpRequesterWithHeaders requester = new HttpRequesterWithHeaders(builder);
String response = "StatusCode: 200";
when(builder.request()).thenReturn(response);
assertThat(requester.request("URI")).isEqualTo(response);
}
public static <T> T mock(Class<T> classToMock)
See examples in javadoc for Mockito
class
classToMock
- class or interface to mockpublic static <T> T mock(Class<T> classToMock, String name)
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.
See examples in javadoc for Mockito
class
classToMock
- class or interface to mockname
- of the mockpublic static MockingDetails mockingDetails(Object toInspect)
In future Mockito versions MockingDetails may grow and provide other useful information about the mock, e.g. invocations, stubbing info, etc.
toInspect
- - object to inspect. null input is allowed.MockingDetails
instance.public static <T> T mock(Class<T> classToMock, Answer defaultAnswer)
It is the default answer so it will be used only when you don't stub the method call.
Foo mock = mock(Foo.class, RETURNS_SMART_NULLS);
Foo mockTwo = mock(Foo.class, new YourOwnAnswer());
See examples in javadoc for Mockito
class
classToMock
- class or interface to mockdefaultAnswer
- default answer for unstubbed methodspublic static <T> T mock(Class<T> classToMock, MockSettings mockSettings)
The number of configuration points for a mock grows
so we need a fluent way to introduce new configuration without adding more and more overloaded Mockito.mock() methods.
Hence MockSettings
.
Listener mock = mock(Listener.class, withSettings()
.name("firstListner").defaultBehavior(RETURNS_SMART_NULLS));
);
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?
See also withSettings()
See examples in javadoc for Mockito
class
classToMock
- class or interface to mockmockSettings
- additional mock settingspublic static <T> T spy(T object)
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 tackles 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.
Example:
List list = new LinkedList();
List spy = spy(list);
//optionally, you can stub out some methods:
when(spy.size()).thenReturn(100);
//using the spy calls real methods
spy.add("one");
spy.add("two");
//prints "one" - the first element of a list
System.out.println(spy.get(0));
//size() method was stubbed - 100 is printed
System.out.println(spy.size());
//optionally, you can verify
verify(spy).add("one");
verify(spy).add("two");
when(Object)
for stubbing spies.
Therefore for spies it is recommended to always use doReturn
|Answer
|Throw()
|CallRealMethod
family of methods for stubbing. Example:
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);
See examples in javadoc for Mockito
class
Note that the spy won't have any annotations of the spied type, because CGLIB won't rewrite them. It may troublesome for code that rely on the spy to have these annotations.
object
- to spy on@Incubating public static <T> T spy(Class<T> classToSpy)
spy(Object)
.
Overusing spies hints at code design smells.
This method, in contrast to the original spy(Object)
, creates a spy based on class instead of an object.
Sometimes it is more convenient to create spy based on the class and avoid providing an instance of a spied object.
This is particularly useful for spying on abstract classes because they cannot be instantiated.
See also MockSettings.useConstructor(Object...)
.
Examples:
SomeAbstract spy = spy(SomeAbstract.class);
//Robust API, via settings builder:
OtherAbstract spy = mock(OtherAbstract.class, withSettings()
.useConstructor().defaultAnswer(CALLS_REAL_METHODS));
//Mocking a non-static inner abstract class:
InnerAbstract spy = mock(InnerAbstract.class, withSettings()
.useConstructor().outerInstance(outerInstance).defaultAnswer(CALLS_REAL_METHODS));
T
- type of the spyclassToSpy
- the class to spy@Incubating public static <T> MockedStatic<T> mockStatic(Class<T> classToMock)
MockedStatic.close()
method must be called upon completing the
test or the mock will remain active on the current thread.
Note: We recommend against mocking static methods of classes in the standard library or classes used by custom class loaders used to executed the block with the mocked class. A mock maker might forbid mocking static methods of know classes that are known to cause problems. Also, if a static method is a JVM-intrinsic, it cannot typically be mocked even if not explicitly forbidden.
See examples in javadoc for Mockito
class
classToMock
- class or interface of which static mocks should be mocked.@Incubating public static <T> MockedStatic<T> mockStatic(Class<T> classToMock, Answer defaultAnswer)
MockedStatic.close()
method must be called upon completing the
test or the mock will remain active on the current thread.
Note: We recommend against mocking static methods of classes in the standard library or classes used by custom class loaders used to executed the block with the mocked class. A mock maker might forbid mocking static methods of know classes that are known to cause problems. Also, if a static method is a JVM-intrinsic, it cannot typically be mocked even if not explicitly forbidden.
See examples in javadoc for Mockito
class
classToMock
- class or interface of which static mocks should be mocked.defaultAnswer
- the default answer when invoking static methods.@Incubating public static <T> MockedStatic<T> mockStatic(Class<T> classToMock, String name)
MockedStatic.close()
method must be called upon completing the
test or the mock will remain active on the current thread.
Note: We recommend against mocking static methods of classes in the standard library or classes used by custom class loaders used to executed the block with the mocked class. A mock maker might forbid mocking static methods of know classes that are known to cause problems. Also, if a static method is a JVM-intrinsic, it cannot typically be mocked even if not explicitly forbidden.
See examples in javadoc for Mockito
class
classToMock
- class or interface of which static mocks should be mocked.name
- the name of the mock to use in error messages.@Incubating public static <T> MockedStatic<T> mockStatic(Class<T> classToMock, MockSettings mockSettings)
MockedStatic.close()
method must be called upon completing the
test or the mock will remain active on the current thread.
Note: We recommend against mocking static methods of classes in the standard library or classes used by custom class loaders used to executed the block with the mocked class. A mock maker might forbid mocking static methods of know classes that are known to cause problems. Also, if a static method is a JVM-intrinsic, it cannot typically be mocked even if not explicitly forbidden.
See examples in javadoc for Mockito
class
classToMock
- class or interface of which static mocks should be mocked.mockSettings
- the settings to use where only name and default answer are considered.public static <T> OngoingStubbing<T> when(T methodCall)
Simply put: "When the x method is called then return y".
Examples:
when(mock.someMethod()).thenReturn(10);
//you can use flexible argument matchers, e.g:
when(mock.someMethod(anyString())).thenReturn(10);
//setting exception to be thrown:
when(mock.someMethod("some arg")).thenThrow(new RuntimeException());
//you can set different behavior for consecutive method calls.
//Last stubbing (e.g: thenReturn("foo")) determines the behavior of further consecutive calls.
when(mock.someMethod("some arg"))
.thenThrow(new RuntimeException())
.thenReturn("foo");
//Alternative, shorter version for consecutive stubbing:
when(mock.someMethod("some arg"))
.thenReturn("one", "two");
//is the same as:
when(mock.someMethod("some arg"))
.thenReturn("one")
.thenReturn("two");
//shorter version for consecutive method calls throwing exceptions:
when(mock.someMethod("some arg"))
.thenThrow(new RuntimeException(), new NullPointerException();
For stubbing void methods with throwables see: doThrow(Throwable...)
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.
See examples in javadoc for Mockito
class
methodCall
- method to be stubbedpublic static <T> T verify(T mock)
Alias to verify(mock, times(1))
E.g:
verify(mock).someMethod("some arg");
Above is equivalent to:
verify(mock, times(1)).someMethod("some arg");
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.
See examples in javadoc for Mockito
class
mock
- to be verifiedpublic static <T> T verify(T mock, VerificationMode mode)
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.
mock
- to be verifiedmode
- times(x), atLeastOnce() or never()public static <T> void reset(T... mocks)
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.
For more information see the FAQ (here).
Don't harm yourself. reset()
in the middle of the test method is a code smell (you're probably testing too much).
List mock = mock(List.class);
when(mock.size()).thenReturn(10);
mock.add(1);
reset(mock);
//at this point the mock forgot any interactions & stubbing
T
- The Type of the mocksmocks
- to be resetpublic static <T> void clearInvocations(T... mocks)
T
- The type of the mocksmocks
- The mocks to clear the invocations forpublic static void verifyNoMoreInteractions(Object... mocks)
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.
If you want stubbed invocations automatically verified, check out Strictness.STRICT_STUBS
feature
introduced in Mockito 2.3.0.
If you want to ignore stubs for verification, see ignoreStubs(Object...)
.
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.
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.
Example:
//interactions
mock.doSomething();
mock.doSomethingUnexpected();
//verification
verify(mock).doSomething();
//following will fail because 'doSomethingUnexpected()' is unexpected
verifyNoMoreInteractions(mock);
See examples in javadoc for Mockito
classmocks
- to be verified@Deprecated public static void verifyZeroInteractions(Object... mocks)
verifyNoInteractions(Object...)
verifyNoMoreInteractions(Object...)
.mocks
- to be verifiedpublic static void verifyNoInteractions(Object... mocks)
verifyNoInteractions(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.
See examples in javadoc for Mockito
class
mocks
- to be verifiedpublic static Stubber doThrow(Throwable... toBeThrown)
doThrow()
when you want to stub the void method with an exception.
Stubbing voids requires different approach from when(Object)
because the compiler
does not like void methods inside brackets...
Example:
doThrow(new RuntimeException()).when(mock).someVoidMethod();
toBeThrown
- to be thrown when the stubbed method is calledpublic static Stubber doThrow(Class<? extends Throwable> toBeThrown)
doThrow()
when you want to stub the void method with an exception.
A new exception instance will be created for each method invocation.
Stubbing voids requires different approach from when(Object)
because the compiler
does not like void methods inside brackets...
Example:
doThrow(RuntimeException.class).when(mock).someVoidMethod();
toBeThrown
- to be thrown when the stubbed method is calledpublic static Stubber doThrow(Class<? extends Throwable> toBeThrown, Class<? extends Throwable>... toBeThrownNext)
doThrow(Class)
but sets consecutive exception classes to be thrown. Remember to use
doThrow()
when you want to stub the void method to throw several exception of specified class.
A new exception instance will be created for each method invocation.
Stubbing voids requires different approach from when(Object)
because the compiler
does not like void methods inside brackets...
Example:
doThrow(RuntimeException.class, BigFailure.class).when(mock).someVoidMethod();
toBeThrown
- to be thrown when the stubbed method is calledtoBeThrownNext
- next to be thrown when the stubbed method is calledpublic static Stubber doCallRealMethod()
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.
Example:
Foo mock = mock(Foo.class);
doCallRealMethod().when(mock).someVoidMethod();
// this will call the real implementation of Foo.someVoidMethod()
mock.someVoidMethod();
See examples in javadoc for Mockito
class
public static Stubber doAnswer(Answer answer)
doAnswer()
when you want to stub a void method with generic Answer
.
Stubbing voids requires different approach from when(Object)
because the compiler does not like void methods inside brackets...
Example:
doAnswer(new Answer() {
public Object answer(InvocationOnMock invocation) {
Object[] args = invocation.getArguments();
Mock mock = invocation.getMock();
return null;
}})
.when(mock).someMethod();
See examples in javadoc for Mockito
class
answer
- to answer when the stubbed method is calledpublic static Stubber doNothing()
doNothing()
for setting void methods to do nothing. Beware that void methods on mocks do nothing by default!
However, there are rare situations when doNothing() comes handy:
doNothing().
doThrow(new RuntimeException())
.when(mock).someVoidMethod();
//does nothing the first time:
mock.someVoidMethod();
//throws RuntimeException the next time:
mock.someVoidMethod();
List list = new LinkedList();
List spy = spy(list);
//let's make clear() do nothing
doNothing().when(spy).clear();
spy.add("one");
//clear() does nothing, so the list still contains "one"
spy.clear();
See examples in javadoc for Mockito
class
public static Stubber doReturn(Object toBeReturned)
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:
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);
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();
See examples in javadoc for Mockito
class
toBeReturned
- to be returned when the stubbed method is calledpublic static Stubber doReturn(Object toBeReturned, Object... toBeReturnedNext)
doReturn(Object)
but sets consecutive values to be returned. Remember to 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:
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", "bar", "qix");
//You have to use doReturn() for stubbing:
doReturn("foo", "bar", "qix").when(spy).get(0);
when(mock.foo()).thenThrow(new RuntimeException());
//Impossible: the exception-stubbed foo() method is called so RuntimeException is thrown.
when(mock.foo()).thenReturn("bar", "foo", "qix");
//You have to use doReturn() for stubbing:
doReturn("bar", "foo", "qix").when(mock).foo();
See examples in javadoc for Mockito
class
toBeReturned
- to be returned when the stubbed method is calledtoBeReturnedNext
- to be returned in consecutive calls when the stubbed method is calledpublic static InOrder inOrder(Object... mocks)
InOrder
object that allows verifying mocks in order.
InOrder inOrder = inOrder(firstMock, 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.
InOrder
verification is 'greedy', but you will hardly ever notice it.
If you want to find out more, read
this wiki page.
As of Mockito 1.8.4 you can verifyNoMoreInteractions() in order-sensitive way. Read more: InOrder.verifyNoMoreInteractions()
See examples in javadoc for Mockito
class
mocks
- to be verified in orderpublic static Object[] ignoreStubs(Object... mocks)
Strictness.STRICT_STUBS
feature which eliminates the need for ignoreStubs()
and provides other benefits.
ignoreStubs()
is sometimes useful when coupled with verifyNoMoreInteractions()
or verification inOrder()
.
Helps avoiding redundant verification of stubbed calls - typically we're not interested in verifying stubs.
Warning, ignoreStubs()
might lead to overuse of verifyNoMoreInteractions(ignoreStubs(...));
Bear in mind that Mockito does not recommend bombarding every test with verifyNoMoreInteractions()
for the reasons outlined in javadoc for verifyNoMoreInteractions(Object...)
Other words: all *stubbed* methods of given mocks are marked *verified* so that they don't get in a way during verifyNoMoreInteractions().
This method changes the input mocks! This method returns input mocks just for convenience.
Ignored stubs will also be ignored for verification inOrder, including InOrder.verifyNoMoreInteractions()
.
See the second example.
Example:
//mocking lists for the sake of the example (if you mock List in real you will burn in hell)
List mock1 = mock(List.class), mock2 = mock(List.class);
//stubbing mocks:
when(mock1.get(0)).thenReturn(10);
when(mock2.get(0)).thenReturn(20);
//using mocks by calling stubbed get(0) methods:
System.out.println(mock1.get(0)); //prints 10
System.out.println(mock2.get(0)); //prints 20
//using mocks by calling clear() methods:
mock1.clear();
mock2.clear();
//verification:
verify(mock1).clear();
verify(mock2).clear();
//verifyNoMoreInteractions() fails because get() methods were not accounted for.
try { verifyNoMoreInteractions(mock1, mock2); } catch (NoInteractionsWanted e);
//However, if we ignore stubbed methods then we can verifyNoMoreInteractions()
verifyNoMoreInteractions(ignoreStubs(mock1, mock2));
//Remember that ignoreStubs() *changes* the input mocks and returns them for convenience.
Ignoring stubs can be used with verification in order:
List list = mock(List.class);
when(list.get(0)).thenReturn("foo");
list.add(0);
list.clear();
System.out.println(list.get(0)); //we don't want to verify this
InOrder inOrder = inOrder(ignoreStubs(list));
inOrder.verify(list).add(0);
inOrder.verify(list).clear();
inOrder.verifyNoMoreInteractions();
Stubbed invocations are automatically verified with Strictness.STRICT_STUBS
feature
and it eliminates the need for ignoreStubs()
. Example below uses JUnit Rules:
@Rule public MockitoRule mockito = MockitoJUnit.rule().strictness(Strictness.STRICT_STUBS);
List list = mock(List.class);
when(list.get(0)).thenReturn("foo");
list.size();
verify(list).size();
list.get(0); // Automatically verified by STRICT_STUBS
verifyNoMoreInteractions(list); // No need of ignoreStubs()
mocks
- input mocks that will be changedpublic static VerificationMode times(int wantedNumberOfInvocations)
verify(mock, times(2)).someMethod("some arg");
See examples in javadoc for Mockito
classwantedNumberOfInvocations
- wanted number of invocationspublic static VerificationMode never()
times(0)
, see times(int)
Verifies that interaction did not happen. E.g:
verify(mock, never()).someMethod();
If you want to verify there were NO interactions with the mock
check out verifyZeroInteractions(Object...)
or verifyNoMoreInteractions(Object...)
See examples in javadoc for Mockito
class
public static VerificationMode atLeastOnce()
verify(mock, atLeastOnce()).someMethod("some arg");
Alias to atLeast(1)
.
See examples in javadoc for Mockito
class
public static VerificationMode atLeast(int minNumberOfInvocations)
verify(mock, atLeast(3)).someMethod("some arg");
See examples in javadoc for Mockito
classminNumberOfInvocations
- minimum number of invocationspublic static VerificationMode atMostOnce()
verify(mock, atMostOnce()).someMethod("some arg");
Alias to atMost(1)
.
See examples in javadoc for Mockito
class
public static VerificationMode atMost(int maxNumberOfInvocations)
verify(mock, atMost(3)).someMethod("some arg");
See examples in javadoc for Mockito
classmaxNumberOfInvocations
- max number of invocationspublic static VerificationMode calls(int wantedNumberOfInvocations)
inOrder.verify( mock, calls( 2 )).someMethod( "some arg" );
wantedNumberOfInvocations
- number of invocations to verifypublic static VerificationMode only()
verify(mock, only()).someMethod();
//above is a shorthand for following 2 lines of code:
verify(mock).someMethod();
verifyNoMoreInteractions(mock);
See also verifyNoMoreInteractions(Object...)
See examples in javadoc for Mockito
class
public static VerificationWithTimeout timeout(long millis)
timeout()
method can be a code smell - there are better ways of testing concurrent code.
See also after(long)
method for testing async code.
Differences between timeout()
and after
are explained in Javadoc for after(long)
.
//passes when someMethod() is called no later than within 100 ms
//exits immediately when verification is satisfied (e.g. may not wait full 100 ms)
verify(mock, timeout(100)).someMethod();
//above is an alias to:
verify(mock, timeout(100).times(1)).someMethod();
//passes as soon as someMethod() has been called 2 times under 100 ms
verify(mock, timeout(100).times(2)).someMethod();
//equivalent: this also passes as soon as someMethod() has been called 2 times under 100 ms
verify(mock, timeout(100).atLeast(2)).someMethod();
See examples in javadoc for Mockito
classmillis
- - duration in millisecondspublic static VerificationAfterDelay after(long millis)
after()
method can be a code smell - there are better ways of testing concurrent code.
Not yet implemented to work with InOrder verification.
See also timeout(long)
method for testing async code.
Differences between timeout()
and after()
are explained below.
//passes after 100ms, if someMethod() has only been called once at that time.
verify(mock, after(100)).someMethod();
//above is an alias to:
verify(mock, after(100).times(1)).someMethod();
//passes if someMethod() is called *exactly* 2 times, as tested after 100 millis
verify(mock, after(100).times(2)).someMethod();
//passes if someMethod() has not been called, as tested after 100 millis
verify(mock, after(100).never()).someMethod();
//verifies someMethod() after a given time span using given verification mode
//useful only if you have your own custom verification modes.
verify(mock, new After(100, yourOwnVerificationMode)).someMethod();
timeout() vs. after()
//1.
mock.foo();
verify(mock, after(1000)).foo();
//waits 1000 millis and succeeds
//2.
mock.foo();
verify(mock, timeout(1000)).foo();
//succeeds immediately
See examples in javadoc for Mockito
classmillis
- - duration in millisecondspublic static void validateMockitoUsage()
In case of questions you may also post to mockito mailing list: http://groups.google.com/group/mockito
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:
//Oops, thenReturn() part is missing:
when(mock.get());
//Oops, verified method call is inside verify() where it should be on the outside:
verify(mock.execute());
//Oops, missing 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 and rule 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.
Both built-in runner: MockitoJUnitRunner
and rule: MockitoRule
do validateMockitoUsage() after each test method.
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.
See examples in javadoc for Mockito
class
public static MockSettings withSettings()
Don't use it too often. Consider writing simple tests that use simple mocks. Repeat after me: simple tests push simple, KISSy, readable & maintainable code. If you cannot write a test in a simple way - refactor the code under test.
Examples of mock settings:
//Creates mock with different default answer & name
Foo mock = mock(Foo.class, withSettings()
.defaultAnswer(RETURNS_SMART_NULLS)
.name("cool mockie"));
//Creates mock with different default answer, descriptive name and extra interfaces
Foo mock = mock(Foo.class, withSettings()
.defaultAnswer(RETURNS_SMART_NULLS)
.name("cool mockie")
.extraInterfaces(Bar.class));
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.
See javadoc for MockSettings
to learn about possible mock settings.
public static VerificationMode description(String description)
verify(mock, description("This will print on failure")).someMethod("some arg");
description
- The description to print on failure.@Incubating public static MockitoFramework framework()
MockitoFramework
class.@Incubating public static MockitoSessionBuilder mockitoSession()
MockitoSession
is an optional, highly recommended feature
that helps driving cleaner tests by eliminating boilerplate code and adding extra validation.
For more information, including use cases and sample code, see the javadoc for MockitoSession
.
@Incubating public static LenientStubber lenient()
Strictness.STRICT_STUBS
).
When stubbing is declared as lenient, it will not be checked for potential stubbing problems such as
'unnecessary stubbing' (UnnecessaryStubbingException
) or for 'stubbing argument mismatch' PotentialStubbingProblem
.
lenient().when(mock.foo()).thenReturn("ok");
Most mocks in most tests don't need leniency and should happily prosper with Strictness.STRICT_STUBS
.
MockSettings.lenient()
MockitoJUnit
or Mockito Session (MockitoSession
)This example is simplified and not realistic. Pushing stubbings to 'before()' method may cause tests to be less readable. Some repetition in tests is OK, use your own judgement to write great tests! It is not desired to eliminate all possible duplication from the test code because it may add complexity and conceal important test information.
public class SomeTest {
@Rule public MockitoRule mockito = MockitoJUnit.rule().strictness(STRICT_STUBS);
@Mock Foo foo;
@Mock Bar bar;
@Before public void before() {
when(foo.foo()).thenReturn("ok");
// it is better to configure the stubbing to be lenient:
// lenient().when(foo.foo()).thenReturn("ok");
// or the entire mock to be lenient:
// foo = mock(Foo.class, withSettings().lenient());
}
@Test public void test1() {
foo.foo();
}
@Test public void test2() {
foo.foo();
}
@Test public void test3() {
bar.bar();
}
}