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

Modern Fake Timers

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

Advanced fake timer implementation built on @sinonjs/fake-timers, providing comprehensive time control including Date mocking, async timer operations, and advanced scheduling features.

Capabilities

Constructor

Creates a new ModernFakeTimers instance with the specified global object and Jest configuration.

/**
 * Creates a new ModernFakeTimers instance
 * @param options - Configuration object with global and config
 */
constructor(options: {
  global: typeof globalThis;
  config: Config.ProjectConfig;
}): ModernFakeTimers;

Usage Example:

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

const fakeTimers = new ModernFakeTimers({
  global: globalThis,
  config: makeProjectConfig()
});

Timer Control

Use Fake Timers

Enables fake timers with optional configuration, replacing all timer APIs with fake implementations.

/**
 * Enables fake timers with optional configuration
 * @param fakeTimersConfig - Optional configuration for timer behavior
 */
useFakeTimers(fakeTimersConfig?: Config.FakeTimersConfig): void;

Usage Example:

// Enable with default settings
fakeTimers.useFakeTimers();

// Enable with custom configuration
fakeTimers.useFakeTimers({
  now: new Date('2023-01-01'),
  doNotFake: ['nextTick', 'setImmediate'],
  timerLimit: 50000
});

Use Real Timers

Restores the original timer implementations, disabling fake timers.

/**
 * Restores original timer implementations
 */
useRealTimers(): void;

Timer Execution

Run All Timers

Executes all pending timers synchronously until no timers remain.

/**
 * Runs all pending timers synchronously
 */
runAllTimers(): void;

Run All Timers Async

Executes all pending timers asynchronously, allowing for Promise-based timer handling.

/**
 * Runs all pending timers asynchronously
 */
runAllTimersAsync(): Promise<void>;

Run Only Pending Timers

Executes only the timers that are currently pending, without running timers created during execution.

/**
 * Runs only currently pending timers
 */
runOnlyPendingTimers(): void;

Run Only Pending Timers Async

Executes only currently pending timers asynchronously.

/**
 * Runs only currently pending timers asynchronously
 */
runOnlyPendingTimersAsync(): Promise<void>;

Time Advancement

Advance Timers by Time

Advances the fake timer by the specified number of milliseconds.

/**
 * Advances fake time by specified milliseconds
 * @param msToRun - Number of milliseconds to advance
 */
advanceTimersByTime(msToRun: number): void;

Usage Example:

// Set up a timer
setTimeout(() => console.log('Timer fired!'), 1000);

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

Advance Timers by Time Async

Advances the fake timer asynchronously by the specified number of milliseconds.

/**
 * Advances fake time asynchronously by specified milliseconds
 * @param msToRun - Number of milliseconds to advance
 */
advanceTimersByTimeAsync(msToRun: number): Promise<void>;

Advance Timers to Next Timer

Advances time to the next scheduled timer and optionally repeats for multiple steps.

/**
 * Advances time to the next scheduled timer
 * @param steps - Number of timer steps to advance (default: 1)
 */
advanceTimersToNextTimer(steps?: number): void;

Advance Timers to Next Timer Async

Advances time asynchronously to the next scheduled timer.

/**
 * Advances time asynchronously to the next scheduled timer
 * @param steps - Number of timer steps to advance (default: 1)
 */
advanceTimersToNextTimerAsync(steps?: number): Promise<void>;

Advance Timers to Next Frame

Advances time to the next animation frame.

/**
 * Advances time to the next animation frame
 */
advanceTimersToNextFrame(): void;

Microtask Control

Run All Ticks

Executes all pending process.nextTick callbacks and microtasks.

/**
 * Runs all pending process.nextTick callbacks
 */
runAllTicks(): void;

Time Management

Set System Time

Sets the current system time for the fake timers.

/**
 * Sets the current system time
 * @param now - Time to set (number as milliseconds or Date object)
 */
setSystemTime(now?: number | Date): void;

Usage Example:

// Set specific date
fakeTimers.setSystemTime(new Date('2023-12-25'));

// Set timestamp
fakeTimers.setSystemTime(1640995200000);

Get Real System Time

Returns the actual system time (not fake time).

/**
 * Gets the real system time
 * @returns Current real system time in milliseconds
 */
getRealSystemTime(): number;

Now

Returns the current fake time if fake timers are enabled, otherwise returns real time.

/**
 * Gets current time (fake or real depending on state)
 * @returns Current time in milliseconds
 */
now(): number;

State Management

Reset

Resets the timer state while preserving the current fake time.

/**
 * Resets timer state while preserving current time
 */
reset(): void;

Clear All Timers

Clears all pending timers without executing them.

/**
 * Clears all pending timers
 */
clearAllTimers(): void;

Get Timer Count

Returns the number of pending timers.

/**
 * Gets the count of pending timers
 * @returns Number of pending timers
 */
getTimerCount(): number;

Dispose

Disposes of the fake timers instance and restores real timers.

/**
 * Disposes of the fake timers instance
 */
dispose(): void;

Usage Example:

// Always clean up in test teardown
afterEach(() => {
  fakeTimers.dispose();
});

docs

index.md

legacy-fake-timers.md

modern-fake-timers.md

tile.json

tessl/npm-jest--fake-timers