0
# Testing Utilities
1

2
Specialized utilities for testing assertion failures, soft assertions with batched failure reporting, and integration with testing frameworks.
3

4
## Capabilities
5

6
### Expect - Soft Assertions TestRule
7

8
JUnit TestRule that collects multiple assertion failures and reports them together at the end of the test.
9

10
```java { .api }
11
/**
12
 * Creates a new Expect instance for collecting assertion failures.
13
 * @return a new Expect instance
14
 */
15
public static Expect create();
16

17
/**
18
 * JUnit TestRule that can be used with @Rule annotation for automatic failure collection.
19
 */
20
public class Expect implements TestRule {
21
    /**
22
     * Creates an assertion about the given subject but collects failures instead of throwing immediately.
23
     * @param actual the value under test
24
     * @return Subject for making assertions
25
     */
26
    public <T> Subject that(T actual);
27
    
28
    /**
29
     * Adds a custom failure message prefix for subsequent assertions.
30
     * @param message the message to prepend to failure messages
31
     * @return this Expect instance for chaining
32
     */
33
    public Expect withMessage(String message);
34
    
35
    /**
36
     * Adds a formatted custom failure message prefix for subsequent assertions.
37
     * @param format format string using lenient formatting
38
     * @param args arguments for the format string
39
     * @return this Expect instance for chaining
40
     */
41
    public Expect withMessage(String format, Object... args);
42
    
43
    /**
44
     * Creates assertions using custom Subject factories.
45
     * @param factory the Subject factory
46
     * @return SimpleSubjectBuilder for custom assertions
47
     */
48
    public <S extends Subject, A> SimpleSubjectBuilder<S, A> about(Subject.Factory<S, A> factory);
49
}
50
```
51

52
**Basic Usage Examples:**
53

54
```java
55
import static com.google.common.truth.Expect.create;
56

57
public class ExpectExampleTest {
58
    @Rule
59
    public final Expect expect = create();
60
    
61
    @Test
62
    public void testMultipleAssertions() {
63
        User user = new User("Alice", 25, "alice@example.com");
64
        
65
        // All assertions are collected - test continues even if some fail
66
        expect.that(user.getName()).isEqualTo("Alice");
67
        expect.that(user.getAge()).isGreaterThan(18);
68
        expect.that(user.getEmail()).contains("@");
69
        expect.that(user.isActive()).isTrue();
70
        
71
        // If any assertions failed, they are all reported at the end
72
    }
73
    
74
    @Test
75
    public void testWithCustomMessages() {
76
        List<String> items = Arrays.asList("apple", "banana");
77
        
78
        expect.withMessage("List should not be empty")
79
              .that(items).isNotEmpty();
80
        expect.withMessage("List should contain fruit")
81
              .that(items).contains("apple");
82
        expect.withMessage("List should have correct size")
83
              .that(items).hasSize(2);
84
    }
85
}
86
```
87

88
#### Advanced Expect Patterns
89

90
Complex testing scenarios using Expect for comprehensive validation.
91

92
```java
93
// Testing complex object validation
94
@Test
95
public void testComplexObjectValidation() {
96
    Order order = createTestOrder();
97
    
98
    // Customer validation
99
    expect.withMessage("Customer validation")
100
          .that(order.getCustomer()).isNotNull();
101
    expect.that(order.getCustomer().getName()).isNotEmpty();
102
    expect.that(order.getCustomer().getEmail()).matches(".*@.*\\..*");
103
    
104
    // Order details validation  
105
    expect.withMessage("Order details validation")
106
          .that(order.getItems()).isNotEmpty();
107
    expect.that(order.getItems()).hasSize(3);
108
    expect.that(order.getTotalAmount()).isGreaterThan(BigDecimal.ZERO);
109
    
110
    // Order status validation
111
    expect.withMessage("Order status validation")
112
          .that(order.getStatus()).isEqualTo(OrderStatus.PENDING);
113
    expect.that(order.getOrderDate()).isAtMost(Instant.now());
114
}
115

116
// Testing collection contents with multiple criteria
117
@Test
118
public void testCollectionValidation() {
119
    List<Product> products = productService.getAllProducts();
120
    
121
    // Collection-level assertions
122
    expect.that(products).isNotEmpty();
123
    expect.that(products).hasSize(expectedProductCount);
124
    
125
    // Individual product validation
126
    for (int i = 0; i < products.size(); i++) {
127
        Product product = products.get(i);
128
        expect.withMessage("Product %d validation", i)
129
              .that(product.getId()).isNotNull();
130
        expect.that(product.getName()).isNotEmpty();
131
        expect.that(product.getPrice()).isGreaterThan(BigDecimal.ZERO);
132
        expect.that(product.getCategory()).isNotNull();
133
    }
134
}
135

136
// Testing API response validation
137
@Test
138
public void testApiResponseValidation() {
139
    ApiResponse response = apiClient.getUserProfile(userId);
140
    
141
    // Response structure validation
142
    expect.that(response).isNotNull();
143
    expect.that(response.getStatus()).isEqualTo(200);
144
    expect.that(response.getMessage()).isEqualTo("Success");
145
    
146
    // Data validation
147
    UserProfile profile = response.getData();
148
    expect.that(profile).isNotNull();
149
    expect.that(profile.getUserId()).isEqualTo(userId);
150
    expect.that(profile.getUsername()).isNotEmpty();
151
    expect.that(profile.getCreatedDate()).isLessThan(Instant.now());
152
    
153
    // Optional fields validation
154
    if (profile.getLastLoginDate() != null) {
155
        expect.that(profile.getLastLoginDate()).isAtMost(Instant.now());
156
    }
157
}
158
```
159

160
### ExpectFailure - Testing Assertion Failures
161

162
Utilities for testing that Truth assertions fail as expected with proper error messages.
163

164
```java { .api }
165
/**
166
 * Tests that the given assertion callback fails and returns the AssertionError.
167
 * @param assertionCallback callback containing the assertion that should fail
168
 * @return the AssertionError thrown by the failed assertion
169
 */
170
public static AssertionError expectFailure(SimpleSubjectBuilderCallback<?> assertionCallback);
171

172
/**
173
 * Tests that the given assertion callback fails when using a custom Subject factory.
174
 * @param factory the Subject factory to use
175
 * @param assertionCallback callback containing the assertion that should fail
176
 * @return the AssertionError thrown by the failed assertion
177
 */
178
public static <S extends Subject, A> AssertionError expectFailureAbout(
179
    Subject.Factory<S, A> factory, 
180
    SubjectBuilderCallback<S> assertionCallback);
181

182
/**
183
 * Functional interface for assertion callbacks.
184
 */
185
@FunctionalInterface
186
public interface SimpleSubjectBuilderCallback<T> {
187
    void invokeAssertion(SimpleSubjectBuilder<?, T> expect);
188
}
189

190
/**
191
 * Functional interface for custom subject assertion callbacks.
192
 */
193
@FunctionalInterface  
194
public interface SubjectBuilderCallback<S extends Subject> {
195
    void invokeAssertion(SimpleSubjectBuilder<S, ?> expect);
196
}
197
```
198

199
**Basic Usage Examples:**
200

201
```java
202
import static com.google.common.truth.ExpectFailure.expectFailure;
203

204
@Test
205
public void testAssertionFailureMessages() {
206
    // Test that assertion fails with expected message
207
    AssertionError error = expectFailure(
208
        whenTesting -> whenTesting.that("actual").isEqualTo("expected")
209
    );
210
    
211
    assertThat(error).hasMessageThat().contains("actual");
212
    assertThat(error).hasMessageThat().contains("expected");
213
}
214

215
@Test
216
public void testCustomErrorMessage() {
217
    AssertionError error = expectFailure(
218
        whenTesting -> whenTesting.withMessage("Custom error")
219
                                  .that(42).isEqualTo(24)
220
    );
221
    
222
    assertThat(error).hasMessageThat().contains("Custom error");
223
    assertThat(error).hasMessageThat().contains("42");
224
    assertThat(error).hasMessageThat().contains("24");
225
}
226

227
@Test
228
public void testCollectionAssertionFailure() {
229
    List<String> actual = Arrays.asList("apple", "banana");
230
    List<String> expected = Arrays.asList("apple", "cherry");
231
    
232
    AssertionError error = expectFailure(
233
        whenTesting -> whenTesting.that(actual).containsExactlyElementsIn(expected)
234
    );
235
    
236
    assertThat(error).hasMessageThat().contains("missing");
237
    assertThat(error).hasMessageThat().contains("cherry");
238
    assertThat(error).hasMessageThat().contains("unexpected");
239
    assertThat(error).hasMessageThat().contains("banana");
240
}
241
```
242

243
#### Advanced ExpectFailure Patterns
244

245
Testing complex assertion failure scenarios and error message formatting.
246

247
```java
248
// Testing numeric comparison failures
249
@Test
250
public void testNumericComparisonFailures() {
251
    AssertionError error = expectFailure(
252
        whenTesting -> whenTesting.that(5).isGreaterThan(10)
253
    );
254
    
255
    assertThat(error).hasMessageThat().contains("5");
256
    assertThat(error).hasMessageThat().contains("10");
257
    assertThat(error).hasMessageThat().contains("greater than");
258
}
259

260
// Testing floating-point tolerance failures
261
@Test
262
public void testToleranceFailures() {
263
    AssertionError error = expectFailure(
264
        whenTesting -> whenTesting.that(1.0).isWithin(0.001).of(2.0)
265
    );
266
    
267
    assertThat(error).hasMessageThat().contains("1.0");
268
    assertThat(error).hasMessageThat().contains("2.0");
269
    assertThat(error).hasMessageThat().contains("0.001");
270
}
271

272
// Testing string assertion failures
273
@Test
274
public void testStringAssertionFailures() {
275
    AssertionError error = expectFailure(
276
        whenTesting -> whenTesting.that("hello world").matches("\\d+")
277
    );
278
    
279
    assertThat(error).hasMessageThat().contains("hello world");
280
    assertThat(error).hasMessageThat().contains("\\d+");
281
    assertThat(error).hasMessageThat().contains("match");
282
}
283

284
// Testing custom subject failure messages
285
@Test
286
public void testCustomSubjectFailure() {
287
    // Assuming a custom PersonSubject
288
    Person person = new Person("Alice", 25);
289
    
290
    AssertionError error = expectFailureAbout(
291
        PersonSubject.factory(),
292
        whenTesting -> whenTesting.that(person).hasName("Bob")
293
    );
294
    
295
    assertThat(error).hasMessageThat().contains("Alice");
296
    assertThat(error).hasMessageThat().contains("Bob");
297
}
298
```
299

300
### TruthFailureSubject - Asserting About Assertion Failures
301

302
Specialized Subject for making assertions about Truth assertion failures and error messages.
303

304
```java { .api }
305
/**
306
 * Returns a Subject.Factory for creating TruthFailureSubject instances.
307
 * @return factory for TruthFailureSubject
308
 */
309
public static Subject.Factory<TruthFailureSubject, AssertionError> truthFailures();
310

311
/**
312
 * Subject for making assertions about Truth assertion failures.
313
 */
314
public class TruthFailureSubject extends Subject {
315
    /**
316
     * Returns a StringSubject for making assertions about the failure message.
317
     */
318
    public StringSubject hasMessageThat();
319
    
320
    /**
321
     * Asserts that the failure message contains the given fact key-value pair.
322
     * @param key the fact key
323
     * @param value the fact value
324
     */
325
    public void factKeys(String... keys);
326
    
327
    /**
328
     * Asserts about the facts contained in the failure message.
329
     */
330
    public void factValue(String key, String value);
331
}
332
```
333

334
**Usage Examples:**
335

336
```java
337
import static com.google.common.truth.TruthFailureSubject.truthFailures;
338

339
@Test
340
public void testFailureMessageStructure() {
341
    AssertionError failure = expectFailure(
342
        whenTesting -> whenTesting.that(Arrays.asList(1, 2, 3))
343
                                  .containsExactly(1, 2, 4)
344
    );
345
    
346
    assertThat(failure)
347
        .factKeys()
348
        .contains("missing (1)");
349
        
350
    assertThat(failure)
351
        .factKeys()
352
        .contains("unexpected (1)");
353
        
354
    assertThat(failure)
355
        .factValue("missing (1)", "4");
356
        
357
    assertThat(failure)
358
        .factValue("unexpected (1)", "3");
359
}
360
```
361

362
### TruthJUnit - JUnit Integration
363

364
Integration utilities for using Truth with JUnit features like assumptions.
365

366
```java { .api }
367
/**
368
 * Returns a StandardSubjectBuilder that uses JUnit's assumption mechanism.
369
 * Failed assertions will cause the test to be skipped rather than failed.
370
 * @return StandardSubjectBuilder for JUnit assumptions
371
 */
372
public static StandardSubjectBuilder assume();
373
```
374

375
**Usage Examples:**
376

377
```java
378
import static com.google.common.truth.TruthJUnit.assume;
379

380
@Test
381
public void testThatRequiresSpecificEnvironment() {
382
    // Skip test if not in the expected environment
383
    assume().that(System.getProperty("test.environment")).isEqualTo("integration");
384
    
385
    // Skip test if required service is not available
386
    assume().that(serviceHealthCheck.isHealthy()).isTrue();
387
    
388
    // Continue with test only if assumptions pass
389
    String result = integrationService.performOperation();
390
    assertThat(result).isEqualTo("expected");
391
}
392

393
@Test
394
public void testWithOSAssumption() {
395
    // Skip test on Windows
396
    assume().that(System.getProperty("os.name")).doesNotContain("Windows");
397
    
398
    // Unix-specific test logic
399
    String command = executeUnixCommand("ls -la");
400
    assertThat(command).contains("total");
401
}
402
```
403

404
### Advanced Testing Utilities Patterns
405

406
#### Custom Test Rules and Extensions
407

408
```java
409
// Custom test rule combining Expect with setup/teardown
410
public class DatabaseTestRule implements TestRule {
411
    private final Expect expect = Expect.create();
412
    private DatabaseConnection connection;
413
    
414
    @Override
415
    public Statement apply(Statement base, Description description) {
416
        return new Statement() {
417
            @Override
418
            public void evaluate() throws Throwable {
419
                connection = setupDatabase();
420
                try {
421
                    base.evaluate();
422
                } finally {
423
                    expect.checkAndClearFailures(); // Manual failure checking
424
                    cleanupDatabase(connection);
425
                }
426
            }
427
        };
428
    }
429
    
430
    public Expect expect() {
431
        return expect;
432
    }
433
}
434

435
// Usage in test
436
public class DatabaseIntegrationTest {
437
    @Rule
438
    public final DatabaseTestRule dbRule = new DatabaseTestRule();
439
    
440
    @Test
441
    public void testDatabaseOperations() {
442
        dbRule.expect().that(dbRule.getConnection()).isNotNull();
443
        // Additional database tests using dbRule.expect()
444
    }
445
}
446
```
447

448
#### Parameterized Test Validation
449

450
```java
451
// Using Expect with parameterized tests for comprehensive validation
452
@RunWith(Parameterized.class)
453
public class ParameterizedValidationTest {
454
    @Rule
455
    public final Expect expect = Expect.create();
456
    
457
    @Parameter
458
    public String input;
459
    
460
    @Parameter(1)
461
    public String expectedOutput;
462
    
463
    @Parameters
464
    public static Collection<Object[]> data() {
465
        return Arrays.asList(new Object[][] {
466
            {"hello", "HELLO"},
467
            {"world", "WORLD"},
468
            {"test", "TEST"}
469
        });
470
    }
471
    
472
    @Test
473
    public void testTransformation() {
474
        String result = transformService.transform(input);
475
        
476
        expect.withMessage("Input: %s", input)
477
              .that(result).isEqualTo(expectedOutput);
478
        expect.that(result).hasLength(input.length());
479
        expect.that(result).matches("[A-Z]+");
480
    }
481
}
482
```
483

484
## Types
485

486
```java { .api }
487
/**
488
 * JUnit TestRule for collecting assertion failures and reporting them together.
489
 */
490
public class Expect implements TestRule {
491
    /**
492
     * Creates a new Expect instance.
493
     */
494
    public static Expect create();
495
    
496
    /**
497
     * Creates assertions that collect failures instead of throwing immediately.
498
     * @param actual the value under test
499
     */
500
    public <T> Subject that(T actual);
501
    
502
    /**
503
     * Adds failure message prefix for subsequent assertions.
504
     * @param message the message to prepend
505
     */
506
    public Expect withMessage(String message);
507
    
508
    /**
509
     * Adds formatted failure message prefix for subsequent assertions.
510
     * @param format format string
511
     * @param args format arguments
512
     */
513
    public Expect withMessage(String format, Object... args);
514
    
515
    /**
516
     * Creates custom subject assertions that collect failures.
517
     * @param factory Subject factory
518
     */
519
    public <S extends Subject, A> SimpleSubjectBuilder<S, A> about(Subject.Factory<S, A> factory);
520
}
521

522
/**
523
 * Utilities for testing Truth assertion failures.
524
 */
525
public class ExpectFailure {
526
    /**
527
     * Tests that an assertion fails and returns the error.
528
     * @param callback assertion that should fail
529
     */
530
    public static AssertionError expectFailure(SimpleSubjectBuilderCallback<?> callback);
531
    
532
    /**
533
     * Tests that a custom subject assertion fails.
534
     * @param factory Subject factory
535
     * @param callback assertion that should fail
536
     */
537
    public static <S extends Subject, A> AssertionError expectFailureAbout(
538
        Subject.Factory<S, A> factory, 
539
        SubjectBuilderCallback<S> callback);
540
}
541

542
/**
543
 * Functional interface for assertion callbacks.
544
 */
545
@FunctionalInterface
546
public interface SimpleSubjectBuilderCallback<T> {
547
    void invokeAssertion(SimpleSubjectBuilder<?, T> expect);
548
}
549

550
/**
551
 * Functional interface for custom subject assertion callbacks.
552
 */
553
@FunctionalInterface
554
public interface SubjectBuilderCallback<S extends Subject> {
555
    void invokeAssertion(SimpleSubjectBuilder<S, ?> expect);
556
}
557

558
/**
559
 * Subject for making assertions about Truth assertion failures.
560
 */
561
public class TruthFailureSubject extends Subject {
562
    /**
563
     * Factory for creating TruthFailureSubject instances.
564
     */
565
    public static Subject.Factory<TruthFailureSubject, AssertionError> truthFailures();
566
    
567
    /**
568
     * Returns StringSubject for asserting about failure message.
569
     */
570
    public StringSubject hasMessageThat();
571
    
572
    /**
573
     * Asserts about fact keys in the failure message.
574
     * @param keys expected fact keys
575
     */
576
    public void factKeys(String... keys);
577
    
578
    /**
579
     * Asserts about a specific fact value in the failure message.
580
     * @param key fact key
581
     * @param value expected fact value
582
     */
583
    public void factValue(String key, String value);
584
}
585

586
/**
587
 * JUnit integration utilities.
588
 */
589
public class TruthJUnit {
590
    /**
591
     * Returns StandardSubjectBuilder using JUnit assumption mechanism.
592
     * Failed assertions skip the test instead of failing it.
593
     */
594
    public static StandardSubjectBuilder assume();
595
}
596
```