0
# Dates and Times
1

2
Comprehensive assertions for both legacy Date API and modern java.time API including temporal comparisons, offsets, and period validations.
3

4
## Core Imports
5

6
```java
7
import static org.assertj.core.api.Assertions.*;
8
import java.time.*;
9
import java.time.temporal.ChronoUnit;
10
import java.util.Date;
11
```
12

13
## Capabilities
14

15
### Legacy Date Assertions
16

17
Assertions for java.util.Date objects.
18

19
```java { .api }
20
DateAssert assertThat(Date actual)
21

22
// Date comparison methods
23
DateAssert isBefore(Date date)
24
DateAssert isBeforeOrEqualTo(Date date)
25
DateAssert isAfter(Date date)
26
DateAssert isAfterOrEqualTo(Date date)
27
DateAssert isEqualTo(Date expected)
28
DateAssert isNotEqualTo(Date expected)
29
DateAssert isEqualToIgnoringHours(Date expected)
30
DateAssert isEqualToIgnoringMinutes(Date expected)
31
DateAssert isEqualToIgnoringSeconds(Date expected)
32
DateAssert isEqualToIgnoringMillis(Date expected)
33

34
// Date range methods
35
DateAssert isBetween(Date start, Date end)
36
DateAssert isStrictlyBetween(Date start, Date end)
37
DateAssert isCloseTo(Date expected, long deltaInMilliseconds)
38

39
// Date component methods
40
DateAssert isInSameYearAs(Date date)
41
DateAssert isInSameMonthAs(Date date)
42
DateAssert isInSameDayAs(Date date)
43
DateAssert isInSameHourAs(Date date)
44
DateAssert isInSameMinuteAs(Date date)
45
DateAssert isInSameSecondAs(Date date)
46

47
// Date specific checks
48
DateAssert isToday()
49
DateAssert isInThePast()
50
DateAssert isInTheFuture()
51
```
52

53
Usage examples:
54
```java
55
Date now = new Date();
56
Date yesterday = new Date(System.currentTimeMillis() - 24 * 60 * 60 * 1000);
57
Date tomorrow = new Date(System.currentTimeMillis() + 24 * 60 * 60 * 1000);
58

59
assertThat(now)
60
    .isToday()
61
    .isAfter(yesterday)
62
    .isBefore(tomorrow)
63
    .isInSameDayAs(now);
64

65
assertThat(yesterday).isInThePast();
66
assertThat(tomorrow).isInTheFuture();
67
```
68

69
### LocalDate Assertions
70

71
Assertions for LocalDate objects.
72

73
```java { .api }
74
LocalDateAssert assertThat(LocalDate actual)
75

76
// LocalDate comparison methods
77
LocalDateAssert isBefore(LocalDate date)
78
LocalDateAssert isBeforeOrEqualTo(LocalDate date)
79
LocalDateAssert isAfter(LocalDate date)
80
LocalDateAssert isAfterOrEqualTo(LocalDate date)
81
LocalDateAssert isEqualTo(LocalDate expected)
82
LocalDateAssert isNotEqualTo(LocalDate expected)
83

84
// LocalDate range methods
85
LocalDateAssert isBetween(LocalDate start, LocalDate end)
86
LocalDateAssert isStrictlyBetween(LocalDate start, LocalDate end)
87
LocalDateAssert isCloseTo(LocalDate expected, TemporalUnitWithinOffset offset)
88

89
// LocalDate component methods
90
LocalDateAssert hasYear(int year)
91
LocalDateAssert hasMonth(Month month)
92
LocalDateAssert hasMonthValue(int month)
93
LocalDateAssert hasDayOfMonth(int dayOfMonth)
94
LocalDateAssert hasDayOfWeek(DayOfWeek dayOfWeek)
95
LocalDateAssert hasDayOfYear(int dayOfYear)
96

97
// LocalDate specific checks
98
LocalDateAssert isToday()
99
LocalDateAssert isYesterday()
100
LocalDateAssert isTomorrow()
101
LocalDateAssert isInThePast()
102
LocalDateAssert isInTheFuture()
103
LocalDateAssert isWeekend()
104
LocalDateAssert isNotWeekend()
105
LocalDateAssert isLeapYear()
106
LocalDateAssert isNotLeapYear()
107
```
108

109
Usage examples:
110
```java
111
LocalDate today = LocalDate.now();
112
LocalDate birthday = LocalDate.of(1990, Month.JUNE, 15);
113
LocalDate futureDate = LocalDate.of(2025, 12, 31);
114

115
assertThat(today)
116
    .isToday()
117
    .isAfter(birthday)
118
    .isBefore(futureDate);
119

120
assertThat(birthday)
121
    .hasYear(1990)
122
    .hasMonth(Month.JUNE)
123
    .hasDayOfMonth(15)
124
    .isInThePast();
125

126
LocalDate weekend = LocalDate.of(2023, 12, 23); // Saturday
127
assertThat(weekend).isWeekend();
128
```
129

130
### LocalDateTime Assertions
131

132
Assertions for LocalDateTime objects combining date and time.
133

134
```java { .api }
135
LocalDateTimeAssert assertThat(LocalDateTime actual)
136

137
// LocalDateTime comparison methods  
138
LocalDateTimeAssert isBefore(LocalDateTime dateTime)
139
LocalDateTimeAssert isBeforeOrEqualTo(LocalDateTime dateTime)
140
LocalDateTimeAssert isAfter(LocalDateTime dateTime)
141
LocalDateTimeAssert isAfterOrEqualTo(LocalDateTime dateTime)
142
LocalDateTimeAssert isEqualTo(LocalDateTime expected)
143
LocalDateTimeAssert isEqualToIgnoringNanos(LocalDateTime expected)
144
LocalDateTimeAssert isEqualToIgnoringSeconds(LocalDateTime expected)
145
LocalDateTimeAssert isEqualToIgnoringMinutes(LocalDateTime expected)
146
LocalDateTimeAssert isEqualToIgnoringHours(LocalDateTime expected)
147

148
// LocalDateTime range methods
149
LocalDateTimeAssert isBetween(LocalDateTime start, LocalDateTime end)
150
LocalDateTimeAssert isStrictlyBetween(LocalDateTime start, LocalDateTime end)
151
LocalDateTimeAssert isCloseTo(LocalDateTime expected, TemporalUnitWithinOffset offset)
152

153
// LocalDateTime component methods (combines LocalDate and LocalTime)
154
LocalDateTimeAssert hasYear(int year)
155
LocalDateTimeAssert hasHour(int hour)
156
LocalDateTimeAssert hasMinute(int minute)
157
LocalDateTimeAssert hasSecond(int second)
158
LocalDateTimeAssert hasNano(int nano)
159
```
160

161
Usage examples:
162
```java
163
LocalDateTime now = LocalDateTime.now();
164
LocalDateTime meeting = LocalDateTime.of(2023, 12, 25, 14, 30);
165
LocalDateTime deadline = now.plusHours(2);
166

167
assertThat(now)
168
    .isBefore(deadline)
169
    .isCloseTo(now, within(1, ChronoUnit.SECONDS));
170

171
assertThat(meeting)
172
    .hasYear(2023)
173
    .hasHour(14)
174
    .hasMinute(30)
175
    .isEqualToIgnoringSeconds(LocalDateTime.of(2023, 12, 25, 14, 30, 45));
176
```
177

178
### LocalTime Assertions
179

180
Assertions for LocalTime objects.
181

182
```java { .api }
183
LocalTimeAssert assertThat(LocalTime actual)
184

185
// LocalTime comparison methods
186
LocalTimeAssert isBefore(LocalTime time)
187
LocalTimeAssert isBeforeOrEqualTo(LocalTime time)
188
LocalTimeAssert isAfter(LocalTime time)
189
LocalTimeAssert isAfterOrEqualTo(LocalTime time)
190
LocalTimeAssert isEqualTo(LocalTime expected)
191
LocalTimeAssert isEqualToIgnoringNanos(LocalTime expected)
192
LocalTimeAssert isEqualToIgnoringSeconds(LocalTime expected)
193

194
// LocalTime range methods
195
LocalTimeAssert isBetween(LocalTime start, LocalTime end)
196
LocalTimeAssert isStrictlyBetween(LocalTime start, LocalTime end)
197

198
// LocalTime component methods
199
LocalTimeAssert hasHour(int hour)
200
LocalTimeAssert hasMinute(int minute)
201
LocalTimeAssert hasSecond(int second)
202
LocalTimeAssert hasNano(int nano)
203
```
204

205
Usage examples:
206
```java
207
LocalTime now = LocalTime.now();
208
LocalTime noon = LocalTime.of(12, 0);
209
LocalTime evening = LocalTime.of(18, 30, 45);
210

211
assertThat(evening)
212
    .isAfter(noon)
213
    .hasHour(18)
214
    .hasMinute(30)
215
    .hasSecond(45);
216

217
assertThat(now).isBetween(LocalTime.MIN, LocalTime.MAX);
218
```
219

220
### Instant Assertions
221

222
Assertions for Instant objects representing precise moments in time.
223

224
```java { .api }
225
InstantAssert assertThat(Instant actual)
226

227
// Instant comparison methods
228
InstantAssert isBefore(Instant instant)
229
InstantAssert isBeforeOrEqualTo(Instant instant)
230
InstantAssert isAfter(Instant instant)
231
InstantAssert isAfterOrEqualTo(Instant instant)
232
InstantAssert isEqualTo(Instant expected)
233

234
// Instant range methods
235
InstantAssert isBetween(Instant start, Instant end)
236
InstantAssert isStrictlyBetween(Instant start, Instant end)
237
InstantAssert isCloseTo(Instant expected, TemporalUnitWithinOffset offset)
238

239
// Instant specific checks
240
InstantAssert isInThePast()
241
InstantAssert isInTheFuture()
242
```
243

244
Usage examples:
245
```java
246
Instant now = Instant.now();
247
Instant start = Instant.ofEpochSecond(1640995200); // 2022-01-01T00:00:00Z
248
Instant end = now.plusSeconds(3600);
249

250
assertThat(now)
251
    .isAfter(start)
252
    .isBefore(end)
253
    .isCloseTo(now, within(1, ChronoUnit.SECONDS));
254
```
255

256
### ZonedDateTime Assertions
257

258
Assertions for ZonedDateTime objects with timezone information.
259

260
```java { .api }
261
ZonedDateTimeAssert assertThat(ZonedDateTime actual)
262

263
// ZonedDateTime comparison methods
264
ZonedDateTimeAssert isBefore(ZonedDateTime dateTime)
265
ZonedDateTimeAssert isAfter(ZonedDateTime dateTime)
266
ZonedDateTimeAssert isEqualTo(ZonedDateTime expected)
267
ZonedDateTimeAssert isEqualToIgnoringNanos(ZonedDateTime expected)
268
ZonedDateTimeAssert isEqualToIgnoringSeconds(ZonedDateTime expected)
269
ZonedDateTimeAssert isEqualToIgnoringMinutes(ZonedDateTime expected)
270
ZonedDateTimeAssert isEqualToIgnoringHours(ZonedDateTime expected)
271

272
// ZonedDateTime range methods
273
ZonedDateTimeAssert isBetween(ZonedDateTime start, ZonedDateTime end)
274
ZonedDateTimeAssert isCloseTo(ZonedDateTime expected, TemporalUnitWithinOffset offset)
275

276
// Zone-specific methods
277
ZonedDateTimeAssert hasZoneId(ZoneId expected)
278
ZonedDateTimeAssert hasZoneSameInstantAs(ZonedDateTime expected)
279
```
280

281
Usage examples:
282
```java
283
ZonedDateTime utc = ZonedDateTime.now(ZoneId.of("UTC"));
284
ZonedDateTime pst = ZonedDateTime.now(ZoneId.of("America/Los_Angeles"));
285
ZonedDateTime future = utc.plusHours(5);
286

287
assertThat(utc)
288
    .hasZoneId(ZoneId.of("UTC"))
289
    .isBefore(future);
290

291
assertThat(utc)
292
    .hasZoneSameInstantAs(pst.withZoneSameInstant(ZoneId.of("UTC")));
293
```
294

295
### OffsetDateTime and OffsetTime Assertions
296

297
Assertions for offset-based date/time objects.
298

299
```java { .api }
300
OffsetDateTimeAssert assertThat(OffsetDateTime actual)
301
OffsetTimeAssert assertThat(OffsetTime actual)
302

303
// OffsetDateTime methods
304
OffsetDateTimeAssert isBefore(OffsetDateTime dateTime)
305
OffsetDateTimeAssert isAfter(OffsetDateTime dateTime)
306
OffsetDateTimeAssert isEqualTo(OffsetDateTime expected)
307
OffsetDateTimeAssert hasOffset(ZoneOffset expected)
308

309
// OffsetTime methods  
310
OffsetTimeAssert isBefore(OffsetTime time)
311
OffsetTimeAssert isAfter(OffsetTime time)
312
OffsetTimeAssert isEqualTo(OffsetTime expected)
313
OffsetTimeAssert hasOffset(ZoneOffset expected)
314
```
315

316
### Duration Assertions
317

318
Assertions for Duration objects representing time spans.
319

320
```java { .api }
321
DurationAssert assertThat(Duration actual)
322

323
// Duration comparison methods
324
DurationAssert isEqualTo(Duration expected)
325
DurationAssert isNotEqualTo(Duration expected)
326
DurationAssert isGreaterThan(Duration expected)
327
DurationAssert isGreaterThanOrEqualTo(Duration expected)
328
DurationAssert isLessThan(Duration expected)
329
DurationAssert isLessThanOrEqualTo(Duration expected)
330

331
// Duration range methods
332
DurationAssert isBetween(Duration start, Duration end)
333
DurationAssert isStrictlyBetween(Duration start, Duration end)
334
DurationAssert isCloseTo(Duration expected, Duration offset)
335

336
// Duration properties
337
DurationAssert isZero()
338
DurationAssert isNotZero()
339
DurationAssert isPositive()
340
DurationAssert isNegative()
341
DurationAssert hasMillis(long millis)
342
DurationAssert hasNanos(long nanos)
343
DurationAssert hasSeconds(long seconds)
344
DurationAssert hasMinutes(long minutes)
345
DurationAssert hasHours(long hours)
346
DurationAssert hasDays(long days)
347
```
348

349
Usage examples:
350
```java
351
Duration short = Duration.ofMinutes(30);
352
Duration long = Duration.ofHours(2);
353
Duration zero = Duration.ZERO;
354

355
assertThat(short)
356
    .isPositive()
357
    .isLessThan(long)
358
    .hasMinutes(30);
359

360
assertThat(zero).isZero();
361

362
assertThat(long)
363
    .hasHours(2)
364
    .isGreaterThan(short)
365
    .isBetween(Duration.ofMinutes(90), Duration.ofHours(3));
366
```
367

368
### Period Assertions
369

370
Assertions for Period objects representing date-based durations.
371

372
```java { .api }
373
PeriodAssert assertThat(Period actual)
374

375
// Period comparison methods
376
PeriodAssert isEqualTo(Period expected)
377
PeriodAssert isNotEqualTo(Period expected)
378

379
// Period properties
380
PeriodAssert isZero()
381
PeriodAssert isNotZero()
382
PeriodAssert isPositive()
383
PeriodAssert isNegative()
384
PeriodAssert hasYears(int years)
385
PeriodAssert hasMonths(int months)
386
PeriodAssert hasDays(int days)
387
```
388

389
Usage examples:
390
```java
391
Period oneYear = Period.ofYears(1);
392
Period sixMonths = Period.ofMonths(6);
393
Period thirtyDays = Period.ofDays(30);
394

395
assertThat(oneYear)
396
    .isPositive()
397
    .hasYears(1)
398
    .hasMonths(0)
399
    .hasDays(0);
400

401
assertThat(Period.ZERO).isZero();
402
```
403

404
### YearMonth Assertions
405

406
Assertions for YearMonth objects.
407

408
```java { .api }
409
YearMonthAssert assertThat(YearMonth actual)
410

411
// YearMonth comparison methods
412
YearMonthAssert isBefore(YearMonth yearMonth)
413
YearMonthAssert isAfter(YearMonth yearMonth)
414
YearMonthAssert isEqualTo(YearMonth expected)
415

416
// YearMonth properties
417
YearMonthAssert hasYear(int year)
418
YearMonthAssert hasMonth(Month month)
419
YearMonthAssert hasMonthValue(int month)
420
YearMonthAssert isLeapYear()
421
YearMonthAssert isNotLeapYear()
422
```
423

424
### Temporal Offsets and Utilities
425

426
Temporal offset utilities for precise time comparisons.
427

428
```java { .api }
429
// Temporal offset factory methods
430
TemporalUnitWithinOffset within(long value, TemporalUnit unit)
431
TemporalUnitLessThanOffset byLessThan(long value, TemporalUnit unit)
432
TemporalUnitWithinOffset within(Duration duration)
433

434
// Common offset usage
435
within(5, ChronoUnit.MINUTES)
436
within(30, ChronoUnit.SECONDS)  
437
byLessThan(1, ChronoUnit.HOURS)
438
within(Duration.ofMillis(100))
439
```
440

441
Usage examples:
442
```java
443
LocalDateTime now = LocalDateTime.now();
444
LocalDateTime almostNow = now.plusSeconds(2);
445

446
assertThat(almostNow)
447
    .isCloseTo(now, within(5, ChronoUnit.SECONDS));
448

449
Instant start = Instant.now();
450
Instant end = start.plusMillis(50);
451

452
assertThat(end)
453
    .isCloseTo(start, byLessThan(100, ChronoUnit.MILLIS));
454
```
455

456
## Types
457

458
```java { .api }
459
// Temporal offset classes
460
class TemporalUnitWithinOffset {
461
    static TemporalUnitWithinOffset within(long value, TemporalUnit unit)
462
    static TemporalUnitWithinOffset within(Duration duration)
463
}
464

465
class TemporalUnitLessThanOffset {
466
    static TemporalUnitLessThanOffset byLessThan(long value, TemporalUnit unit)
467
}
468

469
// Java time enums and interfaces
470
enum ChronoUnit implements TemporalUnit {
471
    NANOS, MICROS, MILLIS, SECONDS, MINUTES, HOURS, HALF_DAYS, DAYS, 
472
    WEEKS, MONTHS, YEARS, DECADES, CENTURIES, MILLENNIA, ERAS
473
}
474

475
enum Month {
476
    JANUARY, FEBRUARY, MARCH, APRIL, MAY, JUNE,
477
    JULY, AUGUST, SEPTEMBER, OCTOBER, NOVEMBER, DECEMBER
478
}
479

480
enum DayOfWeek {
481
    MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY
482
}
483

484
// Zone classes
485
class ZoneId {
486
    static ZoneId of(String zoneId)
487
    static ZoneId systemDefault()
488
}
489

490
class ZoneOffset extends ZoneId {
491
    static ZoneOffset of(String offsetId)
492
    static ZoneOffset ofHours(int hours)
493
    static ZoneOffset UTC
494
}
495
```