0
# Verification
1

2
Comprehensive call verification system with support for call ordering, counting, timeouts, and complex verification patterns to ensure mocks are used as expected.
3

4
## Capabilities
5

6
### Basic Verification
7

8
Core verification functions for confirming mock interactions.
9

10
```kotlin { .api }
11
/**
12
 * Verifies that calls were made in the past
13
 * @param ordering How the verification should be ordered (default: UNORDERED)
14
 * @param inverse When true, verifies that calls did NOT happen
15
 * @param atLeast Minimum number of times the call should have occurred
16
 * @param atMost Maximum number of times the call should have occurred
17
 * @param exactly Exact number of times (-1 to disable)
18
 * @param timeout Timeout in milliseconds for verification
19
 * @param verifyBlock Block containing calls to verify
20
 */
21
fun verify(
22
    ordering: Ordering = Ordering.UNORDERED,
23
    inverse: Boolean = false,
24
    atLeast: Int = 1,
25
    atMost: Int = Int.MAX_VALUE,
26
    exactly: Int = -1,
27
    timeout: Long = 0,
28
    verifyBlock: MockKVerificationScope.() -> Unit
29
)
30

31
/**
32
 * Coroutine version of verify for suspend functions
33
 */
34
fun coVerify(
35
    ordering: Ordering = Ordering.UNORDERED,
36
    inverse: Boolean = false,
37
    atLeast: Int = 1,
38
    atMost: Int = Int.MAX_VALUE,
39
    exactly: Int = -1,
40
    timeout: Long = 0,
41
    verifyBlock: suspend MockKVerificationScope.() -> Unit
42
)
43
```
44

45
**Usage Examples:**
46

47
```kotlin
48
val userService = mockk<UserService>(relaxed = true)
49

50
// Call the mock
51
userService.getUserById("123")
52
userService.saveUser(User("123", "John"))
53

54
// Basic verification
55
verify { userService.getUserById("123") }
56
verify { userService.saveUser(any()) }
57

58
// Verify with call count
59
verify(exactly = 1) { userService.getUserById("123") }
60
verify(atLeast = 1) { userService.saveUser(any()) }
61
verify(atMost = 2) { userService.getUserById(any()) }
62

63
// Verify coroutine calls
64
coVerify { userService.getUserByIdAsync("123") }
65
```
66

67
### Verification Variants
68

69
Specialized verification functions for different scenarios.
70

71
```kotlin { .api }
72
/**
73
 * Verifies all specified calls happened (no specific order required)
74
 * @param inverse When true, verifies calls did NOT happen
75
 * @param verifyBlock Block containing all calls that should be verified
76
 */
77
fun verifyAll(
78
    inverse: Boolean = false,
79
    verifyBlock: MockKVerificationScope.() -> Unit
80
)
81

82
/**
83
 * Verifies calls happened in the declared order
84
 * @param inverse When true, verifies calls did NOT happen in order
85
 * @param verifyBlock Block containing calls in expected order
86
 */
87
fun verifyOrder(
88
    inverse: Boolean = false,
89
    verifyBlock: MockKVerificationScope.() -> Unit
90
)
91

92
/**
93
 * Verifies calls happened in exact sequence with no other calls
94
 * @param inverse When true, verifies sequence did NOT happen
95
 * @param verifyBlock Block containing exact call sequence
96
 */
97
fun verifySequence(
98
    inverse: Boolean = false,
99
    verifyBlock: MockKVerificationScope.() -> Unit
100
)
101

102
/**
103
 * Verifies specific call counts and patterns
104
 * @param verifyBlock Block for count-based verification
105
 */
106
fun verifyCount(verifyBlock: MockKCallCountVerificationScope.() -> Unit)
107
```
108

109
**Usage Examples:**
110

111
```kotlin
112
val userService = mockk<UserService>(relaxed = true)
113

114
// Make some calls
115
userService.getUserById("123")
116
userService.saveUser(User("123", "John"))
117
userService.deleteUser("456")
118

119
// Verify all calls happened (any order)
120
verifyAll {
121
    userService.getUserById("123")
122
    userService.saveUser(any())
123
    userService.deleteUser("456")
124
}
125

126
// Verify calls happened in specific order
127
verifyOrder {
128
    userService.getUserById("123")
129
    userService.saveUser(any())
130
    userService.deleteUser("456")
131
}
132

133
// Verify exact sequence (no other calls allowed)
134
verifySequence {
135
    userService.getUserById("123")
136
    userService.saveUser(any())
137
    userService.deleteUser("456")
138
}
139

140
// Count-based verification
141
verifyCount {
142
    verify(exactly = 1) { userService.getUserById("123") }
143
    verify(exactly = 1) { userService.saveUser(any()) }
144
}
145
```
146

147
### Coroutine Verification
148

149
Verification functions specifically for suspend functions.
150

151
```kotlin { .api }
152
/**
153
 * Coroutine versions of verification functions
154
 */
155
fun coVerifyAll(
156
    inverse: Boolean = false,
157
    verifyBlock: suspend MockKVerificationScope.() -> Unit
158
)
159

160
fun coVerifyOrder(
161
    inverse: Boolean = false,
162
    verifyBlock: suspend MockKVerificationScope.() -> Unit
163
)
164

165
fun coVerifySequence(
166
    inverse: Boolean = false,
167
    verifyBlock: suspend MockKVerificationScope.() -> Unit
168
)
169

170
fun coVerifyCount(verifyBlock: MockKCallCountCoVerificationScope.() -> Unit)
171
```
172

173
**Usage Examples:**
174

175
```kotlin
176
val userService = mockk<UserService>()
177

178
// Stub suspend functions
179
coEvery { userService.getUserByIdAsync("123") } returns User("123", "John")
180
coJustRun { userService.saveUserAsync(any()) }
181

182
// Call suspend functions
183
runBlocking {
184
    userService.getUserByIdAsync("123")
185
    userService.saveUserAsync(User("123", "John"))
186
}
187

188
// Verify suspend function calls
189
coVerifyAll {
190
    userService.getUserByIdAsync("123")
191
    userService.saveUserAsync(any())
192
}
193

194
coVerifyOrder {
195
    userService.getUserByIdAsync("123")
196
    userService.saveUserAsync(any())
197
}
198
```
199

200
### Timeout Verification
201

202
Verification with timeout support for concurrent scenarios.
203

204
```kotlin { .api }
205
/**
206
 * Verification with timeout - waits until verification passes or timeout
207
 * @param timeout Timeout in milliseconds
208
 */
209
fun verify(timeout: Long, verifyBlock: MockKVerificationScope.() -> Unit)
210
```
211

212
**Usage Examples:**
213

214
```kotlin
215
val userService = mockk<UserService>(relaxed = true)
216

217
// Start async operation that will call the mock
218
thread {
219
    Thread.sleep(500)
220
    userService.saveUser(User("123", "John"))
221
}
222

223
// Verify with timeout (waits up to 1000ms)
224
verify(timeout = 1000) { userService.saveUser(any()) }
225
```
226

227
### Inverse Verification
228

229
Verifying that calls did NOT happen.
230

231
```kotlin { .api }
232
/**
233
 * Verify calls did NOT happen using inverse parameter
234
 */
235
fun verify(inverse: Boolean = true, verifyBlock: MockKVerificationScope.() -> Unit)
236
```
237

238
**Usage Examples:**
239

240
```kotlin
241
val userService = mockk<UserService>(relaxed = true)
242

243
userService.getUserById("123")
244
// Don't call deleteUser
245

246
// Verify call happened
247
verify { userService.getUserById("123") }
248

249
// Verify call did NOT happen
250
verify(inverse = true) { userService.deleteUser(any()) }
251
```
252

253
### Was Not Called Verification
254

255
Specialized verification for confirming no calls were made.
256

257
```kotlin { .api }
258
/**
259
 * Verifies that a mock was not called at all
260
 */
261
val MockKVerificationScope.wasNot: WasNotCalled
262
object Called
263
infix fun WasNotCalled.called(called: Called)
264
```
265

266
**Usage Examples:**
267

268
```kotlin
269
val userService = mockk<UserService>()
270

271
// Don't call the mock
272

273
// Verify no calls were made
274
verify { userService wasNot Called }
275
```
276

277
### Argument Verification
278

279
Verifying and asserting on captured arguments.
280

281
```kotlin { .api }
282
abstract class MockKVerificationScope : MockKMatcherScope {
283
    /**
284
     * Verify argument with custom assertion
285
     * @param captureBlock Block for asserting on the captured argument
286
     */
287
    fun <T> withArg(captureBlock: MockKAssertScope.(T) -> Unit): T
288
    
289
    fun <T> withNullableArg(captureBlock: MockKAssertScope.(T?) -> Unit): T?
290
    
291
    fun <T> coWithArg(captureBlock: suspend MockKAssertScope.(T) -> Unit): T
292
    
293
    fun <T> coWithNullableArg(captureBlock: suspend MockKAssertScope.(T?) -> Unit): T?
294
}
295

296
abstract class MockKAssertScope {
297
    /**
298
     * Assert equality with automatic message generation
299
     */
300
    fun checkEquals(expected: Any?)
301
    
302
    /**
303
     * Assert equality with custom message
304
     */
305
    fun checkEquals(msg: String, expected: Any?)
306
}
307
```
308

309
**Usage Examples:**
310

311
```kotlin
312
val userService = mockk<UserService>(relaxed = true)
313

314
// Call with specific user
315
userService.saveUser(User("123", "John Doe"))
316

317
// Verify with argument assertion
318
verify {
319
    userService.saveUser(
320
        withArg { user ->
321
            checkEquals("123", user.id)
322
            checkEquals("User name should be John Doe", "John Doe", user.name)
323
        }
324
    )
325
}
326

327
// Nullable argument verification
328
verify {
329
    userService.processNullableUser(
330
        withNullableArg { user ->
331
            if (user != null) {
332
                checkEquals("123", user.id)
333
            }
334
        }
335
    )
336
}
337
```
338

339
### Verification Utilities
340

341
Additional utilities for comprehensive verification.
342

343
```kotlin { .api }
344
/**
345
 * Confirms that all recorded calls have been verified
346
 * @param mocks Mocks to check for unverified calls
347
 */
348
fun confirmVerified(vararg mocks: Any)
349

350
/**
351
 * Checks if all recorded calls are necessary (not over-stubbed)
352
 * @param mocks Mocks to check for unnecessary stubs
353
 */
354
fun checkUnnecessaryStub(vararg mocks: Any)
355
```
356

357
**Usage Examples:**
358

359
```kotlin
360
val userService = mockk<UserService>()
361
val orderService = mockk<OrderService>()
362

363
// Stub and call mocks
364
every { userService.getUserById("123") } returns User("123", "John")
365
every { orderService.getOrdersFor("123") } returns emptyList()
366

367
userService.getUserById("123")
368
orderService.getOrdersFor("123")
369

370
// Verify all calls
371
verify { userService.getUserById("123") }
372
verify { orderService.getOrdersFor("123") }
373

374
// Confirm all recorded calls were verified
375
confirmVerified(userService, orderService)
376

377
// Check for unnecessary stubs
378
checkUnnecessaryStub(userService, orderService)
379
```
380

381
### Ordering Types
382

383
Enumeration defining different verification ordering modes.
384

385
```kotlin { .api }
386
enum class Ordering {
387
    /** No specific order required (default) */
388
    UNORDERED,
389
    
390
    /** All specified calls must match */
391
    ALL,
392
    
393
    /** Calls must be in the specified order */
394
    ORDERED,
395
    
396
    /** Exact sequence match with no other calls */
397
    SEQUENCE
398
}
399
```
400

401
**Usage Examples:**
402

403
```kotlin
404
val userService = mockk<UserService>(relaxed = true)
405

406
// Make ordered calls
407
userService.startTransaction()
408
userService.saveUser(User("123", "John"))
409
userService.commitTransaction()
410

411
// Verify with different ordering modes
412
verify(ordering = Ordering.ORDERED) {
413
    userService.startTransaction()
414
    userService.saveUser(any())
415
    userService.commitTransaction()
416
}
417

418
verify(ordering = Ordering.SEQUENCE) {
419
    userService.startTransaction()
420
    userService.saveUser(any())
421
    userService.commitTransaction()
422
}
423
```