Package org.mockito.stubbing

Interface OngoingStubbing<T>

  • @NotExtensible
public interface OngoingStubbing<T>
    Simply put: "When the x method is called then return y". E.g: 
    
 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");

 //There is a shorter way of consecutive stubbing:
 when(mock.someMethod()).thenReturn(1,2,3);
 when(mock.otherMethod()).thenThrow(exc1, exc2);
    See examples in javadoc for Mockito.when(T)

    • Method Detail

      • thenReturn

        OngoingStubbing<T> thenReturn​(T value)
        Sets a return value to be returned when the method is called. E.g: 
        
 when(mock.someMethod()).thenReturn(10);
        See examples in javadoc for Mockito.when(T)
        Parameters:
        value - return value
        Returns:
        object that allows stubbing consecutive calls

      • thenReturn

        OngoingStubbing<T> thenReturn​(T value,
                              T... values)
        Sets consecutive return values to be returned when the method is called. E.g: 
        
 when(mock.someMethod()).thenReturn(1, 2, 3);
        Last return value in the sequence (in example: 3) determines the behavior of further consecutive calls.

        See examples in javadoc for Mockito.when(T)

        Parameters:
        value - first return value
        values - next return values
        Returns:
        object that allows stubbing consecutive calls

      • thenThrow

        OngoingStubbing<T> thenThrow​(Throwable... throwables)
        Sets Throwable objects to be thrown when the method is called. E.g: 
        
 when(mock.someMethod()).thenThrow(new RuntimeException());
        If throwables contain a checked exception then it has to match one of the checked exceptions of method signature.

        You can specify throwables to be thrown for consecutive calls. In that case the last throwable determines the behavior of further consecutive calls.

        If throwable is null then exception will be thrown.

        See examples in javadoc for Mockito.when(T)

        Parameters:
        throwables - to be thrown on method invocation
        Returns:
        object that allows stubbing consecutive calls

      • thenThrow

        OngoingStubbing<T> thenThrow​(Class<? extends Throwable> throwableType)
        Sets a Throwable type to be thrown when the method is called. E.g: 
        
 when(mock.someMethod()).thenThrow(RuntimeException.class);

        If the throwable class is a checked exception then it has to match one of the checked exceptions of the stubbed method signature.

        If throwable is null then exception will be thrown.

        See examples in javadoc for Mockito.when(T)

        Note depending on the JVM, stack trace information may not be available in the generated throwable instance. If you require stack trace information, use thenThrow(Throwable...) instead.

        Parameters:
        throwableType - to be thrown on method invocation
        Returns:
        object that allows stubbing consecutive calls
        Since:
        2.1.0

      • thenThrow

        OngoingStubbing<T> thenThrow​(Class<? extends Throwable> toBeThrown,
                             Class<? extends Throwable>... nextToBeThrown)
        Sets Throwable classes to be thrown when the method is called. E.g: 
        
 when(mock.someMethod()).thenThrow(RuntimeException.class);

        Each throwable class will be instantiated for each method invocation.

        If throwableTypes contain a checked exception then it has to match one of the checked exceptions of method signature.

        You can specify throwableTypes to be thrown for consecutive calls. In that case the last throwable determines the behavior of further consecutive calls.

        If throwable is null then exception will be thrown.

        See examples in javadoc for Mockito.when(T)

        Note since JDK 7, invoking this method will raise a compiler warning "possible heap pollution", this API is safe to use. If you don't want to see this warning it is possible to chain thenThrow(Class)

        Note depending on the JVM, stack trace information may not be available in the generated throwable instance. If you require stack trace information, use thenThrow(Throwable...) instead.

        Parameters:
        toBeThrown - to be thrown on method invocation
        nextToBeThrown - next to be thrown on method invocation
        Returns:
        object that allows stubbing consecutive calls
        Since:
        2.1.0

      • thenCallRealMethod

        OngoingStubbing<T> thenCallRealMethod()
        Sets the real implementation to be called when the method is called on a mock object.

        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 and well-designed code. 

        
   // someMethod() must be safe (e.g. doesn't throw, doesn't have dependencies to the object state, etc.)
   // if it isn't safe then you will have trouble stubbing it using this api. Use Mockito.doCallRealMethod() instead.
   when(mock.someMethod()).thenCallRealMethod();

   // calls real method:
   mock.someMethod();
        See also javadoc Mockito.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.

        See examples in javadoc for Mockito.when(T)

        Returns:
        object that allows stubbing consecutive calls

      • thenAnswer

        OngoingStubbing<T> thenAnswer​(Answer<?> answer)
        Sets a generic Answer for the method. E.g: 
        
 when(mock.someMethod(10)).thenAnswer(new Answer<Integer>() {
     public Integer answer(InvocationOnMock invocation) throws Throwable {
         return (Integer) invocation.getArguments()[0];
     }
 }
        Parameters:
        answer - the custom answer to execute.
        Returns:
        object that allows stubbing consecutive calls

      • then

        OngoingStubbing<T> then​(Answer<?> answer)
        Sets a generic Answer for the method. This method is an alias of thenAnswer(Answer). This alias allows more readable tests on occasion, for example: 
        
 //using 'then' alias:
 when(mock.foo()).then(returnCoolValue());

 //versus good old 'thenAnswer:
 when(mock.foo()).thenAnswer(byReturningCoolValue());
        Parameters:
        answer - the custom answer to execute.
        Returns:
        object that allows stubbing consecutive calls
        Since:
        1.9.0
        See Also:
        thenAnswer(Answer)

      • getMock

        <M> M getMock()
        Returns the mock that was used for this stub.

        It allows to create a stub in one line of code. This can be helpful to keep test code clean. For example, some boring stub can be created and stubbed at field initialization in a test: 

        
 public class CarTest {
   Car boringStubbedCar = when(mock(Car.class).shiftGear()).thenThrow(EngineNotStarted.class).getMock();

   @Test public void should... {}
        Type Parameters:
        M - The mock type given by the variable type.
        Returns:
        Mock used in this ongoing stubbing.
        Since:
        1.9.0