Skip navigation links
Mockito 2.17.0 API
org.mockito

Class Mockito

    • Field Detail

      • RETURNS_DEFAULTS

        public static final Answer<Object> RETURNS_DEFAULTS
        The default 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.

      • RETURNS_SMART_NULLS

        public static final Answer<Object> RETURNS_SMART_NULLS
        Optional 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 3.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.

      • RETURNS_MOCKS

        public static final Answer<Object> RETURNS_MOCKS
        Optional 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.

      • RETURNS_DEEP_STUBS

        public static final Answer<Object> RETURNS_DEEP_STUBS
        Optional 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.

      • CALLS_REAL_METHODS

        public static final Answer<Object> CALLS_REAL_METHODS
        Optional 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: 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.

      • RETURNS_SELF

        public static final Answer<Object> RETURNS_SELF
        Optional 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.

        Consider a HttpBuilder used in a HttpRequesterWithHeaders. 
        
 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);
  }

    • Constructor Detail

      • Mockito

        public Mockito()

    • Method Detail

      • mock

        public static <T> T mock(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(Class<T> classToMock,
                         String name)
        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.

        See examples in javadoc for Mockito class

        Parameters:
        classToMock - class or interface to mock
        name - of the mock
        Returns:
        mock object

      • mockingDetails

        public static MockingDetails mockingDetails(Object toInspect)
        Returns a MockingDetails instance that enables inspecting a particular object for Mockito related information. Can be used to find out if given object is a Mockito mock or to find out if a given mock is a spy or mock.

        In future Mockito versions MockingDetails may grow and provide other useful information about the mock, e.g. invocations, stubbing info, etc.

        Parameters:
        toInspect - - object to inspect. null input is allowed.
        Returns:
        A MockingDetails instance.
        Since:
        1.9.5

      • mock

        public static <T> T mock(Class<T> classToMock,
                         Answer defaultAnswer)
        Creates mock with a specified strategy for its answers to interactions. It's quite an 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. 

        
   Foo mock = mock(Foo.class, RETURNS_SMART_NULLS);
   Foo mockTwo = mock(Foo.class, new YourOwnAnswer());

        See examples in javadoc for Mockito class

        Parameters:
        classToMock - class or interface to mock
        defaultAnswer - default answer for unstubbed methods
        Returns:
        mock object

      • mock

        public static <T> T mock(Class<T> classToMock,
                         MockSettings mockSettings)
        Creates a mock with some non-standard settings.

        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

        Parameters:
        classToMock - class or interface to mock
        mockSettings - additional mock settings
        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.

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

        Important gotcha on spying real objects!

        1. Sometimes it's impossible or impractical to use 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);
        2. Mockito *does not* delegate calls to the passed real instance, instead it actually creates a copy of it. So if you keep the real instance and interact with it, don't expect the spied to be aware of those interaction and their effect on real instance state. The corollary is that when an *unstubbed* method is called *on the spy* but *not on the real instance*, you won't see any effects on the real instance.
        3. 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. Also you won't be able to verify those method as well.

        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.

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

      • spy

        @Incubating
public static <T> T spy(Class<T> classToSpy)
        Please refer to the documentation of 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));
        Type Parameters:
        T - type of the spy
        Parameters:
        classToSpy - the class to spy
        Returns:
        a spy of the provided class
        Since:
        1.10.12

      • when

        public static <T> OngoingStubbing<T> when(T methodCall)
        Enables stubbing methods. Use it when you want the mock to return particular value when particular method is called.

        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. Not convinced? See here.

        See examples in javadoc for Mockito class

        Parameters:
        methodCall - method to be stubbed
        Returns:
        OngoingStubbing object used to stub fluently. Do not create a reference to this returned object.

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

        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.

        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, 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. 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
        Type Parameters:
        T - The Type of the mocks
        Parameters:
        mocks - to be reset

      • clearInvocations

        public static <T> void clearInvocations(T... mocks)
        Use this method in order to only clear invocations, when stubbing is non-trivial. Use-cases can be:
        • You are using a dependency injection framework to inject your mocks.
        • The mock is used in a stateful scenario. For example a class is Singleton which depends on your mock.
        Try to avoid this method at all costs. Only clear invocations if you are unable to efficiently test your program.
        Type Parameters:
        T - The type of the mocks
        Parameters:
        mocks - The mocks to clear the invocations for

      • verifyNoMoreInteractions

        public static void verifyNoMoreInteractions(Object... mocks)
        Checks 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 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. 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.

        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(Object... mocks)
        Verifies that no interactions happened on given mocks beyond the previously verified interactions.
        This method has the same behavior as verifyNoMoreInteractions(Object...).
        Parameters:
        mocks - to be verified

      • doThrow

        public static Stubber doThrow(Throwable... toBeThrown)
        Use 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();
        Parameters:
        toBeThrown - to be thrown when the stubbed method is called
        Returns:
        stubber - to select a method for stubbing

      • doThrow

        public static Stubber doThrow(Class<? extends Throwable> toBeThrown)
        Use 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();
        Parameters:
        toBeThrown - to be thrown when the stubbed method is called
        Returns:
        stubber - to select a method for stubbing
        Since:
        2.1.0

      • doThrow

        public static Stubber doThrow(Class<? extends Throwable> toBeThrown,
                              Class<? extends Throwable>... toBeThrownNext)
        Same as 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();
        Parameters:
        toBeThrown - to be thrown when the stubbed method is called
        toBeThrownNext - next to be thrown when the stubbed method is called
        Returns:
        stubber - to select a method for stubbing
        Since:
        2.1.0

      • doCallRealMethod

        public static Stubber 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.

        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

        Returns:
        stubber - to select a method for stubbing
        Since:
        1.9.5

      • 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 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

        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 on mocks 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();

        See examples in javadoc for Mockito class

        Returns:
        stubber - to select a method for stubbing

      • doReturn

        public static Stubber doReturn(Object toBeReturned)
        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 elegant 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.

        See examples in javadoc for Mockito class

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

      • doReturn

        public static Stubber doReturn(Object toBeReturned,
                               Object... toBeReturnedNext)
        Same as 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:

        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", "bar", "qix");

   //You have to use doReturn() for stubbing:
   doReturn("foo", "bar", "qix").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", "foo", "qix");

   //You have to use doReturn() for stubbing:
   doReturn("bar", "foo", "qix").when(mock).foo();
        Above scenarios shows a trade-off of Mockito's elegant 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.

        See examples in javadoc for Mockito class

        Parameters:
        toBeReturned - to be returned when the stubbed method is called
        toBeReturnedNext - to be returned in consecutive calls when the stubbed method is called
        Returns:
        stubber - to select a method for stubbing
        Since:
        2.1.0

      • inOrder

        public static InOrder inOrder(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.

        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 verifyNoMoreInvocations() in order-sensitive way. Read more: InOrder.verifyNoMoreInteractions()

        See examples in javadoc for Mockito class

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

      • ignoreStubs

        public static Object[] ignoreStubs(Object... mocks)
        Ignores stubbed methods of given mocks for the sake of verification. 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(mock.get(0)).thenReturn("foo");

  list.add(0);
  System.out.println(list.get(0)); //we don't want to verify this
  list.clear();

  InOrder inOrder = inOrder(ignoreStubs(list));
  inOrder.verify(list).add(0);
  inOrder.verify(list).clear();
  inOrder.verifyNoMoreInteractions();
        Parameters:
        mocks - input mocks that will be changed
        Returns:
        the same mocks that were passed in as parameters
        Since:
        1.9.0

      • 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

      • atLeastOnce

        public static VerificationMode atLeastOnce()
        Allows at-least-once verification. E.g: 
        
   verify(mock, atLeastOnce()).someMethod("some arg");
        Alias to atLeast(1).

        See examples in javadoc for Mockito class

        Returns:
        verification mode

      • atLeast

        public static VerificationMode atLeast(int minNumberOfInvocations)
        Allows at-least-x verification. E.g: 
        
   verify(mock, atLeast(3)).someMethod("some arg");
        See examples in javadoc for Mockito class
        Parameters:
        minNumberOfInvocations - minimum number of invocations
        Returns:
        verification mode

      • atMost

        public static VerificationMode atMost(int maxNumberOfInvocations)
        Allows at-most-x verification. E.g: 
        
   verify(mock, atMost(3)).someMethod("some arg");
        See examples in javadoc for Mockito class
        Parameters:
        maxNumberOfInvocations - max number of invocations
        Returns:
        verification mode

      • calls

        public static VerificationMode calls(int wantedNumberOfInvocations)
        Allows non-greedy verification in order. For example 
        
   inOrder.verify( mock, calls( 2 )).someMethod( "some arg" );
        • will not fail if the method is called 3 times, unlike times( 2 )
        • will not mark the third invocation as verified, unlike atLeast( 2 )
        This verification mode can only be used with in order verification.
        Parameters:
        wantedNumberOfInvocations - number of invocations to verify
        Returns:
        verification mode

      • only

        public static VerificationMode only()
        Allows checking if given method was the only one invoked. E.g: 
        
   verify(mock, only()).someMethod();
   //above is a shorthand for following 2 lines of code:
   verify(mock).someMethod();
   verifyNoMoreInvocations(mock);

        See also verifyNoMoreInteractions(Object...)

        See examples in javadoc for Mockito class

        Returns:
        verification mode

      • timeout

        public static VerificationWithTimeout timeout(long millis)
        Allows verifying with timeout. It causes a verify to wait for a specified period of time for a desired interaction rather than fails immediately if has not already happened. May be useful for testing in concurrent conditions.

        This differs from after() in that after() will wait the full period, unless the final test result is known early (e.g. if a never() fails), whereas timeout() will stop early as soon as verification passes, producing different behaviour when used with times(2), for example, which can pass and then later fail. In that case, timeout would pass as soon as times(2) passes, whereas after would run until times(2) failed, and then fail.

        This feature should be used rarely - figure out a better way of testing your multi-threaded system. 

        
   //passes when someMethod() is called within given time span
   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 before the given timeout
   verify(mock, timeout(100).times(2)).someMethod();

   //equivalent: this also passes as soon as someMethod() has been called 2 times before the given timeout
   verify(mock, timeout(100).atLeast(2)).someMethod();

   //verifies someMethod() within given time span using given verification mode
   //useful only if you have your own custom verification modes.
   verify(mock, new Timeout(100, yourOwnVerificationMode)).someMethod();
        See examples in javadoc for Mockito class
        Parameters:
        millis - - time span in milliseconds
        Returns:
        verification mode

      • after

        public static VerificationAfterDelay after(long millis)
        Allows verifying over a given period. It causes a verify to wait for a specified period of time for a desired interaction rather than failing immediately if has not already happened. May be useful for testing in concurrent conditions.

        This differs from timeout() in that after() will wait the full period, whereas timeout() will stop early as soon as verification passes, producing different behaviour when used with times(2), for example, which can pass and then later fail. In that case, timeout would pass as soon as times(2) passes, whereas after would run the full time, which point it will fail, as times(2) has failed.

        This feature should be used rarely - figure out a better way of testing your multi-threaded system.

        Not yet implemented to work with InOrder verification. 

        
   //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 after the given timespan
   verify(mock, after(100).times(2)).someMethod();

   //passes if someMethod() has not been called after the given timespan
   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();
        See examples in javadoc for Mockito class
        Parameters:
        millis - - time span in milliseconds
        Returns:
        verification mode

      • validateMockitoUsage

        public 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

        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

      • withSettings

        public static MockSettings withSettings()
        Allows mock creation with additional mock settings.

        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.

        Returns:
        mock settings instance with defaults.

      • description

        public static VerificationMode description(String description)
        Adds a description to be printed if verification fails. 
        
 verify(mock, description("This will print on failure")).someMethod("some arg");
        Parameters:
        description - The description to print on failure.
        Returns:
        verification mode
        Since:
        2.1.0

      • mockitoSession

        @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.

        Since:
        2.7.0
Skip navigation links
Mockito 2.17.0 API