0
# Collections
1

2
Comprehensive assertions for arrays, lists, maps, iterables, and other collection types with size, content, ordering, and membership verification.
3

4
## Core Imports
5

6
```java
7
import static org.assertj.core.api.Assertions.*;
8
```
9

10
## Capabilities
11

12
### Array Assertions
13

14
Assertions for object and primitive arrays.
15

16
```java { .api }
17
// Object arrays
18
ObjectArrayAssert<T> assertThat(T[] actual)
19

20
// Primitive arrays
21
BooleanArrayAssert assertThat(boolean[] actual)
22
ByteArrayAssert assertThat(byte[] actual)
23
CharArrayAssert assertThat(char[] actual)
24
DoubleArrayAssert assertThat(double[] actual)
25
FloatArrayAssert assertThat(float[] actual)
26
IntArrayAssert assertThat(int[] actual)
27
LongArrayAssert assertThat(long[] actual)
28
ShortArrayAssert assertThat(short[] actual)
29

30
// Array methods
31
ObjectArrayAssert<T> hasSize(int expected)
32
ObjectArrayAssert<T> isEmpty()
33
ObjectArrayAssert<T> isNotEmpty()
34
ObjectArrayAssert<T> contains(T... values)
35
ObjectArrayAssert<T> containsOnly(T... values)
36
ObjectArrayAssert<T> containsExactly(T... values)
37
ObjectArrayAssert<T> containsExactlyInAnyOrder(T... values)
38
ObjectArrayAssert<T> containsSequence(T... sequence)
39
ObjectArrayAssert<T> containsSubsequence(T... subsequence)
40
ObjectArrayAssert<T> doesNotContain(T... values)
41
ObjectArrayAssert<T> startsWith(T... sequence)
42
ObjectArrayAssert<T> endsWith(T... sequence)
43
ObjectArrayAssert<T> isSorted()
44
ObjectArrayAssert<T> isSortedAccordingTo(Comparator<? super T> comparator)
45
```
46

47
Usage examples:
48
```java
49
String[] names = {"Alice", "Bob", "Charlie"};
50
assertThat(names)
51
    .hasSize(3)
52
    .contains("Bob")
53
    .containsExactly("Alice", "Bob", "Charlie")
54
    .startsWith("Alice")
55
    .endsWith("Charlie");
56

57
int[] numbers = {1, 2, 3, 4, 5};
58
assertThat(numbers)
59
    .hasSize(5)
60
    .contains(3)
61
    .isSorted()
62
    .containsSequence(2, 3, 4);
63
```
64

65
### List Assertions
66

67
Specialized assertions for List collections.
68

69
```java { .api }
70
ListAssert<T> assertThat(List<T> actual)
71

72
// List-specific methods (in addition to Iterable methods)
73
ListAssert<T> isSorted()
74
ListAssert<T> isSortedAccordingTo(Comparator<? super T> comparator)
75
ObjectAssert<T> element(int index)
76
ListAssert<T> hasOnlyOneElementSatisfying(Consumer<T> elementAssertions)
77
```
78

79
Usage examples:
80
```java
81
List<String> fruits = Arrays.asList("apple", "banana", "cherry");
82
assertThat(fruits)
83
    .hasSize(3)
84
    .containsExactly("apple", "banana", "cherry")
85
    .element(1).isEqualTo("banana");
86

87
List<Integer> sortedNumbers = Arrays.asList(1, 2, 3, 4, 5);
88
assertThat(sortedNumbers).isSorted();
89
```
90

91
### Iterable Assertions
92

93
Generic assertions for any Iterable collection.
94

95
```java { .api }
96
IterableAssert<T> assertThat(Iterable<T> actual)
97

98
// Iterable methods
99
IterableAssert<T> hasSize(int expected)
100
IterableAssert<T> hasSizeGreaterThan(int expected)
101
IterableAssert<T> hasSizeLessThan(int expected)
102
IterableAssert<T> hasSizeBetween(int lowerBoundary, int higherBoundary)
103
IterableAssert<T> isEmpty()
104
IterableAssert<T> isNotEmpty()
105
IterableAssert<T> contains(T... values)
106
IterableAssert<T> containsOnly(T... values)
107
IterableAssert<T> containsOnlyOnce(T... values)
108
IterableAssert<T> containsExactly(T... values)
109
IterableAssert<T> containsExactlyInAnyOrder(T... values)
110
IterableAssert<T> containsSequence(T... sequence)
111
IterableAssert<T> containsSubsequence(T... subsequence)
112
IterableAssert<T> doesNotContain(T... values)
113
IterableAssert<T> doesNotContainAnyElementsOf(Iterable<T> iterable)
114
IterableAssert<T> containsAll(Iterable<T> iterable)
115
IterableAssert<T> allMatch(Predicate<? super T> predicate)
116
IterableAssert<T> anyMatch(Predicate<? super T> predicate)
117
IterableAssert<T> noneMatch(Predicate<? super T> predicate)
118
IterableAssert<T> hasOnlyOneElementSatisfying(Consumer<T> elementAssertions)
119
```
120

121
Usage examples:
122
```java
123
Set<String> colors = Set.of("red", "green", "blue");
124
assertThat(colors)
125
    .hasSize(3)
126
    .contains("red", "blue")
127
    .doesNotContain("yellow")
128
    .allMatch(color -> color.length() >= 3);
129

130
Collection<User> users = getActiveUsers();
131
assertThat(users)
132
    .isNotEmpty()
133
    .allMatch(User::isActive)
134
    .anyMatch(user -> user.getRole() == Role.ADMIN);
135
```
136

137
### Map Assertions
138

139
Comprehensive assertions for Map collections.
140

141
```java { .api }
142
MapAssert<K, V> assertThat(Map<K, V> actual)
143

144
// Map methods
145
MapAssert<K, V> hasSize(int expected)
146
MapAssert<K, V> isEmpty()
147
MapAssert<K, V> isNotEmpty()
148
MapAssert<K, V> containsKey(K key)
149
MapAssert<K, V> containsKeys(K... keys)
150
MapAssert<K, V> doesNotContainKey(K key)
151
MapAssert<K, V> doesNotContainKeys(K... keys)
152
MapAssert<K, V> containsValue(V value)
153
MapAssert<K, V> containsValues(V... values)
154
MapAssert<K, V> doesNotContainValue(V value)
155
MapAssert<K, V> containsEntry(K key, V value)
156
MapAssert<K, V> containsEntry(MapEntry entry)
157
MapAssert<K, V> containsExactlyEntriesOf(Map<K, V> other)
158
MapAssert<K, V> containsExactlyInAnyOrderEntriesOf(Map<K, V> other)
159
MapAssert<K, V> doesNotContainEntry(K key, V value)
160
MapAssert<K, V> containsOnlyKeys(K... keys)
161
MapAssert<K, V> containsOnlyKeys(Iterable<K> keys)
162
MapAssert<K, V> hasEntrySatisfying(K key, Consumer<V> valueRequirements)
163
```
164

165
Usage examples:
166
```java
167
Map<String, Integer> scores = Map.of(
168
    "Alice", 95, 
169
    "Bob", 87, 
170
    "Charlie", 92
171
);
172

173
assertThat(scores)
174
    .hasSize(3)
175
    .containsKeys("Alice", "Bob", "Charlie")
176
    .containsEntry("Alice", 95)
177
    .containsValue(87)
178
    .doesNotContainKey("David");
179

180
assertThat(scores)
181
    .hasEntrySatisfying("Alice", score -> assertThat(score).isGreaterThan(90));
182
```
183

184
### 2D Array Assertions
185

186
Assertions for two-dimensional arrays.
187

188
```java { .api }
189
// 2D Object arrays
190
Object2DArrayAssert<T> assertThat(T[][] actual)
191

192
// 2D Primitive arrays
193
Boolean2DArrayAssert assertThat(boolean[][] actual)
194
Byte2DArrayAssert assertThat(byte[][] actual)
195
Char2DArrayAssert assertThat(char[][] actual)
196
Double2DArrayAssert assertThat(double[][] actual)
197
Float2DArrayAssert assertThat(float[][] actual)
198
Int2DArrayAssert assertThat(int[][] actual)
199
Long2DArrayAssert assertThat(long[][] actual)
200
Short2DArrayAssert assertThat(short[][] actual)
201

202
// 2D Array methods
203
Object2DArrayAssert<T> hasSize(int expected)
204
Object2DArrayAssert<T> hasDimensions(int expectedFirstDimension, int expectedSecondDimension)
205
Object2DArrayAssert<T> isEmpty()
206
Object2DArrayAssert<T> isNotEmpty()
207
Object2DArrayAssert<T> isDeepEqualTo(T[][] expected)
208
Object2DArrayAssert<T> isNotDeepEqualTo(T[][] expected)
209
```
210

211
Usage examples:
212
```java
213
String[][] matrix = {
214
    {"a", "b", "c"},
215
    {"d", "e", "f"}
216
};
217

218
assertThat(matrix)
219
    .hasSize(2)
220
    .hasDimensions(2, 3);
221

222
int[][] numbers = {{1, 2}, {3, 4}};
223
assertThat(numbers).hasDimensions(2, 2);
224
```
225

226
### Iterator and Spliterator Assertions
227

228
Assertions for iterators and spliterators.
229

230
```java { .api }
231
IteratorAssert<T> assertThat(Iterator<T> actual)
232
SpliteratorAssert<T> assertThat(Spliterator<T> actual)
233

234
// Iterator methods
235
IteratorAssert<T> hasNext()
236
IteratorAssert<T> isExhausted()
237
IteratorAssert<T> toIterable()
238

239
// Spliterator methods
240
SpliteratorAssert<T> hasCharacteristics(int... characteristics)
241
SpliteratorAssert<T> hasOnlyCharacteristics(int... characteristics)
242
```
243

244
### Filtering and Extraction
245

246
Extract values from collections for focused assertions.
247

248
```java { .api }
249
// Filtering arrays and collections
250
Filters<E> filter(E[] array)
251
Filters<E> filter(Iterable<E> iterable)
252

253
// Property extraction from objects
254
ObjectArrayAssert<Object> extracting(String propertyName)
255
ObjectArrayAssert<Tuple> extracting(String... propertyNames)
256
ObjectArrayAssert<Object> extracting(Function<T, Object> extractor)
257
ObjectArrayAssert<Tuple> extracting(Function<T, Object>... extractors)
258

259
// Flattening nested collections
260
ListAssert<Object> flatExtracting(String propertyName)
261
ListAssert<Object> flatExtracting(Function<T, ?> extractor)
262
```
263

264
Usage examples:
265
```java
266
List<Person> people = Arrays.asList(
267
    new Person("Alice", 30),
268
    new Person("Bob", 25),
269
    new Person("Charlie", 35)
270
);
271

272
// Extract property values
273
assertThat(people)
274
    .extracting(Person::getName)
275
    .containsExactly("Alice", "Bob", "Charlie");
276

277
// Extract multiple properties
278
assertThat(people)
279
    .extracting("name", "age")
280
    .contains(tuple("Alice", 30), tuple("Bob", 25));
281

282
// Filter then assert
283
assertThat(people)
284
    .filteredOn(person -> person.getAge() > 28)
285
    .extracting(Person::getName)
286
    .containsOnly("Alice", "Charlie");
287

288
// Using string-based filtering
289
assertThat(people)
290
    .filteredOn("age", 30)
291
    .hasSize(1)
292
    .extracting("name")
293
    .containsExactly("Alice");
294
```
295

296
### Advanced Collection Operations
297

298
```java { .api }
299
// Grouping elements
300
Map<K, List<T>> groupBy(Function<T, K> classifier)
301

302
// Element access with index
303
ObjectAssert<T> element(int index)
304
ObjectAssert<T> first()
305
ObjectAssert<T> last()
306

307
// Satisfying conditions
308
IterableAssert<T> allSatisfy(Consumer<T> requirements)
309
IterableAssert<T> anySatisfy(Consumer<T> requirements) 
310
IterableAssert<T> noneSatisfy(Consumer<T> requirements)
311
IterableAssert<T> hasOnlyOneElementSatisfying(Consumer<T> requirements)
312
```
313

314
Usage examples:
315
```java
316
List<String> words = Arrays.asList("hello", "world", "test");
317

318
assertThat(words)
319
    .first().isEqualTo("hello");
320
    
321
assertThat(words)
322
    .last().isEqualTo("test");
323
    
324
assertThat(words)
325
    .allSatisfy(word -> assertThat(word).isNotBlank())
326
    .anySatisfy(word -> assertThat(word).startsWith("h"));
327
```
328

329
## Types
330

331
```java { .api }
332
// Index for element access
333
class Index {
334
    static Index atIndex(int index)
335
}
336

337
// Map entry for map assertions
338
class MapEntry<K, V> {
339
    static <K, V> MapEntry<K, V> entry(K key, V value)
340
}
341

342
// Tuple for multi-value extraction
343
class Tuple {
344
    static Tuple tuple(Object... values)
345
    Object[] toArray()
346
}
347

348
// Filter operators
349
class InFilter<E> implements FilterOperator<E> {
350
    static <E> InFilter<E> in(E... elements)
351
    static <E> InFilter<E> in(Iterable<E> elements)
352
}
353

354
class NotInFilter<E> implements FilterOperator<E> {
355
    static <E> NotInFilter<E> notIn(E... elements)
356
    static <E> NotInFilter<E> notIn(Iterable<E> elements)
357
}
358

359
// Predicates for matching
360
interface Predicate<T> {
361
    boolean test(T t);
362
}
363

364
// Functions for extraction
365
interface Function<T, R> {
366
    R apply(T t);
367
}
368

369
// Comparators for sorting
370
interface Comparator<T> {
371
    int compare(T o1, T o2);
372
}
373

374
// Consumer for element validation
375
interface Consumer<T> {
376
    void accept(T t);
377
}
378
```