0
# Array Assertions
1
2
Comprehensive array support for both object arrays and all primitive array types with collection-like assertion methods.
3
4
## Capabilities
5
6
### Object Array Assertions
7
8
Assertions for arrays of any object type, providing collection-like functionality.
9
10
```java { .api }
11
/**
12
* Creates an ObjectArraySubject for asserting about object arrays.
13
* @param actual the object array under test
14
*/
15
public static <T> ObjectArraySubject<T> assertThat(T[] actual);
16
```
17
18
#### Core Array Methods
19
20
Methods for basic array validation including size, emptiness, and element access.
21
22
```java { .api }
23
/**
24
* Fails if the array is not empty.
25
*/
26
public void isEmpty();
27
28
/**
29
* Fails if the array is empty.
30
*/
31
public void isNotEmpty();
32
33
/**
34
* Fails if the array does not have the given length.
35
* @param expectedLength the expected array length
36
*/
37
public void hasLength(int expectedLength);
38
```
39
40
**Usage Examples:**
41
42
```java
43
String[] fruits = {"apple", "banana", "cherry"};
44
assertThat(fruits).isNotEmpty();
45
assertThat(fruits).hasLength(3);
46
47
String[] emptyArray = {};
48
assertThat(emptyArray).isEmpty();
49
assertThat(emptyArray).hasLength(0);
50
```
51
52
#### Element Containment
53
54
Methods for checking array element containment and membership.
55
56
```java { .api }
57
/**
58
* Fails if the array does not contain the given element.
59
* @param element the element that should be present
60
*/
61
public void contains(Object element);
62
63
/**
64
* Fails if the array contains the given element.
65
* @param element the element that should not be present
66
*/
67
public void doesNotContain(Object element);
68
69
/**
70
* Fails if the array does not contain at least one of the given elements.
71
* @param first the first element to check for
72
* @param rest additional elements to check for
73
*/
74
public void containsAnyOf(Object first, Object... rest);
75
76
/**
77
* Fails if the array contains any of the given elements.
78
* @param first the first element to check against
79
* @param rest additional elements to check against
80
*/
81
public void containsNoneOf(Object first, Object... rest);
82
```
83
84
**Usage Examples:**
85
86
```java
87
String[] colors = {"red", "green", "blue"};
88
assertThat(colors).contains("red");
89
assertThat(colors).doesNotContain("yellow");
90
assertThat(colors).containsAnyOf("red", "purple", "orange");
91
assertThat(colors).containsNoneOf("yellow", "black", "white");
92
```
93
94
#### Exact Content Matching
95
96
Methods for asserting exact array contents with optional ordering constraints.
97
98
```java { .api }
99
/**
100
* Fails if the array does not contain exactly the given elements, in any order.
101
* @param elements the expected elements
102
*/
103
public Ordered containsExactly(Object... elements);
104
105
/**
106
* Fails if the array does not contain exactly the elements in the given iterable, in any order.
107
* @param expected the iterable containing expected elements
108
*/
109
public Ordered containsExactlyElementsIn(Iterable<?> expected);
110
111
/**
112
* Fails if the array does not contain exactly the elements in the given array, in any order.
113
* @param expected the array containing expected elements
114
*/
115
public Ordered containsExactlyElementsIn(Object[] expected);
116
```
117
118
**Usage Examples:**
119
120
```java
121
String[] fruits = {"apple", "banana", "cherry"};
122
123
// Order doesn't matter
124
assertThat(fruits).containsExactly("cherry", "apple", "banana");
125
126
// With ordering constraint
127
assertThat(fruits).containsExactly("apple", "banana", "cherry").inOrder();
128
129
// From another collection
130
List<String> expected = Arrays.asList("apple", "banana", "cherry");
131
assertThat(fruits).containsExactlyElementsIn(expected).inOrder();
132
```
133
134
#### Subset Assertions
135
136
Methods for asserting that arrays contain at least the specified elements.
137
138
```java { .api }
139
/**
140
* Fails if the array does not contain at least the given elements.
141
* @param elements the elements that should all be present
142
*/
143
public void containsAtLeast(Object... elements);
144
145
/**
146
* Fails if the array does not contain at least the elements in the given iterable.
147
* @param expected the iterable containing elements that should all be present
148
*/
149
public void containsAtLeastElementsIn(Iterable<?> expected);
150
151
/**
152
* Fails if the array does not contain at least the elements in the given array.
153
* @param expected the array containing elements that should all be present
154
*/
155
public void containsAtLeastElementsIn(Object[] expected);
156
```
157
158
**Usage Examples:**
159
160
```java
161
String[] fruits = {"apple", "banana", "cherry", "date"};
162
assertThat(fruits).containsAtLeast("apple", "cherry");
163
164
List<String> required = Arrays.asList("banana", "date");
165
assertThat(fruits).containsAtLeastElementsIn(required);
166
```
167
168
#### Array Ordering
169
170
Methods for asserting array element ordering using natural or custom comparison.
171
172
```java { .api }
173
/**
174
* Fails if the array is not in natural order (each element less than or equal to the next).
175
*/
176
public void isInOrder();
177
178
/**
179
* Fails if the array is not in order according to the given comparator.
180
* @param comparator the comparator to use for ordering comparison
181
*/
182
public void isInOrder(Comparator<? super T> comparator);
183
184
/**
185
* Fails if the array is not in strictly increasing natural order (each element strictly less than the next).
186
*/
187
public void isInStrictOrder();
188
189
/**
190
* Fails if the array is not in strictly increasing order according to the given comparator.
191
* @param comparator the comparator to use for ordering comparison
192
*/
193
public void isInStrictOrder(Comparator<? super T> comparator);
194
```
195
196
**Usage Examples:**
197
198
```java
199
Integer[] numbers = {1, 2, 3, 4, 5};
200
assertThat(numbers).isInOrder();
201
assertThat(numbers).isInStrictOrder();
202
203
String[] words = {"apple", "banana", "cherry"};
204
assertThat(words).isInOrder();
205
206
// Custom ordering
207
String[] byLength = {"cat", "dog", "elephant"};
208
assertThat(byLength).isInOrder(Comparator.comparing(String::length));
209
```
210
211
### Primitive Array Assertions
212
213
Truth provides specialized subjects for all primitive array types with appropriate type-safe methods.
214
215
#### Boolean Arrays
216
217
```java { .api }
218
/**
219
* Creates a PrimitiveBooleanArraySubject for asserting about boolean arrays.
220
* @param actual the boolean array under test
221
*/
222
public static PrimitiveBooleanArraySubject assertThat(boolean[] actual);
223
```
224
225
**Usage Examples:**
226
227
```java
228
boolean[] flags = {true, false, true};
229
assertThat(flags).hasLength(3);
230
assertThat(flags).contains(true);
231
assertThat(flags).containsExactly(true, false, true).inOrder();
232
```
233
234
#### Integer Arrays
235
236
```java { .api }
237
/**
238
* Creates a PrimitiveIntArraySubject for asserting about int arrays.
239
* @param actual the int array under test
240
*/
241
public static PrimitiveIntArraySubject assertThat(int[] actual);
242
```
243
244
**Usage Examples:**
245
246
```java
247
int[] numbers = {1, 2, 3, 4, 5};
248
assertThat(numbers).hasLength(5);
249
assertThat(numbers).contains(3);
250
assertThat(numbers).containsExactly(1, 2, 3, 4, 5).inOrder();
251
assertThat(numbers).isInOrder();
252
assertThat(numbers).isInStrictOrder();
253
```
254
255
#### Long Arrays
256
257
```java { .api }
258
/**
259
* Creates a PrimitiveLongArraySubject for asserting about long arrays.
260
* @param actual the long array under test
261
*/
262
public static PrimitiveLongArraySubject assertThat(long[] actual);
263
```
264
265
**Usage Examples:**
266
267
```java
268
long[] timestamps = {1000000L, 2000000L, 3000000L};
269
assertThat(timestamps).hasLength(3);
270
assertThat(timestamps).isInStrictOrder();
271
assertThat(timestamps).containsAtLeast(1000000L, 3000000L);
272
```
273
274
#### Double Arrays with Tolerance
275
276
```java { .api }
277
/**
278
* Creates a PrimitiveDoubleArraySubject for asserting about double arrays.
279
* @param actual the double array under test
280
*/
281
public static PrimitiveDoubleArraySubject assertThat(double[] actual);
282
283
/**
284
* Returns a tolerance-based comparison for double arrays.
285
* @param tolerance the tolerance for floating-point comparisons
286
*/
287
public TolerantPrimitiveDoubleArrayComparison usingTolerance(double tolerance);
288
```
289
290
**Usage Examples:**
291
292
```java
293
double[] measurements = {1.1, 2.2, 3.3};
294
assertThat(measurements).hasLength(3);
295
assertThat(measurements).isInStrictOrder();
296
297
// Tolerance-based comparisons for floating-point precision
298
double[] calculated = {1.0000001, 2.0000002, 3.0000003};
299
double[] expected = {1.0, 2.0, 3.0};
300
assertThat(calculated).usingTolerance(0.001).containsExactlyElementsIn(expected).inOrder();
301
```
302
303
#### Float Arrays with Tolerance
304
305
```java { .api }
306
/**
307
* Creates a PrimitiveFloatArraySubject for asserting about float arrays.
308
* @param actual the float array under test
309
*/
310
public static PrimitiveFloatArraySubject assertThat(float[] actual);
311
312
/**
313
* Returns a tolerance-based comparison for float arrays.
314
* @param tolerance the tolerance for floating-point comparisons
315
*/
316
public TolerantPrimitiveFloatArrayComparison usingTolerance(float tolerance);
317
```
318
319
**Usage Examples:**
320
321
```java
322
float[] coordinates = {1.5f, 2.7f, 3.9f};
323
assertThat(coordinates).hasLength(3);
324
assertThat(coordinates).isInOrder();
325
326
// Tolerance-based comparisons
327
float[] actual = {1.00001f, 2.00002f};
328
float[] expected = {1.0f, 2.0f};
329
assertThat(actual).usingTolerance(0.001f).containsExactlyElementsIn(expected);
330
```
331
332
#### Other Primitive Arrays
333
334
```java { .api }
335
/**
336
* Creates a PrimitiveByteArraySubject for asserting about byte arrays.
337
* @param actual the byte array under test
338
*/
339
public static PrimitiveByteArraySubject assertThat(byte[] actual);
340
341
/**
342
* Creates a PrimitiveCharArraySubject for asserting about char arrays.
343
* @param actual the char array under test
344
*/
345
public static PrimitiveCharArraySubject assertThat(char[] actual);
346
347
/**
348
* Creates a PrimitiveShortArraySubject for asserting about short arrays.
349
* @param actual the short array under test
350
*/
351
public static PrimitiveShortArraySubject assertThat(short[] actual);
352
```
353
354
**Usage Examples:**
355
356
```java
357
// Byte arrays - useful for binary data
358
byte[] data = {0x01, 0x02, 0x03, 0x04};
359
assertThat(data).hasLength(4);
360
assertThat(data).contains((byte) 0x02);
361
362
// Character arrays - useful for string-like data
363
char[] letters = {'a', 'b', 'c'};
364
assertThat(letters).hasLength(3);
365
assertThat(letters).isInOrder();
366
assertThat(letters).containsExactly('a', 'b', 'c').inOrder();
367
368
// Short arrays
369
short[] values = {100, 200, 300};
370
assertThat(values).isInStrictOrder();
371
assertThat(values).containsAtLeast((short) 100, (short) 300);
372
```
373
374
### Advanced Array Patterns
375
376
Real-world examples of array testing patterns and best practices.
377
378
#### Multi-dimensional Arrays
379
380
```java
381
// Testing 2D arrays
382
int[][] matrix = {{1, 2}, {3, 4}};
383
assertThat(matrix).hasLength(2);
384
assertThat(matrix[0]).containsExactly(1, 2).inOrder();
385
assertThat(matrix[1]).containsExactly(3, 4).inOrder();
386
387
// Testing jagged arrays
388
String[][] jaggedArray = {{"a"}, {"b", "c"}, {"d", "e", "f"}};
389
assertThat(jaggedArray).hasLength(3);
390
assertThat(jaggedArray[0]).hasLength(1);
391
assertThat(jaggedArray[1]).hasLength(2);
392
assertThat(jaggedArray[2]).hasLength(3);
393
```
394
395
#### Array Transformations
396
397
```java
398
// Testing array contents after transformations
399
String[] names = {"Alice", "Bob", "Charlie"};
400
String[] upperNames = Arrays.stream(names)
401
.map(String::toUpperCase)
402
.toArray(String[]::new);
403
404
assertThat(upperNames).containsExactly("ALICE", "BOB", "CHARLIE").inOrder();
405
406
// Testing filtered arrays
407
int[] numbers = {1, 2, 3, 4, 5, 6};
408
int[] evenNumbers = Arrays.stream(numbers)
409
.filter(n -> n % 2 == 0)
410
.toArray();
411
412
assertThat(evenNumbers).containsExactly(2, 4, 6).inOrder();
413
```
414
415
#### Array Equality with Custom Logic
416
417
```java
418
// Custom comparison using Correspondence
419
Correspondence<String, String> IGNORING_CASE =
420
Correspondence.from((actual, expected) ->
421
actual.toLowerCase().equals(expected.toLowerCase()),
422
"equals ignoring case");
423
424
String[] actual = {"Hello", "WORLD"};
425
String[] expected = {"hello", "world"};
426
427
// Note: This would require custom extension - Truth's array subjects
428
// don't directly support Correspondence, but you can convert to lists
429
assertThat(Arrays.asList(actual))
430
.comparingElementsUsing(IGNORING_CASE)
431
.containsExactlyElementsIn(Arrays.asList(expected));
432
```
433
434
#### Performance Testing Arrays
435
436
```java
437
// Testing large array properties
438
int[] largeArray = new int[1000000];
439
Arrays.fill(largeArray, 42);
440
441
assertThat(largeArray).hasLength(1000000);
442
assertThat(largeArray[0]).isEqualTo(42);
443
assertThat(largeArray[999999]).isEqualTo(42);
444
445
// Testing sorted array properties
446
int[] sortedData = IntStream.range(0, 10000).toArray();
447
assertThat(sortedData).isInStrictOrder();
448
assertThat(sortedData).contains(5000);
449
```
450
451
## Types
452
453
```java { .api }
454
/**
455
* Subject class for making assertions about object arrays.
456
* @param <T> the type of array elements
457
*/
458
public class ObjectArraySubject<T> extends Subject {
459
/**
460
* Constructor for ObjectArraySubject.
461
* @param metadata failure metadata for context
462
* @param actual the array under test
463
*/
464
protected ObjectArraySubject(FailureMetadata metadata, T[] actual);
465
}
466
467
/**
468
* Subject class for making assertions about boolean arrays.
469
*/
470
public class PrimitiveBooleanArraySubject extends Subject {
471
protected PrimitiveBooleanArraySubject(FailureMetadata metadata, boolean[] actual);
472
}
473
474
/**
475
* Subject class for making assertions about int arrays.
476
*/
477
public class PrimitiveIntArraySubject extends Subject {
478
protected PrimitiveIntArraySubject(FailureMetadata metadata, int[] actual);
479
}
480
481
/**
482
* Subject class for making assertions about long arrays.
483
*/
484
public class PrimitiveLongArraySubject extends Subject {
485
protected PrimitiveLongArraySubject(FailureMetadata metadata, long[] actual);
486
}
487
488
/**
489
* Subject class for making assertions about double arrays with tolerance support.
490
*/
491
public class PrimitiveDoubleArraySubject extends Subject {
492
protected PrimitiveDoubleArraySubject(FailureMetadata metadata, double[] actual);
493
494
/**
495
* Returns a tolerance-based comparison for double arrays.
496
* @param tolerance the tolerance for floating-point comparisons
497
*/
498
public TolerantPrimitiveDoubleArrayComparison usingTolerance(double tolerance);
499
}
500
501
/**
502
* Subject class for making assertions about float arrays with tolerance support.
503
*/
504
public class PrimitiveFloatArraySubject extends Subject {
505
protected PrimitiveFloatArraySubject(FailureMetadata metadata, float[] actual);
506
507
/**
508
* Returns a tolerance-based comparison for float arrays.
509
* @param tolerance the tolerance for floating-point comparisons
510
*/
511
public TolerantPrimitiveFloatArrayComparison usingTolerance(float tolerance);
512
}
513
514
/**
515
* Subject class for making assertions about byte arrays.
516
*/
517
public class PrimitiveByteArraySubject extends Subject {
518
protected PrimitiveByteArraySubject(FailureMetadata metadata, byte[] actual);
519
}
520
521
/**
522
* Subject class for making assertions about char arrays.
523
*/
524
public class PrimitiveCharArraySubject extends Subject {
525
protected PrimitiveCharArraySubject(FailureMetadata metadata, char[] actual);
526
}
527
528
/**
529
* Subject class for making assertions about short arrays.
530
*/
531
public class PrimitiveShortArraySubject extends Subject {
532
protected PrimitiveShortArraySubject(FailureMetadata metadata, short[] actual);
533
}
534
535
/**
536
* Provides tolerance-based comparison methods for double arrays.
537
*/
538
public class TolerantPrimitiveDoubleArrayComparison {
539
/**
540
* Fails if the array does not contain exactly the given elements within tolerance.
541
* @param expected the expected elements
542
*/
543
public Ordered containsExactly(double... expected);
544
545
/**
546
* Fails if the array does not contain exactly the elements in the given iterable within tolerance.
547
* @param expected the iterable containing expected elements
548
*/
549
public Ordered containsExactlyElementsIn(Iterable<Double> expected);
550
}
551
552
/**
553
* Provides tolerance-based comparison methods for float arrays.
554
*/
555
public class TolerantPrimitiveFloatArrayComparison {
556
/**
557
* Fails if the array does not contain exactly the given elements within tolerance.
558
* @param expected the expected elements
559
*/
560
public Ordered containsExactly(float... expected);
561
562
/**
563
* Fails if the array does not contain exactly the elements in the given iterable within tolerance.
564
* @param expected the iterable containing expected elements
565
*/
566
public Ordered containsExactlyElementsIn(Iterable<Float> expected);
567
}
568
569
/**
570
* Interface returned by containsExactly methods to enforce ordering constraints.
571
*/
572
public interface Ordered {
573
/**
574
* Requires that the elements appear in the given order.
575
*/
576
void inOrder();
577
}
578
```