Hamcrest Date

A date matching library for Java Hamcrest

What is Hamcrest Date?

Hamcrest Date is an extension library for the Java Hamcrest matcher library which provides Matcher implementations for Java date types including LocalDate, LocalTime, LocalDateTime, ZonedDateTime, and Date.

Downloads

You can obtain Hamcrest Date binaries from maven central. To include in your project:

A maven project

<dependency>
    <groupId>org.exparity</groupId>
    <artifactId>hamcrest-date</artifactId>
    <version>2.0.8</version>
</dependency>

Versions 2.x.x onwards require Java 8. If you are using an earlier version of Java 8 then include version

<dependency>
    <groupId>org.exparity</groupId>
    <artifactId>hamcrest-date</artifactId>
    <version>1.1.0</version>
</dependency>

Binaries

Hamcrest Date has a single binary, hamcrest-date.jar, which contains all the date matchers. Sources and JavaDoc jars are available.

Usage

The matchers are exposed as static methods on the LocalDateMatchers, LocalTimeMatchers, LocalDateTimeMatchers, ZonedDateTimeMatchers, OffsetDateTimeMatchers, SqlDateMatchers and DateMatchers class.

Units of time are imported from the ChronoUnit class:

import static java.time.temporal.ChronoUnit.*;

Each matcher can be imported statically (preferred) or normally:

// static, makes sameDay, within, etc available
import static org.exparity.hamcrest.date.LocalDateMatchers.*;
// non-static, must use qualified LocalDateMatchers.sameDay, etc.
import org.exparity.hamcrest.date.LocalDateMatchers;

For example, with non-static imports:

LocalDate today = LocalDate.now(); myBirthday = LocalDate.of(2015, AUGUST, 9);
MatcherAssert.assertThat(today, LocalDateMatchers.sameDay(myBirthday));

or to test if you're getting closer to your birthday:

LocalDate today = LocalDate.now(); myBirthday = LocalDate.of(2015, AUGUST, 9);
MatcherAssert.assertThat(today, LocalDateMatchers.within(1, ChronoUnit.DAY, myBirthday));

or with static importing:

LocalDate today = LocalDate.now(); myBirthday = LocalDate.of(2015, AUGUST, 9);
assertThat(today, within(1, DAY, myBirthday));

The same matchers are available for all date types so to match LocalDateTime values:

LocalDateTime myAppointment = LocalDateTime.of(2015, AUGUST, 9, 10, 30, 0);
assertThat(LocalDateTime.now(), within(15, MINUTES, myAppointment));

or to match ZonedDateTime values:

ZonedDateTime myAppointment = ZonedDateTime.of(LocalDateTime.of(2015, AUGUST, 9, 10, 30, 0), ZoneId.of("UTC"));
assertThat(ZonedDateTime.now(), within(15, MINUTES, myAppointment));

or to match Instant values:

Instant instant = Instant.now();
assertThat(instant, within(1, SECONDS, Instant.now());

or to match OffsetDateTime values:

OffsetDateTime myAppointment = OffsetDateTime.of(LocalDateTime.of(2015, AUGUST, 9, 10, 30, 0), ZoneOffset.UTC);
assertThat(OffsetDateTime.now(), within(15, MINUTES, myAppointment));

or to match LocalTime values:

LocalTime myAppointment = LocalTime.NOON;
assertThat(LocalTime.now(), within(15, MINUTES, myAppointment));

or to match java.sql.Date values:

java.sql.Date myAppointment = java.sql.Date.valueOf(LocalDate.of(2015, AUGUST, 9);
assertThat(new java.sql.Date(), within(15, MINUTES, myAppointment));

The library includes date matchers for:

after - Test if the actual date is after the reference date
before - Test if the actual date is before the reference date
within - Test if the actual date is within a given period (before or after) of the reference date
sameDay - Test if the actual date is on the same day as the reference date
sameHourOfDay - Test if the actual date is on the same hour of the day as the reference date
sameInstant - Test if the actual date at the same instance as the reference date
sameOrBefore - Test if the actual date is the same or before the reference date
sameOrAfter - Test if the actual date is the same or after the reference date
sameMinuteOfHour - Test if the actual date is on the same minute of the hour as the reference date
sameMonthOfYear - Test if the actual date is on the same month of the year as the reference date
sameSecondOfMinute - Test if the actual date is on the same second of the minute as the reference date
sameDayOfWeek - Test if the actual date is on the same week day as the reference date
sameYear - Test if the actual date is on the same year as the reference date
isInstance - Test if the actual date is at the exact instant
isSecond - Test if the actual date is on the given second
isMinute - Test if the actual date is on the given minute
isHour - Test if the actual date is on the given hour
isDayOfWeek - Test if the actual date is on the given day of the week
isDayOfMonth - Test if the actual date is on the given day of the month
isMonth - Test if the actual date is on the given month
isYear - Test if the actual date is on the given year
isYesterday - Test if the actual date is yesterday
isToday - Test if the actual date is today
isTomorrow - Test if the actual date is tomorrow
isMonday - Test if the actual date is on a monday
isTuesday - Test if the actual date is on a tuesday
isWednesday - Test if the actual date is on a wednesday
isThursday - Test if the actual date is on a thursday
isFriday - Test if the actual date is on a friday
isSaturday - Test if the actual date is on a saturday
isSunday - Test if the actual date is on a sunday
isWeekday - Test if the actual date is on a weekday
isWeekend - Test if the actual date is on a weekend
isJanuary - Test if the actual date is in january
isFebruary - Test if the actual date is in february
isMarch - Test if the actual date is in march
isApril - Test if the actual date is in april
isMay - Test if the actual date is in may
isJune - Test if the actual date is in june
isJuly - Test if the actual date is in july
isAugust - Test if the actual date is in august
isSeptember - Test if the actual date is in september
isOctober - Test if the actual date is in october
isNovember - Test if the actual date is in november
isDecember - Test if the actual date is in december
isLeapYear - Test if the actual date is on a leap year

The Javadocs include examples on all methods so you can look there for examples for specific methods

Source

The source is structured along the lines of the maven standard folder structure for a jar project.

Core classes [src/main/java]
Unit tests [src/test/java]

The source includes a pom.xml for building with Maven

Release Notes

Changes 2.0.7 -> 2.0.8

Fix Issue 37 - Add support for InstantMatchers

Changes 2.0.6 -> 2.0.7

Fix Issue 26 - Use licence consistently in release jar files
Fix Issue 32 - Fix assertion errors for temporals with timezones

Changes 2.0.5 -> 2.0.6

Fix Issue 21 - Add support for changing Locale
Fix Issue 24 - Add OffsetDateTimeMatchers
Fix Issue 27 - (UnsupportedOperationException with java.sql.Date)
Handle java.sql.Date in DateMatchers
Add SqlDateMatchers

Changes 2.0.4 -> 2.0.5

Fix Issue 20 - (DateMatchers.isDay(int, Month, int) not adapted for non-zero time zones)
Support for time zones in temporal fields matchers

Changes 2.0.3 -> 2.0.4

Fix Issue 18 - Add test scope to testng

Changes 2.0.2 -> 2.0.3

Fix Issue 16 - Incorrect assertion message for before
Fix Issue 17 - AM/PM Indicator missing in assertion message

Changes 2.0.1 -> 2.0.2

Add Support for LocalTime

Changes 1.1.0 -> 2.0.0

Add Support for Java 8 date types.
Add new is{*} matchers
Move matcher classes to .core package

Changes 1.0.1 -> 1.1

Remove deprecated uk.co.it.modular.hamcrest.date.DateMatchers.

Changes 1.0.0 -> 1.0.1

Restore and deprecate uk.co.it.modular.hamcrest.date.DateMatchers for backwards compatibility with previous package structure.

Changes 0.9.5 -> 1.0.0

Package change to new organisation org.exparity from uk.co.it.modular
Fixup flaky tests by using local timezone in non-timezone tests

Acknowledgements

Developers:

Stewart Bissett

Thanks to the developers at Java Hamcrest. Without their hardwork and core libraries there'd be nothing to be extend and we be stuck with old school, non-declarative, non-reusable, assertions.

eXparity/hamcrest-date