0
# Verification
1

2
Comprehensive verification system with support for coroutines, custom verification modes, and order-dependent verification. Essential for validating mock interactions in Kotlin tests.
3

4
## Capabilities
5

6
### Basic Verification
7

8
Core verification functions for validating mock interactions.
9

10
```kotlin { .api }
11
/**
12
 * Verifies that certain behavior happened exactly once
13
 * @param mock The mock object to verify
14
 * @returns The mock object for method call verification
15
 */
16
fun <T> verify(mock: T): T
17

18
/**
19
 * Verifies behavior with a specific verification mode
20
 * @param mock The mock object to verify
21
 * @param mode Verification mode (times, atLeast, never, etc.)
22
 * @returns The mock object for method call verification
23
 */
24
fun <T> verify(mock: T, mode: VerificationMode): T
25
```
26

27
**Usage Examples:**
28

29
```kotlin
30
import com.nhaarman.mockitokotlin2.*
31

32
// Verify method was called once
33
verify(userService).findUser("john123")
34

35
// Verify method was called specific number of times
36
verify(userService, times(3)).findUser(any())
37

38
// Verify method was never called
39
verify(userService, never()).deleteUser(any())
40
```
41

42
### Coroutine Verification
43

44
Special verification functions for suspending functions and coroutines.
45

46
```kotlin { .api }
47
/**
48
 * Verifies certain suspending behavior happened exactly once
49
 * Warning: Only one method call can be verified in the function
50
 * @param mock The mock object to verify
51
 * @param f Suspending lambda containing the method call to verify
52
 */
53
fun <T> verifyBlocking(mock: T, f: suspend T.() -> Unit)
54

55
/**
56
 * Verifies suspending behavior with a specific verification mode
57
 * Warning: Only one method call can be verified in the function
58
 * @param mock The mock object to verify
59
 * @param mode Verification mode (times, atLeast, never, etc.)  
60
 * @param f Suspending lambda containing the method call to verify
61
 */
62
fun <T> verifyBlocking(mock: T, mode: VerificationMode, f: suspend T.() -> Unit)
63
```
64

65
**Usage Examples:**
66

67
```kotlin
68
import com.nhaarman.mockitokotlin2.*
69

70
// Verify suspending function was called once
71
verifyBlocking(asyncUserService) { 
72
    loadUserAsync("john123") 
73
}
74

75
// Verify suspending function with specific count
76
verifyBlocking(asyncUserService, times(2)) {
77
    refreshUserData(any())
78
}
79
```
80

81
### Verification Modes
82

83
Functions that create verification modes for controlling how verification is performed.
84

85
```kotlin { .api }
86
/**
87
 * Allows verifying exact number of invocations
88
 * @param numInvocations The exact number of expected invocations
89
 * @returns VerificationMode for exact count verification
90
 */
91
fun times(numInvocations: Int): VerificationMode
92

93
/**
94
 * Allows at-least-x verification
95
 * @param numInvocations The minimum number of expected invocations
96
 * @returns VerificationMode for minimum count verification
97
 */
98
fun atLeast(numInvocations: Int): VerificationMode
99

100
/**
101
 * Allows at-least-once verification
102
 * @returns VerificationMode for at-least-once verification
103
 */
104
fun atLeastOnce(): VerificationMode
105

106
/**
107
 * Allows at-most-x verification
108
 * @param maxNumberOfInvocations The maximum number of allowed invocations
109
 * @returns VerificationMode for maximum count verification
110
 */
111
fun atMost(maxNumberOfInvocations: Int): VerificationMode
112

113
/**
114
 * Allows non-greedy verification in order
115
 * @param wantedNumberOfInvocations The number of invocations to verify
116
 * @returns VerificationMode for ordered verification
117
 */
118
fun calls(wantedNumberOfInvocations: Int): VerificationMode
119

120
/**
121
 * Alias for times(0) - verifies method was never called
122
 * @returns VerificationMode for zero invocations
123
 */
124
fun never(): VerificationMode
125
```
126

127
**Usage Examples:**
128

129
```kotlin
130
import com.nhaarman.mockitokotlin2.*
131

132
// Verify exact number of calls
133
verify(userService, times(5)).findUser(any())
134

135
// Verify at least some calls
136
verify(userService, atLeast(1)).findUser(any())
137
verify(userService, atLeastOnce()).findUser(any())
138

139
// Verify at most some calls  
140
verify(userService, atMost(3)).deleteUser(any())
141

142
// Verify never called
143
verify(userService, never()).deleteAllUsers()
144
```
145

146
### Interaction Verification
147

148
Functions for verifying overall interaction patterns with mocks.
149

150
```kotlin { .api }
151
/**
152
 * Checks if any of given mocks has any unverified interaction
153
 * @param mocks The mock objects to check for unverified interactions
154
 */
155
fun <T> verifyNoMoreInteractions(vararg mocks: T)
156

157
/**
158
 * Verifies that no interactions happened on given mocks
159
 * @param mocks The mock objects to verify had zero interactions
160
 */
161
fun verifyZeroInteractions(vararg mocks: Any)
162

163
/**
164
 * Use this method to clear invocations when stubbing is non-trivial
165
 * @param mocks The mock objects to clear invocations from
166
 */
167
fun <T> clearInvocations(vararg mocks: T)
168
```
169

170
**Usage Examples:**
171

172
```kotlin
173
import com.nhaarman.mockitokotlin2.*
174

175
// After verifying specific calls, ensure no other interactions occurred
176
verify(userService).findUser("john123")
177
verify(userService).updateLastLogin(any())
178
verifyNoMoreInteractions(userService)
179

180
// Verify mock had no interactions at all
181
verifyZeroInteractions(unusedService)
182

183
// Clear previous interactions to start fresh verification
184
clearInvocations(userService)
185
```
186

187
### Order Verification
188

189
Functions for verifying the order of method invocations across multiple mocks.
190

191
```kotlin { .api }
192
/**
193
 * Creates InOrder object that allows verifying mocks in order
194
 * @param mocks The mock objects to verify in order
195
 * @returns InOrder instance for ordered verification
196
 */
197
fun inOrder(vararg mocks: Any): InOrder
198

199
/**
200
 * Creates InOrder object with immediate lambda evaluation
201
 * @param mocks The mock objects to verify in order
202
 * @param evaluation Lambda containing ordered verification calls
203
 */
204
inline fun inOrder(
205
    vararg mocks: Any,
206
    evaluation: InOrder.() -> Unit
207
)
208
```
209

210
**Usage Examples:**
211

212
```kotlin
213
import com.nhaarman.mockitokotlin2.*
214

215
// Verify calls happened in specific order
216
val inOrder = inOrder(userService, emailService)
217
inOrder.verify(userService).findUser("john123")
218
inOrder.verify(emailService).sendWelcomeEmail(any())
219
inOrder.verify(userService).updateLastLogin(any())
220

221
// Using lambda syntax
222
inOrder(userService, emailService) {
223
    verify(userService).findUser("john123")
224
    verify(emailService).sendWelcomeEmail(any())
225
}
226
```
227

228
### Single Mock Order Verification
229

230
Extension function for convenient order verification on single mocks.
231

232
```kotlin { .api }
233
/**
234
 * Allows InOrder verification for a single mocked instance
235
 * @param block Lambda containing verification calls in expected order
236
 */
237
inline fun <T> T.inOrder(block: InOrderOnType<T>.() -> Any)
238

239
/**
240
 * Helper class for single mock InOrder verification
241
 */
242
class InOrderOnType<T>(private val t: T) : InOrder by inOrder(t as Any) {
243
    /**
244
     * Creates verification proxy for the wrapped mock
245
     * @returns The mock object for method call verification
246
     */
247
    fun verify(): T
248
}
249
```
250

251
**Usage Examples:**
252

253
```kotlin
254
import com.nhaarman.mockitokotlin2.*
255

256
// Verify order of calls on single mock
257
userService.inOrder {
258
    verify().findUser("john123")
259
    verify().updateLastLogin(any())
260
    verify().saveUser(any())
261
}
262
```
263

264
### Enhanced Verification
265

266
Additional verification utilities and modes.
267

268
```kotlin { .api }
269
/**
270
 * Adds a description to be printed if verification fails
271
 * @param description Description text for failed verification
272
 * @returns VerificationMode with description
273
 */
274
fun description(description: String): VerificationMode
275

276
/**
277
 * Allows verifying over a given period - waits for desired interaction
278
 * @param millis Time period to wait in milliseconds
279
 * @returns VerificationAfterDelay for time-based verification
280
 */
281
fun after(millis: Long): VerificationAfterDelay
282

283
/**
284
 * Allows verifying with timeout - waits up to specified time
285
 * @param millis Timeout in milliseconds
286
 * @returns VerificationWithTimeout for timeout-based verification
287
 */
288
fun timeout(millis: Long): VerificationWithTimeout
289

290
/**
291
 * Ignores stubbed methods of given mocks for verification purposes
292
 * @param mocks The mock objects whose stubs should be ignored
293
 * @returns Array of mocks with stubs ignored
294
 */
295
fun ignoreStubs(vararg mocks: Any): Array<out Any>
296

297
/**
298
 * Verifies that given method was the only one invoked
299
 * @returns VerificationMode for exclusive invocation verification
300
 */
301
fun only(): VerificationMode
302
```
303

304
**Usage Examples:**
305

306
```kotlin
307
import com.nhaarman.mockitokotlin2.*
308

309
// Add description for better error messages
310
verify(userService, description("User service should find user"))
311
    .findUser("john123")
312

313
// Wait for interaction to happen (for concurrent testing)
314
verify(asyncService, timeout(5000)).processData(any())
315

316
// Verify after delay (useful for eventual consistency)
317
verify(eventHandler, after(1000)).handleEvent(any())
318

319
// Verify only this method was called
320
verify(userService, only()).findUser("john123")
321

322
// Ignore stubbed methods when verifying
323
val mocksIgnoringStubs = ignoreStubs(userService, emailService)
324
```
325

326
### Scoped Verification
327

328
DSL-style verification with enhanced readability using scope blocks.
329

330
```kotlin { .api }
331
/**
332
 * Verify multiple calls on mock using enhanced DSL syntax
333
 * @param mock The mock object to verify
334
 * @param block Lambda containing verification specifications
335
 */
336
inline fun <T> verify(mock: T, block: VerifyScope<T>.() -> Unit)
337

338
/**
339
 * Scope class for DSL-style verification
340
 */
341
class VerifyScope<out T>(val mock: T) {
342
    /**
343
     * Times operator for specifying call count in DSL
344
     * @param call Lambda containing the method call to verify
345
     */
346
    inline operator fun Int.times(call: T.() -> Unit)
347
}
348
```
349

350
**Usage Examples:**
351

352
```kotlin
353
import com.nhaarman.mockitokotlin2.*
354

355
// DSL-style verification with readable syntax
356
verify(userService) {
357
    1 * { findUser("john123") }
358
    2 * { updateLastLogin(any()) }
359
    3 * { saveUser(any()) }
360
}
361
```
362

363
### Verification Predicates
364

365
Custom verification predicates for complex argument validation.
366

367
```kotlin { .api }
368
/**
369
 * For usage with verification only. Performs actions to verify an argument
370
 * @param predicate A function that performs actions to verify an argument T
371
 * @returns Argument matcher that applies the predicate
372
 */
373
inline fun <reified T : Any> check(noinline predicate: (T) -> Unit): T
374
```
375

376
**Usage Examples:**
377

378
```kotlin
379
import com.nhaarman.mockitokotlin2.*
380
import org.junit.Assert.assertThat
381
import org.hamcrest.CoreMatchers.`is`
382

383
// Verify with custom predicate
384
verify(userService).processUser(check { user ->
385
    assertThat(user.email, `is`("john@example.com"))
386
    assertThat(user.age, `is`(25))
387
})
388

389
// Complex validation during verification
390
verify(orderService).createOrder(check { order ->
391
    assertThat(order.items.size, `is`(3))
392
    assertThat(order.total, `it`(greaterThan(100.0)))
393
})
394
```
395

396
## Types
397

398
```kotlin { .api }
399
// From org.mockito
400
interface VerificationMode
401
interface InOrder
402
class VerificationAfterDelay
403
class VerificationWithTimeout
404

405
// From mockito-kotlin
406
class InOrderOnType<T>(private val t: T) : InOrder {
407
    fun verify(): T
408
}
409

410
class VerifyScope<out T>(val mock: T) {
411
    inline operator fun Int.times(call: T.() -> Unit)
412
}
413
```