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