0
# Collection Matchers
1

2
Comprehensive collection assertions for lists, sets, maps, arrays, and sequences including element access, ordering, uniqueness, containment, and size validation with powerful pattern matching capabilities.
3

4
## Capabilities
5

6
### Element Access and Indexing
7

8
Matchers for accessing and validating elements at specific positions.
9

10
```kotlin { .api }
11
/**
12
 * Assert that list has specific element at given index
13
 * @param index The index position to check
14
 * @param element The expected element at that index
15
 * @return The original List for chaining
16
 */
17
fun <T> List<T>.shouldHaveElementAt(index: Int, element: T): List<T>
18

19
/**
20
 * Assert that array has specific element at given index
21
 * @param index The index position to check
22
 * @param element The expected element at that index
23
 * @return The original Array for chaining
24
 */
25
fun <T> Array<T>.shouldHaveElementAt(index: Int, element: T): Array<T>
26

27
/**
28
 * Assert that iterable has specific element at given index
29
 * @param index The index position to check (0-based)
30
 * @param element The expected element at that index
31
 * @return The original Iterable for chaining
32
 */
33
fun <T> Iterable<T>.shouldHaveElementAt(index: Int, element: T): Iterable<T>
34

35
/**
36
 * Create matcher for element at index validation
37
 * @param index The index position to check
38
 * @param element The expected element
39
 * @return Matcher that passes when element exists at specified index
40
 */
41
fun <T, L : List<T>> haveElementAt(index: Int, element: T): Matcher<L>
42

43
/**
44
 * Assert that list should not have specific element at given index
45
 * @param index The index position to check
46
 * @param element The element that should not be at that index
47
 * @return The original List for chaining
48
 */
49
fun <T> List<T>.shouldNotHaveElementAt(index: Int, element: T): List<T>
50
```
51

52
**Usage Examples:**
53

54
```kotlin
55
import io.kotest.matchers.collections.*
56

57
val numbers = listOf(1, 2, 3, 4, 5)
58
val names = arrayOf("Alice", "Bob", "Charlie")
59

60
// Element position validation
61
numbers.shouldHaveElementAt(0, 1)
62
numbers.shouldHaveElementAt(2, 3)
63
names.shouldHaveElementAt(1, "Bob")
64

65
// Using matcher syntax
66
numbers should haveElementAt(4, 5)
67
```
68

69
### Existence and Predicate Matching
70

71
Matchers for checking element existence based on predicates and conditions.
72

73
```kotlin { .api }
74
/**
75
 * Assert that collection contains at least one element matching predicate
76
 * @param p Predicate function to test elements
77
 * @return The original Collection for chaining
78
 */
79
infix fun <T> Collection<T>.shouldExist(p: (T) -> Boolean): Collection<T>
80

81
/**
82
 * Assert that collection does not contain any element matching predicate
83
 * @param p Predicate function to test elements
84
 * @return The original Collection for chaining
85
 */
86
infix fun <T> Collection<T>.shouldNotExist(p: (T) -> Boolean): Collection<T>
87

88
/**
89
 * Assert that all elements in collection match the predicate
90
 * @param p Predicate function that should match all elements
91
 * @return The original Collection for chaining
92
 */
93
infix fun <T> Collection<T>.shouldForAll(p: (T) -> Boolean): Collection<T>
94

95
/**
96
 * Assert that no elements in collection match the predicate
97
 * @param p Predicate function that should match no elements
98
 * @return The original Collection for chaining
99
 */
100
infix fun <T> Collection<T>.shouldForNone(p: (T) -> Boolean): Collection<T>
101

102
/**
103
 * Assert that exactly one element matches the predicate
104
 * @param p Predicate function to test elements
105
 * @return The original Collection for chaining
106
 */
107
infix fun <T> Collection<T>.shouldExistExactlyOnce(p: (T) -> Boolean): Collection<T>
108

109
/**
110
 * Create matcher for element existence validation
111
 * @param p Predicate function to test elements
112
 * @return Matcher that passes when at least one element matches
113
 */
114
fun <T> exist(p: (T) -> Boolean): Matcher<Collection<T>>
115

116
/**
117
 * Create matcher for universal predicate validation
118
 * @param p Predicate function to test all elements
119
 * @return Matcher that passes when all elements match
120
 */
121
fun <T> forAll(p: (T) -> Boolean): Matcher<Collection<T>>
122

123
/**
124
 * Create matcher for no matches validation
125
 * @param p Predicate function to test elements
126
 * @return Matcher that passes when no elements match
127
 */
128
fun <T> forNone(p: (T) -> Boolean): Matcher<Collection<T>>
129
```
130

131
**Usage Examples:**
132

133
```kotlin
134
import io.kotest.matchers.collections.*
135

136
val scores = listOf(85, 92, 78, 96, 88)
137
val users = listOf(
138
    User("Alice", 25),
139
    User("Bob", 30),
140
    User("Charlie", 35)
141
)
142

143
// Predicate-based existence
144
scores shouldExist { it > 90 }
145
users shouldExist { it.age >= 30 }
146

147
// Universal conditions
148
scores shouldForAll { it >= 70 }
149
users shouldForAll { it.name.isNotEmpty() }
150

151
// Exact occurrence
152
scores shouldExistExactlyOnce { it > 95 }
153

154
// Using matcher syntax
155
scores should exist { it == 85 }
156
users should forAll { it.age > 18 }
157
```
158

159
### Pattern Matching and Ordering
160

161
Advanced matchers for validating element patterns and order relationships.
162

163
```kotlin { .api }
164
/**
165
 * Assert that list elements match assertions in order
166
 * @param assertions Variable number of assertion functions
167
 * @return The original List for chaining
168
 */
169
fun <T> List<T>.shouldMatchInOrder(vararg assertions: (T) -> Unit): List<T>
170

171
/**
172
 * Assert that list contains subset of elements matching assertions in order
173
 * @param assertions Variable number of assertion functions
174
 * @return The original List for chaining
175
 */
176
fun <T> List<T>.shouldMatchInOrderSubset(vararg assertions: (T) -> Unit): List<T>
177

178
/**
179
 * Assert that each list element matches corresponding assertion
180
 * @param assertions Variable number of assertion functions (must match list size)
181
 * @return The original List for chaining
182
 */
183
fun <T> List<T>.shouldMatchEach(vararg assertions: (T) -> Unit): List<T>
184

185
/**
186
 * Assert that elements exist in the list in specified order
187
 * @param expected List of predicate functions to match in order
188
 * @return The original List for chaining
189
 */
190
infix fun <T> List<T>.shouldExistInOrder(expected: List<(T) -> Boolean>): List<T>
191

192
/**
193
 * Create matcher for in-order pattern matching
194
 * @param assertions Variable number of assertion functions
195
 * @return Matcher that passes when elements match assertions in order
196
 */
197
fun <T> matchInOrder(vararg assertions: (T) -> Unit): Matcher<List<T>>
198

199
/**
200
 * Create matcher for subset order matching
201
 * @param assertions Variable number of assertion functions  
202
 * @return Matcher that passes when subset matches in order
203
 */
204
fun <T> matchInOrderSubset(vararg assertions: (T) -> Unit): Matcher<List<T>>
205

206
/**
207
 * Create matcher for each element matching
208
 * @param assertions Variable number of assertion functions
209
 * @return Matcher that passes when each element matches corresponding assertion
210
 */
211
fun <T> matchEach(vararg assertions: (T) -> Unit): Matcher<List<T>>
212
```
213

214
**Usage Examples:**
215

216
```kotlin
217
import io.kotest.matchers.collections.*
218
import io.kotest.matchers.shouldBe
219
import io.kotest.matchers.ints.shouldBeGreaterThan
220

221
val numbers = listOf(1, 5, 10, 15, 20)
222
val words = listOf("apple", "banana", "cherry")
223

224
// Order-based pattern matching
225
numbers.shouldMatchInOrder(
226
    { it shouldBe 1 },
227
    { it shouldBeGreaterThan 3 },
228
    { it shouldBe 10 }
229
)
230

231
// Each element validation
232
words.shouldMatchEach(
233
    { it.shouldStartWith("a") },
234
    { it.shouldStartWith("b") },
235
    { it.shouldStartWith("c") }
236
)
237

238
// Subset order matching
239
numbers.shouldMatchInOrderSubset(
240
    { it shouldBe 1 },
241
    { it shouldBe 20 }
242
)
243
```
244

245
### Containment and Membership
246

247
Matchers for checking element containment and membership relationships.
248

249
```kotlin { .api }
250
/**
251
 * Assert that collection contains any of the specified elements
252
 * @param ts Variable number of elements to check
253
 * @return The original Collection for chaining
254
 */
255
fun <T> Collection<T>.shouldContainAnyOf(vararg ts: T): Collection<T>
256

257
/**
258
 * Assert that collection contains any element from another collection
259
 * @param elements Collection of elements to check
260
 * @return The original Collection for chaining
261
 */
262
fun <T> Collection<T>.shouldContainAnyOf(elements: Collection<T>): Collection<T>
263

264
/**
265
 * Assert that collection contains all specified elements
266
 * @param ts Variable number of elements that must all be present
267
 * @return The original Collection for chaining
268
 */
269
fun <T> Collection<T>.shouldContainAll(vararg ts: T): Collection<T>
270

271
/**
272
 * Assert that collection contains all elements from another collection
273
 * @param elements Collection of elements that must all be present
274
 * @return The original Collection for chaining
275
 */
276
fun <T> Collection<T>.shouldContainAll(elements: Collection<T>): Collection<T>
277

278
/**
279
 * Assert that collection contains exactly the specified elements (order independent)
280
 * @param ts Variable number of elements that should comprise the collection
281
 * @return The original Collection for chaining
282
 */
283
fun <T> Collection<T>.shouldContainExactly(vararg ts: T): Collection<T>
284

285
/**
286
 * Assert that collection contains exactly elements from another collection
287
 * @param elements Collection that should match exactly
288
 * @return The original Collection for chaining
289
 */
290
fun <T> Collection<T>.shouldContainExactly(elements: Collection<T>): Collection<T>
291

292
/**
293
 * Assert that collection contains exactly the elements in specified order
294
 * @param ts Variable number of elements in expected order
295
 * @return The original Collection for chaining
296
 */
297
fun <T> Collection<T>.shouldContainExactlyInAnyOrder(vararg ts: T): Collection<T>
298

299
/**
300
 * Create matcher for any element containment
301
 * @param ts Collection of possible elements
302
 * @return Matcher that passes when collection contains any of the elements
303
 */
304
fun <T> containAnyOf(ts: Collection<T>): Matcher<Collection<T>>
305

306
/**
307
 * Create matcher for all elements containment
308
 * @param ts Collection of required elements
309
 * @return Matcher that passes when all elements are present
310
 */
311
fun <T> containAll(ts: Collection<T>): Matcher<Collection<T>>
312

313
/**
314
 * Create matcher for exact element matching
315
 * @param ts Collection of exact elements expected
316
 * @return Matcher that passes when collections contain exactly the same elements
317
 */
318
fun <T> containExactly(ts: Collection<T>): Matcher<Collection<T>>
319

320
/**
321
 * Create matcher for exact elements in any order
322
 * @param ts Collection of elements (order independent)
323
 * @return Matcher that passes when same elements present regardless of order
324
 */
325
fun <T> containExactlyInAnyOrder(ts: Collection<T>): Matcher<Collection<T>>
326
```
327

328
### Size and Emptiness
329

330
Matchers for validating collection size and emptiness states.
331

332
```kotlin { .api }
333
/**
334
 * Assert that collection is empty (contains no elements)
335
 * @return The original Collection for chaining
336
 */
337
fun <T> Collection<T>.shouldBeEmpty(): Collection<T>
338

339
/**
340
 * Assert that collection is not empty
341
 * @return The original Collection for chaining
342
 */
343
fun <T> Collection<T>.shouldNotBeEmpty(): Collection<T>
344

345
/**
346
 * Assert that collection has exactly specified size
347
 * @param size The expected number of elements
348
 * @return The original Collection for chaining
349
 */
350
fun <T> Collection<T>.shouldHaveSize(size: Int): Collection<T>
351

352
/**
353
 * Assert that collection does not have specified size
354
 * @param size The size that should not match
355
 * @return The original Collection for chaining
356
 */
357
fun <T> Collection<T>.shouldNotHaveSize(size: Int): Collection<T>
358

359
/**
360
 * Assert that collection size is within specified range
361
 * @param range IntRange for valid size values
362
 * @return The original Collection for chaining
363
 */
364
infix fun <T> Collection<T>.shouldHaveSizeBetween(range: IntRange): Collection<T>
365

366
/**
367
 * Assert that collection size is between two values (inclusive)
368
 * @param min Minimum size (inclusive)
369
 * @param max Maximum size (inclusive)
370
 * @return The original Collection for chaining
371
 */
372
fun <T> Collection<T>.shouldHaveSizeBetween(min: Int, max: Int): Collection<T>
373

374
/**
375
 * Assert that collection has at least specified size
376
 * @param size Minimum required size
377
 * @return The original Collection for chaining
378
 */
379
fun <T> Collection<T>.shouldHaveAtLeastSize(size: Int): Collection<T>
380

381
/**
382
 * Assert that collection has at most specified size
383
 * @param size Maximum allowed size
384
 * @return The original Collection for chaining
385
 */
386
fun <T> Collection<T>.shouldHaveAtMostSize(size: Int): Collection<T>
387

388
/**
389
 * Create matcher for empty collection validation
390
 * @return Matcher that passes for empty collections
391
 */
392
fun <T> beEmpty(): Matcher<Collection<T>>
393

394
/**
395
 * Create matcher for size validation
396
 * @param size The expected collection size
397
 * @return Matcher that passes for collections of exact size
398
 */
399
fun <T> haveSize(size: Int): Matcher<Collection<T>>
400

401
/**
402
 * Create matcher for size range validation
403
 * @param range IntRange for valid size values
404
 * @return Matcher that passes for collections within size range
405
 */
406
fun <T> haveSizeBetween(range: IntRange): Matcher<Collection<T>>
407
```
408

409
**Usage Examples:**
410

411
```kotlin
412
import io.kotest.matchers.collections.*
413

414
val items = listOf("apple", "banana", "cherry")
415
val empty = emptyList<String>()
416
val numbers = setOf(1, 2, 3, 4, 5)
417

418
// Size validation
419
items.shouldHaveSize(3)
420
empty.shouldBeEmpty()
421
numbers.shouldHaveSizeBetween(3..10)
422
numbers.shouldHaveAtLeastSize(3)
423

424
// Containment validation
425
items.shouldContainAll("apple", "banana")
426
items.shouldContainAnyOf("apple", "grape", "orange")
427
numbers.shouldContainExactly(1, 2, 3, 4, 5)
428

429
// Using matcher syntax
430
items should haveSize(3)
431
numbers should containAll(listOf(1, 2, 3))
432
```
433

434
### Single Element and Uniqueness
435

436
Matchers for collections with specific element count and uniqueness constraints.
437

438
```kotlin { .api }
439
/**
440
 * Assert that collection contains exactly one element
441
 * @return The original Collection for chaining
442
 */
443
fun <T> Collection<T>.shouldBeSingleton(): Collection<T>
444

445
/**
446
 * Assert that collection is not a singleton
447
 * @return The original Collection for chaining
448
 */
449
fun <T> Collection<T>.shouldNotBeSingleton(): Collection<T>
450

451
/**
452
 * Assert that collection contains exactly one element matching predicate
453
 * @param predicate Function to test elements
454
 * @return The original Collection for chaining
455
 */
456
fun <T> Collection<T>.shouldBeSingleton(predicate: (T) -> Boolean): Collection<T>
457

458
/**
459
 * Assert that collection has unique elements (no duplicates)
460
 * @return The original Collection for chaining
461
 */
462
fun <T> Collection<T>.shouldBeUnique(): Collection<T>
463

464
/**
465
 * Assert that collection has duplicate elements
466
 * @return The original Collection for chaining
467
 */
468
fun <T> Collection<T>.shouldHaveDuplicates(): Collection<T>
469

470
/**
471
 * Assert that collection should not have duplicates
472
 * @return The original Collection for chaining
473
 */
474
fun <T> Collection<T>.shouldNotHaveDuplicates(): Collection<T>
475

476
/**
477
 * Create matcher for singleton validation
478
 * @return Matcher that passes for single-element collections
479
 */
480
fun <T> beSingleton(): Matcher<Collection<T>>
481

482
/**
483
 * Create matcher for singleton with predicate validation
484
 * @param predicate Function to test the single element
485
 * @return Matcher that passes for single-element collections matching predicate
486
 */
487
fun <T> beSingleton(predicate: (T) -> Boolean): Matcher<Collection<T>>
488

489
/**
490
 * Create matcher for uniqueness validation
491
 * @return Matcher that passes for collections with all unique elements
492
 */
493
fun <T> beUnique(): Matcher<Collection<T>>
494

495
/**
496
 * Create matcher for duplicate presence validation
497
 * @return Matcher that passes for collections containing duplicates
498
 */
499
fun <T> haveDuplicates(): Matcher<Collection<T>>
500
```
501

502
### Ordering and Sorting
503

504
Matchers for validating element order and sorting properties.
505

506
```kotlin { .api }
507
/**
508
 * Assert that collection is sorted in natural ascending order
509
 * @return The original Collection for chaining
510
 */
511
fun <T : Comparable<T>> Collection<T>.shouldBeSorted(): Collection<T>
512

513
/**
514
 * Assert that collection is not sorted in natural order
515
 * @return The original Collection for chaining
516
 */
517
fun <T : Comparable<T>> Collection<T>.shouldNotBeSorted(): Collection<T>
518

519
/**
520
 * Assert that collection is sorted using custom comparator
521
 * @param comparator Custom comparison function
522
 * @return The original Collection for chaining
523
 */
524
fun <T> Collection<T>.shouldBeSortedBy(comparator: Comparator<T>): Collection<T>
525

526
/**
527
 * Assert that collection is sorted in descending order
528
 * @return The original Collection for chaining
529
 */
530
fun <T : Comparable<T>> Collection<T>.shouldBeSortedDescending(): Collection<T>
531

532
/**
533
 * Assert that collection is monotonically increasing
534
 * @return The original Collection for chaining
535
 */
536
fun <T : Comparable<T>> List<T>.shouldBeMonotonicallyIncreasing(): List<T>
537

538
/**
539
 * Assert that collection is monotonically decreasing
540
 * @return The original Collection for chaining
541
 */
542
fun <T : Comparable<T>> List<T>.shouldBeMonotonicallyDecreasing(): List<T>
543

544
/**
545
 * Assert that collection is strictly increasing (no equal adjacent elements)
546
 * @return The original Collection for chaining
547
 */
548
fun <T : Comparable<T>> List<T>.shouldBeStrictlyIncreasing(): List<T>
549

550
/**
551
 * Assert that collection is strictly decreasing (no equal adjacent elements)
552
 * @return The original Collection for chaining
553
 */
554
fun <T : Comparable<T>> List<T>.shouldBeStrictlyDecreasing(): List<T>
555

556
/**
557
 * Create matcher for sorted validation
558
 * @return Matcher that passes for naturally sorted collections
559
 */
560
fun <T : Comparable<T>> beSorted(): Matcher<Collection<T>>
561

562
/**
563
 * Create matcher for custom sort validation
564
 * @param comparator Custom comparison function
565
 * @return Matcher that passes for collections sorted by comparator
566
 */
567
fun <T> beSortedBy(comparator: Comparator<T>): Matcher<Collection<T>>
568

569
/**
570
 * Create matcher for monotonic increasing validation
571
 * @return Matcher that passes for monotonically increasing sequences
572
 */
573
fun <T : Comparable<T>> beMonotonicallyIncreasing(): Matcher<List<T>>
574

575
/**
576
 * Create matcher for strict increasing validation
577
 * @return Matcher that passes for strictly increasing sequences
578
 */
579
fun <T : Comparable<T>> beStrictlyIncreasing(): Matcher<List<T>>
580
```
581

582
**Usage Examples:**
583

584
```kotlin
585
import io.kotest.matchers.collections.*
586

587
val sortedNumbers = listOf(1, 2, 3, 4, 5)
588
val reversedNumbers = listOf(5, 4, 3, 2, 1)
589
val names = listOf("Alice", "Bob", "Charlie")
590
val duplicates = listOf(1, 2, 2, 3, 3, 3)
591

592
// Sorting validation
593
sortedNumbers.shouldBeSorted()
594
reversedNumbers.shouldBeSortedDescending()
595
sortedNumbers.shouldBeStrictlyIncreasing()
596

597
// Uniqueness validation
598
sortedNumbers.shouldBeUnique()
599
duplicates.shouldHaveDuplicates()
600

601
// Single element validation
602
listOf("only").shouldBeSingleton()
603

604
// Using matcher syntax
605
sortedNumbers should beSorted()
606
names should beSortedBy(String.CASE_INSENSITIVE_ORDER)
607
```
608

609
### Map-Specific Matchers
610

611
Special matchers for Map collections including key/value operations.
612

613
```kotlin { .api }
614
/**
615
 * Assert that map contains specific key
616
 * @param key The key that should be present
617
 * @return The original Map for chaining
618
 */
619
fun <K, V> Map<K, V>.shouldContainKey(key: K): Map<K, V>
620

621
/**
622
 * Assert that map does not contain specific key
623
 * @param key The key that should not be present
624
 * @return The original Map for chaining
625
 */
626
fun <K, V> Map<K, V>.shouldNotContainKey(key: K): Map<K, V>
627

628
/**
629
 * Assert that map contains specific value
630
 * @param value The value that should be present
631
 * @return The original Map for chaining
632
 */
633
fun <K, V> Map<K, V>.shouldContainValue(value: V): Map<K, V>
634

635
/**
636
 * Assert that map does not contain specific value
637
 * @param value The value that should not be present
638
 * @return The original Map for chaining
639
 */
640
fun <K, V> Map<K, V>.shouldNotContainValue(value: V): Map<K, V>
641

642
/**
643
 * Assert that map contains specific key-value pair
644
 * @param key The expected key
645
 * @param value The expected value for that key
646
 * @return The original Map for chaining
647
 */
648
fun <K, V> Map<K, V>.shouldContain(key: K, value: V): Map<K, V>
649

650
/**
651
 * Assert that map does not contain specific key-value pair
652
 * @param key The key to check
653
 * @param value The value that should not be associated with key
654
 * @return The original Map for chaining
655
 */
656
fun <K, V> Map<K, V>.shouldNotContain(key: K, value: V): Map<K, V>
657

658
/**
659
 * Create matcher for key presence validation
660
 * @param key The key to check for
661
 * @return Matcher that passes when map contains the key
662
 */
663
fun <K, V> containKey(key: K): Matcher<Map<K, V>>
664

665
/**
666
 * Create matcher for value presence validation
667
 * @param value The value to check for
668
 * @return Matcher that passes when map contains the value
669
 */
670
fun <K, V> containValue(value: V): Matcher<Map<K, V>>
671

672
/**
673
 * Create matcher for key-value pair validation
674
 * @param key The expected key
675
 * @param value The expected value
676
 * @return Matcher that passes when map contains the key-value pair
677
 */
678
fun <K, V> contain(key: K, value: V): Matcher<Map<K, V>>
679
```
680

681
**Usage Examples:**
682

683
```kotlin
684
import io.kotest.matchers.maps.*
685

686
val userMap = mapOf(
687
    "alice" to 25,
688
    "bob" to 30,
689
    "charlie" to 35
690
)
691

692
// Map-specific validations
693
userMap.shouldContainKey("alice")
694
userMap.shouldContainValue(30)
695
userMap.shouldContain("bob", 30)
696

697
// Size validation works with maps too
698
userMap.shouldHaveSize(3)
699

700
// Using matcher syntax
701
userMap should containKey("charlie")
702
userMap should contain("alice", 25)
703
```
704

705
## Error Handling
706

707
Collection matchers provide detailed error messages that help identify specific assertion failures:
708

709
- **Size failures**: Show expected vs actual size with element preview
710
- **Element failures**: Highlight which elements are missing, unexpected, or in wrong positions
711
- **Ordering failures**: Show the sequence where ordering requirements are violated
712
- **Predicate failures**: Indicate which elements failed predicate tests with context
713
- **Containment failures**: List missing or unexpected elements with clear categorization
714
- **Pattern failures**: Show exactly where pattern matching breaks down with element details
715

716
All collection matchers handle empty collections, null elements, and edge cases appropriately while maintaining type safety and providing meaningful error context.