0
# Argument Matching
1

2
Powerful argument matchers designed for Kotlin's type system, providing type-safe matching with reified generics and null safety. Essential for flexible verification and stubbing in Kotlin tests.
3

4
## Capabilities
5

6
### Basic Matchers
7

8
Core argument matchers for common matching scenarios.
9

10
```kotlin { .api }
11
/**
12
 * Object argument that is equal to the given value
13
 * @param value The value to match against
14
 * @returns The value (for Mockito's internal use)
15
 */
16
fun <T> eq(value: T): T
17

18
/**
19
 * Object argument that is the same instance as the given value
20
 * @param value The instance to match against
21
 * @returns The value (for Mockito's internal use)
22
 */
23
fun <T> same(value: T): T
24
```
25

26
**Usage Examples:**
27

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

31
// Verify with exact value match
32
verify(userService).findUser(eq("john123"))
33

34
// Verify with same instance match
35
val specificUser = User("John")
36
verify(userService).saveUser(same(specificUser))
37
```
38

39
### Type-Safe Any Matchers
40

41
Type-safe matchers that work with Kotlin's null safety and reified generics.
42

43
```kotlin { .api }
44
/**
45
 * Matches any object of type T, excluding nulls
46
 * @returns A dummy instance of T for Mockito's use
47
 */
48
inline fun <reified T : Any> any(): T
49

50
/**
51
 * Matches anything including nulls
52
 * @returns A dummy instance of T for Mockito's use
53
 */
54
inline fun <reified T : Any> anyOrNull(): T
55

56
/**
57
 * Matches any vararg object, including nulls
58
 * @returns A dummy instance of T for Mockito's use
59
 */
60
inline fun <reified T : Any> anyVararg(): T
61

62
/**
63
 * Matches any array of type T
64
 * @returns A dummy array instance for Mockito's use
65
 */
66
inline fun <reified T : Any?> anyArray(): Array<T>
67
```
68

69
**Usage Examples:**
70

71
```kotlin
72
import com.nhaarman.mockitokotlin2.*
73

74
// Verify with any non-null argument
75
verify(userService).findUser(any<String>())
76

77
// Verify with any argument including null
78
verify(userService).findUserOptional(anyOrNull<String>())
79

80
// Stub with any array argument
81
whenever(dataProcessor.processItems(anyArray<String>())).doReturn(emptyList())
82
```
83

84
### Custom Matchers
85

86
Create custom argument matchers with predicates for complex matching logic.
87

88
```kotlin { .api }
89
/**
90
 * Creates a custom argument matcher using a predicate extension function
91
 * Null values will never evaluate to true
92
 * @param predicate Extension function on T that returns true when T matches
93
 * @returns A dummy instance of T for Mockito's use
94
 */
95
inline fun <reified T : Any> argThat(noinline predicate: T.() -> Boolean): T
96

97
/**
98
 * Creates a custom argument matcher using an ArgumentMatcher instance
99
 * @param matcher The ArgumentMatcher instance to register
100
 * @returns A dummy instance of T for Mockito's use
101
 */
102
inline fun <reified T : Any> argThat(matcher: ArgumentMatcher<T>): T
103

104
/**
105
 * Alias for argThat - creates a custom argument matcher with predicate
106
 * @param predicate Extension function on T that returns true when T matches
107
 * @returns A dummy instance of T for Mockito's use
108
 */
109
inline fun <reified T : Any> argForWhich(noinline predicate: T.() -> Boolean): T
110

111
/**
112
 * Creates a custom argument matcher using a regular function predicate
113
 * @param predicate Function that returns true when given T matches
114
 * @returns A dummy instance of T for Mockito's use
115
 */
116
inline fun <reified T : Any> argWhere(noinline predicate: (T) -> Boolean): T
117
```
118

119
**Usage Examples:**
120

121
```kotlin
122
import com.nhaarman.mockitokotlin2.*
123

124
// Verify with custom predicate using extension function
125
verify(userService).findUser(argThat<String> { length > 5 })
126

127
// Verify with custom predicate using regular function
128
verify(userService).findUser(argWhere<String> { it.startsWith("user_") })
129

130
// Stub with complex matching logic
131
whenever(emailService.sendEmail(argThat<EmailRequest> {
132
    recipients.isNotEmpty() && subject.isNotBlank()
133
})).doReturn(true)
134

135
// Using ArgumentMatcher instance
136
val customMatcher = ArgumentMatcher<User> { user ->
137
    user.email.contains("@example.com")
138
}
139
verify(userService).saveUser(argThat(customMatcher))
140
```
141

142
### Type and Null Matchers
143

144
Matchers for type checking and null/non-null verification.
145

146
```kotlin { .api }
147
/**
148
 * Argument that implements the given class or interface
149
 * @returns A dummy instance of T for Mockito's use
150
 */
151
inline fun <reified T : Any> isA(): T
152

153
/**
154
 * Matches null arguments
155
 * @returns null
156
 */
157
fun <T : Any> isNull(): T?
158

159
/**
160
 * Matches non-null arguments
161
 * @returns null (Mockito internal)
162
 */
163
fun <T : Any> isNotNull(): T?
164

165
/**
166
 * Alias for isNotNull - matches non-null arguments
167
 * @returns null (Mockito internal)
168
 */
169
fun <T : Any> notNull(): T?
170
```
171

172
**Usage Examples:**
173

174
```kotlin
175
import com.nhaarman.mockitokotlin2.*
176

177
// Verify argument implements specific type
178
verify(processor).handle(isA<ProcessingRequest>())
179

180
// Verify null argument
181
verify(userService).findUser(isNull())
182

183
// Verify non-null argument
184
verify(userService).findUser(isNotNull())
185
```
186

187
### Reflection-Based Matching
188

189
Advanced matcher for object equality using reflection with field exclusion.
190

191
```kotlin { .api }
192
/**
193
 * Object argument that is reflection-equal to the given value
194
 * Supports excluding specific fields from comparison
195
 * @param value The value to compare against using reflection
196
 * @param excludeFields Field names to exclude from comparison
197
 * @returns A dummy instance of T for Mockito's use
198
 */
199
inline fun <reified T : Any> refEq(value: T, vararg excludeFields: String): T
200
```
201

202
**Usage Examples:**
203

204
```kotlin
205
import com.nhaarman.mockitokotlin2.*
206

207
val expectedUser = User(
208
    id = 123,
209
    name = "John",
210
    createdAt = LocalDateTime.now(),
211
    modifiedAt = LocalDateTime.now()
212
)
213

214
// Verify with reflection equality, excluding timestamp fields
215
verify(userService).saveUser(refEq(expectedUser, "createdAt", "modifiedAt"))
216
```
217

218
### Verification-Only Matcher
219

220
Special matcher designed specifically for verification with custom validation logic.
221

222
```kotlin { .api }
223
/**
224
 * For usage with verification only - not for stubbing
225
 * Executes a predicate function to verify argument properties
226
 * @param predicate Function that performs validation on the argument
227
 * @returns A dummy instance of T for Mockito's use
228
 */
229
inline fun <reified T : Any> check(noinline predicate: (T) -> Unit): T
230
```
231

232
**Usage Examples:**
233

234
```kotlin
235
import com.nhaarman.mockitokotlin2.*
236

237
// Verify with custom assertions
238
verify(userService).saveUser(check<User> { user ->
239
    assertThat(user.email).isNotEmpty()
240
    assertThat(user.age).isGreaterThan(0)
241
})
242

243
// Complex verification with multiple assertions
244
verify(orderService).processOrder(check<Order> { order ->
245
    assertThat(order.items).isNotEmpty()
246
    assertThat(order.totalAmount).isPositive()
247
    assertThat(order.status).isEqualTo(OrderStatus.PENDING)
248
})
249
```
250

251
## Types
252

253
```kotlin { .api }
254
// From org.mockito
255
class ArgumentMatcher<T>
256

257
// Standard Kotlin/Java types used in matchers
258
interface Array<T>
259
```