jest-date

jest-date

Custom jest matchers to compare dates against eachother

---

The problem

You want to use jest to write tests that assert how dates compare to eachother. As part of that goal, you want to avoid all the repetitive patterns that arise in doing so.

This solution

The jest-date library provides a set of custom jest matchers that you can use to extend jest. These will make your tests more declarative, clear to read and to maintain.

Table of Contents

• Installation
• Usage
• Custom matchers
  • toBeBefore
  • toBeAfter
  • toBeSameSecondAs
  • toBeSameMinuteAs
  • toBeSameHourAs
  • toBeSameDayAs
  • toBeSameWeekAs
  • toBeSameMonthAs
  • toBeSameQuarterAs
  • toBeSameYearAs
  • toBeMonday
  • toBeTuesday
  • toBeWednesday
  • toBeThursday
  • toBeFriday
  • toBeSaturday
  • toBeSunday
• Inspiration
• LICENSE

Installation

This module is distributed via npm which is bundled with node and should be installed as one of your project's devDependencies:

npm install --save-dev jest-date

Usage

Import jest-date once (for instance in your tests setup file) and you're good to go:

import 'jest-date'

Note: If you're using TypeScript, make sure your setup file is a .ts and not a .js to include the necessary types.

Alternatively, you can selectively import only the matchers you intend to use, and extend jest's expect yourself:

import {
  toBeBefore,
  toBeSameMonthAs,
} from 'jest-date/matchers'

expect.extend({toBeBefore, toBeSameMonthAs})

Note: when using TypeScript, this way of importing matchers won't provide the necessary type definitions.

Custom matchers

jest-date can work with any library or framework. The custom matcher examples below are written using functions from the awesome date-fns library (e.g. isBefore, isSameDayAs, formatDistance, etc.)

toBeBefore

toBeBefore(date: Date)

This allows you to check whether a date is before another.

Examples

expect(new Date('1970')).toBeBefore(new Date('2020')) // ✔️ pass
expect(new Date('2020')).toBeBefore(new Date('1970')) // ❌ fail

expect(new Date('1970')).not.toBeBefore(new Date('2020')) // ❌ fail
expect(new Date('2020')).not.toBeBefore(new Date('1970')) // ✔️ pass

---

toBeAfter

toBeAfter(date: Date)

This allows you to check whether a date is after another.

Examples

expect(new Date('2020')).toBeAfter(new Date('1970')) // ✔️ pass
expect(new Date('1970')).toBeAfter(new Date('2020')) // ❌ fail

expect(new Date('2020')).not.toBeAfter(new Date('1970')) // ❌ fail
expect(new Date('1970')).not.toBeAfter(new Date('2020')) // ✔️ pass

toBeSameSecondAs

toBeSameSecondAs(date: Date)

This allows you to check whether a date is in the same second as another.

Examples

import {startOfSecond, addSeconds} from 'date-fns'

const date = new Date()

expect(startOfSecond(date)).toBeSameSecondAs(date) // ✔️ pass
expect(addSeconds(date, 2)).toBeSameSecondAs(date) // ❌ fail

expect(startOfSecond(date)).not.toBeSameSecondAs(date) // ❌ fail
expect(addSeconds(date, 2)).not.toBeSameSecondAs(date) // ✔️ pass

---

toBeSameMinuteAs

toBeSameMinuteAs(date: Date)

This allows you to check whether a date is in the same minute as another.

Examples

import {startOfMinute, addMinutes} from 'date-fns'

const date = new Date()

expect(startOfMinute(date)).toBeSameMinuteAs(date) // ✔️ pass
expect(addMinutes(date, 2)).toBeSameMinuteAs(date) // ❌ fail

expect(startOfMinute(date)).not.toBeSameMinuteAs(date) // ❌ fail
expect(addMinutes(date, 2)).not.toBeSameMinuteAs(date) // ✔️ pass

---

toBeSameHourAs

toBeSameHourAs(date: Date)

This allows you to check whether a date is in the same hour as another.

Examples

import {startOfHour, addHours} from 'date-fns'

const date = new Date()

expect(startOfHour(date)).toBeSameHourAs(date) // ✔️ pass
expect(addHours(date, 2)).toBeSameHourAs(date) // ❌ fail

expect(startOfHour(date)).not.toBeSameHourAs(date) // ❌ fail
expect(addHours(date, 2)).not.toBeSameHourAs(date) // ✔️ pass

---

toBeSameDayAs

toBeSameDayAs(date: Date)

This allows you to check whether a date is in the same day as another.

Examples

import {startOfDay, addDays} from 'date-fns'

const date = new Date()

expect(startOfDay(date)).toBeSameDayAs(date) // ✔️ pass
expect(addDays(date, 2)).toBeSameDayAs(date) // ❌ fail

expect(startOfDay(date)).not.toBeSameDayAs(date) // ❌ fail
expect(addDays(date, 2)).not.toBeSameDayAs(date) // ✔️ pass

---

toBeSameWeekAs

toBeSameWeekAs(date: Date)

This allows you to check whether a date is in the same week as another.

Examples

import {startOfWeek, addWeeks} from 'date-fns'

const date = new Date()

expect(startOfWeek(date)).toBeSameWeekAs(date) // ✔️ pass
expect(addWeeks(date, 2)).toBeSameWeekAs(date) // ❌ fail

expect(startOfWeek(date)).not.toBeSameWeekAs(date) // ❌ fail
expect(addWeeks(date, 2)).not.toBeSameWeekAs(date) // ✔️ pass

---

toBeSameMonthAs

toBeSameMonthAs(date: Date)

This allows you to check whether a date is in the same month as another.

Examples

import {startOfMonth, addMonths} from 'date-fns'

const date = new Date()

expect(startOfMonth(date)).toBeSameMonthAs(date) // ✔️ pass
expect(addMonths(date, 2)).toBeSameMonthAs(date) // ❌ fail

expect(startOfMonth(date)).not.toBeSameMonthAs(date) // ❌ fail
expect(addMonths(date, 2)).not.toBeSameMonthAs(date) // ✔️ pass

---

toBeSameQuarterAs

toBeSameQuarterAs(date: Date)

This allows you to check whether a date is in the same quarter as another.

Examples

import {startOfQuarter, addQuarters} from 'date-fns'

const date = new Date()

expect(startOfQuarter(date)).toBeSameQuarterAs(date) // ✔️ pass
expect(addQuarters(date, 2)).toBeSameQuarterAs(date) // ❌ fail

expect(startOfQuarter(date)).not.toBeSameQuarterAs(date) // ❌ fail
expect(addQuarters(date, 2)).not.toBeSameQuarterAs(date) // ✔️ pass

---

toBeSameYearAs

toBeSameYearAs(date: Date)

This allows you to check whether a date is in the same year as another.

Examples

import {startOfYear, addYears} from 'date-fns'

const date = new Date()

expect(startOfYear(date)).toBeSameYearAs(date) // ✔️ pass
expect(addYears(date, 2)).toBeSameYearAs(date) // ❌ fail

expect(startOfYear(date)).not.toBeSameYearAs(date) // ❌ fail
expect(addYears(date, 2)).not.toBeSameYearAs(date) // ✔️ pass

---

toBeMonday

toBeMonday()

This allows you to check whether a date is on a monday.

Examples

expect(new Date()).toBeMonday()
expect(new Date()).not.toBeMonday()

---

toBeTuesday

toBeTuesday()

This allows you to check whether a date is on a tuesday.

Examples

expect(new Date()).toBeTuesday()
expect(new Date()).not.toBeTuesday()

---

toBeWednesday

toBeWednesday()

This allows you to check whether a date is on a wednesday.

Examples

expect(new Date()).toBeWednesday()
expect(new Date()).not.toBeWednesday()

---

toBeThursday

toBeThursday()

This allows you to check whether a date is on a thursday.

Examples

expect(new Date()).toBeThursday()
expect(new Date()).not.toBeThursday()

---

toBeFriday

toBeFriday()

This allows you to check whether a date is on a friday.

Examples

expect(new Date()).toBeFriday()
expect(new Date()).not.toBeFriday()

---

toBeSaturday

toBeSaturday()

This allows you to check whether a date is on a saturday.

Examples

expect(new Date()).toBeSaturday()
expect(new Date()).not.toBeSaturday()

---

toBeSunday

toBeSunday()

This allows you to check whether a date is on a Sunday.

Examples

expect(new Date()).toBeSunday()
expect(new Date()).not.toBeSunday()

---

Inspiration

This library was created because as far as I know, there is no matcher library out there dedicated to only comparing dates. I ended up using the functions from date-fns to create assertions like this one:

expect(isSameDay(date1, date2)).toBe(true)

But when this fails, you get no feedback at all other than the fact that the dates are not the same day. By making date matchers with helpful failure messages, I hope to make the debugging lives of developers a little bit easier.

Project structure and tooling hugely inspired by @testing-library/jest-dom

LICENSE

MIT