search

eXparity / hamcrest-date

A Java library which provides a suite hamcrest matchers for matching dates, times, and moments in time
BSD 3-Clause "New" or "Revised" License
70 stars 11 forks source link

readme

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:

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.

The source includes a pom.xml for building with Maven

Release Notes

Changes 2.0.7 -> 2.0.8

Changes 2.0.6 -> 2.0.7

Changes 2.0.5 -> 2.0.6

Changes 2.0.4 -> 2.0.5

Changes 2.0.3 -> 2.0.4

Changes 2.0.2 -> 2.0.3

Changes 2.0.1 -> 2.0.2

Changes 1.1.0 -> 2.0.0

Changes 1.0.1 -> 1.1

Changes 1.0.0 -> 1.0.1

Changes 0.9.5 -> 1.0.0

Acknowledgements

Developers:

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.