@jest/fake-timers

What is @jest/fake-timers?

@jest/fake-timers is a package that provides fake timer functions for Jest, a popular JavaScript testing framework. It allows you to control the passage of time in your tests, making it easier to test code that relies on timers, such as setTimeout, setInterval, and Date.

What are @jest/fake-timers's main functionalities?

Mocking setTimeout and setInterval

This feature allows you to mock setTimeout and setInterval functions, enabling you to control the passage of time in your tests. The code sample demonstrates how to use jest.useFakeTimers() to mock the timers and jest.advanceTimersByTime() to fast-forward time.

const { jest } = require('@jest/globals');

jest.useFakeTimers();

setTimeout(() => {
  console.log('This will be logged after 1 second');
}, 1000);

jest.advanceTimersByTime(1000); // Fast-forward time by 1 second

// Output: 'This will be logged after 1 second'

Mocking Date

This feature allows you to mock the Date object, enabling you to control the current date and time in your tests. The code sample demonstrates how to use jest.useFakeTimers('modern') to mock the Date object and jest.setSystemTime() to set a specific date and time.

const { jest } = require('@jest/globals');

jest.useFakeTimers('modern');

const now = Date.now();
console.log(now); // Outputs the current timestamp

jest.setSystemTime(new Date('2020-01-01'));

const newNow = Date.now();
console.log(newNow); // Outputs the timestamp for 2020-01-01

Clearing timers

This feature allows you to clear mocked timers, ensuring that the associated callbacks are not executed. The code sample demonstrates how to use clearTimeout() to clear a setTimeout timer.

const { jest } = require('@jest/globals');

jest.useFakeTimers();

const timeoutId = setTimeout(() => {
  console.log('This will not be logged');
}, 1000);

clearTimeout(timeoutId);

jest.advanceTimersByTime(1000); // Fast-forward time by 1 second

// No output

Other packages similar to @jest/fake-timers

sinon

Sinon is a popular standalone test spies, stubs, and mocks library for JavaScript. It provides similar functionalities to @jest/fake-timers, including the ability to mock timers and control the passage of time. However, Sinon is not tied to any specific testing framework and can be used with various testing libraries.

lolex

Lolex is a standalone library for creating fake timers and controlling the passage of time. It provides similar functionalities to @jest/fake-timers, such as mocking setTimeout, setInterval, and Date. Lolex can be used independently or integrated with other testing frameworks.

README

The README file is missing

Changelog

27.1.0

Features

• [jest-haste-map] Use watchman suffix-set option for faster file indexing. (#11784)
• [jest-cli] Adds a new config options snapshotFormat which offers a way to override any of the formatting settings which come with pretty-format. (#11654)
• [jest-reporters] Expose the getSummary util (#11695).
• [jest-resolver] Support node: prefix when importing Node core modules (#11331)

Fixes

• [jest-each] Relaxed the validation to allow multibyte characters in headings (#11575)
• [jest-environment-jsdom] Add support for userAgent option (#11773)
• [jest-environment-node] Add Event and EventTarget to node global environment. (#11727)
• [jest-mock] Fix spyOn to use Object.prototype.hasOwnProperty (#11721)
• [jest-resolver] Add dependency on jest-haste-map (#11759)
• [jest-types] Compat with @types/node v16 (#11645)

Chore & Maintenance

• [docs] Correct expects.assertions documentation by adding async/await for asynchronous function.