1 /* 2 * Copyright (c) 2016 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.exceptions.misusing.RedundantListenerException; 8 import org.mockito.invocation.Invocation; 9 import org.mockito.invocation.InvocationFactory; 10 import org.mockito.listeners.MockitoListener; 11 import org.mockito.plugins.MockitoPlugins; 12 13 /** 14 * Mockito framework settings and lifecycle listeners, for advanced users or for integrating with other frameworks. 15 * <p> 16 * To get <code>MockitoFramework</code> instance use {@link Mockito#framework()}. 17 * <p> 18 * For more info on listeners see {@link #addListener(MockitoListener)}. 19 * 20 * @since 2.1.0 21 */ 22 @Incubating 23 public interface MockitoFramework { 24 25 /** 26 * Adds listener to Mockito. 27 * For a list of supported listeners, see the interfaces that extend {@link MockitoListener}. 28 * <p> 29 * Listeners can be useful for engs that extend Mockito framework. 30 * They are used in the implementation of unused stubbings warnings ({@link org.mockito.quality.MockitoHint}). 31 * <p> 32 * Make sure you remove the listener when the job is complete, see {@link #removeListener(MockitoListener)}. 33 * Currently the listeners list is thread local so you need to remove listener from the same thread otherwise 34 * remove is ineffectual. 35 * In typical scenarios, it is not a problem, because adding & removing listeners typically happens in the same thread. 36 * <p> 37 * If you are trying to add the listener but a listener of the same type was already added (and not removed) 38 * this method will throw {@link RedundantListenerException}. 39 * This is a safeguard to ensure users actually remove the listeners via {@link #removeListener(MockitoListener)}. 40 * We do not anticipate the use case where adding the same listener type multiple times is useful. 41 * If this safeguard is problematic, please contact us via Mockito issue tracker. 42 * <p> 43 * For usage examples, see Mockito codebase. 44 * If you have ideas and feature requests about Mockito listeners API 45 * we are very happy to hear about it via our issue tracker or mailing list. 46 * 47 * <pre class="code"><code class="java"> 48 * Mockito.framework().addListener(myListener); 49 * </code></pre> 50 * 51 * @param listener to add to Mockito 52 * @return this instance of mockito framework (fluent builder pattern) 53 * @since 2.1.0 54 */ 55 @Incubating addListener(MockitoListener listener)56 MockitoFramework addListener(MockitoListener listener) throws RedundantListenerException; 57 58 /** 59 * When you add listener using {@link #addListener(MockitoListener)} make sure to remove it. 60 * Currently the listeners list is thread local so you need to remove listener from the same thread otherwise 61 * remove is ineffectual. 62 * In typical scenarios, it is not a problem, because adding & removing listeners typically happens in the same thread. 63 * <p> 64 * For usage examples, see Mockito codebase. 65 * If you have ideas and feature requests about Mockito listeners API 66 * we are very happy to hear about it via our issue tracker or mailing list. 67 * 68 * @param listener to remove 69 * @return this instance of mockito framework (fluent builder pattern) 70 * @since 2.1.0 71 */ 72 @Incubating removeListener(MockitoListener listener)73 MockitoFramework removeListener(MockitoListener listener); 74 75 /** 76 * Returns an object that has access to Mockito plugins. 77 * An example plugin is {@link org.mockito.plugins.MockMaker}. 78 * For information why and how to use this method see {@link MockitoPlugins}. 79 * 80 * @return object that gives access to mockito plugins 81 * @since 2.10.0 82 */ 83 @Incubating getPlugins()84 MockitoPlugins getPlugins(); 85 86 /** 87 * Returns a factory that can create instances of {@link Invocation}. 88 * It is useful for framework integrations, because {@link Invocation} is {@link NotExtensible}. 89 * 90 * @return object that can construct invocations 91 * @since 2.10.0 92 */ 93 @Incubating getInvocationFactory()94 InvocationFactory getInvocationFactory(); 95 96 /** 97 * Clears up internal state of all inline mocks. 98 * This method is only meaningful if inline mock maker is in use. 99 * Otherwise this method is a no-op and need not be used. 100 * <p> 101 * This method is useful to tackle subtle memory leaks that are possible due to the nature of inline mocking 102 * (issue <a href="https://github.com/mockito/mockito/pull/1619">#1619</a>). 103 * If you are facing those problems, call this method at the end of the test (or in "@After" method). 104 * See examples of using "clearInlineMocks" in Mockito test code. 105 * To find out why inline mock maker keeps track of the mock objects see {@link org.mockito.plugins.InlineMockMaker}. 106 * <p> 107 * Mockito's "inline mocking" enables mocking final types, enums and final methods 108 * (read more in section 39 of {@link Mockito} javadoc). 109 * This method is only meaningful when {@link org.mockito.plugins.InlineMockMaker} is in use. 110 * If you're using a different {@link org.mockito.plugins.MockMaker} then this method is a no-op. 111 * 112 * <pre class="code"><code class="java"> 113 * public class ExampleTest { 114 * 115 * @After 116 * public void clearMocks() { 117 * Mockito.framework().clearInlineMocks(); 118 * } 119 * 120 * @Test 121 * public void someTest() { 122 * ... 123 * } 124 * } 125 * </pre> 126 * 127 * If you have feedback or a better idea how to solve the problem please reach out. 128 * 129 * @since 2.25.0 130 * @see #clearInlineMock(Object) 131 */ 132 @Incubating clearInlineMocks()133 void clearInlineMocks(); 134 135 /** 136 * Clears up internal state of specific inline mock. 137 * This method is a single-mock variant of {@link #clearInlineMocks()}. 138 * Please read javadoc for {@link #clearInlineMocks()}. 139 * 140 * @param mock to clear up 141 * @since 2.25.0 142 * @see #clearInlineMocks() 143 */ 144 @Incubating clearInlineMock(Object mock)145 void clearInlineMock(Object mock); 146 } 147