0
# Mockito JUnit Jupiter
1

2
Mockito JUnit Jupiter provides seamless integration between the Mockito mocking framework and JUnit 5 testing platform through the MockitoExtension. It enables automatic mock creation, injection, and cleanup in JUnit 5 test classes using annotations like @Mock, @Spy, and @InjectMocks.
3

4
## Package Information
5

6
- **Package Name**: mockito-junit-jupiter
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Maven Coordinates**: `org.mockito:mockito-junit-jupiter:4.11.0`
10
- **Installation**: Add to your Maven dependencies or Gradle build file
11

12
## Core Imports
13

14
```java
15
// Main classes from mockito-junit-jupiter
16
import org.mockito.junit.jupiter.MockitoExtension;
17
import org.mockito.junit.jupiter.MockitoSettings;
18

19
// JUnit 5 extension support
20
import org.junit.jupiter.api.extension.ExtendWith;
21
import org.junit.jupiter.api.extension.ParameterResolutionException;
22

23
// Standard Mockito annotations
24
import org.mockito.Mock;
25
import org.mockito.Spy;
26
import org.mockito.InjectMocks;
27

28
// Strictness configuration
29
import org.mockito.quality.Strictness;
30
```
31

32
## Basic Usage
33

34
```java
35
import org.junit.jupiter.api.Test;
36
import org.junit.jupiter.api.extension.ExtendWith;
37
import org.mockito.Mock;
38
import org.mockito.junit.jupiter.MockitoExtension;
39
import java.util.List;
40

41
@ExtendWith(MockitoExtension.class)
42
public class ExampleTest {
43

44
    @Mock
45
    private List<String> mockList;
46

47
    @Test
48
    void testMockCreation() {
49
        // Mock is automatically initialized by MockitoExtension
50
        mockList.add("test");
51
        // Verify or stub the mock as needed
52
    }
53
}
54
```
55

56
## Architecture
57

58
Mockito JUnit Jupiter is built around the JUnit 5 extension model:
59

60
- **MockitoExtension**: Core extension that handles mock lifecycle and parameter injection
61
- **MockitoSettings**: Configuration annotation for customizing mock behavior
62
- **JUnit 5 Integration**: Uses BeforeEachCallback, AfterEachCallback, and ParameterResolver
63
- **Mock Lifecycle**: Automatic initialization before each test and cleanup after each test
64
- **Parameter Resolution**: Support for injecting mocks into test method and constructor parameters
65

66
## Capabilities
67

68
### Extension Setup
69

70
The MockitoExtension integrates Mockito with JUnit 5's extension model to provide automatic mock management.
71

72
```java { .api }
73
/**
74
 * Extension that initializes mocks and handles strict stubbings.
75
 * This extension is the JUnit Jupiter equivalent of MockitoJUnitRunner.
76
 */
77
public class MockitoExtension implements BeforeEachCallback, AfterEachCallback, ParameterResolver {
78
    
79
    /**
80
     * Default constructor invoked by JUnit Jupiter via reflection or ServiceLoader
81
     */
82
    public MockitoExtension();
83
    
84
    /**
85
     * Callback invoked before each test is invoked
86
     * @param context the current extension context; never null
87
     */
88
    public void beforeEach(final ExtensionContext context);
89
    
90
    /**
91
     * Callback invoked after each test has been invoked
92
     * @param context the current extension context; never null
93
     */
94
    public void afterEach(ExtensionContext context);
95
    
96
    /**
97
     * Determine if this resolver supports resolution of an argument for the Parameter
98
     * @param parameterContext the context for the parameter for which an argument should be resolved
99
     * @param context the extension context for the test method about to be invoked
100
     * @return true if parameter is annotated with @Mock
101
     */
102
    public boolean supportsParameter(ParameterContext parameterContext, ExtensionContext context) throws ParameterResolutionException;
103
    
104
    /**
105
     * Resolve an argument for the Parameter in the supplied ParameterContext
106
     * @param parameterContext the context for the parameter for which an argument should be resolved
107
     * @param context the extension context for the test method about to be invoked
108
     * @return the resolved argument for the parameter
109
     */
110
    public Object resolveParameter(ParameterContext parameterContext, ExtensionContext context) throws ParameterResolutionException;
111
}
112
```
113

114
**Usage Examples:**
115

116
```java
117
// Basic extension usage
118
@ExtendWith(MockitoExtension.class)
119
public class MyTest {
120
    @Mock private Service service;
121
    
122
    @Test
123
    void testMethod() {
124
        // service mock is automatically initialized
125
    }
126
}
127

128
// Method parameter injection
129
@ExtendWith(MockitoExtension.class)
130
public class MyTest {
131
    @Test
132
    void testWithParameter(@Mock Repository repository) {
133
        // repository mock is injected as method parameter
134
    }
135
}
136

137
// Constructor parameter injection
138
@ExtendWith(MockitoExtension.class)
139
public class MyTest {
140
    private final Database database;
141
    
142
    MyTest(@Mock Database database) {
143
        this.database = database;
144
    }
145
    
146
    @Test
147
    void testMethod() {
148
        // database mock is available as instance field
149
    }
150
}
151
```
152

153
### Mock Configuration
154

155
The MockitoSettings annotation allows configuration of mock behavior when used with MockitoExtension.
156

157
```java { .api }
158
/**
159
 * Annotation that can configure Mockito as invoked by the MockitoExtension.
160
 * Automatically applies @ExtendWith(MockitoExtension.class).
161
 */
162
@ExtendWith(MockitoExtension.class)
163
@Inherited
164
@Retention(RUNTIME)
165
public @interface MockitoSettings {
166
    
167
    /**
168
     * Configure the strictness used in this test.
169
     * @return The strictness to configure, by default Strictness.STRICT_STUBS
170
     */
171
    Strictness strictness() default Strictness.STRICT_STUBS;
172
}
173
```
174

175
**Usage Examples:**
176

177
```java
178
// Default strictness (STRICT_STUBS)
179
@MockitoSettings
180
public class StrictTest {
181
    @Mock private Service service;
182
    
183
    @Test
184
    void testMethod() {
185
        // Runs with strict stub validation
186
    }
187
}
188

189
// Custom strictness configuration
190
@MockitoSettings(strictness = Strictness.LENIENT)
191
public class LenientTest {
192
    @Mock private Service service;
193
    
194
    @Test
195
    void testMethod() {
196
        // Runs with lenient stub validation
197
    }
198
}
199

200
// Inherited by nested classes
201
@MockitoSettings(strictness = Strictness.WARN)
202
public class ParentTest {
203
    @Nested
204
    class NestedTest {
205
        @Mock private Service service;
206
        
207
        @Test
208
        void testMethod() {
209
            // Inherits WARN strictness from parent
210
        }
211
    }
212
}
213
```
214

215
## Types
216

217
```java { .api }
218
/**
219
 * JUnit 5 extension context namespace for Mockito state storage
220
 */
221
interface ExtensionContext {
222
    // Standard JUnit 5 ExtensionContext interface
223
}
224

225
/**
226
 * JUnit 5 parameter context for parameter resolution
227
 */
228
interface ParameterContext {
229
    // Standard JUnit 5 ParameterContext interface
230
}
231

232
/**
233
 * Exception thrown when parameter resolution fails
234
 */
235
class ParameterResolutionException extends RuntimeException {
236
    // Standard JUnit 5 ParameterResolutionException
237
}
238

239
/**
240
 * Mockito strictness levels for stub validation
241
 */
242
enum Strictness {
243
    STRICT_STUBS,  // Default - validates all stubs are used
244
    LENIENT,       // Allows unused stubs
245
    WARN          // Warns about unused stubs
246
}
247

248
/**
249
 * Mockito session for managing mock lifecycle
250
 */
251
interface MockitoSession {
252
    // Internal Mockito session management
253
}
254

255
/**
256
 * Scoped mock for automatic cleanup
257
 */
258
interface ScopedMock {
259
    // Internal Mockito scoped mock management
260
}
261
```
262

263
## Integration with Standard Mockito Annotations
264

265
The extension works seamlessly with standard Mockito annotations:
266

267
- **@Mock**: Creates a mock instance
268
- **@Spy**: Creates a spy instance (partial mock)
269
- **@InjectMocks**: Injects mocks into the annotated instance
270
- **@Captor**: Creates an ArgumentCaptor instance
271

272
## Error Handling
273

274
The extension handles various error scenarios:
275

276
- **ParameterResolutionException**: Thrown when parameter resolution fails for unsupported parameters
277
- **Mock Creation Failures**: Handled through Mockito's standard error reporting
278
- **Session Management**: Automatic cleanup ensures proper mock lifecycle management
279
- **Strictness Violations**: Configured strictness level determines how unused stubs are handled
280

281
## Nested Test Support
282

283
The extension fully supports JUnit 5 nested test classes:
284

285
- Mocks from parent test classes are available in nested classes
286
- Nested classes can define additional mocks
287
- Settings inheritance follows JUnit 5 semantics
288
- Duplicate extension registration is automatically handled