forked from mockito/mockito
/
MockitoFramework.java
105 lines (98 loc) · 4.34 KB
/
MockitoFramework.java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
/*
* Copyright (c) 2016 Mockito contributors
* This program is made available under the terms of the MIT License.
*/
package org.mockito;
import org.mockito.exceptions.misusing.RedundantListenerException;
import org.mockito.invocation.Invocation;
import org.mockito.invocation.InvocationFactory;
import org.mockito.listeners.MockitoListener;
import org.mockito.plugins.MockitoPlugins;
/**
* Mockito framework settings and lifecycle listeners, for advanced users or for integrating with other frameworks.
* <p>
* To get <code>MockitoFramework</code> instance use {@link Mockito#framework()}.
* <p>
* For more info on listeners see {@link #addListener(MockitoListener)}.
*
* @since 2.1.0
*/
@Incubating
public interface MockitoFramework {
/**
* Adds listener to Mockito.
* For a list of supported listeners, see the interfaces that extend {@link MockitoListener}.
* <p>
* Listeners can be useful for engs that extend Mockito framework.
* They are used in the implementation of unused stubbings warnings ({@link org.mockito.quality.MockitoHint}).
* <p>
* Make sure you remove the listener when the job is complete, see {@link #removeListener(MockitoListener)}.
* Currently the listeners list is thread local so you need to remove listener from the same thread otherwise
* remove is ineffectual.
* In typical scenarios, it is not a problem, because adding & removing listeners typically happens in the same thread.
* <p>
* If you are trying to add the listener but a listener of the same type was already added (and not removed)
* this method will throw {@link RedundantListenerException}.
* This is a safeguard to ensure users actually remove the listeners via {@link #removeListener(MockitoListener)}.
* We do not anticipate the use case where adding the same listener type multiple times is useful.
* If this safeguard is problematic, please contact us via Mockito issue tracker.
* <p>
* For usage examples, see Mockito codebase.
* If you have ideas and feature requests about Mockito listeners API
* we are very happy to hear about it via our issue tracker or mailing list.
*
* <pre class="code"><code class="java">
* Mockito.framework().addListener(myListener);
* </code></pre>
*
* @param listener to add to Mockito
* @return this instance of mockito framework (fluent builder pattern)
* @since 2.1.0
*/
@Incubating
MockitoFramework addListener(MockitoListener listener) throws RedundantListenerException;
/**
* When you add listener using {@link #addListener(MockitoListener)} make sure to remove it.
* Currently the listeners list is thread local so you need to remove listener from the same thread otherwise
* remove is ineffectual.
* In typical scenarios, it is not a problem, because adding & removing listeners typically happens in the same thread.
* <p>
* For usage examples, see Mockito codebase.
* If you have ideas and feature requests about Mockito listeners API
* we are very happy to hear about it via our issue tracker or mailing list.
*
* @param listener to remove
* @return this instance of mockito framework (fluent builder pattern)
* @since 2.1.0
*/
@Incubating
MockitoFramework removeListener(MockitoListener listener);
/**
* Returns an object that has access to Mockito plugins.
* An example plugin is {@link org.mockito.plugins.MockMaker}.
* For information why and how to use this method see {@link MockitoPlugins}.
*
* @return object that gives access to mockito plugins
* @since 2.10.0
*/
@Incubating
MockitoPlugins getPlugins();
/**
* Returns a factory that can create instances of {@link Invocation}.
* It is useful for framework integrations, because {@link Invocation} is {@link NotExtensible}.
*
* @return object that can construct invocations
* @since 2.10.0
*/
@Incubating
InvocationFactory getInvocationFactory();
/**
* Clears up all existing mocks. This is useful when testing with {@link org.mockito.plugins.InlineMockMaker} which
* may hold references to mocks and leak memory. No interaction to any mock created previously is not allowed after
* calling this method.
*
* @since 2.24.8
*/
@Incubating
void clearAllMocks();
}