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 iOngoingStubbing 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 iOngoingStubbing 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 iOngoingStubbing 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 iOngoingStubbing 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 iOngoingStubbing 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 iOngoingStubbing 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<Integer>() { 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 iOngoingStubbing 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 iOngoingStubbing 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 * @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