• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /*
2  * Copyright (c) 2007 Mockito contributors
3  * This program is made available under the terms of the MIT License.
4  */
5 package org.mockito.stubbing;
6 
7 import org.mockito.Mockito;
8 
9 /**
10  * Simply put: "<b>When</b> the x method is called <b>then</b> return y". E.g:
11  *
12  * <pre class="code"><code class="java">
13  * <b>when</b>(mock.someMethod()).<b>thenReturn</b>(10);
14  *
15  * //you can use flexible argument matchers, e.g:
16  * when(mock.someMethod(<b>anyString()</b>)).thenReturn(10);
17  *
18  * //setting exception to be thrown:
19  * when(mock.someMethod("some arg")).thenThrow(new RuntimeException());
20  *
21  * //you can set different behavior for consecutive method calls.
22  * //Last stubbing (e.g: thenReturn("foo")) determines the behavior of further consecutive calls.
23  * when(mock.someMethod("some arg"))
24  *  .thenThrow(new RuntimeException())
25  *  .thenReturn("foo");
26  *
27  * //There is a shorter way of consecutive stubbing:
28  * when(mock.someMethod()).thenReturn(1,2,3);
29  * when(mock.otherMethod()).thenThrow(exc1, exc2);
30  * </code></pre>
31  *
32  * See examples in javadoc for {@link Mockito#when}
33  */
34 public interface OngoingStubbing<T> {
35 
36     /**
37      * Sets a return value to be returned when the method is called. E.g:
38      * <pre class="code"><code class="java">
39      * when(mock.someMethod()).thenReturn(10);
40      * </code></pre>
41      *
42      * See examples in javadoc for {@link Mockito#when}
43      *
44      * @param value return value
45      *
46      * @return object that allows stubbing consecutive calls
47      */
thenReturn(T value)48     OngoingStubbing<T> thenReturn(T value);
49 
50     /**
51      * Sets consecutive return values to be returned when the method is called. E.g:
52      * <pre class="code"><code class="java">
53      * when(mock.someMethod()).thenReturn(1, 2, 3);
54      * </code></pre>
55      *
56      * Last return value in the sequence (in example: 3) determines the behavior of further consecutive calls.
57      * <p>
58      * See examples in javadoc for {@link Mockito#when}
59      *
60      * @param value first return value
61      * @param values next return values
62      *
63      * @return object that allows stubbing consecutive calls
64      */
65     // Additional method helps users of JDK7+ to hide heap pollution / unchecked generics array creation warnings (on call site)
66     @SuppressWarnings ({"unchecked", "varargs"})
thenReturn(T value, T... values)67     OngoingStubbing<T> thenReturn(T value, T... values);
68 
69     /**
70      * Sets Throwable objects to be thrown when the method is called. E.g:
71      * <pre class="code"><code class="java">
72      * when(mock.someMethod()).thenThrow(new RuntimeException());
73      * </code></pre>
74      *
75      * If throwables contain a checked exception then it has to
76      * match one of the checked exceptions of method signature.
77      * <p>
78      * You can specify throwables to be thrown for consecutive calls.
79      * In that case the last throwable determines the behavior of further consecutive calls.
80      * <p>
81      * If throwable is null then exception will be thrown.
82      * <p>
83      * See examples in javadoc for {@link Mockito#when}
84      *
85      * @param throwables to be thrown on method invocation
86      *
87      * @return object that allows stubbing consecutive calls
88      */
thenThrow(Throwable... throwables)89     OngoingStubbing<T> thenThrow(Throwable... throwables);
90 
91     /**
92      * Sets a Throwable type to be thrown when the method is called. E.g:
93      * <pre class="code"><code class="java">
94      * when(mock.someMethod()).thenThrow(RuntimeException.class);
95      * </code></pre>
96      *
97      * <p>
98      * If the throwable class is a checked exception then it has to
99      * match one of the checked exceptions of the stubbed method signature.
100      * <p>
101      * If throwable is null then exception will be thrown.
102      * <p>
103      * See examples in javadoc for {@link Mockito#when}
104      *
105      * <p>Note depending on the JVM, stack trace information may not be available in
106      * the generated throwable instance.  If you require stack trace information,
107      * use {@link OngoingStubbing#thenThrow(Throwable...)} instead.
108      *
109      * @param throwableType to be thrown on method invocation
110      *
111      * @return object that allows stubbing consecutive calls
112      * @since 2.1.0
113      */
thenThrow(Class<? extends Throwable> throwableType)114     OngoingStubbing<T> thenThrow(Class<? extends Throwable> throwableType);
115 
116     /**
117      * Sets Throwable classes to be thrown when the method is called. E.g:
118      * <pre class="code"><code class="java">
119      * when(mock.someMethod()).thenThrow(RuntimeException.class);
120      * </code></pre>
121      *
122      * <p>
123      * Each throwable class will be instantiated for each method invocation.
124      * <p>
125      * If <code>throwableTypes</code> contain a checked exception then it has to
126      * match one of the checked exceptions of method signature.
127      * <p>
128      * You can specify <code>throwableTypes</code> to be thrown for consecutive calls.
129      * In that case the last throwable determines the behavior of further consecutive calls.
130      * <p>
131      * If throwable is null then exception will be thrown.
132      * <p>
133      * See examples in javadoc for {@link Mockito#when}
134      *
135      * <p>Note since JDK 7, invoking this method will raise a compiler warning "possible heap pollution",
136      * this API is safe to use. If you don't want to see this warning it is possible to chain {@link #thenThrow(Class)}
137      * <p>Note depending on the JVM, stack trace information may not be available in
138      * the generated throwable instance.  If you require stack trace information,
139      * use {@link OngoingStubbing#thenThrow(Throwable...)} instead.
140      *
141      * @param toBeThrown to be thrown on method invocation
142      * @param nextToBeThrown next to be thrown on method invocation
143      *
144      * @return object that allows stubbing consecutive calls
145      * @since 2.1.0
146      */
147     // Additional method helps users of JDK7+ to hide heap pollution / unchecked generics array creation warnings (on call site)
148     @SuppressWarnings ({"unchecked", "varargs"})
thenThrow(Class<? extends Throwable> toBeThrown, Class<? extends Throwable>... nextToBeThrown)149     OngoingStubbing<T> thenThrow(Class<? extends Throwable> toBeThrown, Class<? extends Throwable>... nextToBeThrown);
150 
151     /**
152      * Sets the real implementation to be called when the method is called on a mock object.
153      * <p>
154      * As usual you are going to read <b>the partial mock warning</b>:
155      * Object oriented programming is more less tackling complexity by dividing the complexity into separate, specific, SRPy objects.
156      * How does partial mock fit into this paradigm? Well, it just doesn't...
157      * Partial mock usually means that the complexity has been moved to a different method on the same object.
158      * In most cases, this is not the way you want to design your application.
159      * <p>
160      * However, there are rare cases when partial mocks come handy:
161      * dealing with code you cannot change easily (3rd party interfaces, interim refactoring of legacy code etc.)
162      * However, I wouldn't use partial mocks for new, test-driven & well-designed code.
163      * <pre class="code"><code class="java">
164      *   // someMethod() must be safe (e.g. doesn't throw, doesn't have dependencies to the object state, etc.)
165      *   // if it isn't safe then you will have trouble stubbing it using this api. Use Mockito.doCallRealMethod() instead.
166      *   when(mock.someMethod()).thenCallRealMethod();
167      *
168      *   // calls real method:
169      *   mock.someMethod();
170      *
171      * </code></pre>
172      * See also javadoc {@link Mockito#spy(Object)} to find out more about partial mocks.
173      * <b>Mockito.spy() is a recommended way of creating partial mocks.</b>
174      * 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.
175      * <p>
176      * See examples in javadoc for {@link Mockito#when}
177      *
178      * @return object that allows stubbing consecutive calls
179      */
thenCallRealMethod()180     OngoingStubbing<T> thenCallRealMethod();
181 
182     /**
183      * Sets a generic Answer for the method. E.g:
184      * <pre class="code"><code class="java">
185      * when(mock.someMethod(10)).thenAnswer(new Answer&lt;Integer&gt;() {
186      *     public Integer answer(InvocationOnMock invocation) throws Throwable {
187      *         return (Integer) invocation.getArguments()[0];
188      *     }
189      * }
190      * </code></pre>
191      *
192      * @param answer the custom answer to execute.
193      *
194      * @return object that allows stubbing consecutive calls
195      */
thenAnswer(Answer<?> answer)196     OngoingStubbing<T> thenAnswer(Answer<?> answer);
197 
198     /**
199      * Sets a generic Answer for the method.
200      *
201      * This method is an alias of {@link #thenAnswer(Answer)}. This alias allows
202      * more readable tests on occasion, for example:
203      * <pre class="code"><code class="java">
204      * //using 'then' alias:
205      * when(mock.foo()).then(returnCoolValue());
206      *
207      * //versus good old 'thenAnswer:
208      * when(mock.foo()).thenAnswer(byReturningCoolValue());
209      * </code></pre>
210      *
211      * @param answer the custom answer to execute.
212      * @return object that allows stubbing consecutive calls
213      *
214      * @see #thenAnswer(Answer)
215      * @since 1.9.0
216      */
then(Answer<?> answer)217     OngoingStubbing<T> then(Answer<?> answer);
218 
219     /**
220      * Returns the mock that was used for this stub.
221      * <p>
222      * It allows to create a stub in one line of code.
223      * This can be helpful to keep test code clean.
224      * For example, some boring stub can be created & stubbed at field initialization in a test:
225      * <pre class="code"><code class="java">
226      * public class CarTest {
227      *   Car boringStubbedCar = when(mock(Car.class).shiftGear()).thenThrow(EngineNotStarted.class).getMock();
228      *
229      *   &#064;Test public void should... {}
230      * </code></pre>
231      *
232      * @param <M> The mock type given by the variable type.
233      * @return Mock used in this ongoing stubbing.
234      * @since 1.9.0
235      */
getMock()236     <M> M getMock();
237 
238 }
239