org.mockito.listeners.VerificationStartedListener Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of mockito-core Show documentation
Mockito mock objects library core API and implementation
There is a newer version: 5.12.0
/*
 * Copyright (c) 2017 Mockito contributors
 * This program is made available under the terms of the MIT License.
 */
package org.mockito.listeners;

import org.mockito.Incubating;

/**
 * This listener gets notified when the user starts verification.
 * It allows to replace the mock object for verification.
 * This API is not needed for regular Mockito users who want to write beautiful and clean tests.
 * It is only needed for advanced framework integrations where there are multiple layers of proxying.
 * An example framework that leverages this API is Spring Boot.
 * For details about the use case see issue 1191.
 * For sample code see {@code VerificationStartedListenerTest} class.
 * Mockito is Open Source so feel free to dive into the code!
 * 
 * How can you add listeners?
 * The listener is attached to the mock object during creation:
 * 

 *     List mock = Mockito.mock(List.class, withSettings().verificationStartedListeners(myListener));
 * 

 * When multiple listeners are added, they are notified in order.
 * 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.
 * See {@link org.mockito.MockSettings#verificationStartedListeners(VerificationStartedListener...)}.
 * 
 * When is the listener notified?
 * 

 *     //given verification:
 *     verify(mock).someMethod();
 *
 *     //let's slit it into 2 distinct steps so that it is easy to explain:
 *
 *     //step 1
 *     verify(mock);
 *
 *     //step 2
 *     mock.someMethod();
 *
 *     //the listener is notified during step 1
 *     //step 2 is when Mockito attempts to verify the method call
 * 

 * 
 * What can I do when the listener is notified?
 * The main reason we added this listener to the API is to allow to replace the mock object that is about to be verified.
 * This is a pretty hardcore use case, needed by other frameworks that wrap Mockito with another layer of proxying.
 * Such framework may need to unwrap the outer proxy layer and pass genuine Mockito mock to the verification.
 * For specific use case how it is needed by Spring Boot, see issue 1191.
 * 
 * When do I use the listener?
 * Unless you write a framework that integrates with Mockito, there is no reason for you to use this API.
 * Keep mocking and writing great unit tests!
 *
 * @since 2.11.0
 */
@Incubating
public interface VerificationStartedListener {

    /**
     * Triggered when the user calls {@code Mockito.verify()}.
     * For details see {@link VerificationStartedListener}.
     *
     * @param event object that allows to identify and replace mock for verification.
     * @since 2.11.0
     */
    @Incubating
    void onVerificationStarted(VerificationStartedEvent event);
}