1 package org.mockito; 2 3 import org.mockito.exceptions.misusing.UnfinishedMockingSessionException; 4 import org.mockito.exceptions.misusing.UnnecessaryStubbingException; 5 import org.mockito.junit.MockitoJUnitRunner; 6 import org.mockito.junit.MockitoRule; 7 import org.mockito.listeners.MockitoListener; 8 import org.mockito.quality.MockitoHint; 9 import org.mockito.quality.Strictness; 10 import org.mockito.session.MockitoSessionBuilder; 11 12 /** 13 * {@code MockitoSession} is an optional, highly recommended feature 14 * that helps driving cleaner tests by eliminating boilerplate code and adding extra validation. 15 * If you already use {@link MockitoJUnitRunner} or {@link MockitoRule} 16 * *you don't need* {@code MockitoSession} because it is used by the runner/rule. 17 * <p> 18 * {@code MockitoSession} is a session of mocking, during which the user creates and uses Mockito mocks. 19 * Typically the session is an execution of a single test method. 20 * {@code MockitoSession} initializes mocks, validates usage and detects incorrect stubbing. 21 * When the session is started it must be concluded with {@link #finishMocking()} 22 * otherwise {@link UnfinishedMockingSessionException} is triggered when the next session is created. 23 * <p> 24 * {@code MockitoSession} is useful when you cannot use {@link MockitoJUnitRunner} or {@link MockitoRule}. 25 * For example, you work with TestNG instead of JUnit. 26 * Another example is when different JUnit runner is in use (Jukito, Springockito) 27 * and it cannot be combined with Mockito's own runner. 28 * <p> 29 * Framework integrators are welcome to use {@code MockitoSession} and give us feedback by commenting on 30 * <a href="https://github.com/mockito/mockito/issues/857">issue 857</a>. 31 * <p> 32 * 33 * Example: 34 * <pre class="code"><code class="java"> 35 * public class ExampleTest { 36 * @Mock Foo foo; 37 * 38 * //Keeping session object in a field so that we can complete session in 'tear down' method. 39 * //It is recommended to hide the session object, along with 'setup' and 'tear down' methods in a base class / runner. 40 * //Keep in mind that you can use Mockito's JUnit runner or rule instead of MockitoSession and get the same behavior. 41 * MockitoSession mockito; 42 * 43 * @Before public void setup() { 44 * //initialize session to start mocking 45 * mockito = Mockito.mockitoSession() 46 * .initMocks(this) 47 * .strictness(Strictness.STRICT_STUBS) 48 * .startMocking(); 49 * } 50 * 51 * @After public void tearDown() { 52 * //It is necessary to finish the session so that Mockito 53 * // can detect incorrect stubbing and validate Mockito usage 54 * //'finishMocking()' is intended to be used in your test framework's 'tear down' method. 55 * mockito.finishMocking(); 56 * } 57 * 58 * // test methods ... 59 * } 60 * </code></pre> 61 * 62 * <p> 63 * Why to use {@code MockitoSession}? 64 * What's the difference between {@code MockitoSession}, {@link MockitoJUnitRunner}, {@link MockitoRule} 65 * and traditional {@link MockitoAnnotations#initMocks(Object)}? 66 * <p> 67 * Great questions! 68 * There is no need to use {@code MockitoSession} if you already use {@link MockitoJUnitRunner} or {@link MockitoRule}. 69 * If you are JUnit user who does not leverage Mockito rule or runner we strongly recommend to do so. 70 * Both the runner and the rule support strict stubbing which can really help driving cleaner tests. 71 * See {@link MockitoJUnitRunner.StrictStubs} and {@link MockitoRule#strictness(Strictness)}. 72 * If you cannot use Mockito's JUnit support (for example, you are on TestNG) {@code MockitoSession} exactly is for you! 73 * You can automatically take advantage of strict stubbing ({@link Strictness}), 74 * automatic initialization of annotated mocks ({@link MockitoAnnotations}), 75 * and extra validation ({@link Mockito#validateMockitoUsage()}). 76 * If you use Mockito annotations with {@link MockitoAnnotations#initMocks(Object)} 77 * but not Mockito runner/rule please try out Mockito's JUnit support (runner or rule) or 78 * start using {@code MockitoSession}. You'll get cleaner tests and better productivity. 79 * <p> 80 * Mockito team would really appreciate feedback about {@code MockitoSession} API. 81 * Help us out by commenting at <a href="https://github.com/mockito/mockito/issues/857">issue 857</a>. 82 * 83 * @since 2.7.0 84 */ 85 @Incubating 86 public interface MockitoSession { 87 88 /** 89 * Must be invoked when the user is done with mocking for given session (test method). 90 * It detects unused stubbings and may throw {@link UnnecessaryStubbingException} 91 * or emit warnings ({@link MockitoHint}) depending on the {@link Strictness} level. 92 * The method also detects incorrect Mockito usage via {@link Mockito#validateMockitoUsage()}. 93 * <p> 94 * In order to implement {@link Strictness} Mockito session keeps track of mocking using {@link MockitoListener}. 95 * This method cleans up the listeners and ensures there is no leftover state after the session finishes. 96 * It is necessary to invoke this method to conclude mocking session. 97 * For more information about session lifecycle see {@link MockitoSessionBuilder#startMocking()}. 98 * <p> 99 * This method is intended to be used in your test framework's 'tear down' method. 100 * In the case of JUnit it is the "@After" method. 101 * <p> 102 * For example, see javadoc for {@link MockitoSession}. 103 * 104 * @since 2.7.0 105 */ 106 @Incubating finishMocking()107 void finishMocking(); 108 } 109