NOTE: Fork of jest-date
!versionversion-badgepackage !downloadsdownloads-badgenpmtrends
!Watch on GitHubgithub-watch-badgegithub-watch !Star on GitHubgithub-star-badgegithub-star
- Relative matchers - Weekday matchers -
Alternatively, you can selectively import only the matchers you intend to use, and extend jest's
Here are some concrete examples:
Standard Message:
Inverted Message:
Here are some concrete examples:
Matcher type: relative
This allows you to check whether a date is before another.
Matcher type: relative
This allows you to check whether a date is after another.
Matcher type: relative
This allows you to check whether a date is in the same second as another.
Matcher type: relative
This allows you to check whether a date is in the same minute as another.
Matcher type: relative
This allows you to check whether a date is in the same hour as another.
Matcher type: relative
This allows you to check whether a date is in the same day as another.
Matcher type: relative
This allows you to check whether a date is in the same week as another.
Matcher type: relative
This allows you to check whether a date is in the same month as another.
Matcher type: relative
This allows you to check whether a date is in the same quarter as another.
Matcher type: relative
This allows you to check whether a date is in the same year as another.
Matcher type: relative
This allows you to check whether a date is within 1 minute as another.
Matcher type: weekday
This allows you to check whether a date is on a monday.
Matcher type: weekday
This allows you to check whether a date is on a tuesday.
Matcher type: weekday
This allows you to check whether a date is on a wednesday.
Matcher type: weekday
This allows you to check whether a date is on a thursday.
Matcher type: weekday
This allows you to check whether a date is on a friday.
Matcher type: weekday
This allows you to check whether a date is on a saturday.
Matcher type: weekday
This allows you to check whether a date is on a Sunday.
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-domjest-dom
jest-date-2
height="80"
width="80"
alt="calendar"
src="https://raw.githubusercontent.com/Stefanwullems/jest-date/master/other/calendar.png"
/>
Custom jest matchers to compare dates
!versionversion-badgepackage !downloadsdownloads-badgenpmtrends
!Watch on GitHubgithub-watch-badgegithub-watch !Star on GitHubgithub-star-badgegithub-star
The problem
You want to use jestjest 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 and you want to get valueable feedback when tests fail.This solution
Thejest-date-2
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. Next to that, it will give you valueable information as to why
your test are failing.Table of Contents
- Relative matchers - Weekday matchers -
toBeBefore
- toBeAfter
- toBeSameSecondAs
- toBeSameMinuteAs
- toBeSameHourAs
- toBeSameDayAs
- toBeSameWeekAs
- toBeSameMonthAs
- toBeSameQuarterAs
- toBeSameYearAs
- toBeWithinMinuteAs
- toBeMonday
- toBeTuesday
- toBeWednesday
- toBeThursday
- toBeFriday
- toBeSaturday
- toBeSunday
Installation
This module is distributed via npmnpm which is bundled with nodenode and should be installed as one of your project'sdevDependencies
:npm install --save-dev jest-date-2
Usage
Importjest-date-2
once (for instance in your tests setup file) and you're
good to go:import 'jest-date-2'
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-2/matchers'
expect.extend({toBeBefore, toBeSameMonthAs})
Note: when using TypeScript, this way of importing matchers won't provide the necessary type definitions.
Matcher types
Relative matchers
Relative matchers can be used to compare two dates with eachother. When a matcher fails, it will provide a debug message in the following format:Expected date {expected_date} {matcher} {received_date}, but it was {difference}.
Here are some concrete examples:
toBeSameSecondAs
:
Expected date 2020-07-13T22:05:23.670Z to be same second as 2020-07-13T22:05:22.670Z, but it was 1 second after.
toBeBefore
:
Expected date 1970-01-01T00:00:00.000Z not to be before 2020-01-01T00:00:00.000Z, but it was 50 years before.
toBeSameQuarterAs
:
Expected date 2020-10-13T22:15:12.304Z to be same quarter as 2020-07-13T22:15:12.304Z, but it was 3 months after.
Weekday matchers
Weekday matchers can be used to check if a given date falls on a certain day of the week. When this kind of a matcher fails, it will provide a debug message in either the following formats:Standard Message:
Expected date {received} to be on a {expected_day}, but it was on a {actual_day}.
Inverted Message:
Expected date {received} not be on a {expected_day}, but it was
Here are some concrete examples:
toBeMonday
:
Expected date 2020-07-13T22:25:43.553Z to be on a monday, but it was on a tuesday.
toBeSunday
:
Expected date 2020-07-11T22:26:33.626Z not to be on a sunday, but it was.
Custom matchers
jest-date-2
can work with any library or framework. The custom matcher
examples below are written using functions from the awesome date-fnsdate-fns
library (e.g. isBefore
, isSameDayAs
, formatDistance
, etc.)toBeBefore
Matcher type: relativetoBeBefore(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
Matcher type: relativetoBeAfter(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
Matcher type: relativetoBeSameSecondAs(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
Matcher type: relativetoBeSameMinuteAs(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
Matcher type: relativetoBeSameHourAs(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
Matcher type: relativetoBeSameDayAs(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
Matcher type: relativetoBeSameWeekAs(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
Matcher type: relativetoBeSameMonthAs(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
Matcher type: relativetoBeSameQuarterAs(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
Matcher type: relativetoBeSameYearAs(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
toBeWithinMinuteAs
Matcher type: relativetoBeWithinMinuteAs(date: Date)
This allows you to check whether a date is within 1 minute as another.
Examples
import {addSeconds} from 'date-fns'
const date = new Date()
expect(addSeconds(date, 59)).toBeWithinMinuteAs(date) // ✔️ pass
expect(addSeconds(date, 60)).toBeWithinMinuteAs(date) // ❌ fail
expect(addSeconds(date, 1)).not.toBeWithinMinuteAs(date) // ❌ fail
expect(addSeconds(date, 61)).not.toBeWithinMinuteAs(date) // ✔️ pass
toBeMonday
Matcher type: weekdaytoBeMonday()
This allows you to check whether a date is on a monday.
Examples
expect(new Date()).toBeMonday()
expect(new Date()).not.toBeMonday()
toBeTuesday
Matcher type: weekdaytoBeTuesday()
This allows you to check whether a date is on a tuesday.
Examples
expect(new Date()).toBeTuesday()
expect(new Date()).not.toBeTuesday()
toBeWednesday
Matcher type: weekdaytoBeWednesday()
This allows you to check whether a date is on a wednesday.
Examples
expect(new Date()).toBeWednesday()
expect(new Date()).not.toBeWednesday()
toBeThursday
Matcher type: weekdaytoBeThursday()
This allows you to check whether a date is on a thursday.
Examples
expect(new Date()).toBeThursday()
expect(new Date()).not.toBeThursday()
toBeFriday
Matcher type: weekdaytoBeFriday()
This allows you to check whether a date is on a friday.
Examples
expect(new Date()).toBeFriday()
expect(new Date()).not.toBeFriday()
toBeSaturday
Matcher type: weekdaytoBeSaturday()
This allows you to check whether a date is on a saturday.
Examples
expect(new Date()).toBeSaturday()
expect(new Date()).not.toBeSaturday()
toBeSunday
Matcher type: weekdaytoBeSunday()
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-fnsdate-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-domjest-dom