0
# Map Assertions
1

2
Specialized assertions for maps including key-value pair validation, entry containment, and size verification.
3

4
## Capabilities
5

6
### Map Subject Creation
7

8
```java { .api }
9
/**
10
 * Creates a MapSubject for asserting about Map instances.
11
 * @param actual the Map under test
12
 */
13
public static MapSubject assertThat(Map<?, ?> actual);
14
```
15

16
### Size and Emptiness Assertions
17

18
```java { .api }
19
/**
20
 * Fails if the map is not empty.
21
 */
22
public void isEmpty();
23

24
/**
25
 * Fails if the map is empty.
26
 */
27
public void isNotEmpty();
28

29
/**
30
 * Fails if the map does not have the specified size.
31
 * @param expectedSize the expected number of entries
32
 */
33
public void hasSize(int expectedSize);
34
```
35

36
**Usage Examples:**
37

38
```java
39
Map<String, Integer> emptyMap = new HashMap<>();
40
Map<String, Integer> scores = Map.of("Alice", 95, "Bob", 87, "Charlie", 92);
41

42
assertThat(emptyMap).isEmpty();
43
assertThat(scores).isNotEmpty();
44
assertThat(scores).hasSize(3);
45
```
46

47
### Key Assertions
48

49
```java { .api }
50
/**
51
 * Fails if the map does not contain the specified key.
52
 * @param key the key that should be present
53
 */
54
public void containsKey(Object key);
55

56
/**
57
 * Fails if the map contains the specified key.
58
 * @param key the key that should not be present
59
 */
60
public void doesNotContainKey(Object key);
61
```
62

63
**Usage Examples:**
64

65
```java
66
Map<String, String> config = Map.of(
67
    "database.host", "localhost",
68
    "database.port", "5432",
69
    "app.name", "MyApp"
70
);
71

72
assertThat(config).containsKey("database.host");
73
assertThat(config).containsKey("app.name");
74
assertThat(config).doesNotContainKey("nonexistent.key");
75
```
76

77
### Entry Assertions
78

79
```java { .api }
80
/**
81
 * Fails if the map does not contain the specified key-value entry.
82
 * @param key the expected key
83
 * @param value the expected value for that key
84
 */
85
public void containsEntry(Object key, Object value);
86

87
/**
88
 * Fails if the map contains the specified key-value entry.
89
 * @param key the key to check
90
 * @param value the value that should not be associated with the key
91
 */
92
public void doesNotContainEntry(Object key, Object value);
93
```
94

95
**Usage Examples:**
96

97
```java
98
Map<String, Integer> inventory = Map.of(
99
    "apples", 50,
100
    "bananas", 30,
101
    "oranges", 25
102
);
103

104
assertThat(inventory).containsEntry("apples", 50);
105
assertThat(inventory).containsEntry("bananas", 30);
106
assertThat(inventory).doesNotContainEntry("apples", 25);
107
assertThat(inventory).doesNotContainEntry("pears", 10);
108
```
109

110
### Exact Content Assertions
111

112
```java { .api }
113
/**
114
 * Fails if the map is not empty.
115
 */
116
public Ordered containsExactly();
117

118
/**
119
 * Fails if the map does not contain exactly the specified entries.
120
 * Arguments are key-value pairs: containsExactly(key1, value1, key2, value2, ...)
121
 * @param entries alternating keys and values
122
 */
123
public Ordered containsExactly(Object... entries);
124

125
/**
126
 * Fails if the map does not contain exactly the entries in the specified map.
127
 * @param expectedMap the map containing expected entries
128
 */
129
public Ordered containsExactlyEntriesIn(Map<?, ?> expectedMap);
130
```
131

132
**Usage Examples:**
133

134
```java
135
Map<String, Integer> empty = new HashMap<>();
136
Map<String, Integer> grades = Map.of("Math", 95, "Science", 87);
137
Map<String, Integer> expected = Map.of("Science", 87, "Math", 95);
138

139
// Empty map
140
assertThat(empty).containsExactly();
141

142
// Exact entries (order doesn't matter by default)
143
assertThat(grades).containsExactly("Math", 95, "Science", 87);
144
assertThat(grades).containsExactly("Science", 87, "Math", 95);
145
assertThat(grades).containsExactlyEntriesIn(expected);
146

147
// With ordering (for ordered maps like LinkedHashMap)
148
Map<String, Integer> ordered = new LinkedHashMap<>();
149
ordered.put("first", 1);
150
ordered.put("second", 2);
151
assertThat(ordered).containsExactly("first", 1, "second", 2).inOrder();
152
```
153

154
### At Least Assertions
155

156
```java { .api }
157
/**
158
 * Fails if the map does not contain at least the specified entries.
159
 * Arguments are key-value pairs: containsAtLeast(key1, value1, key2, value2, ...)
160
 * @param entries alternating keys and values that must be present
161
 */
162
public void containsAtLeast(Object... entries);
163

164
/**
165
 * Fails if the map does not contain at least the entries in the specified map.
166
 * @param expectedEntries the map containing entries that must be present
167
 */
168
public void containsAtLeastEntriesIn(Map<?, ?> expectedEntries);
169
```
170

171
**Usage Examples:**
172

173
```java
174
Map<String, String> fullConfig = Map.of(
175
    "host", "localhost",
176
    "port", "8080", 
177
    "protocol", "https",
178
    "timeout", "30000",
179
    "retries", "3"
180
);
181

182
Map<String, String> minimalConfig = Map.of(
183
    "host", "localhost",
184
    "port", "8080"
185
);
186

187
// Must contain at least these entries (can have more)
188
assertThat(fullConfig).containsAtLeast("host", "localhost", "port", "8080");
189
assertThat(fullConfig).containsAtLeastEntriesIn(minimalConfig);
190
```
191

192
### Custom Value Comparison
193

194
```java { .api }
195
/**
196
 * Starts a method chain for a check in which the actual values are compared to expected 
197
 * values using the given Correspondence.
198
 * @param correspondence the correspondence to use for value comparison
199
 */
200
public <A, E> UsingCorrespondence<A, E> comparingValuesUsing(Correspondence<? super A, ? super E> correspondence);
201
```
202

203
**Usage Examples:**
204

205
```java
206
import com.google.common.truth.Correspondence;
207

208
// Compare string values ignoring case
209
Correspondence<String, String> CASE_INSENSITIVE = 
210
    Correspondence.from((actual, expected) -> actual.equalsIgnoreCase(expected), "ignoring case");
211

212
Map<String, String> actualSettings = Map.of(
213
    "MODE", "Production",
214
    "LEVEL", "Debug"
215
);
216

217
Map<String, String> expectedSettings = Map.of(
218
    "MODE", "production", 
219
    "LEVEL", "debug"
220
);
221

222
assertThat(actualSettings)
223
    .comparingValuesUsing(CASE_INSENSITIVE)
224
    .containsExactlyEntriesIn(expectedSettings);
225

226
// Compare numeric values with tolerance
227
Correspondence<Double, Double> TOLERANCE = Correspondence.tolerance(0.1);
228

229
Map<String, Double> measurements = Map.of("temp", 20.05, "humidity", 45.2);
230
Map<String, Double> expected = Map.of("temp", 20.0, "humidity", 45.0);
231

232
assertThat(measurements)
233
    .comparingValuesUsing(TOLERANCE)
234
    .containsAtLeastEntriesIn(expected);
235
```
236

237
### Multimap Assertions
238

239
```java { .api }
240
/**
241
 * Creates a MultimapSubject for asserting about Multimap instances.
242
 * @param actual the Multimap under test
243
 */
244
public static MultimapSubject assertThat(Multimap<?, ?> actual);
245
```
246

247
**Multimap Usage Examples:**
248

249
```java
250
import com.google.common.collect.ArrayListMultimap;
251
import com.google.common.collect.Multimap;
252

253
Multimap<String, String> tags = ArrayListMultimap.create();
254
tags.put("color", "red");
255
tags.put("color", "blue");
256
tags.put("size", "large");
257

258
assertThat(tags).isNotEmpty();
259
assertThat(tags).hasSize(3);  // Total number of key-value pairs
260
assertThat(tags).containsKey("color");
261
assertThat(tags).containsEntry("color", "red");
262
assertThat(tags).containsEntry("color", "blue");
263
```
264

265
### Advanced Map Testing Examples
266

267
```java
268
// Testing configuration maps
269
Map<String, String> config = loadConfiguration();
270
assertThat(config).containsKey("database.url");
271
assertThat(config).containsKey("api.key");
272
assertThat(config).doesNotContainKey("password"); // Should not store plaintext passwords
273

274
// Testing transformation results
275
Map<String, List<Order>> ordersByCustomer = orders.stream()
276
    .collect(groupingBy(Order::getCustomerId));
277

278
assertThat(ordersByCustomer).isNotEmpty();
279
assertThat(ordersByCustomer).containsKey("customer123");
280
assertThat(ordersByCustomer.get("customer123")).hasSize(expectedOrderCount);
281

282
// Testing cache contents
283
Map<String, CachedValue> cache = getCache();
284
assertThat(cache).hasSize(expectedCacheSize);
285
assertThat(cache).containsKey(frequentlyAccessedKey);
286

287
// Testing builder results
288
Map<String, Object> result = new MapBuilder()
289
    .put("name", "John")
290
    .put("age", 30)
291
    .put("active", true)
292
    .build();
293

294
assertThat(result).containsExactly(
295
    "name", "John",
296
    "age", 30,
297
    "active", true
298
);
299
```
300

301
## Types
302

303
```java { .api }
304
/**
305
 * Subject class for making assertions about Map instances.
306
 */
307
public class MapSubject extends Subject {
308
    /**
309
     * Constructor for MapSubject.
310
     * @param metadata failure metadata for context
311
     * @param actual the Map under test
312
     */
313
    protected MapSubject(FailureMetadata metadata, Map<?, ?> actual);
314
}
315

316
/**
317
 * Subject class for making assertions about Multimap instances.
318
 */
319
public class MultimapSubject extends Subject {
320
    /**
321
     * Constructor for MultimapSubject.
322
     * @param metadata failure metadata for context
323
     * @param actual the Multimap under test
324
     */
325
    protected MultimapSubject(FailureMetadata metadata, Multimap<?, ?> actual);
326
}
327

328
/**
329
 * Interface returned by containsExactly methods to enforce ordering constraints.
330
 */
331
public interface Ordered {
332
    /**
333
     * Enforces that the entries appear in the specified order (for ordered map types).
334
     */
335
    void inOrder();
336
}
337

338
/**
339
 * Result of comparingValuesUsing() providing custom value comparison methods.
340
 */
341
public class UsingCorrespondence<A, E> {
342
    /**
343
     * Fails if the map does not contain exactly the specified entries using the correspondence.
344
     * @param entries alternating keys and expected values
345
     */
346
    public Ordered containsExactly(Object... entries);
347
    
348
    /**
349
     * Fails if the map does not contain exactly the entries in the given map using the correspondence.
350
     * @param expectedMap the map containing expected entries
351
     */
352
    public Ordered containsExactlyEntriesIn(Map<?, ? extends E> expectedMap);
353
    
354
    /**
355
     * Fails if the map does not contain at least the specified entries using the correspondence.
356
     * @param entries alternating keys and expected values
357
     */
358
    public void containsAtLeast(Object... entries);
359
    
360
    /**
361
     * Fails if the map does not contain at least the entries in the given map using the correspondence.
362
     * @param expectedEntries the map containing required entries
363
     */
364
    public void containsAtLeastEntriesIn(Map<?, ? extends E> expectedEntries);
365
}
366
```