0
# Collection and Content Assertions
1

2
Comprehensive assertions for working with collections, arrays, ranges, maps, and content comparison. These assertions are essential for verifying data structures and their contents.
3

4
## Capabilities
5

6
### Container Element Assertions
7

8
#### assertContains for Iterables
9

10
Asserts that an iterable contains a specific element.
11

12
```kotlin { .api }
13
/**
14
 * Asserts that the iterable contains the specified element
15
 * @param iterable - Iterable to search in
16
 * @param element - Element to find
17
 * @param message - Optional custom failure message
18
 */
19
fun <T> assertContains(iterable: Iterable<T>, element: T, message: String? = null)
20
```
21

22
**Usage Examples:**
23

24
```kotlin
25
import kotlin.test.*
26

27
@Test
28
fun testIterableContains() {
29
    val numbers = listOf(1, 2, 3, 4, 5)
30
    assertContains(numbers, 3)
31
    assertContains(numbers, 1, "Should contain first element")
32
    
33
    val names = setOf("Alice", "Bob", "Charlie")
34
    assertContains(names, "Bob")
35
    
36
    // Works with any Iterable
37
    val sequence = sequenceOf("a", "b", "c")
38
    assertContains(sequence, "b", "Sequence should contain 'b'")
39
}
40
```
41

42
#### assertContains for Arrays
43

44
Asserts that an array contains a specific element, supporting all array types.
45

46
```kotlin { .api }
47
/**
48
 * Asserts that the array contains the specified element
49
 * @param array - Array to search in
50
 * @param element - Element to find
51
 * @param message - Optional custom failure message
52
 */
53
fun <T> assertContains(array: Array<T>, element: T, message: String? = null)
54

55
// Primitive array variants
56
fun assertContains(array: ByteArray, element: Byte, message: String? = null)
57
fun assertContains(array: ShortArray, element: Short, message: String? = null)
58
fun assertContains(array: IntArray, element: Int, message: String? = null)
59
fun assertContains(array: LongArray, element: Long, message: String? = null)
60
fun assertContains(array: BooleanArray, element: Boolean, message: String? = null)
61
fun assertContains(array: CharArray, element: Char, message: String? = null)
62

63
// Unsigned array variants
64
fun assertContains(array: UByteArray, element: UByte, message: String? = null)
65
fun assertContains(array: UShortArray, element: UShort, message: String? = null)
66
fun assertContains(array: UIntArray, element: UInt, message: String? = null)
67
fun assertContains(array: ULongArray, element: ULong, message: String? = null)
68
```
69

70
**Usage Examples:**
71

72
```kotlin
73
@Test
74
fun testArrayContains() {
75
    // Generic arrays
76
    val stringArray = arrayOf("hello", "world", "test")
77
    assertContains(stringArray, "world")
78
    
79
    // Primitive arrays
80
    val numbers = intArrayOf(10, 20, 30, 40)
81
    assertContains(numbers, 20, "Should contain 20")
82
    
83
    val bytes = byteArrayOf(1, 2, 3)
84
    assertContains(bytes, 2.toByte())
85
    
86
    val chars = charArrayOf('a', 'b', 'c')
87
    assertContains(chars, 'b', "Should contain character 'b'")
88
    
89
    // Unsigned arrays
90
    val uints = uintArrayOf(1u, 2u, 3u)
91
    assertContains(uints, 2u)
92
}
93
```
94

95
#### assertContains for Ranges
96

97
Asserts that a range contains a specific value.
98

99
```kotlin { .api }
100
/**
101
 * Asserts that the range contains the specified value
102
 */
103
fun assertContains(range: IntRange, value: Int, message: String? = null)
104
fun assertContains(range: LongRange, value: Long, message: String? = null)
105
fun assertContains(range: CharRange, value: Char, message: String? = null)
106
fun assertContains(range: UIntRange, value: UInt, message: String? = null)
107
fun assertContains(range: ULongRange, value: ULong, message: String? = null)
108
fun <T : Comparable<T>> assertContains(range: ClosedRange<T>, value: T, message: String? = null)
109
fun <T : Comparable<T>> assertContains(range: OpenEndRange<T>, value: T, message: String? = null)
110
```
111

112
**Usage Examples:**
113

114
```kotlin
115
@Test
116
fun testRangeContains() {
117
    val ageRange = 18..65
118
    assertContains(ageRange, 25, "Age should be in valid range")
119
    assertContains(ageRange, 18, "Should include start of range")
120
    assertContains(ageRange, 65, "Should include end of range")
121
    
122
    val charRange = 'a'..'z'
123
    assertContains(charRange, 'm', "Should contain middle character")
124
    
125
    // Custom comparable range
126
    val dateRange = LocalDate.of(2023, 1, 1)..LocalDate.of(2023, 12, 31)
127
    assertContains(dateRange, LocalDate.of(2023, 6, 15), "Date should be in 2023")
128
}
129
```
130

131
#### assertContains for Maps
132

133
Asserts that a map contains a specific key.
134

135
```kotlin { .api }
136
/**
137
 * Asserts that the map contains the specified key
138
 * @param map - Map to search in
139
 * @param key - Key to find
140
 * @param message - Optional custom failure message
141
 */
142
fun <K, V> assertContains(map: Map<K, V>, key: K, message: String? = null)
143
```
144

145
**Usage Examples:**
146

147
```kotlin
148
@Test
149
fun testMapContains() {
150
    val config = mapOf(
151
        "host" to "localhost",
152
        "port" to 8080,
153
        "ssl" to true
154
    )
155
    
156
    assertContains(config, "host", "Config should contain host setting")
157
    assertContains(config, "port")
158
    assertContains(config, "ssl")
159
    
160
    // Works with any map type
161
    val mutableMap = mutableMapOf("a" to 1, "b" to 2)
162
    assertContains(mutableMap, "a")
163
}
164
```
165

166
#### assertContains for Strings
167

168
Asserts that a string contains a specific character or substring.
169

170
```kotlin { .api }
171
/**
172
 * Asserts that the char sequence contains the specified char
173
 * @param charSequence - String to search in
174
 * @param char - Character to find
175
 * @param ignoreCase - Whether to ignore case when comparing
176
 * @param message - Optional custom failure message
177
 */
178
fun assertContains(charSequence: CharSequence, char: Char, ignoreCase: Boolean = false, message: String? = null)
179

180
/**
181
 * Asserts that the char sequence contains the specified substring
182
 * @param charSequence - String to search in
183
 * @param other - Substring to find
184
 * @param ignoreCase - Whether to ignore case when comparing
185
 * @param message - Optional custom failure message
186
 */
187
fun assertContains(charSequence: CharSequence, other: CharSequence, ignoreCase: Boolean = false, message: String? = null)
188

189
/**
190
 * Asserts that the char sequence contains a match for the regex
191
 * @param charSequence - String to search in
192
 * @param regex - Regular expression to match
193
 * @param message - Optional custom failure message
194
 */
195
fun assertContains(charSequence: CharSequence, regex: Regex, message: String? = null)
196
```
197

198
**Usage Examples:**
199

200
```kotlin
201
@Test
202
fun testStringContains() {
203
    val text = "Hello World"
204
    
205
    // Character search
206
    assertContains(text, 'W', message = "Should contain 'W'")
207
    assertContains(text, 'w', ignoreCase = true, "Should contain 'w' ignoring case")
208
    
209
    // Substring search
210
    assertContains(text, "World", "Should contain 'World'")
211
    assertContains(text, "hello", ignoreCase = true, "Should contain 'hello' ignoring case")
212
    
213
    // Regex search
214
    val emailPattern = Regex("""\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b""")
215
    val email = "Contact us at support@example.com for help"
216
    assertContains(email, emailPattern, "Should contain valid email")
217
    
218
    // Phone number pattern
219
    val phoneText = "Call us at (555) 123-4567"
220
    val phonePattern = Regex("""\(\d{3}\) \d{3}-\d{4}""")
221
    assertContains(phoneText, phonePattern, "Should contain phone number")
222
}
223
```
224

225
### Content Comparison Assertions
226

227
#### assertContentEquals for Iterables
228

229
Asserts that two iterables have the same content in the same order.
230

231
```kotlin { .api }
232
/**
233
 * Asserts that the expected iterable is structurally equal to the actual iterable
234
 * Two iterables are structurally equal if they have the same size and elements
235
 * at corresponding positions are equal
236
 * @param expected - Expected iterable content
237
 * @param actual - Actual iterable to compare
238
 * @param message - Optional custom failure message
239
 */
240
fun <T> assertContentEquals(expected: Iterable<T>?, actual: Iterable<T>?, message: String? = null)
241

242
/**
243
 * Asserts that the expected sequence is structurally equal to the actual sequence
244
 */
245
fun <T> assertContentEquals(expected: Sequence<T>?, actual: Sequence<T>?, message: String? = null)
246
```
247

248
**Usage Examples:**
249

250
```kotlin
251
@Test
252
fun testIterableContentEquals() {
253
    val list1 = listOf(1, 2, 3)
254
    val list2 = mutableListOf(1, 2, 3)
255
    
256
    // Different list types, same content
257
    assertContentEquals(list1, list2, "Lists should have same content")
258
    
259
    // Sequences
260
    val seq1 = sequenceOf("a", "b", "c")
261
    val seq2 = listOf("a", "b", "c").asSequence()
262
    assertContentEquals(seq1, seq2, "Sequences should have same content")
263
    
264
    // Null handling
265
    assertContentEquals(null, null, "Both null should be equal")
266
    
267
    // Order matters
268
    val ordered1 = listOf(1, 2, 3)
269
    val ordered2 = listOf(3, 2, 1)
270
    // This would fail: assertContentEquals(ordered1, ordered2)
271
}
272
```
273

274
#### assertContentEquals for Arrays
275

276
Asserts that two arrays have the same content in the same order.
277

278
```kotlin { .api }
279
/**
280
 * Asserts that arrays are structurally equal (same size, equal elements at corresponding indices)
281
 */
282
fun <T> assertContentEquals(expected: Array<T>?, actual: Array<T>?, message: String? = null)
283

284
// Primitive array variants
285
fun assertContentEquals(expected: ByteArray?, actual: ByteArray?, message: String? = null)
286
fun assertContentEquals(expected: ShortArray?, actual: ShortArray?, message: String? = null)
287
fun assertContentEquals(expected: IntArray?, actual: IntArray?, message: String? = null)
288
fun assertContentEquals(expected: LongArray?, actual: LongArray?, message: String? = null)
289
fun assertContentEquals(expected: BooleanArray?, actual: BooleanArray?, message: String? = null)
290
fun assertContentEquals(expected: CharArray?, actual: CharArray?, message: String? = null)
291
fun assertContentEquals(expected: FloatArray?, actual: FloatArray?, message: String? = null)
292
fun assertContentEquals(expected: DoubleArray?, actual: DoubleArray?, message: String? = null)
293

294
// Unsigned array variants
295
fun assertContentEquals(expected: UByteArray?, actual: UByteArray?, message: String? = null)
296
fun assertContentEquals(expected: UShortArray?, actual: UShortArray?, message: String? = null)
297
fun assertContentEquals(expected: UIntArray?, actual: UIntArray?, message: String? = null)
298
fun assertContentEquals(expected: ULongArray?, actual: ULongArray?, message: String? = null)
299
```
300

301
**Usage Examples:**
302

303
```kotlin
304
@Test
305
fun testArrayContentEquals() {
306
    // Generic arrays
307
    val array1 = arrayOf("hello", "world")
308
    val array2 = arrayOf("hello", "world")
309
    assertContentEquals(array1, array2, "String arrays should match")
310
    
311
    // Primitive arrays
312
    val ints1 = intArrayOf(1, 2, 3, 4, 5)
313
    val ints2 = intArrayOf(1, 2, 3, 4, 5)
314
    assertContentEquals(ints1, ints2, "Int arrays should match")
315
    
316
    val chars1 = charArrayOf('a', 'b', 'c')
317
    val chars2 = "abc".toCharArray()
318
    assertContentEquals(chars1, chars2, "Char arrays should match")
319
    
320
    // Floating point arrays (exact equality)
321
    val doubles1 = doubleArrayOf(1.0, 2.0, Double.NaN)
322
    val doubles2 = doubleArrayOf(1.0, 2.0, Double.NaN)
323
    assertContentEquals(doubles1, doubles2, "Double arrays with NaN should match")
324
    
325
    // Null handling
326
    assertContentEquals(null, null as IntArray?, "Null arrays should be equal")
327
}
328
```
329

330
## Advanced Usage Patterns
331

332
### Testing Data Transformations
333

334
```kotlin
335
@Test
336
fun testDataProcessing() {
337
    val input = listOf("apple", "banana", "cherry")
338
    val processed = input.map { it.uppercase() }
339
    
340
    val expected = listOf("APPLE", "BANANA", "CHERRY")
341
    assertContentEquals(expected, processed, "Should uppercase all strings")
342
    
343
    // Array transformation
344
    val numbers = intArrayOf(1, 2, 3, 4, 5)
345
    val doubled = numbers.map { it * 2 }.toIntArray()
346
    val expectedDoubled = intArrayOf(2, 4, 6, 8, 10)
347
    assertContentEquals(expectedDoubled, doubled, "Should double all numbers")
348
}
349
```
350

351
### Testing Collections with Custom Objects
352

353
```kotlin
354
data class Person(val name: String, val age: Int)
355

356
@Test
357
fun testCustomObjectCollections() {
358
    val people1 = listOf(
359
        Person("Alice", 30),
360
        Person("Bob", 25)
361
    )
362
    
363
    val people2 = mutableListOf<Person>().apply {
364
        add(Person("Alice", 30))
365
        add(Person("Bob", 25))
366
    }
367
    
368
    assertContentEquals(people1, people2, "Person lists should match")
369
    
370
    // With arrays
371
    val peopleArray1 = arrayOf(Person("Charlie", 35))
372
    val peopleArray2 = arrayOf(Person("Charlie", 35))
373
    assertContentEquals(peopleArray1, peopleArray2, "Person arrays should match")
374
}
375
```
376

377
### Testing Search and Filter Operations
378

379
```kotlin
380
@Test
381
fun testSearchOperations() {
382
    val inventory = listOf("apples", "bananas", "oranges", "grapes")
383
    
384
    // Test contains operation
385
    assertContains(inventory, "bananas", "Inventory should contain bananas")
386
    
387
    // Test filtering results
388
    val fruitsWithA = inventory.filter { it.contains('a') }
389
    val expectedWithA = listOf("apples", "bananas", "oranges", "grapes")
390
    assertContentEquals(expectedWithA, fruitsWithA, "Should find all fruits with 'a'")
391
    
392
    // Test map operations
393
    val prices = mapOf("apple" to 1.50, "banana" to 0.75, "orange" to 2.00)
394
    assertContains(prices, "apple", "Price list should contain apple")
395
    
396
    val expensiveItems = prices.filter { it.value > 1.0 }.keys
397
    assertContains(expensiveItems, "apple")
398
    assertContains(expensiveItems, "orange")
399
}
400
```
401

402
### Complex String Pattern Testing
403

404
```kotlin
405
@Test
406
fun testComplexStringPatterns() {
407
    val logEntry = "2023-12-01 14:30:25 [INFO] User john.doe@example.com logged in from 192.168.1.100"
408
    
409
    // Test multiple patterns
410
    assertContains(logEntry, Regex("""\d{4}-\d{2}-\d{2}"""), "Should contain date")
411
    assertContains(logEntry, Regex("""\d{2}:\d{2}:\d{2}"""), "Should contain time")
412
    assertContains(logEntry, Regex("""\[INFO\]"""), "Should contain log level")
413
    assertContains(logEntry, Regex("""\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b"""), "Should contain email")
414
    assertContains(logEntry, Regex("""\b\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}\b"""), "Should contain IP address")
415
}