0
# Additional Argument Matchers
1

2
This section covers advanced argument matchers for complex matching scenarios, including numerical comparisons, logical combinations, array equality, and specialized string matching.
3

4
## Numerical Comparison Matchers
5

6
### Greater Than or Equal (geq)
7

8
Match arguments greater than or equal to a specified value.
9

10
```java { .api }
11
public static <T extends Comparable<T>> T geq(T value)
12
public static byte geq(byte value)
13
public static double geq(double value)
14
public static float geq(float value)
15
public static int geq(int value)
16
public static long geq(long value)
17
public static short geq(short value)
18
```
19

20
**Usage Examples:**
21

22
```java
23
NumberService mockService = mock(NumberService.class);
24

25
// Stub methods with geq matchers
26
when(mockService.processScore(geq(85))).thenReturn("Grade A");
27
when(mockService.processAge(geq((byte) 18))).thenReturn("Adult");
28
when(mockService.processDouble(geq(3.14))).thenReturn("Pi or greater");
29

30
// Use the mock
31
mockService.processScore(90);     // Returns "Grade A"
32
mockService.processScore(85);     // Returns "Grade A"  
33
mockService.processScore(80);     // No match, returns default
34

35
// Verify with geq matcher
36
verify(mockService).processScore(geq(85));
37
verify(mockService).processAge(geq((byte) 18));
38
```
39

40
### Less Than or Equal (leq)
41

42
Match arguments less than or equal to a specified value.
43

44
```java { .api }
45
public static <T extends Comparable<T>> T leq(T value)
46
public static byte leq(byte value)
47
public static double leq(double value)
48
public static float leq(float value)
49
public static int leq(int value)
50
public static long leq(long value)
51
public static short leq(short value)
52
```
53

54
**Usage Examples:**
55

56
```java
57
ValidationService mockService = mock(ValidationService.class);
58

59
// Stub with leq matchers
60
when(mockService.checkLimit(leq(100))).thenReturn(true);
61
when(mockService.validatePrice(leq(99.99f))).thenReturn("Affordable");
62
when(mockService.checkBuffer(leq(1024L))).thenReturn("Within limit");
63

64
// Use the mock
65
mockService.checkLimit(75);        // Returns true
66
mockService.checkLimit(100);       // Returns true
67
mockService.checkLimit(150);       // No match
68

69
// Verify with leq matcher
70
verify(mockService).checkLimit(leq(100));
71
verify(mockService).validatePrice(leq(99.99f));
72
```
73

74
### Greater Than (gt)
75

76
Match arguments strictly greater than a specified value.
77

78
```java { .api }
79
public static <T extends Comparable<T>> T gt(T value)
80
public static byte gt(byte value)
81
public static double gt(double value)
82
public static float gt(float value)
83
public static int gt(int value)
84
public static long gt(long value)
85
public static short gt(short value)
86
```
87

88
**Usage Examples:**
89

90
```java
91
ScoreService mockService = mock(ScoreService.class);
92

93
// Stub with gt matchers
94
when(mockService.evaluateScore(gt(90))).thenReturn("Excellent");
95
when(mockService.checkTemperature(gt(100.0))).thenReturn("Boiling");
96
when(mockService.validateCount(gt((short) 0))).thenReturn("Positive");
97

98
// Use the mock
99
mockService.evaluateScore(95);     // Returns "Excellent"
100
mockService.evaluateScore(90);     // No match (not greater than 90)
101
mockService.evaluateScore(85);     // No match
102

103
// Verify with gt matcher
104
verify(mockService).evaluateScore(gt(90));
105
verify(mockService).checkTemperature(gt(100.0));
106
```
107

108
### Less Than (lt)
109

110
Match arguments strictly less than a specified value.
111

112
```java { .api }
113
public static <T extends Comparable<T>> T lt(T value)
114
public static byte lt(byte value)
115
public static double lt(double value)
116
public static float lt(float value)
117
public static int lt(int value)
118
public static long lt(long value)
119
public static short lt(short value)
120
```
121

122
**Usage Examples:**
123

124
```java
125
RangeService mockService = mock(RangeService.class);
126

127
// Stub with lt matchers
128
when(mockService.processSmallNumbers(lt(10))).thenReturn("Single digit");
129
when(mockService.checkPrecision(lt(0.001))).thenReturn("High precision");
130
when(mockService.validateThreshold(lt(500L))).thenReturn("Below threshold");
131

132
// Use the mock
133
mockService.processSmallNumbers(5);    // Returns "Single digit"
134
mockService.processSmallNumbers(10);   // No match (not less than 10)
135
mockService.processSmallNumbers(15);   // No match
136

137
// Verify with lt matcher
138
verify(mockService).processSmallNumbers(lt(10));
139
verify(mockService).checkPrecision(lt(0.001));
140
```
141

142
## Comparison-Based Matchers
143

144
### Comparable Equality (cmpEq)
145

146
Match arguments equal according to their `compareTo` method rather than `equals`.
147

148
```java { .api }
149
public static <T extends Comparable<T>> T cmpEq(T value)
150
```
151

152
**Usage Examples:**
153

154
```java
155
DateService mockService = mock(DateService.class);
156

157
// Create dates that are compareTo equal but not equals
158
Date date1 = new Date(1000);
159
Date date2 = new Date(1000);
160

161
// Stub with cmpEq matcher
162
when(mockService.processDate(cmpEq(date1))).thenReturn("Processed");
163

164
// Use the mock
165
mockService.processDate(date2);   // Matches via compareTo
166

167
// Verify with cmpEq matcher
168
verify(mockService).processDate(cmpEq(date1));
169

170
// Works with other Comparable types
171
BigDecimal decimal = new BigDecimal("10.00");
172
when(mockService.processDecimal(cmpEq(decimal))).thenReturn("Valid");
173

174
// Matches BigDecimal("10.0") via compareTo
175
mockService.processDecimal(new BigDecimal("10.0"));
176
```
177

178
## String Pattern Matchers
179

180
### Regular Expression Matching (find)
181

182
Match string arguments that contain a substring matching a regular expression.
183

184
```java { .api }
185
public static String find(String regex)
186
```
187

188
**Usage Examples:**
189

190
```java
191
TextService mockService = mock(TextService.class);
192

193
// Stub with regex pattern matchers
194
when(mockService.validateEmail(find("@[a-zA-Z0-9.-]+\\."))).thenReturn(true);
195
when(mockService.parsePhoneNumber(find("\\d{3}-\\d{3}-\\d{4}"))).thenReturn("Valid format");
196
when(mockService.extractNumbers(find("\\d+"))).thenReturn("Contains digits");
197

198
// Use the mock
199
mockService.validateEmail("user@example.com");           // Matches email pattern
200
mockService.parsePhoneNumber("Call me at 555-123-4567"); // Matches phone pattern
201
mockService.extractNumbers("Room 101");                  // Contains digits
202

203
// Verify with find matcher
204
verify(mockService).validateEmail(find("@[a-zA-Z0-9.-]+\\."));
205
verify(mockService).parsePhoneNumber(find("\\d{3}-\\d{3}-\\d{4}"));
206

207
// Complex patterns
208
when(mockService.validateCode(find("^[A-Z]{2}\\d{4}$"))).thenReturn("Valid code");
209
mockService.validateCode("AB1234");  // Matches exact pattern
210
```
211

212
## Array Equality Matchers
213

214
### Object Array Equality (aryEq)
215

216
Match array arguments using deep equality comparison.
217

218
```java { .api }
219
public static <T> T[] aryEq(T[] value)
220
public static boolean[] aryEq(boolean[] value)
221
public static byte[] aryEq(byte[] value)
222
public static char[] aryEq(char[] value)
223
public static double[] aryEq(double[] value)
224
public static float[] aryEq(float[] value)
225
public static int[] aryEq(int[] value)
226
public static long[] aryEq(long[] value)
227
public static short[] aryEq(short[] value)
228
```
229

230
**Usage Examples:**
231

232
```java
233
ArrayService mockService = mock(ArrayService.class);
234

235
// Object array matching
236
String[] expectedStrings = {"hello", "world"};
237
when(mockService.processStrings(aryEq(expectedStrings))).thenReturn("Processed");
238

239
String[] actualStrings = {"hello", "world"};
240
mockService.processStrings(actualStrings);  // Matches via array equality
241

242
// Primitive array matching
243
int[] expectedNumbers = {1, 2, 3, 4, 5};
244
when(mockService.processNumbers(aryEq(expectedNumbers))).thenReturn(15);
245

246
int[] actualNumbers = {1, 2, 3, 4, 5};
247
mockService.processNumbers(actualNumbers);  // Matches
248

249
// Other primitive types
250
double[] expectedDoubles = {1.1, 2.2, 3.3};
251
when(mockService.processDoubles(aryEq(expectedDoubles))).thenReturn("Calculated");
252

253
boolean[] expectedFlags = {true, false, true};
254
when(mockService.processFlags(aryEq(expectedFlags))).thenReturn("Flags processed");
255

256
// Verify with array equality
257
verify(mockService).processStrings(aryEq(expectedStrings));
258
verify(mockService).processNumbers(aryEq(expectedNumbers));
259
```
260

261
## Logical Combination Matchers
262

263
### Logical AND (and)
264

265
Match arguments that satisfy both of two matchers.
266

267
```java { .api }
268
public static <T> T and(T first, T second)
269
public static boolean and(boolean first, boolean second)
270
public static byte and(byte first, byte second)
271
public static char and(char first, char second)
272
public static double and(double first, double second)
273
public static float and(float first, float second)
274
public static int and(int first, int second)
275
public static long and(long first, long second)
276
public static short and(short first, short second)
277
```
278

279
**Usage Examples:**
280

281
```java
282
RangeService mockService = mock(RangeService.class);
283

284
// Combine numeric matchers with AND
285
when(mockService.processInRange(and(gt(10), lt(100)))).thenReturn("In range");
286
when(mockService.validateScore(and(geq(0), leq(100)))).thenReturn("Valid score");
287

288
// Use the mock
289
mockService.processInRange(50);    // Matches: 50 > 10 AND 50 < 100
290
mockService.processInRange(5);     // No match: 5 not > 10
291
mockService.processInRange(150);   // No match: 150 not < 100
292

293
// Combine string matchers
294
when(mockService.validateInput(and(startsWith("user_"), endsWith(".txt"))))
295
    .thenReturn("Valid filename");
296

297
mockService.validateInput("user_data.txt");  // Matches both conditions
298
mockService.validateInput("user_data.pdf");  // No match (wrong extension)
299

300
// Verify with AND combinations
301
verify(mockService).processInRange(and(gt(10), lt(100)));
302
verify(mockService).validateScore(and(geq(0), leq(100)));
303
```
304

305
### Logical OR (or)
306

307
Match arguments that satisfy either of two matchers.
308

309
```java { .api }
310
public static <T> T or(T first, T second)
311
public static boolean or(boolean first, boolean second)
312
public static byte or(byte first, byte second)
313
public static char or(char first, char second)
314
public static double or(double first, double second)
315
public static float or(float first, float second)
316
public static int or(int first, int second)
317
public static long or(long first, long second)
318
public static short or(short first, short short)
319
```
320

321
**Usage Examples:**
322

323
```java
324
ValidationService mockService = mock(ValidationService.class);
325

326
// Combine conditions with OR
327
when(mockService.isSpecialNumber(or(eq(0), eq(1)))).thenReturn("Binary digit");
328
when(mockService.isExtreme(or(lt(10), gt(90)))).thenReturn("Extreme value");
329

330
// Use the mock
331
mockService.isSpecialNumber(0);    // Matches: equals 0
332
mockService.isSpecialNumber(1);    // Matches: equals 1
333
mockService.isSpecialNumber(5);    // No match
334

335
mockService.isExtreme(5);          // Matches: 5 < 10
336
mockService.isExtreme(95);         // Matches: 95 > 90
337
mockService.isExtreme(50);         // No match
338

339
// String combinations
340
when(mockService.isValidExtension(or(endsWith(".jpg"), endsWith(".png"))))
341
    .thenReturn("Valid image");
342

343
mockService.isValidExtension("photo.jpg");  // Matches
344
mockService.isValidExtension("image.png");  // Matches
345
mockService.isValidExtension("doc.txt");    // No match
346

347
// Verify with OR combinations
348
verify(mockService).isSpecialNumber(or(eq(0), eq(1)));
349
verify(mockService).isExtreme(or(lt(10), gt(90)));
350
```
351

352
### Logical NOT (not)
353

354
Match arguments that do NOT satisfy the given matcher.
355

356
```java { .api }
357
public static <T> T not(T matcher)
358
public static boolean not(boolean matcher)
359
public static byte not(byte matcher)
360
public static char not(char matcher)
361
public static double not(double matcher)
362
public static float not(float matcher)
363
public static int not(int matcher)
364
public static long not(long matcher)
365
public static short not(short matcher)
366
```
367

368
**Usage Examples:**
369

370
```java
371
FilterService mockService = mock(FilterService.class);
372

373
// Negate matchers with NOT
374
when(mockService.processNonZero(not(eq(0)))).thenReturn("Non-zero");
375
when(mockService.excludeRange(not(and(geq(10), leq(20))))).thenReturn("Outside range");
376

377
// Use the mock
378
mockService.processNonZero(5);     // Matches: 5 is not equal to 0
379
mockService.processNonZero(0);     // No match: 0 equals 0
380

381
mockService.excludeRange(5);       // Matches: 5 is not in range [10,20]
382
mockService.excludeRange(15);      // No match: 15 is in range [10,20]
383

384
// String negation
385
when(mockService.processNonEmpty(not(eq("")))).thenReturn("Has content");
386
when(mockService.filterFiles(not(endsWith(".tmp")))).thenReturn("Permanent file");
387

388
mockService.processNonEmpty("hello");    // Matches: not empty
389
mockService.processNonEmpty("");         // No match: is empty
390

391
mockService.filterFiles("data.txt");     // Matches: not .tmp
392
mockService.filterFiles("temp.tmp");     // No match: is .tmp
393

394
// Verify with NOT
395
verify(mockService).processNonZero(not(eq(0)));
396
verify(mockService).excludeRange(not(and(geq(10), leq(20))));
397
```
398

399
## Floating-Point Equality with Delta
400

401
### Delta-Based Equality (eq)
402

403
Match floating-point numbers within a specified tolerance.
404

405
```java { .api }
406
public static double eq(double value, double delta)
407
public static float eq(float value, float delta)
408
```
409

410
**Usage Examples:**
411

412
```java
413
MathService mockService = mock(MathService.class);
414

415
// Floating-point equality with tolerance
416
when(mockService.processApproximateDouble(eq(3.14159, 0.001))).thenReturn("Pi");
417
when(mockService.validateFloat(eq(2.5f, 0.1f))).thenReturn("Close enough");
418

419
// Use the mock
420
mockService.processApproximateDouble(3.141);   // Matches: within 0.001 of pi
421
mockService.processApproximateDouble(3.142);   // Matches: within 0.001 of pi
422
mockService.processApproximateDouble(3.15);    // No match: difference > 0.001
423

424
mockService.validateFloat(2.45f);              // Matches: within 0.1 of 2.5
425
mockService.validateFloat(2.55f);              // Matches: within 0.1 of 2.5
426
mockService.validateFloat(2.7f);               // No match: difference > 0.1
427

428
// Common use case: comparing calculated results
429
double expected = calculateExpectedResult();
430
when(mockService.verifyCalculation(eq(expected, 0.0001)))
431
    .thenReturn("Calculation correct");
432

433
// Verify with delta equality
434
verify(mockService).processApproximateDouble(eq(3.14159, 0.001));
435
verify(mockService).validateFloat(eq(2.5f, 0.1f));
436
```
437

438
## Complex Matcher Combinations
439

440
### Advanced Pattern Matching
441

442
Combine multiple additional matchers for sophisticated argument validation.
443

444
**Usage Examples:**
445

446
```java
447
ComplexService mockService = mock(ComplexService.class);
448

449
// Complex numeric range validation
450
when(mockService.processComplexRange(
451
    and(
452
        or(lt(0), gt(100)), 
453
        not(eq(-1))
454
    )
455
)).thenReturn("Complex condition met");
456

457
// This matches numbers that are:
458
// - (Less than 0 OR greater than 100) AND not equal to -1
459
mockService.processComplexRange(-5);   // Matches: < 0 and != -1
460
mockService.processComplexRange(150);  // Matches: > 100 and != -1  
461
mockService.processComplexRange(-1);   // No match: equals -1
462
mockService.processComplexRange(50);   // No match: not < 0 and not > 100
463

464
// Combining string and array matchers
465
String[] validFormats = {"json", "xml", "csv"};
466
when(mockService.processData(
467
    find("\\.(json|xml|csv)$"),
468
    aryEq(validFormats)
469
)).thenReturn("Valid data processing");
470

471
// Array validation with numerical constraints
472
int[] expectedSizes = {1, 5, 10, 50};
473
when(mockService.validateSizes(
474
    aryEq(expectedSizes),
475
    geq(4)
476
)).thenReturn("Size validation passed");
477
```
478

479
## Import Statement
480

481
To use AdditionalMatchers, include this import in your test files:
482

483
```java
484
import static org.mockito.AdditionalMatchers.*;
485
```
486

487
This static import provides access to all additional matcher methods including `geq`, `leq`, `gt`, `lt`, `cmpEq`, `find`, `aryEq`, `and`, `or`, `not`, and `eq` with delta.
488

489
## Best Practices
490

491
### When to Use Additional Matchers
492

493
- **Numerical Ranges**: Use `gt`, `geq`, `lt`, `leq` for validating numeric boundaries
494
- **Array Comparisons**: Use `aryEq` when you need deep equality checking for arrays
495
- **Complex Logic**: Use `and`, `or`, `not` to create sophisticated matching conditions
496
- **String Patterns**: Use `find` for regex-based string validation
497
- **Floating-Point**: Use `eq` with delta for comparing calculated floating-point results
498

499
### Performance Considerations
500

501
Additional matchers may have performance implications in tests with many mock interactions. Consider the complexity of your matching logic and prefer simpler matchers when possible.
502

503
### Readability Guidelines
504

505
While additional matchers are powerful, they can make tests harder to read. Use them judiciously and consider extracting complex matcher combinations into well-named variables:
506

507
```java
508
// Good: Clear and readable
509
ArgumentMatcher<Integer> validScore = and(geq(0), leq(100));
510
when(mockService.validateScore(argThat(validScore))).thenReturn(true);
511

512
// Also good: Inline when simple
513
when(mockService.processPositive(gt(0))).thenReturn("positive");
514
```