1/*
2 * Copyright (c) 2017 Mockito contributors
3 * This program is made available under the terms of the MIT License.
4 */
5package org.mockito.listeners;
6
7import 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
58public 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