| /* |
| * Copyright (c) 2017 Mockito contributors |
| * This program is made available under the terms of the MIT License. |
| */ |
| package org.mockito; |
| |
| import org.mockito.exceptions.misusing.UnfinishedMockingSessionException; |
| import org.mockito.exceptions.misusing.UnnecessaryStubbingException; |
| import org.mockito.junit.MockitoJUnitRunner; |
| import org.mockito.junit.MockitoRule; |
| import org.mockito.listeners.MockitoListener; |
| import org.mockito.quality.MockitoHint; |
| import org.mockito.quality.Strictness; |
| import org.mockito.session.MockitoSessionBuilder; |
| |
| /** |
| * {@code MockitoSession} is an optional, highly recommended feature |
| * that helps driving cleaner tests by eliminating boilerplate code and adding extra validation. |
| * If you already use {@link MockitoJUnitRunner} or {@link MockitoRule} |
| * *you don't need* {@code MockitoSession} because it is used by the runner/rule. |
| * <p> |
| * {@code MockitoSession} is a session of mocking, during which the user creates and uses Mockito mocks. |
| * Typically the session is an execution of a single test method. |
| * {@code MockitoSession} initializes mocks, validates usage and detects incorrect stubbing. |
| * When the session is started it must be concluded with {@link #finishMocking()} |
| * otherwise {@link UnfinishedMockingSessionException} is triggered when the next session is created. |
| * <p> |
| * {@code MockitoSession} is useful when you cannot use {@link MockitoJUnitRunner} or {@link MockitoRule}. |
| * For example, you work with TestNG instead of JUnit. |
| * Another example is when different JUnit runner is in use (Jukito, Springockito) |
| * and it cannot be combined with Mockito's own runner. |
| * <p> |
| * Framework integrators are welcome to use {@code MockitoSession} and give us feedback by commenting on |
| * <a href="https://github.com/mockito/mockito/issues/857">issue 857</a>. |
| * <p> |
| * |
| * Example: |
| * <pre class="code"><code class="java"> |
| * public class ExampleTest { |
| * @Mock Foo foo; |
| * |
| * //Keeping session object in a field so that we can complete session in 'tear down' method. |
| * //It is recommended to hide the session object, along with 'setup' and 'tear down' methods in a base class / runner. |
| * //Keep in mind that you can use Mockito's JUnit runner or rule instead of MockitoSession and get the same behavior. |
| * MockitoSession mockito; |
| * |
| * @Before public void setup() { |
| * //initialize session to start mocking |
| * mockito = Mockito.mockitoSession() |
| * .initMocks(this) |
| * .strictness(Strictness.STRICT_STUBS) |
| * .startMocking(); |
| * } |
| * |
| * @After public void tearDown() { |
| * //It is necessary to finish the session so that Mockito |
| * // can detect incorrect stubbing and validate Mockito usage |
| * //'finishMocking()' is intended to be used in your test framework's 'tear down' method. |
| * mockito.finishMocking(); |
| * } |
| * |
| * // test methods ... |
| * } |
| * </code></pre> |
| * |
| * <p> |
| * Why to use {@code MockitoSession}? |
| * What's the difference between {@code MockitoSession}, {@link MockitoJUnitRunner}, {@link MockitoRule} |
| * and traditional {@link MockitoAnnotations#initMocks(Object)}? |
| * <p> |
| * Great questions! |
| * There is no need to use {@code MockitoSession} if you already use {@link MockitoJUnitRunner} or {@link MockitoRule}. |
| * If you are JUnit user who does not leverage Mockito rule or runner we strongly recommend to do so. |
| * Both the runner and the rule support strict stubbing which can really help driving cleaner tests. |
| * See {@link MockitoJUnitRunner.StrictStubs} and {@link MockitoRule#strictness(Strictness)}. |
| * If you cannot use Mockito's JUnit support (for example, you are on TestNG) {@code MockitoSession} exactly is for you! |
| * You can automatically take advantage of strict stubbing ({@link Strictness}), |
| * automatic initialization of annotated mocks ({@link MockitoAnnotations}), |
| * and extra validation ({@link Mockito#validateMockitoUsage()}). |
| * If you use Mockito annotations with {@link MockitoAnnotations#initMocks(Object)} |
| * but not Mockito runner/rule please try out Mockito's JUnit support (runner or rule) or |
| * start using {@code MockitoSession}. You'll get cleaner tests and better productivity. |
| * <p> |
| * Mockito team would really appreciate feedback about {@code MockitoSession} API. |
| * Help us out by commenting at <a href="https://github.com/mockito/mockito/issues/857">issue 857</a>. |
| * |
| * @since 2.7.0 |
| */ |
| @Incubating |
| public interface MockitoSession { |
| |
| /** |
| * Must be invoked when the user is done with mocking for given session (test method). |
| * It detects unused stubbings and may throw {@link UnnecessaryStubbingException} |
| * or emit warnings ({@link MockitoHint}) depending on the {@link Strictness} level. |
| * The method also detects incorrect Mockito usage via {@link Mockito#validateMockitoUsage()}. |
| * <p> |
| * In order to implement {@link Strictness} Mockito session keeps track of mocking using {@link MockitoListener}. |
| * This method cleans up the listeners and ensures there is no leftover state after the session finishes. |
| * It is necessary to invoke this method to conclude mocking session. |
| * For more information about session lifecycle see {@link MockitoSessionBuilder#startMocking()}. |
| * <p> |
| * This method is intended to be used in your test framework's 'tear down' method. |
| * In the case of JUnit it is the "@After" method. |
| * <p> |
| * For example, see javadoc for {@link MockitoSession}. |
| * |
| * @since 2.7.0 |
| */ |
| @Incubating |
| void finishMocking(); |
| } |