Home | History | Annotate | Download | only in listeners 
      1 /*
      2  * Copyright (c) 2017 Mockito contributors
      3  * This program is made available under the terms of the MIT License.
      4  */
      5 package org.mockito.listeners;
      6 
      7 import org.mockito.Incubating;
      8 
      9 /**
     10  * This listener gets notified when the user starts verification.
     11  * It allows to replace the mock object for verification.
     12  * This API is not needed for regular Mockito users who want to write beautiful and clean tests.
     13  * It is only needed for advanced framework integrations where there are multiple layers of proxying.
     14  * An example framework that leverages this API is <a href="https://projects.spring.io/spring-boot/">Spring Boot</a>.
     15  * For details about the use case see <a href="https://github.com/mockito/mockito/issues/1191">issue 1191</a>.
     16  * For sample code see {@code VerificationStartedListenerTest} class.
     17  * Mockito is Open Source so feel free to dive into the code!
     18  * <p>
     19  * How can you add listeners?
     20  * The listener is attached to the mock object during creation:
     21  * <pre class="code"><code class="java">
     22  *     List mock = Mockito.mock(List.class, withSettings().verificationStartedListeners(myListener));
     23  * </pre>
     24  * When multiple listeners are added, they are notified in order.
     25  * There is no reason to add multiple listeners but we wanted to keep the API simple and consistent with how we manage Mock object listeners.
     26  * See {@link org.mockito.MockSettings#verificationStartedListeners(VerificationStartedListener...)}.
     27  * <p>
     28  * When is the listener notified?
     29  * <pre class="code"><code class="java">
     30  *     //given verification:
     31  *     verify(mock).someMethod();
     32  *
     33  *     //let's slit it into 2 distinct steps so that it is easy to explain:
     34  *
     35  *     //step 1
     36  *     verify(mock);
     37  *
     38  *     //step 2
     39  *     mock.someMethod();
     40  *
     41  *     //the listener is notified during step 1
     42  *     //step 2 is when Mockito attempts to verify the method call
     43  * </pre>
     44  * <p>
     45  * What can I do when the listener is notified?
     46  * The main reason we added this listener to the API is to allow to replace the mock object that is about to be verified.
     47  * This is a pretty hardcore use case, needed by other frameworks that wrap Mockito with another layer of proxying.
     48  * Such framework may need to unwrap the outer proxy layer and pass genuine Mockito mock to the verification.
     49  * For specific use case how it is needed by Spring Boot, see <a href="https://github.com/mockito/mockito/issues/1191">issue 1191</a>.
     50  * <p>
     51  * When do I use the listener?
     52  * Unless you write a framework that integrates with Mockito, there is no reason for you to use this API.
     53  * Keep mocking and writing great unit tests!
     54  *
     55  * @since 2.11.0
     56  */
     57 @Incubating
     58 public interface VerificationStartedListener {
     59 
     60     /**
     61      * Triggered when the user calls {@code Mockito.verify()}.
     62      * For details see {@link VerificationStartedListener}.
     63      *
     64      * @param event object that allows to identify and replace mock for verification.
     65      * @since 2.11.0
     66      */
     67     @Incubating
     68     void onVerificationStarted(VerificationStartedEvent event);
     69 }
     70