0
# Core Assertions
1

2
Foundation assertion methods available on all subjects for equality, nullity, type checking, and basic comparisons. These form the basis of Truth's assertion system.
3

4
## Capabilities
5

6
### Truth Entry Points
7

8
Static factory methods that begin Truth assertion chains.
9

10
```java { .api }
11
/**
12
 * Begins a call chain with the fluent Truth API. If the check made by the chain fails, 
13
 * it will throw AssertionError.
14
 */
15
public static StandardSubjectBuilder assert_();
16

17
/**
18
 * Begins an assertion that, if it fails, will prepend the given message to the failure message.
19
 * @param messageToPrepend custom message to prepend to failure
20
 */
21
public static StandardSubjectBuilder assertWithMessage(String messageToPrepend);
22

23
/**
24
 * Begins an assertion with a formatted message using Strings.lenientFormat (supports %s only).
25
 * @param format format string
26
 * @param args arguments for format string
27
 */
28
public static StandardSubjectBuilder assertWithMessage(String format, Object... args);
29
```
30

31
**Usage Examples:**
32

33
```java
34
import static com.google.common.truth.Truth.assertThat;
35
import static com.google.common.truth.Truth.assertWithMessage;
36

37
// Basic assertion
38
assertThat("actual").isEqualTo("expected");
39

40
// With custom message
41
assertWithMessage("Expected user to be active").that(user.isActive()).isTrue();
42

43
// With formatted message
44
assertWithMessage("User %s should have role %s", user.getName(), expectedRole)
45
    .that(user.getRole())
46
    .isEqualTo(expectedRole);
47
```
48

49
### Generic Object Assertions
50

51
Create assertions for any object type using the base Subject class.
52

53
```java { .api }
54
/**
55
 * Creates a Subject for asserting about any Object.
56
 * @param actual the object under test
57
 */
58
public static Subject assertThat(Object actual);
59
```
60

61
### Equality Assertions
62

63
Core equality and identity comparison methods available on all subjects.
64

65
```java { .api }
66
/**
67
 * Fails if the subject is not null.
68
 */
69
public void isNull();
70

71
/**
72
 * Fails if the subject is null.
73
 */
74
public void isNotNull();
75

76
/**
77
 * Fails if the subject is not equal to the given object (according to equals()).
78
 * @param expected the expected value
79
 */
80
public void isEqualTo(Object expected);
81

82
/**
83
 * Fails if the subject is equal to the given object (according to equals()).
84
 * @param expected the value that should not equal the subject
85
 */
86
public void isNotEqualTo(Object expected);
87

88
/**
89
 * Fails if the subject is not the same instance as the given object (== comparison).
90
 * @param expected the expected instance
91
 */
92
public void isSameInstanceAs(Object expected);
93

94
/**
95
 * Fails if the subject is the same instance as the given object (== comparison).
96
 * @param expected the instance that should not be the same as the subject
97
 */
98
public void isNotSameInstanceAs(Object expected);
99
```
100

101
**Usage Examples:**
102

103
```java
104
// Null checks
105
assertThat(value).isNotNull();
106
assertThat(nullValue).isNull();
107

108
// Equality checks
109
assertThat("hello").isEqualTo("hello");
110
assertThat(42).isNotEqualTo(43);
111

112
// Identity checks
113
String str1 = "hello";
114
String str2 = "hello";
115
assertThat(str1).isSameInstanceAs(str1);  // Same reference
116
assertThat(str1).isNotSameInstanceAs(str2);  // Different references
117
```
118

119
### Type Assertions
120

121
Methods for asserting about the type and class of objects.
122

123
```java { .api }
124
/**
125
 * Fails if the subject is not an instance of the given class.
126
 * @param clazz the expected type
127
 */
128
public void isInstanceOf(Class<?> clazz);
129

130
/**
131
 * Fails if the subject is an instance of the given class.
132
 * @param clazz the type that the subject should not be an instance of
133
 */
134
public void isNotInstanceOf(Class<?> clazz);
135
```
136

137
**Usage Examples:**
138

139
```java
140
assertThat("hello").isInstanceOf(String.class);
141
assertThat(42).isInstanceOf(Number.class);
142
assertThat("hello").isNotInstanceOf(Integer.class);
143

144
// Useful for polymorphic types
145
Animal animal = new Dog();
146
assertThat(animal).isInstanceOf(Dog.class);
147
```
148

149
### Collection Membership
150

151
Methods for asserting whether the subject is contained within collections.
152

153
```java { .api }
154
/**
155
 * Fails if the subject is not equal to any element in the given iterable.
156
 * @param iterable the collection that should contain the subject
157
 */
158
public void isIn(Iterable<?> iterable);
159

160
/**
161
 * Fails if the subject is equal to any element in the given iterable.
162
 * @param iterable the collection that should not contain the subject
163
 */
164
public void isNotIn(Iterable<?> iterable);
165

166
/**
167
 * Fails if the subject is not equal to any of the given elements.
168
 * @param first the first element to check
169
 * @param rest additional elements to check
170
 */
171
public void isAnyOf(Object first, Object... rest);
172

173
/**
174
 * Fails if the subject is equal to any of the given elements.
175
 * @param first the first element to check
176
 * @param rest additional elements to check
177
 */
178
public void isNoneOf(Object first, Object... rest);
179
```
180

181
**Usage Examples:**
182

183
```java
184
List<String> validColors = Arrays.asList("red", "green", "blue");
185
assertThat("red").isIn(validColors);
186
assertThat("yellow").isNotIn(validColors);
187

188
// Multiple value checks
189
assertThat(statusCode).isAnyOf(200, 201, 202);
190
assertThat(errorCode).isNoneOf(400, 401, 403, 404);
191
```
192

193
### Class-Specific Assertions
194

195
Assertions specifically for Class objects.
196

197
```java { .api }
198
/**
199
 * Creates a ClassSubject for asserting about Class objects.
200
 * @param actual the Class under test
201
 */
202
public static ClassSubject assertThat(Class<?> actual);
203

204
/**
205
 * Fails if this class or interface is not the same as, or a subclass or subinterface of, the given class.
206
 * @param supertype the expected supertype
207
 */
208
public void isAssignableTo(Class<?> supertype);
209
```
210

211
**Usage Examples:**
212

213
```java
214
assertThat(String.class).isAssignableTo(Object.class);
215
assertThat(ArrayList.class).isAssignableTo(List.class);
216
assertThat(Integer.class).isAssignableTo(Number.class);
217
```
218

219
### Advanced Subject Creation
220

221
Methods for creating custom subjects and extending Truth with domain-specific assertions.
222

223
```java { .api }
224
/**
225
 * Given a factory for some Subject class, returns a builder whose that(actual) method 
226
 * creates instances of that class.
227
 * @param factory factory for creating custom subjects
228
 */
229
public static <S extends Subject, T> SimpleSubjectBuilder<S, T> assertAbout(Subject.Factory<S, T> factory);
230

231
/**
232
 * A generic, advanced method of extension of Truth to new types.
233
 * @param factory factory for creating custom subject builders
234
 */
235
public static <CustomSubjectBuilderT extends CustomSubjectBuilder> CustomSubjectBuilderT assertAbout(
236
    CustomSubjectBuilder.Factory<CustomSubjectBuilderT> factory);
237
```
238

239
### Subject Factory Interface
240

241
Interface for creating custom subjects.
242

243
```java { .api }
244
/**
245
 * Factory interface for creating Subject instances.
246
 */
247
public interface Subject.Factory<SubjectT extends Subject, ActualT> {
248
    /**
249
     * Creates a new Subject.
250
     * @param metadata failure metadata for context
251
     * @param actual the value under test
252
     */
253
    SubjectT createSubject(FailureMetadata metadata, ActualT actual);
254
}
255
```
256

257
### StandardSubjectBuilder Methods
258

259
Builder methods for configuring assertion chains.
260

261
```java { .api }
262
/**
263
 * Returns a new instance that invokes the given FailureStrategy when a check fails.
264
 * @param failureStrategy custom failure handling strategy
265
 */
266
public static StandardSubjectBuilder forCustomFailureStrategy(FailureStrategy failureStrategy);
267

268
/**
269
 * Sets a custom message to be prepended to failure messages.
270
 * @param message the message to prepend
271
 */
272
public StandardSubjectBuilder withMessage(String message);
273

274
/**
275
 * Sets a formatted custom message to be prepended to failure messages.
276
 * @param format format string using lenient formatting (supports %s only)
277
 * @param args arguments for the format string
278
 */
279
public StandardSubjectBuilder withMessage(String format, Object... args);
280

281
/**
282
 * Creates a SimpleSubjectBuilder for the given Subject factory.
283
 * @param factory the Subject factory
284
 */
285
public <S extends Subject, A> SimpleSubjectBuilder<S, A> about(Subject.Factory<S, A> factory);
286

287
/**
288
 * Creates a custom subject builder.
289
 * @param factory the CustomSubjectBuilder factory
290
 */
291
public <CustomSubjectBuilderT extends CustomSubjectBuilder> CustomSubjectBuilderT about(
292
    CustomSubjectBuilder.Factory<CustomSubjectBuilderT> factory);
293

294
/**
295
 * Triggers an immediate failure with the current message context.
296
 */
297
public void fail();
298
```
299

300
## Types
301

302
```java { .api }
303
/**
304
 * Base class for all Truth subjects providing common assertion methods.
305
 */
306
public class Subject {
307
    /**
308
     * Constructor for use by subclasses.
309
     * @param metadata failure metadata containing context information
310
     * @param actual the value under test
311
     */
312
    protected Subject(FailureMetadata metadata, Object actual);
313
    
314
    /**
315
     * Factory interface for creating Subject instances.
316
     */
317
    public interface Factory<SubjectT extends Subject, ActualT> {
318
        SubjectT createSubject(FailureMetadata metadata, ActualT actual);
319
    }
320
}
321

322
/**
323
 * Builder class for configuring and creating Subject instances.
324
 */
325
public class StandardSubjectBuilder {
326
    // Methods documented above
327
}
328

329
/**
330
 * Builder for specific Subject types created via Subject.Factory.
331
 */
332
public class SimpleSubjectBuilder<S extends Subject, T> {
333
    /**
334
     * Creates a Subject instance of the specified type.
335
     * @param actual the value under test
336
     */
337
    public S that(T actual);
338
}
339

340
/**
341
 * Strategy interface for handling assertion failures.
342
 */
343
@FunctionalInterface
344
public interface FailureStrategy {
345
    /**
346
     * Handle an assertion failure.
347
     * @param failure the AssertionError to handle
348
     */
349
    void fail(AssertionError failure);
350
}
351

352
/**
353
 * Metadata container for failure context information.
354
 */
355
public class FailureMetadata {
356
    /**
357
     * Creates FailureMetadata with the given failure strategy.
358
     * @param failureStrategy the strategy for handling failures
359
     */
360
    public static FailureMetadata forFailureStrategy(FailureStrategy failureStrategy);
361
}
362
```