Module
Utilities to help mock behavior, spy on function calls, stub methods, and fake time for tests.
Very Popular
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478/** This module is browser compatible. */
import { applyMixins, ascend, DelayOptions, RBTree, Vector } from "./deps.ts";
export type NativeDate = Date;export type NativeDateConstructor = DateConstructor;export const NativeDate: NativeDateConstructor = Date;
export const NativeTime = { setTimeout, clearTimeout, setInterval, clearInterval,};
/** An error related to faking time. */export class TimeError extends Error { constructor(message: string) { super(message); this.name = "TimeError"; }}
function isFakeDate(instance: unknown): instance is FakeDate { return instance instanceof FakeDate;}
export interface FakeDate extends NativeDate { date: Date;}export interface FakeDateConstructor extends NativeDateConstructor { new (): FakeDate; new (value: string | number | NativeDate): FakeDate; new ( year: number, month: number, date?: number, hours?: number, minutes?: number, seconds?: number, ms?: number, ): FakeDate; (): string; readonly prototype: FakeDate; parse(s: string): number; UTC( year: number, month: number, date?: number, hours?: number, minutes?: number, seconds?: number, ms?: number, ): number; now(): number;}function FakeDateConstructor(this: void): string;function FakeDateConstructor(this: FakeDate): void;function FakeDateConstructor( this: FakeDate, value: string | number | NativeDate,): void;function FakeDateConstructor( this: FakeDate, year: number, month: number, date?: number, hours?: number, minutes?: number, seconds?: number, ms?: number,): void;function FakeDateConstructor( this: FakeDate | void, // deno-lint-ignore no-explicit-any ...args: any[]): string | void { if (args.length === 0) args.push(FakeDate.now()); if (isFakeDate(this)) { this.date = new NativeDate(...(args as [])); } else { return new NativeDate(args[0]).toString(); }}class FakeDateMixin { declare date: NativeDate;
static now(): number { return time?.now ?? NativeDate.now(); }
[Symbol.toPrimitive](hint: "default"): string; [Symbol.toPrimitive](hint: "string"): string; [Symbol.toPrimitive](hint: "number"): number; [Symbol.toPrimitive](_hint: string): string | number { return this.date[Symbol.toPrimitive].apply( this.date, Array.from(arguments) as [string], ); }}applyMixins(FakeDateConstructor, [FakeDateMixin]);export const FakeDate: FakeDateConstructor = FakeDateConstructor as FakeDateConstructor;FakeDate.parse = Date.parse;FakeDate.UTC = Date.UTC;Object.getOwnPropertyNames(Date.prototype).forEach((name: string) => { const propName: keyof NativeDate = name as keyof NativeDate; FakeDate.prototype[propName] = function ( this: FakeDate, // deno-lint-ignore no-explicit-any ...args: any[] // deno-lint-ignore no-explicit-any ): any { // deno-lint-ignore no-explicit-any return (this.date[propName] as (...args: any[]) => any).apply( this.date, args, ); };});Object.getOwnPropertySymbols(Date.prototype).forEach((name: symbol) => { const propName: keyof NativeDate = name as unknown as keyof NativeDate; FakeDate.prototype[propName] = function ( this: FakeDate, // deno-lint-ignore no-explicit-any ...args: any[] // deno-lint-ignore no-explicit-any ): any { // deno-lint-ignore no-explicit-any return (this.date[propName] as (...args: any[]) => any).apply( this.date, args, ); };});
function* timerId() { let i = 1; while (true) yield i++;}interface Timer { id: number; // deno-lint-ignore no-explicit-any callback: (...args: any[]) => void; delay: number; args: unknown[]; due: number; repeat: boolean;}
export interface FakeTimeOptions { /** * The rate relative to real time at which fake time is updated. * By default time only moves forward through calling tick or setting now. * Set to 1 to have the fake time automatically tick foward at the same rate in milliseconds as real time. */ advanceRate: number; /** * The frequency in milliseconds at which fake time is updated. * If advanceRate is set, we will update the time every 10 milliseconds by default. */ advanceFrequency?: number;}
interface DueNode { due: number; timers: Vector<Timer>;}
let time: FakeTime | undefined = undefined;/** * Overrides the real Date object and timer functions with fake ones that can be * controlled through the fake time instance. */export class FakeTime { private _now: number; private _start: number; private initializedAt: number; private advanceRate: number; private advanceFrequency: number; private advanceIntervalId?: number;
private timerId: Generator<number>; private dueNodes: Map<number, DueNode>; private dueTree: RBTree<DueNode>;
constructor( start?: number | string | NativeDate | null, options?: FakeTimeOptions, ) { FakeTime.restore(); this.initializedAt = NativeDate.now(); this._start = start instanceof NativeDate ? start.valueOf() : typeof start === "number" ? Math.floor(start) : typeof start === "string" ? (new Date(start)).valueOf() : this.initializedAt; if (Number.isNaN(this._start)) throw new TimeError("invalid start"); this._now = this._start;
this.timerId = timerId(); this.dueNodes = new Map(); this.dueTree = new RBTree( (a: Partial<DueNode>, b: Partial<DueNode>) => ascend(a.due, b.due), );
this.overrideGlobals(); time = this;
this.advanceRate = Math.max( 0, options?.advanceRate ? options.advanceRate : 0, ); this.advanceFrequency = Math.max( 0, options?.advanceFrequency ? options.advanceFrequency : 10, ); if (this.advanceRate > 0) { this.advanceIntervalId = NativeTime.setInterval.call(null, () => { this.tick(this.advanceRate * this.advanceFrequency); }, this.advanceFrequency); } }
static restore(): void { if (time) { time.restore(); console.error("already using fake time"); } }
static setTimeout( // deno-lint-ignore no-explicit-any callback: (...args: any[]) => void, delay = 0, // deno-lint-ignore no-explicit-any ...args: any[] ): number { if (!time) throw new TimeError("no fake time"); return time.setTimer(callback, delay, args, false); } static clearTimeout(id?: number): void { if (!time) throw new TimeError("no fake time"); if (typeof id === "number" && time.dueNodes.has(id)) { time.dueNodes.delete(id); } }
static setInterval( // deno-lint-ignore no-explicit-any callback: (...args: any[]) => unknown, delay = 0, // deno-lint-ignore no-explicit-any ...args: any[] ): number { if (!time) throw new TimeError("no fake time"); return time.setTimer(callback, delay, args, true); } static clearInterval(id?: number): void { if (!time) throw new TimeError("no fake time"); if (typeof id === "number" && time.dueNodes.has(id)) { time.dueNodes.delete(id); } }
private overrideGlobals(): void { globalThis.Date = FakeDate; globalThis.setTimeout = FakeTime.setTimeout as typeof NativeTime.setTimeout; globalThis.clearTimeout = FakeTime.clearTimeout; globalThis.setInterval = FakeTime .setInterval as typeof NativeTime.setInterval; globalThis.clearInterval = FakeTime.clearInterval; }
private restoreGlobals(): void { globalThis.Date = NativeDate; globalThis.setTimeout = NativeTime.setTimeout; globalThis.clearTimeout = NativeTime.clearTimeout; globalThis.setInterval = NativeTime.setInterval; globalThis.clearInterval = NativeTime.clearInterval; }
private setTimer( // deno-lint-ignore no-explicit-any callback: (...args: any[]) => void, delay = 0, args: unknown[], repeat = false, ): number { const id: number = this.timerId.next().value; delay = Math.max(repeat ? 1 : 0, Math.floor(delay)); const due: number = this.now + delay; let dueNode: DueNode | null = this.dueTree.find({ due }); if (dueNode === null) { dueNode = { due, timers: new Vector() }; this.dueTree.insert(dueNode); } dueNode.timers.push({ id, callback, args, delay, due, repeat, }); this.dueNodes.set(id, dueNode); return id; }
/** * Restores real time temporarily until callback returns and resolves. */ static async restoreFor<T>( // deno-lint-ignore no-explicit-any callback: (...args: any[]) => Promise<T> | T, // deno-lint-ignore no-explicit-any ...args: any[] ): Promise<T> { if (!time) throw new TimeError("no fake time"); let result: T; time.restoreGlobals(); try { result = await callback.apply(null, args); } finally { time.overrideGlobals(); } return result; }
/** * The amount of milliseconds elapsed since January 1, 1970 00:00:00 UTC for the fake time. * When set, it will call any functions waiting to be called between the current and new fake time. * If the timer callback throws, time will stop advancing forward beyond that timer. */ get now(): number { return this._now; } set now(value: number) { if (value < this._now) throw new Error("time cannot go backwards"); let dueNode: DueNode | null = this.dueTree.min(); while (dueNode && dueNode.due <= value) { const timer: Timer | undefined = dueNode.timers.shift(); if (timer && this.dueNodes.has(timer.id)) { this._now = timer.due; if (timer.repeat) { const due: number = timer.due + timer.delay; let dueNode: DueNode | null = this.dueTree.find({ due }); if (dueNode === null) { dueNode = { due, timers: new Vector() }; this.dueTree.insert(dueNode); } dueNode.timers.push({ ...timer, due }); this.dueNodes.set(timer.id, dueNode); } else { this.dueNodes.delete(timer.id); } timer.callback.apply(null, timer.args); } else if (!timer) { this.dueTree.remove(dueNode); dueNode = this.dueTree.min(); } } this._now = value; }
/** The initial amount of milliseconds elapsed since January 1, 1970 00:00:00 UTC for the fake time. */ get start(): number { return this._start; } set start(value: number) { throw new Error("cannot change start time after initialization"); }
/** Resolves after the given number of milliseconds using real time. */ async delay(ms: number, options: DelayOptions = {}): Promise<void> { const { signal } = options; if (signal?.aborted) { return Promise.reject( new DOMException("Delay was aborted.", "AbortError"), ); } return await new Promise((resolve, reject) => { let timer: number | null = null; const abort = () => FakeTime .restoreFor(() => { if (timer) clearTimeout(timer); }) .then(() => reject(new DOMException("Delay was aborted.", "AbortError")) ); const done = () => { signal?.removeEventListener("abort", abort); resolve(); }; FakeTime.restoreFor(() => setTimeout(done, ms)) .then((id) => timer = id); signal?.addEventListener("abort", abort, { once: true }); }); }
/** Runs all pending microtasks. */ async runMicrotasks(): Promise<void> { await this.delay(0); }
/** * Adds the specified number of milliseconds to the fake time. * This will call any functions waiting to be called between the current and new fake time. */ tick(ms = 0): void { this.now += ms; }
/** * Runs all pending microtasks then adds the specified number of milliseconds to the fake time. * This will call any functions waiting to be called between the current and new fake time. */ async tickAsync(ms = 0): Promise<void> { await this.runMicrotasks(); this.now += ms; }
/** * Advances time to when the next scheduled timer is due. * If there are no pending timers, time will not be changed. * Returns true when there is a scheduled timer and false when there is not. */ next(): boolean { const next = this.dueTree.min(); if (next) this.now = next.due; return !!next; }
/** * Runs all pending microtasks then advances time to when the next scheduled timer is due. * If there are no pending timers, time will not be changed. */ async nextAsync(): Promise<boolean> { await this.runMicrotasks(); return this.next(); }
/** * Advances time forward to the next due timer until there are no pending timers remaining. * If the timers create additional timers, they will be run too. If there is an interval, * time will keep advancing forward until the interval is cleared. */ runAll(): void { while (!this.dueTree.isEmpty()) { this.next(); } }
/** * Advances time forward to the next due timer until there are no pending timers remaining. * If the timers create additional timers, they will be run too. If there is an interval, * time will keep advancing forward until the interval is cleared. * Runs all pending microtasks before each timer. */ async runAllAsync(): Promise<void> { while (!this.dueTree.isEmpty()) { await this.nextAsync(); } }
/** Restores time related global functions to their original state. */ restore(): void { if (!time) throw new TimeError("time already restored"); time = undefined; this.restoreGlobals(); if (this.advanceIntervalId) clearInterval(this.advanceIntervalId); }}