or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.mdlegacy-fake-timers.mdmodern-fake-timers.md
tile.json

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.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@jest/fake-timers@30.1.x

To install, run

npx @tessl/cli install tessl/npm-jest--fake-timers@30.1.0

index.mddocs/

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;