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