Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.mockito
Class Mockito

java.lang.Object
  extended by org.mockito.Matchers
      extended by org.mockito.Mockito

public class Mockito
extends Matchers

Enables mocks creation, verification and stubbing.

Contents

1. Let's verify some behaviour!
2. How about some stubbing?
3. Argument matchers
4. Verifying exact number of invocations / at least once / never
5. Stubbing void methods with exceptions
6. Verification in order
7. Making sure interaction(s) never happened on mock
8. Finding redundant invocations
9. Shorthand for mocks creation - @Mock annotation
10. (**New**) Stubbing consecutive calls (iterator-style stubbing)
11. (**Totally New**) Stubbing with callbacks
12. (**Totally New**) doThrow()|doAnswer()|doNothing()|doReturn() family of methods mostly for stubbing voids
13. (**Totally New**) Spying on real objects

Following examples mock List, because everyone knows its interface (methods like add(), get(), clear() will be used).
You probably wouldn't mock List class 'in real'.

1. Let's verify some behaviour!

 //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, mock will remember all invocations. Then you can selectively verify whatever interaction you are interested in.

2. How about some stubbing?

 //You can mock concrete classes, not only interfaces
 LinkedList mockedList = mock(LinkedList.class);
 
 //stubbing
 stub(mockedList.get(0)).toReturn("first");
 stub(mockedList.get(1)).toThrow(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 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(mockedList).get(0);

3. Argument matchers

 //stubbing using built-in anyInt() argument matcher
 stub(mockedList.get(anyInt())).toReturn("element");
 
 //stubbing using hamcrest (let's say isValid() returns your own hamcrest matcher):
 stub(mockedList.contains(argThat(isValid()))).toReturn("element");
 
 //following prints "element"
 System.out.println(mockedList.get(999));
 
 //you can also verify using argument matcher
 verify(mockedList).get(anyInt());

Argument matchers allow flexible verification or stubbing. See the whole library of Matchers including examples of custom argument matchers / hamcrest matchers.

Warning:

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 argument matcher.

4. Verifying exact number of invocations / at least once / never

 //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 atLeastOnce()
 verify(mockedList, atLeastOnce()).add("three times");

times(1) is the default. Therefore using times(1) explicitly can be omitted.

5. Stubbing void methods with exceptions

doThrow(Throwable) replaces stubVoid(Object) because of improved readability and consistency with the family of doAnswer() methods.

See paragraph 12.

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);

Instead of verifyZeroInteractions() you can call verifyNoMoreInteractions() but the first one is more explicit and can read better.

8. Finding redundant invocations

 //using mocks
 mockedList.add("one");
 mockedList.add("two");
 
 verify(mockedList).add("one");
 
 //following verification will fail 
 verifyNoMoreInteractions(mockedList);
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 an intent well.

9. Shorthand for mocks creation - @Mock annotation

   public class ArticleManagerTest { 
     
       @Mock private ArticleCalculator calculator;
       @Mock private ArticleDatabase database;
       @Mock private UserProvider userProvider;
     
       private ArticleManager manager;
Important! This needs to be somewhere in the base class or a test runner: 
 MockitoAnnotations.initMocks(testClass);
Examples how to write a junit test runner are in Mockito test code (mockito/test/org/mockitousage/examples/junitrunner package);

Read more here: MockitoAnnotations

10. (**New**) 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: 

 stub(mock.someMethod("some arg"))
   .toThrow(new RuntimeException())
   .toReturn("foo");
 
 //First call: throws runtime exception:
 mock.someMethod("some arg");
 
 //Second call: prints "foo"
 System.out.println(mock.someMethod("some arg"));
 
 //Any consecutive call: prints "foo" as well (last stubbing wins). 
 System.out.println(mock.someMethod("some arg"));

11. (**Totally New**) Stubbing with callbacks

Allows stubbing with generic Answer interface.

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

 stub(mock.someMethod(anyString())).toAnswer(new Answer() {
     Object answer(InvocationOnMock invocation) {
         Object[] args = invocation.getArguments();
         Object mock = invocation.getMock();
         return "called with arguments: " + args;
     }
 });
 
 //Following prints "called with arguments: foo"
 System.out.println(mock.someMethod("foo"));

12. (**Totally New**) doThrow()|doAnswer()|doNothing()|doReturn() family of methods for stubbing voids (mostly)

Stubbing voids requires different approach from stub(Object) because the compiler does not like void methods inside brackets...

doThrow(Throwable) replaces the stubVoid(Object) method for stubbing voids. The main reason is improved readability and consistency with the family of doAnswer() methods.

Use doThrow() when you want to stub a void method with an exception: 

   doThrow(new RuntimeException()).when(mockedList).clear();
   
   //following throws RuntimeException:
   mockedList.clear();
Read more about other methods:

doThrow(Throwable)

doAnswer(Answer)

doNothing()

doReturn(Object)

13. (**Totally New**) 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 is associated with "partial mocking" concept. 

   List list = new LinkedList();
   List spy = spy(list);
 
   //optionally, you can stub out some methods:
   stub(spy.size()).toReturn(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");

Important gotcha on spying real objects!

Sometimes it's impossible to use stub(Object) for stubbing spies. 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)
   stub(spy.get(0)).toReturn("foo");
   
   //You have to use doReturn() for stubbing
   doReturn("foo").when(spy).get(0);

Constructor Summary
Mockito()
           
 
Method Summary
static VerificationMode atLeastOnce()
          Allows at-least-once verification.
static Stubber doAnswer(Answer answer)
          Use doAnswer() when you want to stub a void method with generic Answer.
static Stubber doNothing()
          Use doNothing() for setting void methods to do nothing.
static Stubber doReturn(java.lang.Object toBeReturned)
          Use doReturn() in those rare occasions when you cannot use stub(Object).
static Stubber doThrow(java.lang.Throwable toBeThrown)
          Use doThrow() when you want to stub the void method with an exception.
static InOrder inOrder(java.lang.Object... mocks)
          Creates InOrder object that allows verifying mocks in order.
static
<T> T
mock(java.lang.Class<T> classToMock)
          Creates mock object of given class or interface.
static
<T> T
mock(java.lang.Class<T> classToMock, java.lang.String name)
          Creates mock with a name.
static VerificationMode never()
          Alias to times(0), see times(int)
static
<T> T
spy(T object)
          Creates a spy of the real object.
static
<T> OngoingStubbing<T>
stub(T methodCall)
          Stubs with return value or exception.
static
<T> VoidMethodStubbable<T>
stubVoid(T mock)
          Deprecated. Use doThrow(Throwable) method for stubbing voids
static VerificationMode times(int wantedNumberOfInvocations)
          Allows verifying exact number of invocations.
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 verifyNoMoreInteractions(java.lang.Object... mocks)
          Throws an AssertionError if any of given mocks has any unverified interaction.
static void verifyZeroInteractions(java.lang.Object... mocks)
          Verifies that no interactions happened on given mocks.
 
Methods inherited from class org.mockito.Matchers
anyBoolean, anyByte, anyChar, anyCollection, anyDouble, anyFloat, anyInt, anyList, anyLong, anyMap, anyObject, anyShort, anyString, argThat, booleanThat, byteThat, charThat, contains, doubleThat, endsWith, eq, eq, eq, eq, eq, eq, eq, eq, eq, floatThat, intThat, isA, isNotNull, isNull, longThat, matches, notNull, refEq, same, shortThat, startsWith
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Mockito

public Mockito()
Method Detail

mock

public static <T> T mock(java.lang.Class<T> classToMock)
Creates mock object of given class or interface.

See examples in javadoc for Mockito class

Parameters:
classToMock - class or interface to mock
Returns:
mock object

mock

public static <T> T mock(java.lang.Class<T> classToMock,
                         java.lang.String name)
Creates mock with a name. Naming mocks can be helpful for debugging.

Beware that naming mocks is not a solution for complex code which uses too many mocks or collaborators. In that case we recommend merciless refactoring.

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

See examples in javadoc for Mockito class

Parameters:
classToMock - class or interface to mock
Returns:
mock object

spy

public static <T> T spy(T object)
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.

Spying on real objects is associated with "partial mocking" concept.

Example: 

   List list = new LinkedList();
   List spy = spy(list);
 
   //optionally, you can stub out some methods:
   stub(spy.size()).toReturn(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");

Important gotcha on spying real objects!

Sometimes it's impossible to use stub(Object) for stubbing spies. 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)
   stub(spy.get(0)).toReturn("foo");
   
   //You have to use doReturn() for stubbing
   doReturn("foo").when(spy).get(0);

See examples in javadoc for Mockito class

Parameters:
object - to spy on
Returns:
a spy of the real object

stub

public static <T> OngoingStubbing<T> stub(T methodCall)
Stubs with return value or exception. E.g: 
   stub(mock.someMethod()).toReturn(10);
   
   //you can use flexible argument matchers, e.g:
   stub(mock.someMethod(anyString())).toReturn(10);
   
   //setting exception to be thrown:
   stub(mock.someMethod("some arg")).toThrow(new RuntimeException());
   
   //you can stub with different behavior for consecutive calls.
   //Last stubbing (e.g: toReturn("foo")) determines the behavior for further consecutive calls.   
   stub(mock.someMethod("some arg"))
    .toThrow(new RuntimeException())
    .toReturn("foo");
For stubbing void methods with throwables see: stubVoid(T)

Stubbing can be overridden: for example common stubbing can go to fixture setup but test methods can override it.

Once stubbed, mocked 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.

See examples in javadoc for Mockito class

Parameters:
methodCall - method call
Returns:
OngoingStubbing object to set stubbed value/exception

verify

public static <T> T verify(T mock)
Verifies certain behavior happened once

Alias to verify(mock, times(1)) E.g: 

   verify(mock).someMethod("some arg");
Above is equivalent to: 
   verify(mock, times(1)).someMethod("some arg");

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.

See examples in javadoc for Mockito class

Parameters:
mock - to be verified
Returns:
mock object itself

verify

public static <T> T verify(T mock,
                           VerificationMode mode)
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, atLeastOnce()).someMethod("was called at least once");
   
   //you can use flexible argument matchers, e.g:
   verify(mock, atLeastOnce()).someMethod(anyString());
times(1) is the default and can be omitted

See examples in javadoc for Mockito class

Parameters:
mock - to be verified
mode - times(x), atLeastOnce() or never()
Returns:
mock object itself

verifyNoMoreInteractions

public static void verifyNoMoreInteractions(java.lang.Object... mocks)
Throws an AssertionError if any of given mocks has any unverified interaction.

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 an intent well.

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

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.

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 class

Parameters:
mocks - to be verified

verifyZeroInteractions

public static void verifyZeroInteractions(java.lang.Object... mocks)
Verifies that no interactions happened on given mocks. 
   verifyZeroInteractions(mockOne, mockTwo);
Instead of verifyZeroInteractions() you can call verifyNoMoreInteractions() but the first one is more explicit and can read better.

See examples in javadoc for Mockito class

Parameters:
mocks - to be verified

stubVoid

public static <T> VoidMethodStubbable<T> stubVoid(T mock)
Deprecated. Use doThrow(Throwable) method for stubbing voids

Deprecated 
   //Instead of:
   stubVoid(mock).toThrow(e).on().someVoidMethod();
 
   //Please do:
   doThrow(e).when(mock).someVoidMethod();
doThrow() replaces stubVoid() because of improved readability and consistency with the family of doAnswer() methods.

Originally, stubVoid() was used for stubbing void methods with exceptions. E.g: 

 stubVoid(mock).toThrow(new RuntimeException()).on().someMethod();
 
 //you can stub with different behavior for consecutive calls.
 //Last stubbing (e.g. toReturn()) determines the behavior for further consecutive calls.   
 stub(mock)
   .toThrow(new RuntimeException())
   .toReturn()
   .on().someMethod();
See examples in javadoc for Mockito class

Parameters:
mock - to stub
Returns:
stubbable object that allows stubbing with throwable

doThrow

public static Stubber doThrow(java.lang.Throwable toBeThrown)
Use doThrow() when you want to stub the void method with an exception.

Stubbing voids requires different approach from stub(Object) because the compiler does not like void methods inside brackets...

Example: 

   doThrow(new RuntimeException()).when(mock).someVoidMethod();

Parameters:
toBeThrown - to be thrown when the stubbed method is called
Returns:
stubber - to select a method for stubbing

doAnswer

public static Stubber doAnswer(Answer answer)
Use doAnswer() when you want to stub a void method with generic Answer.

Stubbing voids requires different approach from stub(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();

Parameters:
answer - to answer when the stubbed method is called
Returns:
stubber - to select a method for stubbing

doNothing

public static Stubber doNothing()
Use doNothing() for setting void methods to do nothing. Beware that void methods do nothing by default! However, there are rare situations when doNothing() comes handy:

1. Stubbing consecutive calls on a void method: 

   doNothing().
   doThrow(new RuntimeException())
   .when(mock).someVoidMethod();
   
   //does nothing the first time:
   mock.someVoidMethod();
   
   //throws RuntimeException the next time:
   mock.someVoidMethod();
2. When you spy real objects and you want the void method to do nothing: 
   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();

Returns:
stubber - to select a method for stubbing

doReturn

public static Stubber doReturn(java.lang.Object toBeReturned)
Use doReturn() in those rare occasions when you cannot use stub(Object).

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

However, there are 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)
   stub(spy.get(0)).toReturn("foo");
   
   //You have to use doReturn() for stubbing:
   doReturn("foo").when(spy).get(0);
2. Overriding a previous exception-stubbing: 
   stub(mock.foo()).toThrow(new RuntimeException());
   
   //Impossible: the exception-stubbed foo() method is really called so RuntimeException is thrown. 
   stub(mock.foo()).toReturn("bar");
   
   //You have to use doReturn() for stubbing:
   doReturn("bar").when(mock).foo();
Above scenario shows a tradeoff of Mockito's ellegant syntax. The scenario is very rare, though.

Parameters:
toBeReturned - to be returned when the stubbed method is called
Returns:
stubber - to select a method for stubbing

inOrder

public static InOrder inOrder(java.lang.Object... mocks)
Creates 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. See examples in javadoc for Mockito class

Parameters:
mocks - to be verified in order
Returns:
InOrder object to be used to verify in order

atLeastOnce

public static VerificationMode atLeastOnce()
Allows at-least-once verification. E.g: 
   verify(mock, atLeastOnce()).someMethod("some arg");
See examples in javadoc for Mockito class

Returns:
verification mode

times

public static VerificationMode times(int wantedNumberOfInvocations)
Allows verifying exact number of invocations. E.g: 
   verify(mock, times(2)).someMethod("some arg");
See examples in javadoc for Mockito class

Parameters:
wantedNumberOfInvocations - wanted number of invocations
Returns:
verification mode

never

public static VerificationMode never()
Alias to times(0), see times(int)

Verifies that interaction did not happen 

   verify(mock, never()).someMethod();

See examples in javadoc for Mockito class

Returns:
verification mode
Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD