hamcrest date

A Java library which provides a suite hamcrest matchers for matching dates, times, and moments in time

eXparity
71
11
Java

Hamcrest Date Build Status Coverage Status

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