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 onVerificationStarted(VerificationStartedEvent event)68 void onVerificationStarted(VerificationStartedEvent event); 69 } 70