Hamcrest Date

A date matching library for Java Hamcrest

Licensed under BSD License.

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.4</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, and DateMatchers class. For example

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 after 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 LocalTime values:

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

The libary 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.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.