0
# AssertJ Core
1

2
AssertJ Core is a rich assertion library for Java that provides fluent assertions with descriptive error messages. It offers 200+ static assertion methods and 80+ Assert classes for comprehensive testing of all Java types, from primitives to complex objects, collections, dates, exceptions, and more.
3

4
## Package Information
5

6
- **Package Name**: org.assertj:assertj-core
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: 
10
  - Maven: `<dependency><groupId>org.assertj</groupId><artifactId>assertj-core</artifactId><version>3.27.3</version><scope>test</scope></dependency>`
11
  - Gradle: `testImplementation 'org.assertj:assertj-core:3.27.3'`
12

13
## Core Imports
14

15
```java
16
import static org.assertj.core.api.Assertions.*;
17
```
18

19
For specific use cases:
20
```java
21
import static org.assertj.core.api.Assertions.assertThat;
22
import static org.assertj.core.api.Assertions.assertThatThrownBy;
23
import static org.assertj.core.api.Assertions.fail;
24
```
25

26
### Alternative Entry Points
27

28
AssertJ provides specialized entry points for different environments and testing frameworks:
29

30
```java { .api }
31
// Java 6 compatibility entry point
32
import static org.assertj.core.api.Java6Assertions.*;
33

34
// JUnit 5 specific entry point
35
import static org.assertj.core.api.JUnitJupiterAssertions.*;
36

37
// JUnit soft assertions entry point  
38
import static org.assertj.core.api.JUnitSoftAssertions.*;
39
```
40

41
Usage examples:
42
```java
43
// Java 6 Assertions - compatible with older Java versions
44
import static org.assertj.core.api.Java6Assertions.*;
45

46
assertThat("Hello").isEqualTo("Hello");
47
assertThat(Arrays.asList(1, 2, 3)).hasSize(3);
48

49
// JUnit Jupiter Assertions - optimized for JUnit 5
50
import static org.assertj.core.api.JUnitJupiterAssertions.*;
51

52
@Test
53
void testWithJUnitJupiterAssertions() {
54
    assertThat("JUnit 5").startsWith("JUnit");
55
    assertThatThrownBy(() -> { throw new RuntimeException(); })
56
        .isInstanceOf(RuntimeException.class);
57
}
58

59
// JUnit Soft Assertions - JUnit-integrated soft assertions
60
import static org.assertj.core.api.JUnitSoftAssertions.*;
61

62
@ExtendWith(SoftAssertionsExtension.class)
63
class SoftAssertionsTest {
64
    @Test
65
    void testWithJUnitSoftAssertions(SoftAssertions softly) {
66
        softly.assertThat("Hello").startsWith("Hi");
67
        softly.assertThat(42).isNegative();
68
        // Failures collected and reported automatically by JUnit extension
69
    }
70
}
71
```
72

73
## Basic Usage
74

75
```java
76
import static org.assertj.core.api.Assertions.*;
77

78
// Basic assertions
79
assertThat("Hello World").startsWith("Hello").endsWith("World");
80
assertThat(42).isGreaterThan(40).isLessThan(50);
81
assertThat(Arrays.asList(1, 2, 3)).hasSize(3).contains(2);
82

83
// Exception testing
84
assertThatThrownBy(() -> {
85
    throw new IllegalArgumentException("Invalid input");
86
}).isInstanceOf(IllegalArgumentException.class)
87
  .hasMessage("Invalid input");
88

89
// Soft assertions (collect all failures)
90
SoftAssertions softly = new SoftAssertions();
91
softly.assertThat("Hello").startsWith("Hi");
92
softly.assertThat(42).isNegative();
93
softly.assertAll(); // throws AssertionError with all failures
94
```
95

96
## Architecture
97

98
AssertJ follows a fluent API pattern where:
99
1. **Entry Points**: Static methods in `Assertions` class create Assert instances
100
2. **Assert Classes**: Type-specific classes provide focused assertion methods
101
3. **Chaining**: Most assertions return the Assert instance for method chaining
102
4. **Failure Messages**: Descriptive error messages show expected vs actual values
103

104
## Capabilities
105

106
### Basic Assertions
107

108
Core assertion patterns for primitive types, objects, and common operations.
109

110
```java { .api }
111
// Primitive assertions
112
assertThat(boolean actual) → BooleanAssert
113
assertThat(int actual) → IntegerAssert
114
assertThat(String actual) → StringAssert
115
assertThat(Object actual) → ObjectAssert
116

117
// Common assertion methods
118
BooleanAssert isTrue()
119
BooleanAssert isFalse()
120
IntegerAssert isPositive()
121
IntegerAssert isNegative()
122
IntegerAssert isEven()
123
IntegerAssert isOdd()
124
```
125

126
[Basic Assertions](./basic-assertions.md)
127

128
### Collections
129

130
Comprehensive assertions for arrays, lists, maps, and iterables with size, content, and order verification.
131

132
```java { .api }
133
// Collection assertions
134
assertThat(List<T> actual) → ListAssert<T>
135
assertThat(T[] actual) → ObjectArrayAssert<T>
136
assertThat(Map<K,V> actual) → MapAssert<K,V>
137
assertThat(Iterable<T> actual) → IterableAssert<T>
138

139
// Collection methods
140
ListAssert<T> hasSize(int expected)
141
ListAssert<T> contains(T... values)
142
ListAssert<T> containsExactly(T... values)
143
MapAssert<K,V> containsKey(K key)
144
MapAssert<K,V> containsEntry(K key, V value)
145
```
146

147
[Collections](./collections.md)
148

149
### Strings
150

151
String and CharSequence assertions for content, format, and pattern matching.
152

153
```java { .api }
154
// String assertions
155
assertThat(String actual) → StringAssert
156
assertThat(CharSequence actual) → CharSequenceAssert
157

158
// String methods
159
StringAssert startsWith(String prefix)
160
StringAssert endsWith(String suffix)
161
StringAssert contains(String substring)
162
StringAssert matches(String regex)
163
StringAssert hasLength(int length)
164
StringAssert isEmpty()
165
StringAssert isBlank()
166
```
167

168
[Strings](./strings.md)
169

170
### Dates and Times
171

172
Date and time assertions supporting both legacy Date and modern java.time API.
173

174
```java { .api }
175
// Date/Time assertions
176
assertThat(LocalDate actual) → LocalDateAssert
177
assertThat(LocalDateTime actual) → LocalDateTimeAssert
178
assertThat(Instant actual) → InstantAssert
179
assertThat(Duration actual) → DurationAssert
180

181
// Date/Time methods
182
LocalDateAssert isBefore(LocalDate date)
183
LocalDateTimeAssert isAfter(LocalDateTime dateTime)
184
InstantAssert isCloseTo(Instant instant, TemporalUnitWithinOffset offset)
185
DurationAssert isEqualTo(Duration expected)
186
```
187

188
[Dates and Times](./dates-times.md)
189

190
### Exceptions
191

192
Exception testing with ThrowableAssert for verifying exception types, messages, and causes.
193

194
```java { .api }
195
// Exception assertions
196
assertThatThrownBy(ThrowingCallable callable) → ThrowableAssert
197
assertThatExceptionOfType(Class<? extends Throwable> type) → ThrowableTypeAssert
198
assertThatCode(ThrowingCallable callable) → NotThrownAssert
199

200
// Exception methods
201
ThrowableAssert hasMessage(String message)
202
ThrowableAssert isInstanceOf(Class<?> type)
203
ThrowableAssert hasCause(Throwable cause)
204
ThrowableAssert hasRootCause(Throwable rootCause)
205
```
206

207
[Exceptions](./exceptions.md)
208

209
### Soft Assertions
210

211
Collect multiple assertion failures and report them together instead of failing on first error.
212

213
```java { .api }
214
// Soft assertions
215
SoftAssertions softly = new SoftAssertions()
216
AutoCloseableSoftAssertions softly = new AutoCloseableSoftAssertions()
217

218
// JUnit integration
219
@RegisterExtension
220
JUnitSoftAssertions softly = new JUnitSoftAssertions()
221

222
// Soft assertion methods
223
void assertAll()
224
List<AssertionError> assertionErrorsCollected()
225
```
226

227
[Soft Assertions](./soft-assertions.md)
228

229
### Conditions
230

231
Custom conditions and condition combinators for reusable and composable assertions.
232

233
```java { .api }
234
// Condition creation
235
Condition<T> allOf(Condition<? super T>... conditions)
236
Condition<T> anyOf(Condition<? super T>... conditions)
237
Condition<T> not(Condition<? super T> condition)
238

239
// Using conditions
240
ObjectAssert<T> is(Condition<? super T> condition)
241
ObjectAssert<T> has(Condition<? super T> condition)
242
ObjectAssert<T> satisfies(Condition<? super T> condition)
243
```
244

245
[Conditions](./conditions.md)
246

247
### Advanced Features
248

249
Advanced features including filters, groups, atomic types, concurrent types, and utilities.
250

251
```java { .api }
252
// Filtering and extraction
253
Filters<E> filter(E[] array)
254
ObjectArrayAssert<T> extracting(String... properties)
255

256
// Atomic types
257
assertThat(AtomicInteger actual) → AtomicIntegerAssert
258
assertThat(AtomicReference<T> actual) → AtomicReferenceAssert<T>
259

260
// Concurrent types
261
assertThat(CompletableFuture<T> actual) → CompletableFutureAssert<T>
262
assertThat(Future<T> actual) → FutureAssert<T>
263
```
264

265
[Advanced Features](./advanced.md)
266

267
## Types
268

269
```java { .api }
270
// Core interfaces
271
interface ThrowingCallable {
272
    void call() throws Throwable;
273
}
274

275
interface Condition<T> {
276
    boolean matches(T value);
277
    String description();
278
}
279

280
// Common classes
281
class Offset<T extends Number> {
282
    static Offset<Double> offset(Double value)
283
    static Offset<Float> offset(Float value)
284
}
285

286
class Index {
287
    static Index atIndex(int index)
288
}
289

290
class MapEntry<K, V> {
291
    static <K, V> MapEntry<K, V> entry(K key, V value)
292
}
293
```