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 * Allows to choose a method when stubbing in doThrow()|doAnswer()|doNothing()|doReturn() style 11 * <p> 12 * Example: 13 * <pre class="code"><code class="java"> 14 * doThrow(new RuntimeException()).when(mockedList).clear(); 15 * 16 * //following throws RuntimeException: 17 * mockedList.clear(); 18 * </code></pre> 19 * 20 * Also useful when stubbing consecutive calls: 21 * 22 * <pre class="code"><code class="java"> 23 * doThrow(new RuntimeException("one")). 24 * doThrow(new RuntimeException("two")) 25 * .when(mock).someVoidMethod(); 26 * </code></pre> 27 * 28 * Read more about those methods: 29 * <p> 30 * {@link Mockito#doThrow(Throwable[])} 31 * <p> 32 * {@link Mockito#doAnswer(Answer)} 33 * <p> 34 * {@link Mockito#doNothing()} 35 * <p> 36 * {@link Mockito#doReturn(Object)} 37 * <p> 38 * 39 * See examples in javadoc for {@link Mockito} 40 */ 41 @SuppressWarnings("unchecked") 42 public interface Stubber { 43 44 /** 45 * Allows to choose a method when stubbing in doThrow()|doAnswer()|doNothing()|doReturn() style 46 * <p> 47 * Example: 48 * <pre class="code"><code class="java"> 49 * doThrow(new RuntimeException()) 50 * .when(mockedList).clear(); 51 * 52 * //following throws RuntimeException: 53 * mockedList.clear(); 54 * </code></pre> 55 * 56 * Read more about those methods: 57 * <p> 58 * {@link Mockito#doThrow(Throwable[])} 59 * <p> 60 * {@link Mockito#doAnswer(Answer)} 61 * <p> 62 * {@link Mockito#doNothing()} 63 * <p> 64 * {@link Mockito#doReturn(Object)} 65 * <p> 66 * 67 * See examples in javadoc for {@link Mockito} 68 * 69 * @param mock The mock 70 * @return select method for stubbing 71 */ when(T mock)72 <T> T when(T mock); 73 74 /** 75 * Use it for stubbing consecutive calls in {@link Mockito#doThrow(Throwable[])} style: 76 * <pre class="code"><code class="java"> 77 * doThrow(new RuntimeException("one")). 78 * doThrow(new RuntimeException("two")) 79 * .when(mock).someVoidMethod(); 80 * </code></pre> 81 * See javadoc for {@link Mockito#doThrow(Throwable[])} 82 * 83 * @param toBeThrown to be thrown when the stubbed method is called 84 * @return stubber - to select a method for stubbing 85 */ doThrow(Throwable... toBeThrown)86 Stubber doThrow(Throwable... toBeThrown); 87 88 /** 89 * Use it for stubbing consecutive calls in {@link Mockito#doThrow(Class)} style: 90 * <pre class="code"><code class="java"> 91 * doThrow(RuntimeException.class). 92 * doThrow(IllegalArgumentException.class) 93 * .when(mock).someVoidMethod(); 94 * </code></pre> 95 * See javadoc for {@link Mockito#doThrow(Class)} 96 * 97 * @param toBeThrown exception class to be thrown when the stubbed method is called 98 * @return stubber - to select a method for stubbing 99 * 100 * @since 2.1.0 101 */ doThrow(Class<? extends Throwable> toBeThrown)102 Stubber doThrow(Class<? extends Throwable> toBeThrown); 103 104 /** 105 * Use it for stubbing consecutive calls in {@link Mockito#doThrow(Class)} style: 106 * <pre class="code"><code class="java"> 107 * doThrow(RuntimeException.class). 108 * doThrow(IllegalArgumentException.class) 109 * .when(mock).someVoidMethod(); 110 * </code></pre> 111 * See javadoc for {@link Mockito#doThrow(Class)} 112 * 113 * @param toBeThrown exception class to be thrown when the stubbed method is called 114 * @param nextToBeThrown exception class next to be thrown when the stubbed method is called 115 * @return stubber - to select a method for stubbing 116 * 117 * @since 2.1.0 118 */ 119 // Additional method helps users of JDK7+ to hide heap pollution / unchecked generics array creation 120 @SuppressWarnings ({"unchecked", "varargs"}) doThrow(Class<? extends Throwable> toBeThrown, Class<? extends Throwable>... nextToBeThrown)121 Stubber doThrow(Class<? extends Throwable> toBeThrown, Class<? extends Throwable>... nextToBeThrown); 122 123 /** 124 * Use it for stubbing consecutive calls in {@link Mockito#doAnswer(Answer)} style: 125 * <pre class="code"><code class="java"> 126 * doAnswer(answerOne). 127 * doAnswer(answerTwo) 128 * .when(mock).someVoidMethod(); 129 * </code></pre> 130 * See javadoc for {@link Mockito#doAnswer(Answer)} 131 * 132 * @param answer to answer when the stubbed method is called 133 * @return stubber - to select a method for stubbing 134 */ doAnswer(Answer answer)135 Stubber doAnswer(Answer answer); 136 137 /** 138 * Use it for stubbing consecutive calls in {@link Mockito#doNothing()} style: 139 * <pre class="code"><code class="java"> 140 * doNothing(). 141 * doThrow(new RuntimeException("two")) 142 * .when(mock).someVoidMethod(); 143 * </code></pre> 144 * See javadoc for {@link Mockito#doNothing()} 145 * 146 * @return stubber - to select a method for stubbing 147 */ doNothing()148 Stubber doNothing(); 149 150 /** 151 * Use it for stubbing consecutive calls in {@link Mockito#doReturn(Object)} style. 152 * <p> 153 * See javadoc for {@link Mockito#doReturn(Object)} 154 * 155 * @param toBeReturned to be returned when the stubbed method is called 156 * @return stubber - to select a method for stubbing 157 */ doReturn(Object toBeReturned)158 Stubber doReturn(Object toBeReturned); 159 160 /** 161 * Use it for stubbing consecutive calls in {@link Mockito#doReturn(Object)} style. 162 * <p> 163 * See javadoc for {@link Mockito#doReturn(Object, Object...)} 164 * 165 * @param toBeReturned to be returned when the stubbed method is called 166 * @param nextToBeReturned to be returned in consecutive calls when the stubbed method is called 167 * @return stubber - to select a method for stubbing 168 */ 169 @SuppressWarnings({"unchecked", "varargs"}) doReturn(Object toBeReturned, Object... nextToBeReturned)170 Stubber doReturn(Object toBeReturned, Object... nextToBeReturned); 171 172 /** 173 * Use it for stubbing consecutive calls in {@link Mockito#doCallRealMethod()} style. 174 * <p> 175 * See javadoc for {@link Mockito#doCallRealMethod()} 176 * 177 * @return stubber - to select a method for stubbing 178 */ doCallRealMethod()179 Stubber doCallRealMethod(); 180 } 181