1e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson/* 2e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Copyright (c) 2007 Mockito contributors 3e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * This program is made available under the terms of the MIT License. 4e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson */ 5e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinsonpackage org.mockito; 6e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson 7e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinsonimport org.mockito.internal.MockitoCore; 8e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinsonimport org.mockito.internal.creation.MockSettingsImpl; 9e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinsonimport org.mockito.internal.debugging.MockitoDebuggerImpl; 10e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinsonimport org.mockito.internal.stubbing.answers.*; 11e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinsonimport org.mockito.internal.stubbing.defaultanswers.ReturnsEmptyValues; 12e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinsonimport org.mockito.internal.stubbing.defaultanswers.ReturnsMoreEmptyValues; 13e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinsonimport org.mockito.internal.verification.VerificationModeFactory; 14e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinsonimport org.mockito.runners.MockitoJUnitRunner; 15e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinsonimport org.mockito.stubbing.*; 16e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinsonimport org.mockito.verification.Timeout; 17e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinsonimport org.mockito.verification.VerificationMode; 18e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinsonimport org.mockito.verification.VerificationWithTimeout; 19e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson 20e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson/** 21e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p align="left"><img src="logo.jpg"/></p> 22e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Mockito library enables mocks creation, verification and stubbing. 23e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 24e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * This javadoc content is also available on the <a href="http://mockito.org">http://mockito.org</a> web page. 25e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * All documentation is kept in javadocs because it guarantees consistency between what's on the web and what's in the source code. 26e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Also, it makes possible to access documentation straight from the IDE even if you work offline. 27e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 28e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <h1>Contents</h1> 29e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 30e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <b> 31e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <a href="#1">1. Let's verify some behaviour! </a><br/> 32e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <a href="#2">2. How about some stubbing? </a><br/> 33e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <a href="#3">3. Argument matchers </a><br/> 34e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <a href="#4">4. Verifying exact number of invocations / at least once / never </a><br/> 35e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <a href="#5">5. Stubbing void methods with exceptions </a><br/> 36e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <a href="#6">6. Verification in order </a><br/> 37e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <a href="#7">7. Making sure interaction(s) never happened on mock </a><br/> 38e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <a href="#8">8. Finding redundant invocations </a><br/> 39e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <a href="#9">9. Shorthand for mocks creation - <code>@Mock</code> annotation </a><br/> 40e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <a href="#10">10. Stubbing consecutive calls (iterator-style stubbing) </a><br/> 41e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <a href="#11">11. Stubbing with callbacks </a><br/> 42e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <a href="#12">12. <code>doReturn()</code>|<code>doThrow()</code>|<code>doAnswer()</code>|<code>doNothing()</code>|<code>doCallRealMethod()</code> family of methods</a><br/> 43e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <a href="#13">13. Spying on real objects </a><br/> 44e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <a href="#14">14. Changing default return values of unstubbed invocations (Since 1.7) </a><br/> 45e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <a href="#15">15. Capturing arguments for further assertions (Since 1.8.0) </a><br/> 46e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <a href="#16">16. Real partial mocks (Since 1.8.0) </a><br/> 47e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <a href="#17">17. Resetting mocks (Since 1.8.0) </a><br/> 48e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <a href="#18">18. Troubleshooting & validating framework usage (Since 1.8.0) </a><br/> 49e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <a href="#19">19. Aliases for behavior driven development (Since 1.8.0) </a><br/> 50e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <a href="#20">20. Serializable mocks (Since 1.8.1) </a><br/> 51e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <a href="#21">21. New annotations: <code>@Captor</code>, <code>@Spy</code>, <code>@InjectMocks</code> (Since 1.8.3) </a><br/> 52e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <a href="#22">22. Verification with timeout (Since 1.8.5) </a><br/> 53e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <a href="#23">23. (New) Automatic instantiation of <code>@Spies</code>, <code>@InjectMocks</code> and constructor injection goodness (Since 1.9.0)</a><br/> 54e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <a href="#24">24. (New) One-liner stubs (Since 1.9.0)</a><br/> 55e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <a href="#25">25. (New) Verification ignoring stubs (Since 1.9.0)</a><br/> 56e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <a href="#26">26. (**New**) Mocking details (Since 1.9.5)</a><br/> 57e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <a href="#27">27. (**New**) Delegate calls to real instance (Since 1.9.5)</a><br/> 58e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <a href="#28">28. (**New**) <code>MockMaker</code> API (Since 1.9.5)</a><br/> 59e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </b> 60e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 61e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 62e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Following examples mock a List, because everyone knows its interface (methods 63e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * like <code>add()</code>, <code>get()</code>, <code>clear()</code> will be used). <br> 64e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * You probably wouldn't mock List class 'in real'. 65e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 66e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 67e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 68e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 69e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <h3 id="1">1. <a class="meaningful_link" href="#verification">Let's verify some behaviour!</a></h3> 70e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 71e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 72e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //Let's import Mockito statically so that the code looks clearer 73e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * import static org.mockito.Mockito.*; 74e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 75e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //mock creation 76e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * List mockedList = mock(List.class); 77e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 78e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //using mock object 79e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * mockedList.add("one"); 80e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * mockedList.clear(); 81e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 82e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //verification 83e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * verify(mockedList).add("one"); 84e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * verify(mockedList).clear(); 85e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 86e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 87e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 88e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Once created, mock will remember all interactions. Then you can selectively 89e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * verify whatever interaction you are interested in. 90e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 91e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 92e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 93e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 94e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <h3 id="2">2. <a class="meaningful_link" href="#stubbing">How about some stubbing?</a></h3> 95e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 96e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 97e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //You can mock concrete classes, not only interfaces 98e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * LinkedList mockedList = mock(LinkedList.class); 99e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 100e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //stubbing 101e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * when(mockedList.get(0)).thenReturn("first"); 102e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * when(mockedList.get(1)).thenThrow(new RuntimeException()); 103e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 104e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //following prints "first" 105e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * System.out.println(mockedList.get(0)); 106e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 107e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //following throws runtime exception 108e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * System.out.println(mockedList.get(1)); 109e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 110e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //following prints "null" because get(999) was not stubbed 111e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * System.out.println(mockedList.get(999)); 112e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 113e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //Although it is possible to verify a stubbed invocation, usually <b>it's just redundant</b> 114e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //If your code cares what get(0) returns then something else breaks (often before even verify() gets executed). 115e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //If your code doesn't care what get(0) returns then it should not be stubbed. Not convinced? See <a href="http://monkeyisland.pl/2008/04/26/asking-and-telling">here</a>. 116e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * verify(mockedList).get(0); 117e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 118e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 119e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <ul> 120e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <li> By default, for all methods that return value, mock returns null, an 121e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * empty collection or appropriate primitive/primitive wrapper value (e.g: 0, 122e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * false, ... for int/Integer, boolean/Boolean, ...). </li> 123e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 124e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <li> Stubbing can be overridden: for example common stubbing can go to 125e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * fixture setup but the test methods can override it. 126e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Please note that overridding stubbing is a potential code smell that points out too much stubbing</li> 127e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 128e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <li> Once stubbed, the method will always return stubbed value regardless 129e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * of how many times it is called. </li> 130e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 131e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <li> Last stubbing is more important - when you stubbed the same method with 132e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * the same arguments many times. 133e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Other words: <b>the order of stubbing matters</b> but it is only meaningful rarely, 134e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * e.g. when stubbing exactly the same method calls or sometimes when argument matchers are used, etc.</li> 135e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 136e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </ul> 137e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 138e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 139e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 140e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <h3 id="3">3. <a class="meaningful_link" href="#argument_matchers">Argument matchers</a></h3> 141e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 142e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Mockito verifies argument values in natural java style: by using an <code>equals()</code> method. 143e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Sometimes, when extra flexibility is required then you might use argument matchers: 144e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 145e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 146e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //stubbing using built-in anyInt() argument matcher 147e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * when(mockedList.get(anyInt())).thenReturn("element"); 148e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 149e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //stubbing using hamcrest (let's say isValid() returns your own hamcrest matcher): 150e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * when(mockedList.contains(argThat(isValid()))).thenReturn("element"); 151e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 152e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //following prints "element" 153e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * System.out.println(mockedList.get(999)); 154e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 155e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //<b>you can also verify using an argument matcher</b> 156e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * verify(mockedList).get(anyInt()); 157e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 158e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 159e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 160e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Argument matchers allow flexible verification or stubbing. 161e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * {@link Matchers Click here to see} more built-in matchers 162e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * and examples of <b>custom argument matchers / hamcrest matchers</b>. 163e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 164e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * For information solely on <b>custom argument matchers</b> check out javadoc for {@link ArgumentMatcher} class. 165e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 166e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Be reasonable with using complicated argument matching. 167e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * The natural matching style using <code>equals()</code> with occasional <code>anyX()</code> matchers tend to give clean & simple tests. 168e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Sometimes it's just better to refactor the code to allow <code>equals()</code> matching or even implement <code>equals()</code> method to help out with testing. 169e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 170e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Also, read <a href="#15">section 15</a> or javadoc for {@link ArgumentCaptor} class. 171e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * {@link ArgumentCaptor} is a special implementation of an argument matcher that captures argument values for further assertions. 172e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 173e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <b>Warning on argument matchers:</b> 174e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 175e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * If you are using argument matchers, <b>all arguments</b> have to be provided 176e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * by matchers. 177e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 178e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * E.g: (example shows verification but the same applies to stubbing): 179e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 180e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 181e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * verify(mock).someMethod(anyInt(), anyString(), <b>eq("third argument")</b>); 182e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //above is correct - eq() is also an argument matcher 183e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 184e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * verify(mock).someMethod(anyInt(), anyString(), <b>"third argument"</b>); 185e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //above is incorrect - exception will be thrown because third argument is given without an argument matcher. 186e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 187e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 188e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 189e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Matcher methods like <code>anyObject()</code>, <code>eq()</code> <b>do not</b> return matchers. 190e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Internally, they record a matcher on a stack and return a dummy value (usually null). 191e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * This implementation is due static type safety imposed by java compiler. 192e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * The consequence is that you cannot use <code>anyObject()</code>, <code>eq()</code> methods outside of verified/stubbed method. 193e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 194e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 195e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 196e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 197e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <h3 id="4">4. <a class="meaningful_link" href="#exact_verification">Verifying exact number of invocations</a> / 198e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <a class="meaningful_link" href="#at_least_verification">at least x</a> / never</h3> 199e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 200e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 201e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //using mock 202e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * mockedList.add("once"); 203e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 204e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * mockedList.add("twice"); 205e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * mockedList.add("twice"); 206e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 207e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * mockedList.add("three times"); 208e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * mockedList.add("three times"); 209e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * mockedList.add("three times"); 210e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 211e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //following two verifications work exactly the same - times(1) is used by default 212e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * verify(mockedList).add("once"); 213e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * verify(mockedList, times(1)).add("once"); 214e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 215e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //exact number of invocations verification 216e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * verify(mockedList, times(2)).add("twice"); 217e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * verify(mockedList, times(3)).add("three times"); 218e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 219e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //verification using never(). never() is an alias to times(0) 220e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * verify(mockedList, never()).add("never happened"); 221e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 222e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //verification using atLeast()/atMost() 223e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * verify(mockedList, atLeastOnce()).add("three times"); 224e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * verify(mockedList, atLeast(2)).add("five times"); 225e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * verify(mockedList, atMost(5)).add("three times"); 226e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 227e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 228e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 229e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 230e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <b>times(1) is the default.</b> Therefore using times(1) explicitly can be 231e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * omitted. 232e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 233e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 234e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 235e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 236e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <h3 id="5">5. <a class="meaningful_link" href="#stubbing_with_exceptions">Stubbing void methods with exceptions</a></h3> 237e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 238e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 239e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * doThrow(new RuntimeException()).when(mockedList).clear(); 240e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 241e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //following throws RuntimeException: 242e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * mockedList.clear(); 243e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 244e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 245e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Read more about doThrow|doAnswer family of methods in paragraph 12. 246e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 247e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Initially, {@link Mockito#stubVoid(Object)} was used for stubbing voids. 248e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Currently <code>stubVoid()</code> is deprecated in favor of {@link Mockito#doThrow(Throwable)}. 249e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * This is because of improved readability and consistency with the family of {@link Mockito#doAnswer(Answer)} methods. 250e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 251e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 252e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 253e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 254e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <h3 id="6">6. <a class="meaningful_link" href="#in_order_verification">Verification in order</a></h3> 255e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 256e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 257e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * // A. Single mock whose methods must be invoked in a particular order 258e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * List singleMock = mock(List.class); 259e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 260e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //using a single mock 261e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * singleMock.add("was added first"); 262e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * singleMock.add("was added second"); 263e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 264e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //create an inOrder verifier for a single mock 265e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * InOrder inOrder = inOrder(singleMock); 266e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 267e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //following will make sure that add is first called with "was added first, then with "was added second" 268e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * inOrder.verify(singleMock).add("was added first"); 269e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * inOrder.verify(singleMock).add("was added second"); 270e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 271e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * // B. Multiple mocks that must be used in a particular order 272e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * List firstMock = mock(List.class); 273e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * List secondMock = mock(List.class); 274e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 275e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //using mocks 276e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * firstMock.add("was called first"); 277e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * secondMock.add("was called second"); 278e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 279e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //create inOrder object passing any mocks that need to be verified in order 280e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * InOrder inOrder = inOrder(firstMock, secondMock); 281e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 282e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //following will make sure that firstMock was called before secondMock 283e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * inOrder.verify(firstMock).add("was called first"); 284e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * inOrder.verify(secondMock).add("was called second"); 285e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 286e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * // Oh, and A + B can be mixed together at will 287e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 288e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 289e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Verification in order is flexible - <b>you don't have to verify all 290e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * interactions</b> one-by-one but only those that you are interested in 291e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * testing in order. 292e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 293e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Also, you can create InOrder object passing only mocks that are relevant for 294e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * in-order verification. 295e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 296e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 297e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 298e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 299e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <h3 id="7">7. <a class="meaningful_link" href="#never_verification">Making sure interaction(s) never happened on mock</a></h3> 300e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 301e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 302e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //using mocks - only mockOne is interacted 303e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * mockOne.add("one"); 304e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 305e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //ordinary verification 306e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * verify(mockOne).add("one"); 307e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 308e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //verify that method was never called on a mock 309e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * verify(mockOne, never()).add("two"); 310e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 311e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //verify that other mocks were not interacted 312e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * verifyZeroInteractions(mockTwo, mockThree); 313e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 314e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 315e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 316e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 317e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 318e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 319e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <h3 id="8">8. <a class="meaningful_link" href="#finding_redundant_invocations">Finding redundant invocations</a></h3> 320e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 321e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 322e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //using mocks 323e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * mockedList.add("one"); 324e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * mockedList.add("two"); 325e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 326e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * verify(mockedList).add("one"); 327e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 328e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //following verification will fail 329e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * verifyNoMoreInteractions(mockedList); 330e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 331e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 332e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * A word of <b>warning</b>: 333e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Some users who did a lot of classic, expect-run-verify mocking tend to use <code>verifyNoMoreInteractions()</code> very often, even in every test method. 334e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <code>verifyNoMoreInteractions()</code> is not recommended to use in every test method. 335e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <code>verifyNoMoreInteractions()</code> is a handy assertion from the interaction testing toolkit. Use it only when it's relevant. 336e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Abusing it leads to <strong>overspecified</strong>, <strong>less maintainable</strong> tests. You can find further reading 337e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <a href="http://monkeyisland.pl/2008/07/12/should-i-worry-about-the-unexpected/">here</a>. 338e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 339e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 340e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * See also {@link Mockito#never()} - it is more explicit and 341e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * communicates the intent well. 342e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 343e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 344e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 345e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 346e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 347e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <h3 id="9">9. <a class="meaningful_link" href="#mock_annotation">Shorthand for mocks creation - <code>@Mock</code> annotation</a></h3> 348e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 349e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <ul> 350e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <li>Minimizes repetitive mock creation code.</li> 351e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <li>Makes the test class more readable.</li> 352e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <li>Makes the verification error easier to read because the <b>field name</b> 353e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * is used to identify the mock.</li> 354e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </ul> 355e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 356e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 357e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * public class ArticleManagerTest { 358e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 359e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @Mock private ArticleCalculator calculator; 360e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @Mock private ArticleDatabase database; 361e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @Mock private UserProvider userProvider; 362e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 363e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * private ArticleManager manager; 364e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 365e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 366e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <b>Important!</b> This needs to be somewhere in the base class or a test 367e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * runner: 368e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 369e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 370e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * MockitoAnnotations.initMocks(testClass); 371e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 372e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 373e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * You can use built-in runner: {@link MockitoJUnitRunner}. 374e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 375e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Read more here: {@link MockitoAnnotations} 376e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 377e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 378e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 379e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 380e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <h3 id="10">10. <a class="meaningful_link" href="#stubbing_consecutive_calls">Stubbing consecutive calls</a> (iterator-style stubbing)</h3> 381e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 382e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Sometimes we need to stub with different return value/exception for the same 383e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * method call. Typical use case could be mocking iterators. 384e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Original version of Mockito did not have this feature to promote simple mocking. 385e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * For example, instead of iterators one could use {@link Iterable} or simply 386e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * collections. Those offer natural ways of stubbing (e.g. using real 387e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * collections). In rare scenarios stubbing consecutive calls could be useful, 388e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * though: 389e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 390e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 391e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 392e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * when(mock.someMethod("some arg")) 393e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * .thenThrow(new RuntimeException()) 394e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * .thenReturn("foo"); 395e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 396e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //First call: throws runtime exception: 397e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * mock.someMethod("some arg"); 398e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 399e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //Second call: prints "foo" 400e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * System.out.println(mock.someMethod("some arg")); 401e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 402e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //Any consecutive call: prints "foo" as well (last stubbing wins). 403e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * System.out.println(mock.someMethod("some arg")); 404e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 405e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 406e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Alternative, shorter version of consecutive stubbing: 407e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 408e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 409e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * when(mock.someMethod("some arg")) 410e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * .thenReturn("one", "two", "three"); 411e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 412e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 413e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 414e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 415e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 416e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <h3 id="11">11. <a class="meaningful_link" href="#answer_stubs">Stubbing with callbacks</a></h3> 417e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 418e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Allows stubbing with generic {@link Answer} interface. 419e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 420e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Yet another controversial feature which was not included in Mockito 421e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * originally. We recommend using simple stubbing with <code>thenReturn()</code> or 422e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <code>thenThrow()</code> only. Those two should be <b>just enough</b> to test/test-drive 423e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * any clean & simple code. 424e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 425e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 426e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * when(mock.someMethod(anyString())).thenAnswer(new Answer() { 427e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Object answer(InvocationOnMock invocation) { 428e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Object[] args = invocation.getArguments(); 429e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Object mock = invocation.getMock(); 430e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * return "called with arguments: " + args; 431e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * } 432e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * }); 433e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 434e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //Following prints "called with arguments: foo" 435e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * System.out.println(mock.someMethod("foo")); 436e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 437e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 438e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 439e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 440e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 441e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <h3 id="12">12. <a class="meaningful_link" href="#do_family_methods_stubs"><code>doReturn()</code>|<code>doThrow()</code>| 442e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <code>doAnswer()</code>|<code>doNothing()</code>|<code>doCallRealMethod()</code> family of methods</a></h3> 443e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 444e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Stubbing voids requires different approach from {@link Mockito#when(Object)} because the compiler does not 445e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * like void methods inside brackets... 446e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 447e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * {@link Mockito#doThrow(Throwable)} replaces the {@link Mockito#stubVoid(Object)} method for stubbing voids. 448e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * The main reason is improved readability and consistency with the family of <code>doAnswer()</code> methods. 449e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 450e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Use <code>doThrow()</code> when you want to stub a void method with an exception: 451e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 452e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * doThrow(new RuntimeException()).when(mockedList).clear(); 453e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 454e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //following throws RuntimeException: 455e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * mockedList.clear(); 456e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 457e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 458e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 459e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * You can use <code>doThrow()</code>, <code>doAnswer()</code>, <code>doNothing()</code>, <code>doReturn()</code> 460e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * and <code>doCallRealMethod()</code> in place of the corresponding call with <code>when()</code>, for any method. 461e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * It is necessary when you 462e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <ul> 463e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <li>stub void methods</li> 464e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <li>stub methods on spy objects (see below)</li> 465e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <li>stub the same method more than once, to change the behaviour of a mock in the middle of a test.</li> 466e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </ul> 467e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * but you may prefer to use these methods in place of the alternative with <code>when()</code>, for all of your stubbing calls. 468e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 469e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Read more about these methods: 470e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 471e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * {@link Mockito#doReturn(Object)} 472e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 473e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * {@link Mockito#doThrow(Throwable)} 474e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 475e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * {@link Mockito#doThrow(Class)} 476e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 477e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * {@link Mockito#doAnswer(Answer)} 478e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 479e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * {@link Mockito#doNothing()} 480e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 481e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * {@link Mockito#doCallRealMethod()} 482e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 483e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 484e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 485e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 486e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <h3 id="13">13. <a class="meaningful_link" href="#spy">Spying on real objects</a></h3> 487e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 488e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * You can create spies of real objects. When you use the spy then the <b>real</b> methods are called 489e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * (unless a method was stubbed). 490e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 491e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Real spies should be used <b>carefully and occasionally</b>, for example when dealing with legacy code. 492e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 493e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 494e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Spying on real objects can be associated with "partial mocking" concept. 495e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <b>Before the release 1.8</b>, Mockito spies were not real partial mocks. 496e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * The reason was we thought partial mock is a code smell. 497e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * At some point we found legitimate use cases for partial mocks 498e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * (3rd party interfaces, interim refactoring of legacy code, the full article is <a href= 499e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * "http://monkeyisland.pl/2009/01/13/subclass-and-override-vs-partial-mocking-vs-refactoring" 500e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * >here</a>) 501e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 502e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 503e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 504e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * List list = new LinkedList(); 505e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * List spy = spy(list); 506e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 507e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //optionally, you can stub out some methods: 508e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * when(spy.size()).thenReturn(100); 509e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 510e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //using the spy calls <b>*real*</b> methods 511e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * spy.add("one"); 512e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * spy.add("two"); 513e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 514e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //prints "one" - the first element of a list 515e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * System.out.println(spy.get(0)); 516e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 517e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //size() method was stubbed - 100 is printed 518e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * System.out.println(spy.size()); 519e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 520e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //optionally, you can verify 521e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * verify(spy).add("one"); 522e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * verify(spy).add("two"); 523e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 524e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 525e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <h4>Important gotcha on spying real objects!</h4> 526e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <ol> 527e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <li>Sometimes it's impossible or impractical to use {@link Mockito#when(Object)} for stubbing spies. 528e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Therefore when using spies please consider <code>doReturn</code>|<code>Answer</code>|<code>Throw()</code> family of 529e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * methods for stubbing. Example: 530e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 531e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 532e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * List list = new LinkedList(); 533e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * List spy = spy(list); 534e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 535e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //Impossible: real method is called so spy.get(0) throws IndexOutOfBoundsException (the list is yet empty) 536e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * when(spy.get(0)).thenReturn("foo"); 537e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 538e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //You have to use doReturn() for stubbing 539e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * doReturn("foo").when(spy).get(0); 540e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 541e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </li> 542e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 543e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <li>Mockito <b>*does not*</b> delegate calls to the passed real instance, instead it actually creates a copy of it. 544e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * So if you keep the real instance and interact with it, don't expect the spied to be aware of those interaction 545e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * and their effect on real instance state. 546e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * The corollary is that when an <b>*unstubbed*</b> method is called <b>*on the spy*</b> but <b>*not on the real instance*</b>, 547e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * you won't see any effects on the real instance. 548e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </li> 549e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 550e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <li>Watch out for final methods. 551e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Mockito doesn't mock final methods so the bottom line is: when you spy on real objects + you try to stub a final method = trouble. 552e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Also you won't be able to verify those method as well. 553e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </li> 554e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </ol> 555e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 556e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 557e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 558e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 559e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <h3 id="14">14. Changing <a class="meaningful_link" href="#defaultreturn">default return values of unstubbed invocations</a> (Since 1.7)</h3> 560e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 561e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * You can create a mock with specified strategy for its return values. 562e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * It's quite advanced feature and typically you don't need it to write decent tests. 563e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * However, it can be helpful for working with <b>legacy systems</b>. 564e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 565e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * It is the default answer so it will be used <b>only when you don't</b> stub the method call. 566e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 567e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 568e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Foo mock = mock(Foo.class, Mockito.RETURNS_SMART_NULLS); 569e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Foo mockTwo = mock(Foo.class, new YourOwnAnswer()); 570e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 571e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 572e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 573e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Read more about this interesting implementation of <i>Answer</i>: {@link Mockito#RETURNS_SMART_NULLS} 574e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 575e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 576e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 577e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 578e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <h3 id="15">15. <a class="meaningful_link" href="#captors">Capturing arguments</a> for further assertions (Since 1.8.0)</h3> 579e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 580e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Mockito verifies argument values in natural java style: by using an <code>equals()</code> method. 581e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * This is also the recommended way of matching arguments because it makes tests clean & simple. 582e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * In some situations though, it is helpful to assert on certain arguments after the actual verification. 583e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * For example: 584e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 585e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * ArgumentCaptor<Person> argument = ArgumentCaptor.forClass(Person.class); 586e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * verify(mock).doSomething(argument.capture()); 587e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * assertEquals("John", argument.getValue().getName()); 588e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 589e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 590e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <b>Warning:</b> it is recommended to use ArgumentCaptor with verification <b>but not</b> with stubbing. 591e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Using ArgumentCaptor with stubbing may decrease test readability because captor is created outside of assert (aka verify or 'then') block. 592e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Also it may reduce defect localization because if stubbed method was not called then no argument is captured. 593e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 594e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * In a way ArgumentCaptor is related to custom argument matchers (see javadoc for {@link ArgumentMatcher} class). 595e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Both techniques can be used for making sure certain arguments where passed to mocks. 596e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * However, ArgumentCaptor may be a better fit if: 597e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <ul> 598e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <li>custom argument matcher is not likely to be reused</li> 599e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <li>you just need it to assert on argument values to complete verification</li> 600e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </ul> 601e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Custom argument matchers via {@link ArgumentMatcher} are usually better for stubbing. 602e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 603e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 604e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 605e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 606e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <h3 id="16">16. <a class="meaningful_link" href="#partial_mocks">Real partial mocks</a> (Since 1.8.0)</h3> 607e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 608e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Finally, after many internal debates & discussions on the mailing list, partial mock support was added to Mockito. 609e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Previously we considered partial mocks as code smells. However, we found a legitimate use case for partial mocks - more reading: 610e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <a href="http://monkeyisland.pl/2009/01/13/subclass-and-override-vs-partial-mocking-vs-refactoring">here</a> 611e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 612e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <b>Before release 1.8</b> <code>spy()</code> was not producing real partial mocks and it was confusing for some users. 613e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Read more about spying: <a href="#13">here</a> or in javadoc for {@link Mockito#spy(Object)} method. 614e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 615e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 616e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //you can create partial mock with spy() method: 617e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * List list = spy(new LinkedList()); 618e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 619e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //you can enable partial mock capabilities selectively on mocks: 620e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Foo mock = mock(Foo.class); 621e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //Be sure the real implementation is 'safe'. 622e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //If real implementation throws exceptions or depends on specific state of the object then you're in trouble. 623e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * when(mock.someMethod()).thenCallRealMethod(); 624e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 625e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 626e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * As usual you are going to read <b>the partial mock warning</b>: 627e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Object oriented programming is more less tackling complexity by dividing the complexity into separate, specific, SRPy objects. 628e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * How does partial mock fit into this paradigm? Well, it just doesn't... 629e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Partial mock usually means that the complexity has been moved to a different method on the same object. 630e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * In most cases, this is not the way you want to design your application. 631e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 632e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * However, there are rare cases when partial mocks come handy: 633e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * dealing with code you cannot change easily (3rd party interfaces, interim refactoring of legacy code etc.) 634e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * However, I wouldn't use partial mocks for new, test-driven & well-designed code. 635e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 636e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 637e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 638e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 639e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <h3 id="17">17. <a class="meaningful_link" href="#resetting_mocks">Resetting mocks</a> (Since 1.8.0)</h3> 640e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 641e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Smart Mockito users hardly use this feature because they know it could be a sign of poor tests. 642e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Normally, you don't need to reset your mocks, just create new mocks for each test method. 643e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 644e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Instead of <code>reset()</code> please consider writing simple, small and focused test methods over lengthy, over-specified tests. 645e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <b>First potential code smell is <code>reset()</code> in the middle of the test method.</b> This probably means you're testing too much. 646e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Follow the whisper of your test methods: "Please keep us small & focused on single behavior". 647e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * There are several threads about it on mockito mailing list. 648e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 649e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * The only reason we added <code>reset()</code> method is to 650e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * make it possible to work with container-injected mocks. 651e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * See issue 55 (<a href="http://code.google.com/p/mockito/issues/detail?id=55">here</a>) 652e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * or FAQ (<a href="http://code.google.com/p/mockito/wiki/FAQ">here</a>). 653e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 654e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <b>Don't harm yourself.</b> <code>reset()</code> in the middle of the test method is a code smell (you're probably testing too much). 655e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 656e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * List mock = mock(List.class); 657e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * when(mock.size()).thenReturn(10); 658e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * mock.add(1); 659e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 660e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * reset(mock); 661e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //at this point the mock forgot any interactions & stubbing 662e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 663e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 664e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 665e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 666e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 667e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <h3 id="18">18. <a class="meaningful_link" href="#framework_validation">Troubleshooting & validating framework usage</a> (Since 1.8.0)</h3> 668e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 669e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * First of all, in case of any trouble, I encourage you to read the Mockito FAQ: 670e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <a href="http://code.google.com/p/mockito/wiki/FAQ">http://code.google.com/p/mockito/wiki/FAQ</a> 671e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 672e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * In case of questions you may also post to mockito mailing list: 673e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <a href="http://groups.google.com/group/mockito">http://groups.google.com/group/mockito</a> 674e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 675e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Next, you should know that Mockito validates if you use it correctly <b>all the time</b>. 676e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * However, there's a gotcha so please read the javadoc for {@link Mockito#validateMockitoUsage()} 677e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 678e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 679e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 680e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 681e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <h3 id="19">19. <a class="meaningful_link" href="#bdd_mockito">Aliases for behavior driven development</a> (Since 1.8.0)</h3> 682e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 683e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Behavior Driven Development style of writing tests uses <b>//given //when //then</b> comments as fundamental parts of your test methods. 684e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * This is exactly how we write our tests and we warmly encourage you to do so! 685e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 686e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Start learning about BDD here: <a href="http://en.wikipedia.org/wiki/Behavior_Driven_Development">http://en.wikipedia.org/wiki/Behavior_Driven_Development</a> 687e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 688e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * The problem is that current stubbing api with canonical role of <b>when</b> word does not integrate nicely with <b>//given //when //then</b> comments. 689e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * It's because stubbing belongs to <b>given</b> component of the test and not to the <b>when</b> component of the test. 690e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Hence {@link BDDMockito} class introduces an alias so that you stub method calls with {@link BDDMockito#given(Object)} method. 691e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Now it really nicely integrates with the <b>given</b> component of a BDD style test! 692e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 693e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Here is how the test might look like: 694e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 695e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * import static org.mockito.BDDMockito.*; 696e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 697e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Seller seller = mock(Seller.class); 698e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Shop shop = new Shop(seller); 699e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 700e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * public void shouldBuyBread() throws Exception { 701e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //given 702e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * given(seller.askForBread()).willReturn(new Bread()); 703e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 704e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //when 705e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Goods goods = shop.buyBread(); 706e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 707e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //then 708e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * assertThat(goods, containBread()); 709e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * } 710e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 711e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 712e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 713e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 714e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 715e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <h3 id="20">20. <a class="meaningful_link" href="#serializable_mocks">Serializable mocks</a> (Since 1.8.1)</h3> 716e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 717e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Mocks can be made serializable. With this feature you can use a mock in a place that requires dependencies to be serializable. 718e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 719e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * WARNING: This should be rarely used in unit testing. 720e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 721e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * The behaviour was implemented for a specific use case of a BDD spec that had an unreliable external dependency. This 722e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * was in a web environment and the objects from the external dependency were being serialized to pass between layers. 723e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 724e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * To create serializable mock use {@link MockSettings#serializable()}: 725e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 726e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * List serializableMock = mock(List.class, withSettings().serializable()); 727e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 728e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 729e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * The mock can be serialized assuming all the normal <a href='http://java.sun.com/j2se/1.5.0/docs/api/java/io/Serializable.html'> 730e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * serialization requirements</a> are met by the class. 731e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 732e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Making a real object spy serializable is a bit more effort as the spy(...) method does not have an overloaded version 733e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * which accepts MockSettings. No worries, you will hardly ever use it. 734e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 735e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 736e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * List<Object> list = new ArrayList<Object>(); 737e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * List<Object> spy = mock(ArrayList.class, withSettings() 738e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * .spiedInstance(list) 739e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * .defaultAnswer(CALLS_REAL_METHODS) 740e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * .serializable()); 741e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 742e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 743e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 744e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 745e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 746e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <h3 id="21">21. New annotations: <a class="meaningful_link" href="#captor_annotation"><code>@Captor</code></a>, 747e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <a class="meaningful_link" href="#spy_annotation"><code>@Spy</code></a>, 748e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <a class="meaningful_link" href="#injectmocks_annotation"><code>@InjectMocks</code></a> (Since 1.8.3)</h3> 749e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 750e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 751e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Release 1.8.3 brings new annotations that may be helpful on occasion: 752e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 753e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <ul> 754e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <li>@{@link Captor} simplifies creation of {@link ArgumentCaptor} 755e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * - useful when the argument to capture is a nasty generic class and you want to avoid compiler warnings 756e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <li>@{@link Spy} - you can use it instead {@link Mockito#spy(Object)}. 757e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <li>@{@link InjectMocks} - injects mock or spy fields into tested object automatically. 758e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </ul> 759e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 760e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 761e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Note that @{@link InjectMocks} can only be used in combination with the @{@link Spy} annotation, it means 762e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * that Mockito will inject mocks in a partial mock under testing. As a remainder, please read point 16 about partial mocks. 763e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 764e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 765e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * All new annotations are <b>*only*</b> processed on {@link MockitoAnnotations#initMocks(Object)}. 766e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Just like for @{@link Mock} annotation you can use the built-in runner: {@link MockitoJUnitRunner}. 767e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 768e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 769e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 770e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 771e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 772e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <h3 id="22">22. <a class="meaningful_link" href="#verification_timeout">Verification with timeout</a> (Since 1.8.5)</h3> 773e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 774e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Allows verifying with timeout. It causes a verify to wait for a specified period of time for a desired 775e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * interaction rather than fails immediately if had not already happened. May be useful for testing in concurrent 776e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * conditions. 777e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 778e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * It feels this feature should be used rarely - figure out a better way of testing your multi-threaded system. 779e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 780e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Not yet implemented to work with InOrder verification. 781e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 782e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Examples: 783e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 784e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 785e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //passes when someMethod() is called within given time span 786e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * verify(mock, timeout(100)).someMethod(); 787e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //above is an alias to: 788e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * verify(mock, timeout(100).times(1)).someMethod(); 789e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 790e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //passes when someMethod() is called <b>*exactly*</b> 2 times within given time span 791e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * verify(mock, timeout(100).times(2)).someMethod(); 792e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 793e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //passes when someMethod() is called <b>*at least*</b> 2 times within given time span 794e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * verify(mock, timeout(100).atLeast(2)).someMethod(); 795e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 796e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //verifies someMethod() within given time span using given verification mode 797e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //useful only if you have your own custom verification modes. 798e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * verify(mock, new Timeout(100, yourOwnVerificationMode)).someMethod(); 799e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 800e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 801e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 802e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 803e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 804e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <h3 id="23">23. (New) <a class="meaningful_link" href="#automatic_instantiation">Automatic instantiation of <code>@Spies</code>, 805e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <code>@InjectMocks</code></a> and <a class="meaningful_link" href="#constructor_injection">constructor injection goodness</a> (Since 1.9.0)</h3> 806e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 807e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 808e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Mockito will now try to instantiate @{@link Spy} and will instantiate @{@link InjectMocks} fields 809e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * using <b>constructor</b> injection, <b>setter</b> injection, or <b>field</b> injection. 810e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 811e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * To take advantage of this feature you need to use {@link MockitoAnnotations#initMocks(Object)} or {@link MockitoJUnitRunner}. 812e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 813e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Read more about available tricks and the rules of injection in the javadoc for {@link InjectMocks} 814e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 815e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //instead: 816e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @Spy BeerDrinker drinker = new BeerDrinker(); 817e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //you can write: 818e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @Spy BeerDrinker drinker; 819e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 820e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //same applies to @InjectMocks annotation: 821e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @InjectMocks LocalPub; 822e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 823e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 824e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 825e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 826e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 827e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <h3 id="24">24. (New) <a class="meaningful_link" href="#one_liner_stub">One-liner stubs</a> (Since 1.9.0)</h3> 828e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 829e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Mockito will now allow you to create mocks when stubbing. 830e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Basically, it allows to create a stub in one line of code. 831e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * This can be helpful to keep test code clean. 832e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * For example, some boring stub can be created & stubbed at field initialization in a test: 833e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 834e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * public class CarTest { 835e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Car boringStubbedCar = when(mock(Car.class).shiftGear()).thenThrow(EngineNotStarted.class).getMock(); 836e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 837e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @Test public void should... {} 838e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 839e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 840e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 841e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 842e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 843e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <h3 id="25">25. (New) <a class="meaningful_link" href="#ignore_stubs_verification">Verification ignoring stubs</a> (Since 1.9.0)</h3> 844e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 845e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Mockito will now allow to ignore stubbing for the sake of verification. 846e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Sometimes useful when coupled with <code>verifyNoMoreInteractions()</code> or verification <code>inOrder()</code>. 847e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Helps avoiding redundant verification of stubbed calls - typically we're not interested in verifying stubs. 848e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 849e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <b>Warning</b>, <code>ignoreStubs()</code> might lead to overuse of verifyNoMoreInteractions(ignoreStubs(...)); 850e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Bear in mind that Mockito does not recommend bombarding every test with <code>verifyNoMoreInteractions()</code> 851e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * for the reasons outlined in javadoc for {@link Mockito#verifyNoMoreInteractions(Object...)} 852e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p>Some examples: 853e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 854e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * verify(mock).foo(); 855e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * verify(mockTwo).bar(); 856e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 857e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //ignores all stubbed methods: 858e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * verifyNoMoreInvocations(ignoreStubs(mock, mockTwo)); 859e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 860e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //creates InOrder that will ignore stubbed 861e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * InOrder inOrder = inOrder(ignoreStubs(mock, mockTwo)); 862e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * inOrder.verify(mock).foo(); 863e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * inOrder.verify(mockTwo).bar(); 864e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * inOrder.verifyNoMoreInteractions(); 865e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 866e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 867e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Advanced examples and more details can be found in javadoc for {@link Mockito#ignoreStubs(Object...)} 868e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 869e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 870e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 871e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 872e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <h3 id="26">26. (**New**) <a class="meaningful_link" href="#mocking_details">Mocking details</a> (Since 1.9.5)</h3> 873e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 874e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * To identify whether a particular object is a mock or a spy: 875e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 876e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Mockito.mockingDetails(someObject).isMock(); 877e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Mockito.mockingDetails(someObject).isSpy(); 878e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 879e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Both the {@link MockingDetails#isMock} and {@link MockingDetails#isSpy()} methods return <code>boolean</code>. 880e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * As a spy is just a different kind of mock, <code>isMock()</code> returns true if the object is a spy. 881e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * In future Mockito versions MockingDetails may grow and provide other useful information about the mock, 882e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * e.g. invocations, stubbing info, etc. 883e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 884e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 885e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 886e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 887e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <h3 id="27">27. (**New**) <a class="meaningful_link" href="#delegating_call_to_real_instance">Delegate calls to real instance</a> (Since 1.9.5)</h3> 888e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 889e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p>Useful for spies or partial mocks of objects <strong>that are difficult to mock or spy</strong> using the usual spy API. 890e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Possible use cases: 891e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <ul> 892e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <li>Final classes but with an interface</li> 893e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <li>Already custom proxied object</li> 894e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <li>Special objects with a finalize method, i.e. to avoid executing it 2 times</li> 895e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </ul> 896e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 897e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p>The difference with the regular spy: 898e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <ul> 899e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <li> 900e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * The regular spy ({@link #spy(Object)}) contains <strong>all</strong> state from the spied instance 901e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * and the methods are invoked on the spy. The spied instance is only used at mock creation to copy the state from. 902e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * If you call a method on a regular spy and it internally calls other methods on this spy, those calls are remembered 903e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * for verifications, and they can be effectively stubbed. 904e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </li> 905e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <li> 906e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * The mock that delegates simply delegates all methods to the delegate. 907e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * The delegate is used all the time as methods are delegated onto it. 908e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * If you call a method on a mock that delegates and it internally calls other methods on this mock, 909e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * those calls are <strong>not</strong> remembered for verifications, stubbing does not have effect on them, too. 910e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Mock that delegates is less powerful than the regular spy but it is useful when the regular spy cannot be created. 911e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </li> 912e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </ul> 913e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 914e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 915e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * See more information in docs for {@link AdditionalAnswers#delegatesTo(Object)}. 916e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 917e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 918e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 919e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 920e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <h3 id="28">28. (**New**) <a class="meaningful_link" href="#mock_maker_plugin"><code>MockMaker</code> API</a> (Since 1.9.5)</h3> 921e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p>Driven by requirements and patches from Google Android guys Mockito now offers an extension point 922e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * that allows replacing the proxy generation engine. By default, Mockito uses cglib to create dynamic proxies. 923e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p>The extension point is for advanced users that want to extend Mockito. For example, it is now possible 924e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * to use Mockito for Android testing with a help of dexmaker. 925e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p>For more details, motivations and examples please refer to 926e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * the docs for {@link org.mockito.plugins.MockMaker}. 927e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 928e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson */ 929e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson@SuppressWarnings("unchecked") 930e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinsonpublic class Mockito extends Matchers { 931e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson 932e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson static final MockitoCore MOCKITO_CORE = new MockitoCore(); 933e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson 934e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson /** 935e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * The default <code>Answer</code> of every mock <b>if</b> the mock was not stubbed. 936e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Typically it just returns some empty value. 937e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 938e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * {@link Answer} can be used to define the return values of unstubbed invocations. 939e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 940e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * This implementation first tries the global configuration. 941e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * If there is no global configuration then it uses {@link ReturnsEmptyValues} (returns zeros, empty collections, nulls, etc.) 942e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson */ 943e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson public static final Answer<Object> RETURNS_DEFAULTS = Answers.RETURNS_DEFAULTS.get(); 944e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson 945e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson /** 946e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Optional <code>Answer</code> to be used with {@link Mockito#mock(Class, Answer)}. 947e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 948e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * {@link Answer} can be used to define the return values of unstubbed invocations. 949e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 950e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * This implementation can be helpful when working with legacy code. 951e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Unstubbed methods often return null. If your code uses the object returned by an unstubbed call you get a NullPointerException. 952e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * This implementation of Answer <b>returns SmartNull instead of null</b>. 953e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <code>SmartNull</code> gives nicer exception message than NPE because it points out the line where unstubbed method was called. You just click on the stack trace. 954e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 955e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <code>ReturnsSmartNulls</code> first tries to return ordinary return values (see {@link ReturnsMoreEmptyValues}) 956e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * then it tries to return SmartNull. If the return type is final then plain null is returned. 957e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 958e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <code>ReturnsSmartNulls</code> will be probably the default return values strategy in Mockito 2.0. 959e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 960e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Example: 961e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 962e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Foo mock = (Foo.class, RETURNS_SMART_NULLS); 963e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 964e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //calling unstubbed method here: 965e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Stuff stuff = mock.getStuff(); 966e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 967e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //using object returned by unstubbed call: 968e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * stuff.doSomething(); 969e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 970e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //Above doesn't yield NullPointerException this time! 971e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //Instead, SmartNullPointerException is thrown. 972e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //Exception's cause links to unstubbed <i>mock.getStuff()</i> - just click on the stack trace. 973e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 974e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson */ 975e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson public static final Answer<Object> RETURNS_SMART_NULLS = Answers.RETURNS_SMART_NULLS.get(); 976e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson 977e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson /** 978e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Optional <code>Answer</code> to be used with {@link Mockito#mock(Class, Answer)} 979e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 980e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * {@link Answer} can be used to define the return values of unstubbed invocations. 981e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 982e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * This implementation can be helpful when working with legacy code. 983e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 984e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * ReturnsMocks first tries to return ordinary return values (see {@link ReturnsMoreEmptyValues}) 985e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * then it tries to return mocks. If the return type cannot be mocked (e.g. is final) then plain null is returned. 986e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 987e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson */ 988e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson public static final Answer<Object> RETURNS_MOCKS = Answers.RETURNS_MOCKS.get(); 989e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson 990e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson /** 991e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Optional <code>Answer</code> to be used with {@link Mockito#mock(Class, Answer)}. 992e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 993e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Example that shows how deep stub works: 994e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 995e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Foo mock = mock(Foo.class, RETURNS_DEEP_STUBS); 996e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 997e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * // note that we're stubbing a chain of methods here: getBar().getName() 998e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * when(mock.getBar().getName()).thenReturn("deep"); 999e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1000e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * // note that we're chaining method calls: getBar().getName() 1001e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * assertEquals("deep", mock.getBar().getName()); 1002e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 1003e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </p> 1004e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1005e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1006e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <strong>WARNING: </strong> 1007e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * This feature should rarely be required for regular clean code! Leave it for legacy code. 1008e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Mocking a mock to return a mock, to return a mock, (...), to return something meaningful 1009e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * hints at violation of Law of Demeter or mocking a value object (a well known anti-pattern). 1010e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </p> 1011e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1012e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1013e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Good quote I've seen one day on the web: <strong>every time a mock returns a mock a fairy dies</strong>. 1014e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </p> 1015e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1016e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1017e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Please note that this answer will return existing mocks that matches the stub. This 1018e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * behavior is ok with deep stubs and allows verification to work on the last mock of the chain. 1019e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 1020e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * when(mock.getBar(anyString()).getThingy().getName()).thenReturn("deep"); 1021e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1022e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * mock.getBar("candy bar").getThingy().getName(); 1023e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1024e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * assertSame(mock.getBar(anyString()).getThingy().getName(), mock.getBar(anyString()).getThingy().getName()); 1025e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * verify(mock.getBar("candy bar").getThingy()).getName(); 1026e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * verify(mock.getBar(anyString()).getThingy()).getName(); 1027e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 1028e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </p> 1029e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1030e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1031e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Verification only works with the last mock in the chain. You can use verification modes. 1032e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 1033e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * when(person.getAddress(anyString()).getStreet().getName()).thenReturn("deep"); 1034e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * when(person.getAddress(anyString()).getStreet(Locale.ITALIAN).getName()).thenReturn("deep"); 1035e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * when(person.getAddress(anyString()).getStreet(Locale.CHINESE).getName()).thenReturn("deep"); 1036e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1037e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * person.getAddress("the docks").getStreet().getName(); 1038e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * person.getAddress("the docks").getStreet().getLongName(); 1039e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * person.getAddress("the docks").getStreet(Locale.ITALIAN).getName(); 1040e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * person.getAddress("the docks").getStreet(Locale.CHINESE).getName(); 1041e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1042e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * // note that we are actually referring to the very last mock in the stubbing chain. 1043e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * InOrder inOrder = inOrder( 1044e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * person.getAddress("the docks").getStreet(), 1045e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * person.getAddress("the docks").getStreet(Locale.CHINESE), 1046e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * person.getAddress("the docks").getStreet(Locale.ITALIAN) 1047e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * ); 1048e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * inOrder.verify(person.getAddress("the docks").getStreet(), times(1)).getName(); 1049e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * inOrder.verify(person.getAddress("the docks").getStreet()).getLongName(); 1050e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * inOrder.verify(person.getAddress("the docks").getStreet(Locale.ITALIAN), atLeast(1)).getName(); 1051e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * inOrder.verify(person.getAddress("the docks").getStreet(Locale.CHINESE)).getName(); 1052e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 1053e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </p> 1054e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1055e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1056e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * How deep stub work internally? 1057e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 1058e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //this: 1059e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Foo mock = mock(Foo.class, RETURNS_DEEP_STUBS); 1060e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * when(mock.getBar().getName(), "deep"); 1061e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1062e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //is equivalent of 1063e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Foo foo = mock(Foo.class); 1064e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Bar bar = mock(Bar.class); 1065e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * when(foo.getBar()).thenReturn(bar); 1066e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * when(bar.getName()).thenReturn("deep"); 1067e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 1068e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </p> 1069e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1070e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1071e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * This feature will not work when any return type of methods included in the chain cannot be mocked 1072e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * (for example: is a primitive or a final class). This is because of java type system. 1073e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </p> 1074e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson */ 1075e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson public static final Answer<Object> RETURNS_DEEP_STUBS = Answers.RETURNS_DEEP_STUBS.get(); 1076e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson 1077e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson /** 1078e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Optional <code>Answer</code> to be used with {@link Mockito#mock(Class, Answer)} 1079e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1080e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * {@link Answer} can be used to define the return values of unstubbed invocations. 1081e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1082e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * This implementation can be helpful when working with legacy code. 1083e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * When this implementation is used, unstubbed methods will delegate to the real implementation. 1084e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * This is a way to create a partial mock object that calls real methods by default. 1085e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1086e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * As usual you are going to read <b>the partial mock warning</b>: 1087e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Object oriented programming is more less tackling complexity by dividing the complexity into separate, specific, SRPy objects. 1088e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * How does partial mock fit into this paradigm? Well, it just doesn't... 1089e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Partial mock usually means that the complexity has been moved to a different method on the same object. 1090e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * In most cases, this is not the way you want to design your application. 1091e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1092e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * However, there are rare cases when partial mocks come handy: 1093e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * dealing with code you cannot change easily (3rd party interfaces, interim refactoring of legacy code etc.) 1094e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * However, I wouldn't use partial mocks for new, test-driven & well-designed code. 1095e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1096e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Example: 1097e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 1098e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Foo mock = mock(Foo.class, CALLS_REAL_METHODS); 1099e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1100e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * // this calls the real implementation of Foo.getSomething() 1101e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * value = mock.getSomething(); 1102e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1103e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * when(mock.getSomething()).thenReturn(fakeValue); 1104e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1105e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * // now fakeValue is returned 1106e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * value = mock.getSomething(); 1107e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 1108e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson */ 1109e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson public static final Answer<Object> CALLS_REAL_METHODS = Answers.CALLS_REAL_METHODS.get(); 1110e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson 1111e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson /** 1112e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Creates mock object of given class or interface. 1113e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1114e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * See examples in javadoc for {@link Mockito} class 1115e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1116e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @param classToMock class or interface to mock 1117e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @return mock object 1118e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson */ 1119e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson public static <T> T mock(Class<T> classToMock) { 1120e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson return mock(classToMock, withSettings().defaultAnswer(RETURNS_DEFAULTS)); 1121e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson } 1122e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson 1123e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson /** 1124e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Specifies mock name. Naming mocks can be helpful for debugging - the name is used in all verification errors. 1125e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1126e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Beware that naming mocks is not a solution for complex code which uses too many mocks or collaborators. 1127e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <b>If you have too many mocks then refactor the code</b> so that it's easy to test/debug without necessity of naming mocks. 1128e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1129e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <b>If you use <code>@Mock</code> annotation then you've got naming mocks for free!</b> <code>@Mock</code> uses field name as mock name. {@link Mock Read more.} 1130e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1131e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1132e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * See examples in javadoc for {@link Mockito} class 1133e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1134e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @param classToMock class or interface to mock 1135e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @param name of the mock 1136e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @return mock object 1137e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson */ 1138e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson public static <T> T mock(Class<T> classToMock, String name) { 1139e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson return mock(classToMock, withSettings() 1140e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson .name(name) 1141e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson .defaultAnswer(RETURNS_DEFAULTS)); 1142e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson } 1143e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson 1144e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson /** 1145e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Returns a MockingDetails instance that enables inspecting a particular object for Mockito related information. 1146e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Can be used to find out if given object is a Mockito mock 1147e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * or to find out if a given mock is a spy or mock. 1148e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1149e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * In future Mockito versions MockingDetails may grow and provide other useful information about the mock, 1150e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * e.g. invocations, stubbing info, etc. 1151e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1152e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @param toInspect - object to inspect 1153e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @return A {@link org.mockito.MockingDetails} instance. 1154e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @since 1.9.5 1155e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson */ 1156e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson @Incubating 1157e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson public static MockingDetails mockingDetails(Object toInspect) { 1158e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson return MOCKITO_CORE.mockingDetails(toInspect); 1159e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson } 1160e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson 1161e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson /** 1162e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <b>Deprecated : Please use mock(Foo.class, defaultAnswer);</b> 1163e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1164e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * See {@link Mockito#mock(Class, Answer)} 1165e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1166e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Why it is deprecated? ReturnValues is being replaced by Answer 1167e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * for better consistency & interoperability of the framework. 1168e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Answer interface has been in Mockito for a while and it has the same responsibility as ReturnValues. 1169e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * There's no point in mainting exactly the same interfaces. 1170e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1171e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Creates mock with a specified strategy for its return values. 1172e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * It's quite advanced feature and typically you don't need it to write decent tests. 1173e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * However it can be helpful when working with legacy systems. 1174e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1175e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Obviously return values are used only when you don't stub the method call. 1176e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1177e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 1178e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Foo mock = mock(Foo.class, Mockito.RETURNS_SMART_NULLS); 1179e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Foo mockTwo = mock(Foo.class, new YourOwnReturnValues()); 1180e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 1181e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1182e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p>See examples in javadoc for {@link Mockito} class</p> 1183e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1184e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @param classToMock class or interface to mock 1185e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @param returnValues default return values for unstubbed methods 1186e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1187e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @return mock object 1188e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1189e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @deprecated <b>Please use mock(Foo.class, defaultAnswer);</b> 1190e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson */ 1191e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson @Deprecated 1192e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson public static <T> T mock(Class<T> classToMock, ReturnValues returnValues) { 1193e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson return mock(classToMock, withSettings().defaultAnswer(new AnswerReturnValuesAdapter(returnValues))); 1194e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson } 1195e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson 1196e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson /** 1197e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Creates mock with a specified strategy for its answers to interactions. 1198e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * It's quite advanced feature and typically you don't need it to write decent tests. 1199e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * However it can be helpful when working with legacy systems. 1200e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1201e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * It is the default answer so it will be used <b>only when you don't</b> stub the method call. 1202e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1203e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 1204e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Foo mock = mock(Foo.class, RETURNS_SMART_NULLS); 1205e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Foo mockTwo = mock(Foo.class, new YourOwnAnswer()); 1206e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 1207e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1208e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p>See examples in javadoc for {@link Mockito} class</p> 1209e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1210e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @param classToMock class or interface to mock 1211e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @param defaultAnswer default answer for unstubbed methods 1212e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1213e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @return mock object 1214e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson */ 1215e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson public static <T> T mock(Class<T> classToMock, Answer defaultAnswer) { 1216e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson return mock(classToMock, withSettings().defaultAnswer(defaultAnswer)); 1217e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson } 1218e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson 1219e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson /** 1220e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Creates a mock with some non-standard settings. 1221e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1222e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * The number of configuration points for a mock grows 1223e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * so we need a fluent way to introduce new configuration without adding more and more overloaded Mockito.mock() methods. 1224e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Hence {@link MockSettings}. 1225e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 1226e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Listener mock = mock(Listener.class, withSettings() 1227e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * .name("firstListner").defaultBehavior(RETURNS_SMART_NULLS)); 1228e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * ); 1229e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 1230e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <b>Use it carefully and occasionally</b>. What might be reason your test needs non-standard mocks? 1231e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Is the code under test so complicated that it requires non-standard mocks? 1232e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Wouldn't you prefer to refactor the code under test so it is testable in a simple way? 1233e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1234e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * See also {@link Mockito#withSettings()} 1235e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1236e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * See examples in javadoc for {@link Mockito} class 1237e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1238e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @param classToMock class or interface to mock 1239e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @param mockSettings additional mock settings 1240e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @return mock object 1241e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson */ 1242e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson public static <T> T mock(Class<T> classToMock, MockSettings mockSettings) { 1243e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson return MOCKITO_CORE.mock(classToMock, mockSettings); 1244e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson } 1245e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson 1246e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson /** 1247e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Creates a spy of the real object. The spy calls <b>real</b> methods unless they are stubbed. 1248e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1249e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Real spies should be used <b>carefully and occasionally</b>, for example when dealing with legacy code. 1250e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1251e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * As usual you are going to read <b>the partial mock warning</b>: 1252e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Object oriented programming is more less tackling complexity by dividing the complexity into separate, specific, SRPy objects. 1253e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * How does partial mock fit into this paradigm? Well, it just doesn't... 1254e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Partial mock usually means that the complexity has been moved to a different method on the same object. 1255e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * In most cases, this is not the way you want to design your application. 1256e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1257e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * However, there are rare cases when partial mocks come handy: 1258e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * dealing with code you cannot change easily (3rd party interfaces, interim refactoring of legacy code etc.) 1259e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * However, I wouldn't use partial mocks for new, test-driven & well-designed code. 1260e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1261e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Example: 1262e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1263e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 1264e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * List list = new LinkedList(); 1265e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * List spy = spy(list); 1266e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1267e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //optionally, you can stub out some methods: 1268e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * when(spy.size()).thenReturn(100); 1269e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1270e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //using the spy calls <b>real</b> methods 1271e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * spy.add("one"); 1272e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * spy.add("two"); 1273e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1274e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //prints "one" - the first element of a list 1275e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * System.out.println(spy.get(0)); 1276e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1277e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //size() method was stubbed - 100 is printed 1278e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * System.out.println(spy.size()); 1279e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1280e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //optionally, you can verify 1281e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * verify(spy).add("one"); 1282e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * verify(spy).add("two"); 1283e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 1284e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1285e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <h4>Important gotcha on spying real objects!</h4> 1286e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <ol> 1287e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <li>Sometimes it's impossible or impractical to use {@link Mockito#when(Object)} for stubbing spies. 1288e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Therefore for spies it is recommended to always use <code>doReturn</code>|<code>Answer</code>|<code>Throw()</code>|<code>CallRealMethod</code> 1289e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * family of methods for stubbing. Example: 1290e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1291e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 1292e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * List list = new LinkedList(); 1293e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * List spy = spy(list); 1294e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1295e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //Impossible: real method is called so spy.get(0) throws IndexOutOfBoundsException (the list is yet empty) 1296e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * when(spy.get(0)).thenReturn("foo"); 1297e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1298e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //You have to use doReturn() for stubbing 1299e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * doReturn("foo").when(spy).get(0); 1300e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 1301e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </li> 1302e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1303e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <li>Mockito <b>*does not*</b> delegate calls to the passed real instance, instead it actually creates a copy of it. 1304e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * So if you keep the real instance and interact with it, don't expect the spied to be aware of those interaction 1305e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * and their effect on real instance state. 1306e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * The corollary is that when an <b>*unstubbed*</b> method is called <b>*on the spy*</b> but <b>*not on the real instance*</b>, 1307e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * you won't see any effects on the real instance.</li> 1308e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1309e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <li>Watch out for final methods. 1310e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Mockito doesn't mock final methods so the bottom line is: when you spy on real objects + you try to stub a final method = trouble. 1311e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Also you won't be able to verify those method as well. 1312e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </li> 1313e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </ol> 1314e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1315e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * See examples in javadoc for {@link Mockito} class 1316e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1317e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @param object 1318e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * to spy on 1319e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @return a spy of the real object 1320e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson */ 1321e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson public static <T> T spy(T object) { 1322e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson return MOCKITO_CORE.mock((Class<T>) object.getClass(), withSettings() 1323e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson .spiedInstance(object) 1324e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson .defaultAnswer(CALLS_REAL_METHODS)); 1325e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson } 1326e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson 1327e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson /** 1328e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Stubs a method call with return value or an exception. E.g: 1329e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1330e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 1331e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * stub(mock.someMethod()).toReturn(10); 1332e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1333e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //you can use flexible argument matchers, e.g: 1334e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * stub(mock.someMethod(<b>anyString()</b>)).toReturn(10); 1335e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1336e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //setting exception to be thrown: 1337e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * stub(mock.someMethod("some arg")).toThrow(new RuntimeException()); 1338e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1339e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //you can stub with different behavior for consecutive method calls. 1340e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //Last stubbing (e.g: toReturn("foo")) determines the behavior for further consecutive calls. 1341e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * stub(mock.someMethod("some arg")) 1342e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * .toThrow(new RuntimeException()) 1343e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * .toReturn("foo"); 1344e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 1345e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1346e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Some users find stub() confusing therefore {@link Mockito#when(Object)} is recommended over stub() 1347e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 1348e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //Instead of: 1349e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * stub(mock.count()).toReturn(10); 1350e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1351e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //You can do: 1352e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * when(mock.count()).thenReturn(10); 1353e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 1354e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * For stubbing void methods with throwables see: {@link Mockito#doThrow(Throwable)} 1355e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1356e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Stubbing can be overridden: for example common stubbing can go to fixture 1357e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * setup but the test methods can override it. 1358e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Please note that overridding stubbing is a potential code smell that points out too much stubbing. 1359e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1360e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Once stubbed, the method will always return stubbed value regardless 1361e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * of how many times it is called. 1362e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1363e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Last stubbing is more important - when you stubbed the same method with 1364e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * the same arguments many times. 1365e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1366e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Although it is possible to verify a stubbed invocation, usually <b>it's just redundant</b>. 1367e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Let's say you've stubbed foo.bar(). 1368e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * If your code cares what foo.bar() returns then something else breaks(often before even verify() gets executed). 1369e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * If your code doesn't care what get(0) returns then it should not be stubbed. 1370e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Not convinced? See <a href="http://monkeyisland.pl/2008/04/26/asking-and-telling">here</a>. 1371e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1372e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @param methodCall 1373e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * method call 1374e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @return DeprecatedOngoingStubbing object to set stubbed value/exception 1375e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson */ 1376e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson public static <T> DeprecatedOngoingStubbing<T> stub(T methodCall) { 1377e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson return MOCKITO_CORE.stub(methodCall); 1378e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson } 1379e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson 1380e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson /** 1381e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Enables stubbing methods. Use it when you want the mock to return particular value when particular method is called. 1382e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1383e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Simply put: "<b>When</b> the x method is called <b>then</b> return y". 1384e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1385e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <b>when() is a successor of deprecated {@link Mockito#stub(Object)}</b> 1386e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1387e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Examples: 1388e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1389e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 1390e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <b>when</b>(mock.someMethod()).<b>thenReturn</b>(10); 1391e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1392e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //you can use flexible argument matchers, e.g: 1393e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * when(mock.someMethod(<b>anyString()</b>)).thenReturn(10); 1394e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1395e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //setting exception to be thrown: 1396e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * when(mock.someMethod("some arg")).thenThrow(new RuntimeException()); 1397e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1398e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //you can set different behavior for consecutive method calls. 1399e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //Last stubbing (e.g: thenReturn("foo")) determines the behavior of further consecutive calls. 1400e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * when(mock.someMethod("some arg")) 1401e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * .thenThrow(new RuntimeException()) 1402e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * .thenReturn("foo"); 1403e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1404e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //Alternative, shorter version for consecutive stubbing: 1405e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * when(mock.someMethod("some arg")) 1406e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * .thenReturn("one", "two"); 1407e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //is the same as: 1408e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * when(mock.someMethod("some arg")) 1409e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * .thenReturn("one") 1410e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * .thenReturn("two"); 1411e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1412e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //shorter version for consecutive method calls throwing exceptions: 1413e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * when(mock.someMethod("some arg")) 1414e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * .thenThrow(new RuntimeException(), new NullPointerException(); 1415e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1416e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 1417e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1418e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * For stubbing void methods with throwables see: {@link Mockito#doThrow(Throwable)} 1419e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1420e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Stubbing can be overridden: for example common stubbing can go to fixture 1421e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * setup but the test methods can override it. 1422e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Please note that overridding stubbing is a potential code smell that points out too much stubbing. 1423e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1424e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Once stubbed, the method will always return stubbed value regardless 1425e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * of how many times it is called. 1426e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1427e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Last stubbing is more important - when you stubbed the same method with 1428e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * the same arguments many times. 1429e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1430e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Although it is possible to verify a stubbed invocation, usually <b>it's just redundant</b>. 1431e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Let's say you've stubbed <code>foo.bar()</code>. 1432e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * If your code cares what <code>foo.bar()</code> returns then something else breaks(often before even <code>verify()</code> gets executed). 1433e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * If your code doesn't care what <code>get(0)</code> returns then it should not be stubbed. 1434e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Not convinced? See <a href="http://monkeyisland.pl/2008/04/26/asking-and-telling">here</a>. 1435e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1436e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1437e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * See examples in javadoc for {@link Mockito} class 1438e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @param methodCall method to be stubbed 1439e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @return OngoingStubbing object used to stub fluently. 1440e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <strong>Do not</strong> create a reference to this returned object. 1441e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson */ 1442e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson public static <T> OngoingStubbing<T> when(T methodCall) { 1443e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson return MOCKITO_CORE.when(methodCall); 1444e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson } 1445e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson 1446e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson /** 1447e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Verifies certain behavior <b>happened once</b>. 1448e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1449e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Alias to <code>verify(mock, times(1))</code> E.g: 1450e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 1451e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * verify(mock).someMethod("some arg"); 1452e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 1453e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Above is equivalent to: 1454e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 1455e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * verify(mock, times(1)).someMethod("some arg"); 1456e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 1457e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1458e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Arguments passed are compared using <code>equals()</code> method. 1459e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Read about {@link ArgumentCaptor} or {@link ArgumentMatcher} to find out other ways of matching / asserting arguments passed. 1460e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1461e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Although it is possible to verify a stubbed invocation, usually <b>it's just redundant</b>. 1462e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Let's say you've stubbed <code>foo.bar()</code>. 1463e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * If your code cares what <code>foo.bar()</code> returns then something else breaks(often before even <code>verify()</code> gets executed). 1464e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * If your code doesn't care what <code>get(0)</code> returns then it should not be stubbed. 1465e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Not convinced? See <a href="http://monkeyisland.pl/2008/04/26/asking-and-telling">here</a>. 1466e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1467e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1468e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * See examples in javadoc for {@link Mockito} class 1469e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1470e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @param mock to be verified 1471e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @return mock object itself 1472e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson */ 1473e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson public static <T> T verify(T mock) { 1474e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson return MOCKITO_CORE.verify(mock, times(1)); 1475e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson } 1476e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson 1477e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson /** 1478e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Verifies certain behavior happened at least once / exact number of times / never. E.g: 1479e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 1480e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * verify(mock, times(5)).someMethod("was called five times"); 1481e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1482e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * verify(mock, atLeast(2)).someMethod("was called at least two times"); 1483e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1484e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //you can use flexible argument matchers, e.g: 1485e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * verify(mock, atLeastOnce()).someMethod(<b>anyString()</b>); 1486e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 1487e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1488e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <b>times(1) is the default</b> and can be omitted 1489e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1490e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Arguments passed are compared using <code>equals()</code> method. 1491e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Read about {@link ArgumentCaptor} or {@link ArgumentMatcher} to find out other ways of matching / asserting arguments passed. 1492e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1493e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1494e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @param mock to be verified 1495e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @param mode times(x), atLeastOnce() or never() 1496e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1497e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @return mock object itself 1498e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson */ 1499e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson public static <T> T verify(T mock, VerificationMode mode) { 1500e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson return MOCKITO_CORE.verify(mock, mode); 1501e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson } 1502e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson 1503e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson /** 1504e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Smart Mockito users hardly use this feature because they know it could be a sign of poor tests. 1505e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Normally, you don't need to reset your mocks, just create new mocks for each test method. 1506e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1507e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Instead of <code>#reset()</code> please consider writing simple, small and focused test methods over lengthy, over-specified tests. 1508e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <b>First potential code smell is <code>reset()</code> in the middle of the test method.</b> This probably means you're testing too much. 1509e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Follow the whisper of your test methods: "Please keep us small & focused on single behavior". 1510e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * There are several threads about it on mockito mailing list. 1511e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1512e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * The only reason we added <code>reset()</code> method is to 1513e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * make it possible to work with container-injected mocks. 1514e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * See issue 55 (<a href="http://code.google.com/p/mockito/issues/detail?id=55">here</a>) 1515e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * or FAQ (<a href="http://code.google.com/p/mockito/wiki/FAQ">here</a>). 1516e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1517e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <b>Don't harm yourself.</b> <code>reset()</code> in the middle of the test method is a code smell (you're probably testing too much). 1518e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 1519e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * List mock = mock(List.class); 1520e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * when(mock.size()).thenReturn(10); 1521e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * mock.add(1); 1522e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1523e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * reset(mock); 1524e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //at this point the mock forgot any interactions & stubbing 1525e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 1526e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1527e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @param <T> The Type of the mocks 1528e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @param mocks to be reset 1529e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson */ 1530e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson public static <T> void reset(T ... mocks) { 1531e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson MOCKITO_CORE.reset(mocks); 1532e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson } 1533e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson 1534e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson /** 1535e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Checks if any of given mocks has any unverified interaction. 1536e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1537e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * You can use this method after you verified your mocks - to make sure that nothing 1538e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * else was invoked on your mocks. 1539e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1540e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * See also {@link Mockito#never()} - it is more explicit and communicates the intent well. 1541e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1542e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Stubbed invocations (if called) are also treated as interactions. 1543e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1544e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * A word of <b>warning</b>: 1545e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Some users who did a lot of classic, expect-run-verify mocking tend to use <code>verifyNoMoreInteractions()</code> very often, even in every test method. 1546e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <code>verifyNoMoreInteractions()</code> is not recommended to use in every test method. 1547e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <code>verifyNoMoreInteractions()</code> is a handy assertion from the interaction testing toolkit. Use it only when it's relevant. 1548e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Abusing it leads to overspecified, less maintainable tests. You can find further reading 1549e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <a href="http://monkeyisland.pl/2008/07/12/should-i-worry-about-the-unexpected/">here</a>. 1550e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1551e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * This method will also detect unverified invocations that occurred before the test method, 1552e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * for example: in <code>setUp()</code>, <code>@Before</code> method or in constructor. 1553e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Consider writing nice code that makes interactions only in test methods. 1554e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1555e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1556e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Example: 1557e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1558e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 1559e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //interactions 1560e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * mock.doSomething(); 1561e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * mock.doSomethingUnexpected(); 1562e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1563e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //verification 1564e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * verify(mock).doSomething(); 1565e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1566e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //following will fail because 'doSomethingUnexpected()' is unexpected 1567e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * verifyNoMoreInteractions(mock); 1568e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1569e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 1570e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1571e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * See examples in javadoc for {@link Mockito} class 1572e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1573e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @param mocks to be verified 1574e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson */ 1575e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson public static void verifyNoMoreInteractions(Object... mocks) { 1576e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson MOCKITO_CORE.verifyNoMoreInteractions(mocks); 1577e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson } 1578e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson 1579e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson /** 1580e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Verifies that no interactions happened on given mocks. 1581e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 1582e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * verifyZeroInteractions(mockOne, mockTwo); 1583e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 1584e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * This method will also detect invocations 1585e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * that occurred before the test method, for example: in <code>setUp()</code>, <code>@Before</code> method or in constructor. 1586e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Consider writing nice code that makes interactions only in test methods. 1587e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1588e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * See also {@link Mockito#never()} - it is more explicit and communicates the intent well. 1589e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1590e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * See examples in javadoc for {@link Mockito} class 1591e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1592e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @param mocks to be verified 1593e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson */ 1594e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson public static void verifyZeroInteractions(Object... mocks) { 1595e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson MOCKITO_CORE.verifyNoMoreInteractions(mocks); 1596e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson } 1597e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson 1598e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson /** 1599e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 1600e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //Instead of: 1601e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * stubVoid(mock).toThrow(e).on().someVoidMethod(); 1602e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1603e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //Please do: 1604e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * doThrow(e).when(mock).someVoidMethod(); 1605e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 1606e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1607e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * doThrow() replaces stubVoid() because of improved readability and consistency with the family of doAnswer() methods. 1608e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1609e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Originally, <code>stubVoid()</code> was used for stubbing void methods with exceptions. E.g: 1610e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1611e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 1612e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * stubVoid(mock).toThrow(new RuntimeException()).on().someMethod(); 1613e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1614e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //you can stub with different behavior for consecutive calls. 1615e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //Last stubbing (e.g. toReturn()) determines the behavior for further consecutive calls. 1616e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * stubVoid(mock) 1617e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * .toThrow(new RuntimeException()) 1618e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * .toReturn() 1619e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * .on().someMethod(); 1620e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 1621e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1622e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * See examples in javadoc for {@link Mockito} class 1623e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1624e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @deprecated Use {@link Mockito#doThrow(Throwable)} method for stubbing voids 1625e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1626e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @param mock 1627e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * to stub 1628e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @return stubbable object that allows stubbing with throwable 1629e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson */ 1630e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson public static <T> VoidMethodStubbable<T> stubVoid(T mock) { 1631e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson return MOCKITO_CORE.stubVoid(mock); 1632e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson } 1633e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson 1634e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson /** 1635e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Use <code>doThrow()</code> when you want to stub the void method with an exception. 1636e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1637e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Stubbing voids requires different approach from {@link Mockito#when(Object)} because the compiler does not like void methods inside brackets... 1638e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1639e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Example: 1640e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1641e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 1642e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * doThrow(new RuntimeException()).when(mock).someVoidMethod(); 1643e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 1644e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1645e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @param toBeThrown to be thrown when the stubbed method is called 1646e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @return stubber - to select a method for stubbing 1647e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson */ 1648e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson public static Stubber doThrow(Throwable toBeThrown) { 1649e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson return MOCKITO_CORE.doAnswer(new ThrowsException(toBeThrown)); 1650e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson } 1651e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson 1652e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson /** 1653e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Use <code>doThrow()</code> when you want to stub the void method to throw exception of specified class. 1654e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1655e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * A new exception instance will be created for each method invocation. 1656e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1657e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Stubbing voids requires different approach from {@link Mockito#when(Object)} because the compiler does not like void methods inside brackets... 1658e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1659e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Example: 1660e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1661e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 1662e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * doThrow(RuntimeException.class).when(mock).someVoidMethod(); 1663e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 1664e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1665e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @param toBeThrown to be thrown when the stubbed method is called 1666e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @return stubber - to select a method for stubbing 1667e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @since 1.9.0 1668e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson */ 1669e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson public static Stubber doThrow(Class<? extends Throwable> toBeThrown) { 1670e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson return MOCKITO_CORE.doAnswer(new ThrowsExceptionClass(toBeThrown)); 1671e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson } 1672e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson 1673e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson 1674e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson /** 1675e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Use <code>doCallRealMethod()</code> when you want to call the real implementation of a method. 1676e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1677e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * As usual you are going to read <b>the partial mock warning</b>: 1678e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Object oriented programming is more less tackling complexity by dividing the complexity into separate, specific, SRPy objects. 1679e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * How does partial mock fit into this paradigm? Well, it just doesn't... 1680e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Partial mock usually means that the complexity has been moved to a different method on the same object. 1681e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * In most cases, this is not the way you want to design your application. 1682e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1683e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * However, there are rare cases when partial mocks come handy: 1684e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * dealing with code you cannot change easily (3rd party interfaces, interim refactoring of legacy code etc.) 1685e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * However, I wouldn't use partial mocks for new, test-driven & well-designed code. 1686e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1687e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * See also javadoc {@link Mockito#spy(Object)} to find out more about partial mocks. 1688e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <b>Mockito.spy() is a recommended way of creating partial mocks.</b> 1689e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 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. 1690e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1691e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Example: 1692e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 1693e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Foo mock = mock(Foo.class); 1694e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * doCallRealMethod().when(mock).someVoidMethod(); 1695e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1696e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * // this will call the real implementation of Foo.someVoidMethod() 1697e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * mock.someVoidMethod(); 1698e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 1699e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1700e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * See examples in javadoc for {@link Mockito} class 1701e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1702e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @return stubber - to select a method for stubbing 1703e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @since 1.9.5 1704e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson */ 1705e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson public static Stubber doCallRealMethod() { 1706e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson return MOCKITO_CORE.doAnswer(new CallsRealMethods()); 1707e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson } 1708e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson 1709e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson /** 1710e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Use <code>doAnswer()</code> when you want to stub a void method with generic {@link Answer}. 1711e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1712e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Stubbing voids requires different approach from {@link Mockito#when(Object)} because the compiler does not like void methods inside brackets... 1713e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1714e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Example: 1715e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1716e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 1717e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * doAnswer(new Answer() { 1718e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * public Object answer(InvocationOnMock invocation) { 1719e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Object[] args = invocation.getArguments(); 1720e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Mock mock = invocation.getMock(); 1721e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * return null; 1722e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * }}) 1723e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * .when(mock).someMethod(); 1724e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 1725e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1726e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * See examples in javadoc for {@link Mockito} class 1727e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1728e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @param answer to answer when the stubbed method is called 1729e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @return stubber - to select a method for stubbing 1730e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson */ 1731e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson public static Stubber doAnswer(Answer answer) { 1732e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson return MOCKITO_CORE.doAnswer(answer); 1733e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson } 1734e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson 1735e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson /** 1736e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Use <code>doNothing()</code> for setting void methods to do nothing. <b>Beware that void methods on mocks do nothing by default!</b> 1737e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * However, there are rare situations when doNothing() comes handy: 1738e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1739e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <ol> 1740e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <li>Stubbing consecutive calls on a void method: 1741e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 1742e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * doNothing(). 1743e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * doThrow(new RuntimeException()) 1744e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * .when(mock).someVoidMethod(); 1745e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1746e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //does nothing the first time: 1747e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * mock.someVoidMethod(); 1748e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1749e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //throws RuntimeException the next time: 1750e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * mock.someVoidMethod(); 1751e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 1752e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </li> 1753e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <li>When you spy real objects and you want the void method to do nothing: 1754e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 1755e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * List list = new LinkedList(); 1756e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * List spy = spy(list); 1757e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1758e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //let's make clear() do nothing 1759e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * doNothing().when(spy).clear(); 1760e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1761e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * spy.add("one"); 1762e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1763e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //clear() does nothing, so the list still contains "one" 1764e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * spy.clear(); 1765e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 1766e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </li> 1767e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </ol> 1768e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1769e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * See examples in javadoc for {@link Mockito} class 1770e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1771e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @return stubber - to select a method for stubbing 1772e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson */ 1773e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson public static Stubber doNothing() { 1774e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson return MOCKITO_CORE.doAnswer(new DoesNothing()); 1775e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson } 1776e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson 1777e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson /** 1778e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Use <code>doReturn()</code> in those rare occasions when you cannot use {@link Mockito#when(Object)}. 1779e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1780e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <b>Beware that {@link Mockito#when(Object)} is always recommended for stubbing because it is argument type-safe 1781e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * and more readable</b> (especially when stubbing consecutive calls). 1782e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1783e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Here are those rare occasions when doReturn() comes handy: 1784e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1785e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1786e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <ol> 1787e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <li>When spying real objects and calling real methods on a spy brings side effects 1788e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1789e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 1790e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * List list = new LinkedList(); 1791e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * List spy = spy(list); 1792e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1793e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //Impossible: real method is called so spy.get(0) throws IndexOutOfBoundsException (the list is yet empty) 1794e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * when(spy.get(0)).thenReturn("foo"); 1795e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1796e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //You have to use doReturn() for stubbing: 1797e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * doReturn("foo").when(spy).get(0); 1798e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 1799e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </li> 1800e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1801e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <li>Overriding a previous exception-stubbing: 1802e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 1803e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * when(mock.foo()).thenThrow(new RuntimeException()); 1804e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1805e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //Impossible: the exception-stubbed foo() method is called so RuntimeException is thrown. 1806e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * when(mock.foo()).thenReturn("bar"); 1807e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1808e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //You have to use doReturn() for stubbing: 1809e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * doReturn("bar").when(mock).foo(); 1810e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 1811e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </li> 1812e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </ol> 1813e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1814e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Above scenarios shows a tradeoff of Mockito's elegant syntax. Note that the scenarios are very rare, though. 1815e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Spying should be sporadic and overriding exception-stubbing is very rare. Not to mention that in general 1816e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * overridding stubbing is a potential code smell that points out too much stubbing. 1817e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1818e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * See examples in javadoc for {@link Mockito} class 1819e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1820e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @param toBeReturned to be returned when the stubbed method is called 1821e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @return stubber - to select a method for stubbing 1822e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson */ 1823e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson public static Stubber doReturn(Object toBeReturned) { 1824e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson return MOCKITO_CORE.doAnswer(new Returns(toBeReturned)); 1825e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson } 1826e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson 1827e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson /** 1828e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Creates {@link org.mockito.InOrder} object that allows verifying mocks in order. 1829e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1830e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 1831e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * InOrder inOrder = inOrder(firstMock, secondMock); 1832e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1833e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * inOrder.verify(firstMock).add("was called first"); 1834e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * inOrder.verify(secondMock).add("was called second"); 1835e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 1836e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1837e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Verification in order is flexible - <b>you don't have to verify all interactions</b> one-by-one 1838e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * but only those that you are interested in testing in order. 1839e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1840e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Also, you can create InOrder object passing only mocks that are relevant for in-order verification. 1841e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1842e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <code>InOrder</code> verification is 'greedy'. You will hardly every notice it but 1843e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * if you want to find out more search for 'greedy' on the Mockito 1844e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <a href="http://code.google.com/p/mockito/w/list">wiki pages</a>. 1845e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1846e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * As of Mockito 1.8.4 you can verifyNoMoreInvocations() in order-sensitive way. Read more: {@link InOrder#verifyNoMoreInteractions()} 1847e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1848e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * See examples in javadoc for {@link Mockito} class 1849e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1850e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @param mocks to be verified in order 1851e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1852e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @return InOrder object to be used to verify in order 1853e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson */ 1854e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson public static InOrder inOrder(Object... mocks) { 1855e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson return MOCKITO_CORE.inOrder(mocks); 1856e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson } 1857e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson 1858e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson /** 1859e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Ignores stubbed methods of given mocks for the sake of verification. 1860e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Sometimes useful when coupled with <code>verifyNoMoreInteractions()</code> or verification <code>inOrder()</code>. 1861e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Helps avoiding redundant verification of stubbed calls - typically we're not interested in verifying stubs. 1862e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1863e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <b>Warning</b>, <code>ignoreStubs()</code> might lead to overuse of <code>verifyNoMoreInteractions(ignoreStubs(...));</code> 1864e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Bear in mind that Mockito does not recommend bombarding every test with <code>verifyNoMoreInteractions()</code> 1865e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * for the reasons outlined in javadoc for {@link Mockito#verifyNoMoreInteractions(Object...)} 1866e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Other words: all <b>*stubbed*</b> methods of given mocks are marked <b>*verified*</b> so that they don't get in a way during verifyNoMoreInteractions(). 1867e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1868e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * This method <b>changes the input mocks</b>! This method returns input mocks just for convenience. 1869e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1870e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Ignored stubs will also be ignored for verification inOrder, including {@link org.mockito.InOrder#verifyNoMoreInteractions()}. 1871e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * See the second example. 1872e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1873e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Example: 1874e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 1875e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //mocking lists for the sake of the example (if you mock List in real you will burn in hell) 1876e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * List mock1 = mock(List.class), mock2 = mock(List.class); 1877e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1878e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //stubbing mocks: 1879e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * when(mock1.get(0)).thenReturn(10); 1880e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * when(mock2.get(0)).thenReturn(20); 1881e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1882e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //using mocks by calling stubbed get(0) methods: 1883e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * System.out.println(mock1.get(0)); //prints 10 1884e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * System.out.println(mock2.get(0)); //prints 20 1885e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1886e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //using mocks by calling clear() methods: 1887e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * mock1.clear(); 1888e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * mock2.clear(); 1889e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1890e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //verification: 1891e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * verify(mock1).clear(); 1892e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * verify(mock2).clear(); 1893e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1894e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //verifyNoMoreInteractions() fails because get() methods were not accounted for. 1895e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * try { verifyNoMoreInteractions(mock1, mock2); } catch (NoInteractionsWanted e); 1896e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1897e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //However, if we ignore stubbed methods then we can verifyNoMoreInteractions() 1898e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * verifyNoMoreInteractions(ignoreStubs(mock1, mock2)); 1899e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1900e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //Remember that ignoreStubs() <b>*changes*</b> the input mocks and returns them for convenience. 1901e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 1902e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Ignoring stubs can be used with <b>verification in order</b>: 1903e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 1904e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * List list = mock(List.class); 1905e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * when(mock.get(0)).thenReturn("foo"); 1906e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1907e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * list.add(0); 1908e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * System.out.println(list.get(0)); //we don't want to verify this 1909e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * list.clear(); 1910e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1911e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * InOrder inOrder = inOrder(ignoreStubs(list)); 1912e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * inOrder.verify(list).add(0); 1913e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * inOrder.verify(list).clear(); 1914e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * inOrder.verifyNoMoreInteractions(); 1915e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 1916e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1917e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @since 1.9.0 1918e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @param mocks input mocks that will be changed 1919e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @return the same mocks that were passed in as parameters 1920e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson */ 1921e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson public static Object[] ignoreStubs(Object... mocks) { 1922e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson return MOCKITO_CORE.ignoreStubs(mocks); 1923e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson } 1924e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson 1925e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson /** 1926e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Allows verifying exact number of invocations. E.g: 1927e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 1928e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * verify(mock, times(2)).someMethod("some arg"); 1929e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 1930e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1931e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * See examples in javadoc for {@link Mockito} class 1932e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1933e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @param wantedNumberOfInvocations wanted number of invocations 1934e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1935e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @return verification mode 1936e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson */ 1937e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson public static VerificationMode times(int wantedNumberOfInvocations) { 1938e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson return VerificationModeFactory.times(wantedNumberOfInvocations); 1939e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson } 1940e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson 1941e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson /** 1942e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Alias to <code>times(0)</code>, see {@link Mockito#times(int)} 1943e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1944e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Verifies that interaction did not happen. E.g: 1945e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 1946e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * verify(mock, never()).someMethod(); 1947e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 1948e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1949e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1950e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * If you want to verify there were NO interactions with the mock 1951e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * check out {@link Mockito#verifyZeroInteractions(Object...)} 1952e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * or {@link Mockito#verifyNoMoreInteractions(Object...)} 1953e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1954e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * See examples in javadoc for {@link Mockito} class 1955e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1956e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @return verification mode 1957e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson */ 1958e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson public static VerificationMode never() { 1959e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson return times(0); 1960e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson } 1961e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson 1962e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson /** 1963e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Allows at-least-once verification. E.g: 1964e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 1965e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * verify(mock, atLeastOnce()).someMethod("some arg"); 1966e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 1967e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Alias to <code>atLeast(1)</code>. 1968e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 1969e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * See examples in javadoc for {@link Mockito} class 1970e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1971e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @return verification mode 1972e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson */ 1973e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson public static VerificationMode atLeastOnce() { 1974e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson return VerificationModeFactory.atLeastOnce(); 1975e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson } 1976e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson 1977e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson /** 1978e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Allows at-least-x verification. E.g: 1979e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 1980e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * verify(mock, atLeast(3)).someMethod("some arg"); 1981e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 1982e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1983e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * See examples in javadoc for {@link Mockito} class 1984e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1985e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @param minNumberOfInvocations minimum number of invocations 1986e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1987e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @return verification mode 1988e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson */ 1989e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson public static VerificationMode atLeast(int minNumberOfInvocations) { 1990e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson return VerificationModeFactory.atLeast(minNumberOfInvocations); 1991e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson } 1992e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson 1993e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson /** 1994e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Allows at-most-x verification. E.g: 1995e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 1996e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * verify(mock, atMost(3)).someMethod("some arg"); 1997e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 1998e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 1999e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * See examples in javadoc for {@link Mockito} class 2000e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 2001e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @param maxNumberOfInvocations max number of invocations 2002e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 2003e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @return verification mode 2004e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson */ 2005e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson public static VerificationMode atMost(int maxNumberOfInvocations) { 2006e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson return VerificationModeFactory.atMost(maxNumberOfInvocations); 2007e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson } 2008e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson 2009e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson /** 2010e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Allows non-greedy verification in order. For example 2011e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 2012e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * inOrder.verify( mock, calls( 2 )).someMethod( "some arg" ); 2013e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 2014e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <ul> 2015e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <li>will not fail if the method is called 3 times, unlike times( 2 )</li> 2016e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <li>will not mark the third invocation as verified, unlike atLeast( 2 )</li> 2017e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </ul> 2018e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * This verification mode can only be used with in order verification. 2019e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @param wantedNumberOfInvocations number of invocations to verify 2020e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @return verification mode 2021e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson */ 2022e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson public static VerificationMode calls( int wantedNumberOfInvocations ){ 2023e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson return VerificationModeFactory.calls( wantedNumberOfInvocations ); 2024e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson } 2025e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson 2026e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson /** 2027e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Allows checking if given method was the only one invoked. E.g: 2028e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 2029e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * verify(mock, only()).someMethod(); 2030e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //above is a shorthand for following 2 lines of code: 2031e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * verify(mock).someMethod(); 2032e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * verifyNoMoreInvocations(mock); 2033e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 2034e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 2035e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 2036e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * See also {@link Mockito#verifyNoMoreInteractions(Object...)} 2037e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 2038e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * See examples in javadoc for {@link Mockito} class 2039e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 2040e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @return verification mode 2041e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson */ 2042e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson public static VerificationMode only() { 2043e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson return VerificationModeFactory.only(); 2044e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson } 2045e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson 2046e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson /** 2047e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Allows verifying with timeout. It causes a verify to wait for a specified period of time for a desired 2048e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * interaction rather than fails immediately if had not already happened. May be useful for testing in concurrent 2049e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * conditions. 2050e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 2051e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * It feels this feature should be used rarely - figure out a better way of testing your multi-threaded system 2052e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 2053e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Not yet implemented to work with InOrder verification. 2054e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 2055e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //passes when someMethod() is called within given time span 2056e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * verify(mock, timeout(100)).someMethod(); 2057e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //above is an alias to: 2058e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * verify(mock, timeout(100).times(1)).someMethod(); 2059e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 2060e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //passes when someMethod() is called <b>*exactly*</b> 2 times within given time span 2061e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * verify(mock, timeout(100).times(2)).someMethod(); 2062e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 2063e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //passes when someMethod() is called <b>*at least*</b> 2 times within given time span 2064e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * verify(mock, timeout(100).atLeast(2)).someMethod(); 2065e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 2066e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //verifies someMethod() within given time span using given verification mode 2067e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //useful only if you have your own custom verification modes. 2068e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * verify(mock, new Timeout(100, yourOwnVerificationMode)).someMethod(); 2069e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 2070e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 2071e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * See examples in javadoc for {@link Mockito} class 2072e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 2073e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @param millis - time span in millisecond 2074e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 2075e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @return verification mode 2076e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson */ 2077e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson public static VerificationWithTimeout timeout(int millis) { 2078e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson return new Timeout(millis, VerificationModeFactory.times(1)); 2079e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson } 2080e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson 2081e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson /** 2082e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * First of all, in case of any trouble, I encourage you to read the Mockito FAQ: <a href="http://code.google.com/p/mockito/wiki/FAQ">http://code.google.com/p/mockito/wiki/FAQ</a> 2083e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 2084e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * In case of questions you may also post to mockito mailing list: <a href="http://groups.google.com/group/mockito">http://groups.google.com/group/mockito</a> 2085e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 2086e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <code>validateMockitoUsage()</code> <b>explicitly validates</b> the framework state to detect invalid use of Mockito. 2087e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * However, this feature is optional <b>because Mockito validates the usage all the time...</b> but there is a gotcha so read on. 2088e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 2089e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Examples of incorrect use: 2090e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 2091e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //Oups, someone forgot thenReturn() part: 2092e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * when(mock.get()); 2093e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 2094e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //Oups, someone put the verified method call inside verify() where it should be outside: 2095e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * verify(mock.execute()); 2096e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 2097e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //Oups, someone has used EasyMock for too long and forgot to specify the method to verify: 2098e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * verify(mock); 2099e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 2100e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 2101e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Mockito throws exceptions if you misuse it so that you know if your tests are written correctly. 2102e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * The gotcha is that Mockito does the validation <b>next time</b> you use the framework (e.g. next time you verify, stub, call mock etc.). 2103e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * But even though the exception might be thrown in the next test, 2104e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * the exception <b>message contains a navigable stack trace element</b> with location of the defect. 2105e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Hence you can click and find the place where Mockito was misused. 2106e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 2107e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Sometimes though, you might want to validate the framework usage explicitly. 2108e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * For example, one of the users wanted to put <code>validateMockitoUsage()</code> in his <code>@After</code> method 2109e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * so that he knows immediately when he misused Mockito. 2110e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Without it, he would have known about it not sooner than <b>next time</b> he used the framework. 2111e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * One more benefit of having <code>validateMockitoUsage()</code> in <code>@After</code> is that jUnit runner will always fail in the test method with defect 2112e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * whereas ordinary 'next-time' validation might fail the <b>next</b> test method. 2113e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * But even though JUnit might report next test as red, don't worry about it 2114e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * and just click at navigable stack trace element in the exception message to instantly locate the place where you misused mockito. 2115e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 2116e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <b>Built-in runner: {@link MockitoJUnitRunner}</b> does validateMockitoUsage() after each test method. 2117e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 2118e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Bear in mind that <b>usually you don't have to <code>validateMockitoUsage()</code></b> 2119e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * and framework validation triggered on next-time basis should be just enough, 2120e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * mainly because of enhanced exception message with clickable location of defect. 2121e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * However, I would recommend validateMockitoUsage() if you already have sufficient test infrastructure 2122e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * (like your own runner or base class for all tests) because adding a special action to <code>@After</code> has zero cost. 2123e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 2124e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * See examples in javadoc for {@link Mockito} class 2125e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson */ 2126e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson public static void validateMockitoUsage() { 2127e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson MOCKITO_CORE.validateMockitoUsage(); 2128e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson } 2129e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson 2130e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson /** 2131e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Allows mock creation with additional mock settings. 2132e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 2133e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Don't use it too often. 2134e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Consider writing simple tests that use simple mocks. 2135e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Repeat after me: simple tests push simple, KISSy, readable & maintainable code. 2136e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * If you cannot write a test in a simple way - refactor the code under test. 2137e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 2138e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Examples of mock settings: 2139e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <pre class="code"><code class="java"> 2140e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //Creates mock with different default answer & name 2141e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Foo mock = mock(Foo.class, withSettings() 2142e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * .defaultAnswer(RETURNS_SMART_NULLS) 2143e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * .name("cool mockie")); 2144e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 2145e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * //Creates mock with different default answer, descriptive name and extra interfaces 2146e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Foo mock = mock(Foo.class, withSettings() 2147e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * .defaultAnswer(RETURNS_SMART_NULLS) 2148e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * .name("cool mockie") 2149e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * .extraInterfaces(Bar.class)); 2150e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * </code></pre> 2151e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * {@link MockSettings} has been introduced for two reasons. 2152e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Firstly, to make it easy to add another mock settings when the demand comes. 2153e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Secondly, to enable combining different mock settings without introducing zillions of overloaded mock() methods. 2154e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 2155e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * See javadoc for {@link MockSettings} to learn about possible mock settings. 2156e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * <p> 2157e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * 2158e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * @return mock settings instance with defaults. 2159e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson */ 2160e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson public static MockSettings withSettings() { 2161e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson return new MockSettingsImpl().defaultAnswer(RETURNS_DEFAULTS); 2162e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson } 2163e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson 2164e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson /** 2165e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson * Helps debugging failing tests. Experimental - use at your own risk. We're not sure if this method will stay in public api. 2166e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson */ 2167e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson @Deprecated 2168e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson static MockitoDebugger debug() { 2169e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson return new MockitoDebuggerImpl(); 2170e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson } 2171e0ae5d7e87b1dd6e789803c1b9615a84bd7488b7Ian Parkinson} 2172