0
# Mockito-Kotlin
1
2
Mockito-Kotlin is a small library that provides helper functions to work with Mockito in Kotlin. It offers Kotlin-friendly APIs, extension functions, and DSL syntax that address Kotlin's null safety and type inference limitations when using the Java-based Mockito framework. The library enables more idiomatic and concise test code in Kotlin projects.
3
4
## Package Information
5
6
- **Package Name**: mockito-kotlin
7
- **Package Type**: maven
8
- **Language**: Kotlin
9
- **Installation**: Add to your `build.gradle`: `testImplementation "com.nhaarman.mockitokotlin2:mockito-kotlin:2.2.0"`
10
11
## Core Imports
12
13
```kotlin
14
import com.nhaarman.mockitokotlin2.*
15
```
16
17
Or selective imports:
18
19
```kotlin
20
import com.nhaarman.mockitokotlin2.mock
21
import com.nhaarman.mockitokotlin2.verify
22
import com.nhaarman.mockitokotlin2.whenever
23
import com.nhaarman.mockitokotlin2.any
24
```
25
26
## Basic Usage
27
28
```kotlin
29
import com.nhaarman.mockitokotlin2.*
30
31
@Test
32
fun doAction_doesSomething() {
33
// Given - Create mock with immediate stubbing
34
val mock = mock<MyClass> {
35
on { getText() } doReturn "text"
36
}
37
val classUnderTest = ClassUnderTest(mock)
38
39
// When
40
classUnderTest.doAction()
41
42
// Then
43
verify(mock).doSomething(any())
44
}
45
```
46
47
## Architecture
48
49
Mockito-Kotlin is organized around several key areas:
50
51
- **Mock Creation**: Type-safe mock creation with optional immediate stubbing
52
- **Argument Matching**: Kotlin-friendly argument matchers with reified generics
53
- **Verification**: Mockito verification with Kotlin extensions and coroutine support
54
- **Stubbing**: Fluent stubbing API with Kotlin DSL and lambda support
55
- **Spying**: Spy creation with type safety and immediate stubbing options
56
- **BDD Support**: Behavior-driven development style functions
57
58
## Capabilities
59
60
### Mock Creation
61
62
Type-safe mock creation with extensive configuration options and immediate stubbing support. Essential for setting up test doubles in Kotlin.
63
64
```kotlin { .api }
65
inline fun <reified T : Any> mock(
66
extraInterfaces: Array<out KClass<out Any>>? = null,
67
name: String? = null,
68
spiedInstance: Any? = null,
69
defaultAnswer: Answer<Any>? = null,
70
serializable: Boolean = false,
71
serializableMode: SerializableMode? = null,
72
verboseLogging: Boolean = false,
73
invocationListeners: Array<InvocationListener>? = null,
74
stubOnly: Boolean = false,
75
useConstructor: UseConstructor? = null,
76
outerInstance: Any? = null,
77
lenient: Boolean = false
78
): T
79
80
inline fun <reified T : Any> mock(
81
extraInterfaces: Array<out KClass<out Any>>? = null,
82
name: String? = null,
83
spiedInstance: Any? = null,
84
defaultAnswer: Answer<Any>? = null,
85
serializable: Boolean = false,
86
serializableMode: SerializableMode? = null,
87
verboseLogging: Boolean = false,
88
invocationListeners: Array<InvocationListener>? = null,
89
stubOnly: Boolean = false,
90
useConstructor: UseConstructor? = null,
91
outerInstance: Any? = null,
92
lenient: Boolean = false,
93
stubbing: KStubbing<T>.(T) -> Unit
94
): T
95
```
96
97
[Mock Creation](./mock-creation.md)
98
99
### Argument Matching
100
101
Powerful argument matchers designed for Kotlin's type system, providing type-safe matching with reified generics and null safety.
102
103
```kotlin { .api }
104
inline fun <reified T : Any> any(): T
105
inline fun <reified T : Any> anyOrNull(): T
106
inline fun <reified T : Any> anyVararg(): T
107
inline fun <reified T : Any?> anyArray(): Array<T>
108
inline fun <reified T : Any> argThat(noinline predicate: T.() -> Boolean): T
109
inline fun <reified T : Any> argThat(matcher: ArgumentMatcher<T>): T
110
inline fun <reified T : Any> argForWhich(noinline predicate: T.() -> Boolean): T
111
inline fun <reified T : Any> argWhere(noinline predicate: (T) -> Boolean): T
112
fun <T> eq(value: T): T
113
fun <T> same(value: T): T
114
inline fun <reified T : Any> isA(): T
115
fun <T : Any> isNull(): T?
116
fun <T : Any> isNotNull(): T?
117
fun <T : Any> notNull(): T?
118
inline fun <reified T : Any> refEq(value: T, vararg excludeFields: String): T
119
inline fun <reified T : Any> check(noinline predicate: (T) -> Unit): T
120
```
121
122
[Argument Matching](./argument-matching.md)
123
124
### Verification
125
126
Comprehensive verification system with support for coroutines, custom verification modes, and order-dependent verification.
127
128
```kotlin { .api }
129
fun <T> verify(mock: T): T
130
fun <T> verify(mock: T, mode: VerificationMode): T
131
fun <T> verifyBlocking(mock: T, f: suspend T.() -> Unit)
132
fun <T> verifyBlocking(mock: T, mode: VerificationMode, f: suspend T.() -> Unit)
133
fun <T> verifyNoMoreInteractions(vararg mocks: T)
134
fun verifyZeroInteractions(vararg mocks: Any)
135
fun <T> clearInvocations(vararg mocks: T)
136
fun times(numInvocations: Int): VerificationMode
137
fun atLeast(numInvocations: Int): VerificationMode
138
fun atLeastOnce(): VerificationMode
139
fun atMost(maxNumberOfInvocations: Int): VerificationMode
140
fun calls(wantedNumberOfInvocations: Int): VerificationMode
141
fun never(): VerificationMode
142
fun description(description: String): VerificationMode
143
fun after(millis: Long): VerificationAfterDelay
144
fun timeout(millis: Long): VerificationWithTimeout
145
fun ignoreStubs(vararg mocks: Any): Array<out Any>
146
fun only(): VerificationMode
147
fun inOrder(vararg mocks: Any): InOrder
148
inline fun inOrder(vararg mocks: Any, evaluation: InOrder.() -> Unit)
149
inline fun <T> T.inOrder(block: InOrderOnType<T>.() -> Any)
150
inline fun <T> verify(mock: T, block: VerifyScope<T>.() -> Unit)
151
```
152
153
[Verification](./verification.md)
154
155
### Stubbing
156
157
Fluent stubbing API with Kotlin DSL support, lambda-based configuration, and comprehensive response configuration.
158
159
```kotlin { .api }
160
inline fun <T> whenever(methodCall: T): OngoingStubbing<T>
161
infix fun <T> OngoingStubbing<T>.doReturn(t: T): OngoingStubbing<T>
162
infix fun <T> OngoingStubbing<T>.doThrow(t: Throwable): OngoingStubbing<T>
163
infix fun <T> OngoingStubbing<T>.doAnswer(answer: (InvocationOnMock) -> T?): OngoingStubbing<T>
164
165
class KStubbing<out T>(val mock: T) {
166
fun <R> on(methodCall: R): OngoingStubbing<R>
167
inline fun <reified R : Any> onGeneric(noinline methodCall: T.() -> R?): OngoingStubbing<R>
168
fun <T : Any, R> onBlocking(m: suspend T.() -> R): OngoingStubbing<R>
169
}
170
```
171
172
[Stubbing](./stubbing.md)
173
174
### Argument Capturing
175
176
Type-safe argument capturing with Kotlin-friendly APIs and support for multiple argument capture patterns.
177
178
```kotlin { .api }
179
inline fun <reified T : Any> argumentCaptor(): KArgumentCaptor<T>
180
inline fun <reified T : Any> capture(captor: ArgumentCaptor<T>): T
181
182
class KArgumentCaptor<out T : Any?>(
183
private val captor: ArgumentCaptor<T>,
184
private val tClass: KClass<*>
185
) {
186
val firstValue: T
187
val lastValue: T
188
val allValues: List<T>
189
fun capture(): T
190
}
191
```
192
193
[Argument Capturing](./argument-capturing.md)
194
195
### Spying
196
197
Spy creation with type safety and immediate stubbing options for testing real objects with selective method stubbing.
198
199
```kotlin { .api }
200
inline fun <reified T : Any> spy(): T
201
inline fun <reified T : Any> spy(stubbing: KStubbing<T>.(T) -> Unit): T
202
fun <T> spy(value: T): T
203
inline fun <reified T> spy(value: T, stubbing: KStubbing<T>.(T) -> Unit): T
204
```
205
206
[Spying](./spying.md)
207
208
### Stubber Functions
209
210
Flexible stubbing configuration functions for advanced mock behavior setup.
211
212
```kotlin { .api }
213
fun <T> doAnswer(answer: (InvocationOnMock) -> T?): Stubber
214
fun doCallRealMethod(): Stubber
215
fun doNothing(): Stubber
216
fun doReturn(value: Any?): Stubber
217
fun doReturn(toBeReturned: Any?, vararg toBeReturnedNext: Any?): Stubber
218
fun doThrow(toBeThrown: KClass<out Throwable>): Stubber
219
fun doThrow(vararg toBeThrown: Throwable): Stubber
220
fun <T> Stubber.whenever(mock: T): OngoingStubbing<T>
221
```
222
223
### BDD Support
224
225
Behavior-driven development style functions providing Given-When-Then syntax for more expressive tests.
226
227
```kotlin { .api }
228
fun <T> given(methodCall: T): BDDMyOngoingStubbing<T>
229
fun <T> given(methodCall: () -> T): BDDMyOngoingStubbing<T>
230
fun <T> then(mock: T): BDDMockito.Then<T>
231
infix fun <T> BDDMyOngoingStubbing<T>.will(value: Answer<T>): BDDMyOngoingStubbing<T>
232
infix fun <T> BDDMyOngoingStubbing<T>.willAnswer(value: (InvocationOnMock) -> T?): BDDMyOngoingStubbing<T>
233
infix fun <T> BDDMyOngoingStubbing<T>.willReturn(value: () -> T): BDDMyOngoingStubbing<T>
234
infix fun <T> BDDMyOngoingStubbing<T>.willThrow(value: () -> Throwable): BDDMyOngoingStubbing<T>
235
```
236
237
### Core Utilities
238
239
Essential Mockito utility functions for mock management and validation.
240
241
```kotlin { .api }
242
fun validateMockitoUsage()
243
fun <T> reset(vararg mocks: T)
244
fun mockingDetails(toInspect: Any): MockingDetails
245
```
246
247
## Types
248
249
```kotlin { .api }
250
// Mockito-Kotlin specific types
251
class UseConstructor private constructor(val args: Array<Any>) {
252
companion object {
253
fun parameterless(): UseConstructor
254
fun withArguments(vararg arguments: Any): UseConstructor
255
}
256
}
257
258
class MockitoKotlinException(message: String?, cause: Throwable?) : RuntimeException(message, cause)
259
260
class VerifyScope<out T>(val mock: T) {
261
inline operator fun Int.times(call: T.() -> Unit)
262
}
263
264
class KStubbing<out T>(val mock: T) {
265
fun <R> on(methodCall: R): OngoingStubbing<R>
266
fun <R : Any> onGeneric(methodCall: T.() -> R?, c: KClass<R>): OngoingStubbing<R>
267
inline fun <reified R : Any> onGeneric(noinline methodCall: T.() -> R?): OngoingStubbing<R>
268
fun <R> on(methodCall: T.() -> R): OngoingStubbing<R>
269
fun <T : Any, R> onBlocking(m: suspend T.() -> R): OngoingStubbing<R>
270
}
271
272
class KArgumentCaptor<out T : Any?>(
273
private val captor: ArgumentCaptor<T>,
274
private val tClass: KClass<*>
275
) {
276
val firstValue: T
277
val secondValue: T
278
val thirdValue: T
279
val lastValue: T
280
val allValues: List<T>
281
fun capture(): T
282
}
283
284
// Imported Mockito types
285
typealias Answer<T> = org.mockito.stubbing.Answer<T>
286
typealias ArgumentCaptor<T> = org.mockito.ArgumentCaptor<T>
287
typealias ArgumentMatcher<T> = org.mockito.ArgumentMatcher<T>
288
typealias BDDMyOngoingStubbing<T> = org.mockito.BDDMockito.BDDMyOngoingStubbing<T>
289
typealias InOrder = org.mockito.InOrder
290
typealias InvocationListener = org.mockito.listeners.InvocationListener
291
typealias InvocationOnMock = org.mockito.invocation.InvocationOnMock
292
typealias MockSettings = org.mockito.MockSettings
293
typealias MockingDetails = org.mockito.MockingDetails
294
typealias OngoingStubbing<T> = org.mockito.stubbing.OngoingStubbing<T>
295
typealias SerializableMode = org.mockito.mock.SerializableMode
296
typealias Stubber = org.mockito.stubbing.Stubber
297
typealias VerificationAfterDelay = org.mockito.verification.VerificationAfterDelay
298
typealias VerificationMode = org.mockito.verification.VerificationMode
299
typealias VerificationWithTimeout = org.mockito.verification.VerificationWithTimeout
300
```