CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-jest--fake-timers

A comprehensive fake timer implementation for Jest that provides both legacy and modern timer mocking capabilities, enabling developers to control time flow in tests by mocking JavaScript's built-in timer functions.

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

Jest Fake Timers

Jest Fake Timers provides comprehensive timer mocking capabilities for Jest tests, enabling developers to control time flow by replacing JavaScript's built-in timer functions with controllable fake implementations. It offers two complementary approaches: ModernFakeTimers built on @sinonjs/fake-timers for advanced time control, and LegacyFakeTimers for backward compatibility.

Package Information

  • Package Name: @jest/fake-timers
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @jest/fake-timers

Core Imports

import { ModernFakeTimers, LegacyFakeTimers } from "@jest/fake-timers";
import type { Config } from "@jest/types";

For CommonJS:

const { ModernFakeTimers, LegacyFakeTimers } = require("@jest/fake-timers");
// TypeScript types are available for TypeScript projects

Basic Usage

import { ModernFakeTimers } from "@jest/fake-timers";
import { makeProjectConfig } from "@jest/test-utils";

// Initialize modern fake timers
const fakeTimers = new ModernFakeTimers({
  global: globalThis,
  config: makeProjectConfig()
});

// Enable fake timers
fakeTimers.useFakeTimers();

// Your test code with timers...
setTimeout(() => console.log("Timer executed"), 1000);

// Advance time by 1 second
fakeTimers.advanceTimersByTime(1000);

// Clean up
fakeTimers.useRealTimers();
fakeTimers.dispose();

Architecture

Jest Fake Timers is designed around two main implementations:

  • ModernFakeTimers: Built on @sinonjs/fake-timers, providing comprehensive time control including Date mocking, async timer operations, and advanced scheduling features
  • LegacyFakeTimers: Custom Jest implementation for backward compatibility with older Jest configurations, offering precise control over timer execution order

Both implementations provide:

  • Timer Replacement: Mocks all JavaScript timer APIs (setTimeout, setInterval, etc.)
  • Time Control: Precise advancement of fake time without actual delays
  • State Management: Reset, clear, and query timer states
  • Animation Frame Support: requestAnimationFrame/cancelAnimationFrame mocking
  • Process Control: NextTick and setImmediate handling

Capabilities

Modern Fake Timers

Advanced fake timer implementation with comprehensive time control, async operations, and @sinonjs/fake-timers integration.

interface ModernFakeTimersConstructor {
  new (options: {
    global: typeof globalThis;
    config: Config.ProjectConfig;
  }): ModernFakeTimers;
}

interface ModernFakeTimers {
  useFakeTimers(fakeTimersConfig?: Config.FakeTimersConfig): void;
  useRealTimers(): void;
  runAllTimers(): void;
  runAllTimersAsync(): Promise<void>;
  runOnlyPendingTimers(): void;
  runOnlyPendingTimersAsync(): Promise<void>;
  advanceTimersByTime(msToRun: number): void;
  advanceTimersByTimeAsync(msToRun: number): Promise<void>;
  advanceTimersToNextTimer(steps?: number): void;
  advanceTimersToNextTimerAsync(steps?: number): Promise<void>;
  advanceTimersToNextFrame(): void;
  runAllTicks(): void;
  setSystemTime(now?: number | Date): void;
  getRealSystemTime(): number;
  now(): number;
  reset(): void;
  clearAllTimers(): void;
  getTimerCount(): number;
  dispose(): void;
}

Modern Fake Timers

Legacy Fake Timers

Backward-compatible fake timer implementation with custom Jest timer control and precise execution ordering.

interface LegacyFakeTimersConstructor {
  new <TimerRef = unknown>(options: {
    global: typeof globalThis;
    moduleMocker: ModuleMocker;
    timerConfig: TimerConfig<TimerRef>;
    config: StackTraceConfig;
    maxLoops?: number;
  }): LegacyFakeTimers<TimerRef>;
}

interface LegacyFakeTimers<TimerRef = unknown> {
  useFakeTimers(): void;
  useRealTimers(): void;
  runWithRealTimers(cb: Callback): void;
  runAllTimers(): void;
  runOnlyPendingTimers(): void;
  runAllTicks(): void;
  runAllImmediates(): void;
  advanceTimersByTime(msToRun: number): void;
  advanceTimersToNextTimer(steps?: number): void;
  reset(): void;
  clearAllTimers(): void;
  now(): number;
  getTimerCount(): number;
  dispose(): void;
}

Legacy Fake Timers

Configuration Types

interface Config.FakeTimersConfig {
  /** Auto-advance timers by specified milliseconds */
  advanceTimers?: boolean | number;
  /** APIs to exclude from faking */
  doNotFake?: Array<FakeableAPI>;
  /** Initial system time for fake timers */
  now?: number | Date;
  /** Maximum recursive timer limit */
  timerLimit?: number;
  /** Must be false for modern timers */
  legacyFakeTimers?: false;
}

type FakeableAPI = 
  | 'Date'
  | 'hrtime' 
  | 'nextTick'
  | 'performance'
  | 'queueMicrotask'
  | 'requestAnimationFrame'
  | 'cancelAnimationFrame'
  | 'requestIdleCallback'
  | 'cancelIdleCallback'
  | 'setImmediate'
  | 'clearImmediate'
  | 'setInterval'
  | 'clearInterval'
  | 'setTimeout'
  | 'clearTimeout';

interface TimerConfig<Ref> {
  /** Convert timer ID to reference */
  idToRef: (id: number) => Ref;
  /** Convert reference to timer ID */
  refToId: (ref: Ref) => number | void;
}

type Callback = (...args: Array<unknown>) => void;
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@jest/fake-timers@30.1.x
Publish Source
CLI
Badge
tessl/npm-jest--fake-timers badge