1 package org.mockito.session; 2 3 import org.mockito.Incubating; 4 import org.mockito.MockitoAnnotations; 5 import org.mockito.MockitoSession; 6 import org.mockito.exceptions.misusing.UnfinishedMockingSessionException; 7 import org.mockito.quality.Strictness; 8 9 /** 10 * Fluent builder interface for {@code MockitoSession} objects. 11 * See the documentation and examples in Javadoc for {@link MockitoSession}. 12 * 13 * @since 2.7.0 14 */ 15 @Incubating 16 public interface MockitoSessionBuilder { 17 18 /** 19 * Configures the test class instance for initialization of fields annotated with Mockito annotations 20 * like {@link org.mockito.Mock}. 21 * When this method is invoked it <strong>does not perform</strong> initialization of mocks on the spot! 22 * Only when {@link #startMocking()} is invoked then annotated fields will be initialized. 23 * Traditional API to initialize mocks, the {@link MockitoAnnotations#initMocks(Object)} method 24 * has limited support for driving cleaner tests because it does not support configuring {@link Strictness}. 25 * Want cleaner tests and better productivity? 26 * Migrate from {@link MockitoAnnotations#initMocks(Object)} 27 * to {@link MockitoSession}! 28 * <p> 29 * See code sample in {@link MockitoSession}. 30 * 31 * @param testClassInstance test class instance that contains fields with Mockito annotations to be initialized. 32 * Passing {@code null} is permitted and will make the session use a default value. 33 * The current default is '{@code new Object()}'. 34 * @return the same builder instance for fluent configuration of {@code MockitoSession}. 35 * @since 2.7.0 36 */ 37 @Incubating initMocks(Object testClassInstance)38 MockitoSessionBuilder initMocks(Object testClassInstance); 39 40 /** 41 * Configures strictness of {@code MockitoSession} instance. 42 * See examples in {@link MockitoSession}. 43 * 44 * @param strictness for {@code MockitoSession} instance. 45 * Passing {@code null} is permitted and will make the session use a default value. 46 * The current default is {@link Strictness#STRICT_STUBS}. 47 * 48 * @return the same builder instance for fluent configuration of {@code MockitoSession}. 49 * @since 2.7.0 50 */ 51 @Incubating strictness(Strictness strictness)52 MockitoSessionBuilder strictness(Strictness strictness); 53 54 /** 55 * Starts new mocking session! Creates new {@code MockitoSession} instance to initialize the session. 56 * At this point annotated fields are initialized per {@link #initMocks(Object)} method. 57 * When you are done with the session it is required to invoke {@link MockitoSession#finishMocking()}. 58 * This will trigger stubbing validation, cleaning up the internal state like removal of internal listeners. 59 * <p> 60 * Mockito tracks created sessions internally and prevents the user from creating new sessions without 61 * using {@link MockitoSession#finishMocking()}. 62 * When you run tests concurrently in multiple threads, it is legal for each thread to have single active Mockito session. 63 * When you attempt to start new session in a thread that already has an unfinished session 64 * {@link UnfinishedMockingSessionException} will be triggered. 65 * <p> 66 * See examples in {@link MockitoSession}. 67 * 68 * @return new {@code MockitoSession} instance 69 * @since 2.7.0 70 * @throws UnfinishedMockingSessionException 71 * when previous session was not concluded with {@link MockitoSession#finishMocking()} 72 */ 73 @Incubating startMocking()74 MockitoSession startMocking() throws UnfinishedMockingSessionException; 75 } 76