1 /* 2 * Copyright (c) 2007 Mockito contributors 3 * This program is made available under the terms of the MIT License. 4 */ 5 package org.mockito; 6 7 import org.mockito.invocation.Invocation; 8 import org.mockito.invocation.MockHandler; 9 import org.mockito.mock.MockCreationSettings; 10 import org.mockito.quality.MockitoHint; 11 import org.mockito.stubbing.Stubbing; 12 13 import java.util.Collection; 14 15 /** 16 * Provides mocking information. 17 * For example, you can identify whether a particular object is either a mock or a spy. 18 * For examples and more information please refer to the javadoc of the individual methods on this class. 19 * 20 * @since 1.9.5 21 */ 22 public interface MockingDetails { 23 24 /** 25 * Informs if the object is a mock. isMock() for null input returns false. 26 * @return true if the object is a mock or a spy (spy is a different kind of mock, but it is still a mock). 27 * 28 * @since 1.9.5 29 */ isMock()30 boolean isMock(); 31 32 /** 33 * Informs if the object is a spy. isSpy() for null input returns false. 34 * @return true if the object is a spy. 35 * 36 * @since 1.9.5 37 */ isSpy()38 boolean isSpy(); 39 40 /** 41 * All method invocations on this mock. 42 * Can be empty - it means there were no interactions with the mock. 43 * <p> 44 * This method is useful for framework integrators and for certain edge cases. 45 * <p> 46 * Manipulating the collection (e.g. by removing, adding elements) is safe and has no effect on the mock. 47 * <p> 48 * Throws meaningful exception when object wrapped by MockingDetails is not a mock. 49 * 50 * @since 1.10.0 51 */ getInvocations()52 Collection<Invocation> getInvocations(); 53 54 /** 55 * Returns various mock settings provided when the mock was created, for example: 56 * mocked class, mock name (if any), any extra interfaces (if any), etc. 57 * See also {@link MockCreationSettings}. 58 * <p> 59 * This method is useful for framework integrators and for certain edge cases. 60 * <p> 61 * If <code>null</code> or non-mock was passed to {@link Mockito#mockingDetails(Object)} 62 * then this method will throw with an appropriate exception. 63 * After all, non-mock objects do not have any mock creation settings. 64 * @since 2.1.0 65 */ getMockCreationSettings()66 MockCreationSettings<?> getMockCreationSettings(); 67 68 /** 69 * Returns stubbings declared on this mock object. 70 * <pre class="code"><code class="java"> 71 * Mockito.mockingDetails(mock).getStubbings() 72 * </code></pre> 73 * What is 'stubbing'? 74 * Stubbing is your when(x).then(y) declaration, e.g. configuring the mock to behave in a specific way, 75 * when specific method with specific arguments is invoked on a mock. 76 * Typically stubbing is configuring mock to return X when method Y is invoked. 77 * <p> 78 * Why do you need to access stubbings of a mock? 79 * In a normal workflow of creation clean tests, there is no need for this API. 80 * However, it is useful for advanced users, edge cases or framework integrators. 81 * For example, Mockito internally uses this API to report and detect unused stubbings 82 * that should be removed from test. Unused stubbings are dead code that needs to be removed 83 * (see {@link MockitoHint}). 84 * <p> 85 * Manipulating the collection (e.g. by removing, adding elements) is safe and has no effect on the mock. 86 * <p> 87 * This method throws meaningful exception when object wrapped by MockingDetails is not a mock. 88 * 89 * @since 2.2.3 90 */ getStubbings()91 Collection<Stubbing> getStubbings(); 92 93 /** 94 * Returns printing-friendly list of the invocations that occurred with the mock object. 95 * Additionally, this method prints stubbing information, including unused stubbings. 96 * For more information about unused stubbing detection see {@link MockitoHint}. 97 * <p> 98 * You can use this method for debugging, 99 * print the output of this method to the console to find out about all interactions with the mock. 100 * <p> 101 * Content that is printed is subject to change as we discover better ways of presenting important mock information. 102 * Don't write code that depends on the output of this method. 103 * If you need to know about interactions and stubbings, use {@link #getStubbings()} and {@link #getInvocations()}. 104 * <p> 105 * This method was moved from the deprecated and semi-hidden type {@link MockitoDebugger}. 106 * <p> 107 * This method throws meaningful exception when object wrapped by MockingDetails is not a mock. 108 * 109 * @since 2.2.6 110 */ printInvocations()111 String printInvocations(); 112 113 /** 114 * Returns the {@link MockHandler} associated with this mock object. 115 * The handler is the core of mock object method handling. 116 * This method is useful for framework integrators. 117 * For example, other frameworks may use mock handler to simulate method calls on the Mock object. 118 * 119 * @return mock handler instance of this mock 120 * @since 2.10.0 121 */ 122 @Incubating getMockHandler()123 MockHandler getMockHandler(); 124 125 /** 126 * Returns the mock object which is associated with this this instance of {@link MockingDetails}. 127 * Basically, it's the object that you have passed to {@link Mockito#mockingDetails(Object)} method. 128 * 129 * @return the mock object of this mocking details instance 130 * 131 * @since 2.11.0 132 */ getMock()133 Object getMock(); 134 } 135