Jest Date Mock

Common errors

• TypeError: Date.now is not a function

  cause `jest-date-mock` was not correctly configured in Jest's `setupFiles`, or the setup file itself was not properly loaded.
  fix Verify that `jest-date-mock` is listed in `jest.setupFiles` in your `package.json` or that the custom setup file requiring it is correctly path-referenced.

• Expected date to be ... but received ... (time difference)

  cause The `Date` object was not mocked or was reset unexpectedly, causing tests to use the actual system time. This can also happen if `clear()` was called without a subsequent `advanceTo()` in a later test.
  fix Ensure `jest-date-mock` is correctly set up globally, and use `advanceTo(new Date(someValue))` at the beginning of each test or in a `beforeEach` hook to ensure a consistent starting date for every test. Explicitly use `clear()` in an `afterEach` only if you re-initialize the mock in `beforeEach`.

• The value of `Date.name` is not 'Date'.

  cause Using an older version of `jest-date-mock` (prior to v1.0.8) which incorrectly altered the `Date.name` property, affecting libraries that check this for type validation.
  fix Upgrade `jest-date-mock` to version `1.0.8` or newer to resolve the `Date.name` inconsistency.

• performance.now() returns real time or is undefined.

  cause `performance.now()` mocking was added in version 1.0.9. Older versions do not mock this API. Alternatively, `performance` might not be defined in the test environment.
  fix Upgrade `jest-date-mock` to version `1.0.9` or higher. If `performance` is still an issue, ensure your test environment (e.g., JSDOM in Jest) supports `window.performance`.

Warnings

• gotcha Forgetting to add `jest-date-mock` to Jest's `setupFiles` configuration will prevent `Date` from being mocked, leading to tests failing due to incorrect time values.
  Fix: Ensure `jest-date-mock` is listed in the `setupFiles` array within your `jest` configuration in `package.json` or linked via a setup file. Example: `"jest": { "setupFiles": ["jest-date-mock"] }`.
• gotcha `jest-date-mock` specifically mocks `Date` and `performance.now()`. It does not mock other time-related functions like `setTimeout`, `setInterval`, or `requestAnimationFrame`. For these, Jest's built-in `jest.useFakeTimers()` is typically required.
  Fix: If your tests depend on mocking `setTimeout` or other timers, use `jest.useFakeTimers()` in conjunction with, or instead of, `jest-date-mock`. Consider `jest.setSystemTime()` and `jest.advanceTimersByTime()` for Jest's native date mocking.
• breaking Prior to version 1.0.8, `jest-date-mock` incorrectly set `Date.name` to an empty string, which could break third-party libraries (e.g., Mongoose) that rely on `Date.name === 'Date'`. This was a silent behavior change.
  Fix: Upgrade `jest-date-mock` to version `1.0.8` or newer to ensure `Date.name` is correctly preserved as 'Date'.
• gotcha Calling `clear()` permanently shuts down the mock system for the current test scope. If not properly managed (e.g., by calling `advanceTo()` or reloading the mock in subsequent tests or `beforeEach` blocks), subsequent tests may unexpectedly receive real date values or encounter errors.
  Fix: Always ensure your mock state is reset between tests. Use `advanceTo()` at the beginning of each test or in a `beforeEach` hook to establish a consistent starting point, rather than solely relying on `clear()`.
• gotcha Timezone differences can cause inconsistent date test results across different environments (local machine vs. CI/CD).
  Fix: Set a consistent timezone for your Jest tests. Add `process.env.TZ = 'UTC';` (or your desired timezone) to your Jest `setupFiles` or directly in your `jest.config.js` to standardize date calculations.

Install

• npm install jest-date-mock npm
• yarn add jest-date-mock yarn
• pnpm add jest-date-mock pnpm

Imports

• advanceTo
  wrong:

  const { advanceTo } = require('jest-date-mock');

  correct:

  import { advanceTo } from 'jest-date-mock';

  While CommonJS `require` works for the main setup file, named imports are preferred for API functions in modern Jest/TypeScript setups.
• advanceBy
  wrong:

  require('jest-date-mock').advanceBy;

  correct:

  import { advanceBy } from 'jest-date-mock';

  ESM named imports are the idiomatic way to access utility functions.
• setupFiles
  wrong:

  require('jest-date-mock');

  correct:

  import 'jest-date-mock';

  For Jest's `setupFiles`, both ESM `import` and CommonJS `require` statements are supported directly within the setup file. The library provides TypeScript types.

Quickstart

Demonstrates setting a fixed date, advancing time, resetting the date, and verifying both `Date.now()` and `performance.now()` are mocked, with `Date.current()` for real time access.

import { advanceBy, advanceTo, clear } from 'jest-date-mock';

describe('Date mocking', () => {
  // Set the date to a fixed point in time
  beforeEach(() => {
    advanceTo(new Date(2023, 10, 21, 10, 0, 0)); // November 21, 2023, 10:00:00 AM
  });

  // Clear the mock after each test to ensure isolation
  afterEach(() => {
    clear();
  });

  test('should return the mocked date and allow advancing time', () => {
    const initialTimestamp = Date.now();
    expect(new Date().getFullYear()).toBe(2023);
    expect(new Date().getMonth()).toBe(10); // November is month 10
    expect(new Date().getDate()).toBe(21);
    expect(Date.current()).not.toBe(initialTimestamp); // Date.current() gets the actual system time

    advanceBy(5000); // Advance time by 5 seconds
    expect(Date.now() - initialTimestamp).toBe(5000);

    advanceBy(60 * 1000); // Advance time by 1 minute
    expect(new Date().getMinutes()).toBe(1);

    advanceTo(new Date(2024, 0, 1, 0, 0, 0)); // Reset to Jan 1, 2024
    expect(new Date().getFullYear()).toBe(2024);
  });

  test('performance.now() should also be mocked and advance', () => {
    const initialPerformanceNow = performance.now();
    advanceBy(100);
    expect(performance.now() - initialPerformanceNow).toBe(100);
  });
});