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

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Jest Fake Timers

Name: tessl/npm-jest--fake-timers
Author: tessl

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;