Home | History | Annotate | Download | only in session 
      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
     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 JUnit5), 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
     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
     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
     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
    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
    138     MockitoSession startMocking() throws UnfinishedMockingSessionException;
    139 }
    140