1 /* 2 * Copyright (c) 2018 Mockito contributors 3 * This program is made available under the terms of the MIT License. 4 */ 5 package org.mockito.session; 6 7 import org.mockito.Incubating; 8 import org.mockito.MockitoAnnotations; 9 import org.mockito.MockitoSession; 10 import org.mockito.exceptions.misusing.UnfinishedMockingSessionException; 11 import org.mockito.quality.Strictness; 12 13 /** 14 * Fluent builder interface for {@code MockitoSession} objects. 15 * See the documentation and examples in Javadoc for {@link MockitoSession}. 16 * 17 * @since 2.7.0 18 */ 19 @Incubating 20 public interface MockitoSessionBuilder { 21 22 /** 23 * Adds the test class instance for initialization of fields annotated with Mockito annotations 24 * like {@link org.mockito.Mock}. 25 * When this method is invoked it <strong>does not perform</strong> initialization of mocks on the spot! 26 * Only when {@link #startMocking()} is invoked then annotated fields will be initialized. 27 * Traditional API to initialize mocks, the {@link MockitoAnnotations#initMocks(Object)} method 28 * has limited support for driving cleaner tests because it does not support configuring {@link Strictness}. 29 * Want cleaner tests and better productivity? 30 * Migrate from {@link MockitoAnnotations#initMocks(Object)} 31 * to {@link MockitoSession}! 32 * <p> 33 * This method may be called multiple times to add multiple, e.g. nested, test class instances. 34 * <p> 35 * See code sample in {@link MockitoSession}. 36 * 37 * @param testClassInstance test class instance that contains fields with Mockito annotations to be initialized. 38 * Passing {@code null} is permitted but will be ignored. 39 * @return the same builder instance for fluent configuration of {@code MockitoSession}. 40 * @since 2.7.0 41 */ 42 @Incubating initMocks(Object testClassInstance)43 MockitoSessionBuilder initMocks(Object testClassInstance); 44 45 /** 46 * Adds the test class instances for initialization of fields annotated with Mockito annotations 47 * like {@link org.mockito.Mock}. 48 * <p> 49 * In most scenarios, you only need to init mocks on a single test class instance. 50 * This method is useful for advanced framework integrations (like JUnit Jupiter), when a test uses multiple, e.g. nested, test class instances. 51 * <p> 52 * This method calls {@link #initMocks(Object)} for each passed test class instance. 53 * 54 * @param testClassInstances test class instances that contains fields with Mockito annotations to be initialized. 55 * Passing {@code null} or an empty array is permitted but will be ignored. 56 * @return the same builder instance for fluent configuration of {@code MockitoSession}. 57 * @see #initMocks(Object) 58 * @since 2.15.0 59 */ 60 @Incubating initMocks(Object... testClassInstances)61 MockitoSessionBuilder initMocks(Object... testClassInstances); 62 63 /** 64 * Configures the name of the {@code MockitoSession} instance. 65 * <p> 66 * The name is used to output {@linkplain org.mockito.quality.MockitoHint hints} when 67 * {@linkplain MockitoSession#finishMocking() finishing} a session. 68 * <p> 69 * This method is intended to be used by framework integrations, e.g. JUnit. When building 70 * a {@code MockitoSession} for direct use, users are not expected to call it. 71 * 72 * @param name of {@code MockitoSession} instance. 73 * Passing {@code null} is permitted and will make the session use a default value. 74 * The current default is the name of the last test class instance passed to 75 * {@link #initMocks(Object)} or {@link #initMocks(Object...)}, if available; 76 * otherwise, {@code "<Unnamed Session>"} is used. 77 * 78 * @return the same builder instance for fluent configuration of {@code MockitoSession}. 79 * @see org.mockito.quality.MockitoHint 80 * @since 2.15.0 81 */ 82 @Incubating name(String name)83 MockitoSessionBuilder name(String name); 84 85 /** 86 * Configures strictness of {@code MockitoSession} instance. 87 * See examples in {@link MockitoSession}. 88 * 89 * @param strictness for {@code MockitoSession} instance. 90 * Passing {@code null} is permitted and will make the session use a default value. 91 * The current default is {@link Strictness#STRICT_STUBS}. 92 * 93 * @return the same builder instance for fluent configuration of {@code MockitoSession}. 94 * @since 2.7.0 95 */ 96 @Incubating strictness(Strictness strictness)97 MockitoSessionBuilder strictness(Strictness strictness); 98 99 /** 100 * Configures logger used by {@code MockitoSession} for emitting 101 * {@linkplain org.mockito.quality.MockitoHint warnings} when finishing the session. 102 * <p> 103 * Please note that the use of {@linkplain Strictness#STRICT_STUBS strict stubs} is 104 * recommended over emitting warnings because warnings are easily ignored and spoil the log output. 105 * Instead of using this method, please consider setting strictness with {@link #strictness(Strictness)}. 106 * 107 * @param logger for warnings emitted when finishing {@code MockitoSession}. 108 * Passing {@code null} is permitted and will make the session use a default value. 109 * By default, warnings will be logged to the console. 110 * 111 * @return the same builder instance for fluent configuration of {@code MockitoSession}. 112 * @see org.mockito.quality.MockitoHint 113 * @since 2.15.0 114 */ 115 @Incubating logger(MockitoSessionLogger logger)116 MockitoSessionBuilder logger(MockitoSessionLogger logger); 117 118 /** 119 * Starts new mocking session! Creates new {@code MockitoSession} instance to initialize the session. 120 * At this point annotated fields are initialized per {@link #initMocks(Object)} method. 121 * When you are done with the session it is required to invoke {@link MockitoSession#finishMocking()}. 122 * This will trigger stubbing validation, cleaning up the internal state like removal of internal listeners. 123 * <p> 124 * Mockito tracks created sessions internally and prevents the user from creating new sessions without 125 * using {@link MockitoSession#finishMocking()}. 126 * When you run tests concurrently in multiple threads, it is legal for each thread to have single active Mockito session. 127 * When you attempt to start new session in a thread that already has an unfinished session 128 * {@link UnfinishedMockingSessionException} will be triggered. 129 * <p> 130 * See examples in {@link MockitoSession}. 131 * 132 * @return new {@code MockitoSession} instance 133 * @since 2.7.0 134 * @throws UnfinishedMockingSessionException 135 * when previous session was not concluded with {@link MockitoSession#finishMocking()} 136 */ 137 @Incubating startMocking()138 MockitoSession startMocking() throws UnfinishedMockingSessionException; 139 } 140