@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

26.0.0

Features

• [jest-environment-jsdom] [BREAKING] Upgrade jsdom to v16 (#9606)
• [@jest/fake-timers] Add possibility to use a modern implementation of fake timers, backed by @sinonjs/fake-timers (#7776)
• [jest-runtime] Add createMockFromModule as an alias for genMockFromModule (#9962)

Fixes

• [babel-jest] Handle null being passed to createTransformer (#9955)
• [jest-circus, jest-console, jest-jasmine2, jest-reporters, jest-util, pretty-format] Fix time durating formatting and consolidate time formatting code (#9765)
• [jest-circus] [BREAKING] Fail tests if a test takes a done callback and have return values (#9129)
• [jest-circus] [BREAKING] Throw a proper error if a test / hook is defined asynchronously (#8096)
• [jest-circus] Throw more descriptive error if hook is defined inside test (#9957)
• [jest-circus] [BREAKING] Align execution order of tests to match jasmine's top to bottom order (#9965)
• [jest-config, jest-resolve] [BREAKING] Remove support for browser field (#9943)
• [jest-haste-map] Stop reporting files as changed when they are only accessed (#7347)
• [jest-resolve] Show relative path from root dir for module not found errors (#9963)
• [jest-runtime] Fix absolute path moduleNameMapper + jest.mock bug (#8727)

Chore & Maintenance

• [*] [BREAKING] TypeScript definitions requires a minimum of TypeScript v3.8 (#9823)
• [*] [BREAKING] Drop support for Node 8 (#9423)
• [*] Upgrade to chalk@4 (#9752)
• [*] Remove usage of realpath-native (#9952)
• [docs] Fix example reference implementation to use Jest with Phabricator (#8662)
• [docs] Added default compiler to transform (#8583)
• [docs] Updated Testing Frameworks guide with React; make it generic (#9106)
• [expect, jest-mock, pretty-format] [BREAKING] Remove build-es5 from package (#9945)
• [@jest/fake-timers, @jest/environment] [BREAKING] Rename LolexFakeTimers to ModernFakeTimers (#9960)
• [jest-haste-map] [BREAKING] removed providesModuleNodeModules (#8535)
• [jest-runtime] [BREAKING] Remove long-deprecated require.requireActual and require.requireMock methods (#9854)