jest-date

library1.1.6jsnpmunverified

jest-date is a utility library providing custom Jest matchers specifically designed for comparing and asserting dates. It simplifies date-related tests by offering a declarative API, such as `toBeBefore`, `toBeSameDayAs`, and `toBeMonday`, eliminating the need for repetitive date manipulation logic in test assertions. The current stable version is 1.1.6, and while no explicit release cadence is stated, its versioning suggests incremental updates. A key differentiator is the helpful, descriptive failure messages it provides, indicating precise differences (e.g., '1 second after' or '3 months after') rather than generic assertion failures, making debugging significantly easier for developers. It leverages underlying date utility libraries, abstracting their complexity for focused testing scenarios.

testing

npm install jest-date

github ↗package ↗

INSTALL

IMPORT

SIG · JEST-DATE

jest-date

testingjavascriptv1.1.6

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Global Extention

✓ import 'jest-date';

✗ require('jest-date');

This import globally extends Jest's `expect` object with all provided date matchers. For TypeScript, ensure this is placed in a `.ts` setup file (e.g., `setupTests.ts`) to correctly include global type definitions for `expect`.

Specific Matchers

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

✗ import toBeBefore from 'jest-date/matchers';

Allows importing specific matchers for manual extension of `expect`. When using this pattern, you must explicitly call `expect.extend({ toBeBefore, toBeSameMonthAs })`. This method does NOT automatically provide type definitions for `expect` in TypeScript; manual type augmentation might be required if not using the global import elsewhere.

TypeScript Types

✓ // Types are automatically included with `import 'jest-date'` in a .ts setup file.

The library ships with TypeScript types. The recommended way to include these types is to use the global `import 'jest-date'` statement within a TypeScript setup file (e.g., `jest.setup.ts`). Direct type imports are generally not necessary or provided.

This quickstart demonstrates how to install `jest-date`, configure it in a Jest setup file, and use various custom matchers like `toBeBefore`, `toBeSameDayAs`, and `toBeMonday` to assert date comparisons in tests, highlighting their readability and expressive failure messages.

import 'jest-date'; describe('jest-date matchers', () => { const date1 = new Date('2023-01-15T10:00:00.000Z'); const date2 = new Date('2023-01-15T11:00:00.000Z'); const date3 = new Date('2023-01-16T10:00:00.000Z'); const date4 = new Date('2023-02-15T10:00:00.000Z'); test('should check if a date is before another', () => { expect(date1).toBeBefore(date2); }); test('should check if a date is on the same day', () => { expect(date1).toBeSameDayAs(date2); expect(date1).not.toBeSameDayAs(date3); }); test('should check if a date is a Monday', () => { const monday = new Date('2023-01-16T10:00:00.000Z'); // Jan 16, 2023 was a Monday expect(monday).toBeMonday(); }); test('should provide detailed failure messages', () => { // This test will intentionally fail to demonstrate the helpful message const futureDate = new Date('2024-01-01T00:00:00.000Z'); const pastDate = new Date('2023-01-01T00:00:00.000Z'); // expect(futureDate).toBeBefore(pastDate); // Would fail with 'Expected date 2024-01-01T00:00:00.000Z to be before 2023-01-01T00:00:00.000Z, but it was 1 year after.' }); });

Debug

Known issues

gotchaWhen using TypeScript, importing specific matchers (e.g., `import { toBeBefore } from 'jest-date/matchers'`) for manual `expect.extend()` does not automatically provide type definitions for the `expect` object. This can lead to TypeScript errors like 'Property 'toBeBefore' does not exist on type 'Expect<any>''.

fix

For full type support, use the global import `import 'jest-date';` in a `.ts` Jest setup file (e.g., `jest.setup.ts`). If you must use selective imports, you will need to manually augment Jest's `Expect` interface in your project's `d.ts` files.

affects: >=1.0.0

gotchaForgetting to import `jest-date` in a Jest setup file (or at all) will result in matchers not being available, leading to runtime errors like 'expect(...).toBeBefore is not a function'.

fix

Ensure `import 'jest-date';` is present in a file configured in Jest's `setupFilesAfterEnv` option. For example, add `"setupFilesAfterEnv": ["<rootDir>/jest.setup.ts"]` to your `jest.config.js` and create `jest.setup.ts` with the import.

affects: >=1.0.0

Errors

Common errors & fixes

Property 'toBeSameDayAs' does not exist on type 'Expect<any>'.

The TypeScript compiler cannot find the type definitions for `jest-date` matchers on the `expect` object.

fix

Ensure you have `import 'jest-date';` in your Jest setup file (e.g., `jest.setup.ts`) and that this file is correctly referenced in your `jest.config.js` under `setupFilesAfterEnv`.

TypeError: expect(...).toBeBefore is not a function

The `jest-date` matchers have not been loaded and extended into Jest's `expect` object.

fix

Verify that `import 'jest-date';` is correctly placed and executed in your Jest test environment's setup, typically within a file specified by Jest's `setupFilesAfterEnv` configuration option.

Upgrade

Version history

1.1.6latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/pkuczynski/jest-date ↗

packagehttps://www.npmjs.com/package/jest-date ↗