/** * @license * Copyright 2022-2026 Matter.js Authors * SPDX-License-Identifier: Apache-2.0 */ import { Boot } from "./boot.js"; export class TestTimeoutError extends Error { diagnostics; constructor(message: string) { super(`Test timeout: ${message}`); try { this.diagnostics = MatterHooks?.generateDiagnostics?.(); } catch (e) { this.diagnostics = `(diagnostics generation failed: ${(e as Error).message}`; } } code?: number | string; timeout?: number; file?: string; } type TimerCallback = () => any; type MockTimeLike = typeof MockTime; export interface MockTime extends MockTimeLike {} /** * An operation that only settles on a macrotask boundary. A "host" dependent additionally settles on host time * rather than virtual time, so virtual time must stand still while it is pending. An abandoned dependent still * requires macrotask yields to settle but no longer holds virtual time. */ interface Dependent { host: boolean; /** * Host time at which the operation started, against which its budget is measured. */ startedAt: number; abandoned: boolean; /** * Turns the entry still withholds virtual time after settling. Undefined until it settles. */ graceTurns?: number; } const dependents = new Map, Dependent>(); /** * The host's elapsed time in milliseconds. Monotonic where the platform offers it, so a clock adjustment cannot make * an operation look older or younger than it is. */ function hostElapsedMs() { return typeof performance === "undefined" ? Date.now() : performance.now(); } /** * Host milliseconds a single host operation may withhold virtual time for. The budget is measured on the host's own * clock because what it bounds is the host: counted in yields it shrinks exactly when the machine is loaded, which is * when a real operation needs it most. An operation over budget is abandoned: it still requires macrotask yields to * settle but no longer withholds virtual time, so one that never settles costs a bounded delay rather than a stalled * clock. Crypto settles in single-digit milliseconds even on a loaded runner, so this is generous. */ const MAX_HOST_ASYNC_MS = 1000; /** * Iterations of {@link MockTime.resolve} between visits to the host's task queue once it is driving the clock. Work * the host owns cannot progress during a microtask-only loop, so this bounds how much virtual time a continuation * parked on the host can cost. */ const HOST_TURNS_EVERY = 4; /** * Host turns a settled operation keeps withholding virtual time for. Its continuation resumes on the host's task * queue and usually starts the next operation, so without this bridge the handover reads as idle and costs a step. * Counting host turns rather than loop iterations keeps the bridge the same width however fast the loop spins, and * the bridge expires where it is spent, so no wait has to clean up after another. */ const HOST_SETTLE_GRACE_TURNS = 6; function register(dependent: Promise, host: boolean) { const registered = dependent.finally(() => { const entry = dependents.get(registered); if (entry === undefined) { return; } if (entry.host && !entry.abandoned) { entry.graceTurns = HOST_SETTLE_GRACE_TURNS; return; } dependents.delete(registered); }); dependents.set(registered, { host, startedAt: hostElapsedMs(), abandoned: false }); return registered; } /** * The uninstrumented macrotask of each instrumented implementation. {@link instrumentImplementation} replaces the * public getter with one that registers a dependent, which is right for callers but wrong for MockTime's own waits. */ const uninstrumentedMacrotasks = new WeakMap Promise>(); /** * Yield to the host's task queue without registering a dependent, so a wait performed by {@link MockTime} itself does * not read as work in progress. Falls back to a microtask where no implementation is installed, which is the most * MockTime can do on its own. */ function hostTurn() { const macrotask = real === undefined ? undefined : uninstrumentedMacrotasks.get(real); return macrotask === undefined ? Promise.resolve() : macrotask(); } /** * The waiter spending the handover bridge. Waits nest and overlap, so without a single spender a bridge would be * spent once per concurrent waiter rather than once per host turn. */ let charger: object | undefined; /** * Host operations abandoned since the last {@link MockTime.reset}. Any count above zero means virtual time inflated * with host latency, so a test that fails on protocol timing should be read in that light. */ let abandonedHostAsyncOps = 0; /** * Advances with each test. Mocha abandons a timed-out test but not its promises, so a {@link MockTime.resolve} loop * the test left running would keep moving the clock under the tests that follow; the loop stops once this moves on. */ let testGeneration = 0; /** * Report whether virtual time must stand still for a pending host operation. The waiter that owns the bridge also * spends it and abandons any operation that has outlived its budget. */ function withholdVirtualTime(waiter: object, hostTurnTaken: boolean) { if (charger === undefined) { charger = waiter; } const charging = charger === waiter; let withholding = false; for (const [promise, dependent] of dependents) { if (!dependent.host || dependent.abandoned) { continue; } // A settled operation bridges the handover to its continuation, then leaves. Only the charger spends the // bridge, so overlapping waits cannot drain it faster than one turn at a time if (dependent.graceTurns !== undefined) { if (charging && hostTurnTaken) { if (dependent.graceTurns === 0) { dependents.delete(promise); continue; } dependent.graceTurns--; } withholding = true; continue; } if (charging) { if (hostElapsedMs() - dependent.startedAt >= MAX_HOST_ASYNC_MS) { dependent.abandoned = true; abandonedHostAsyncOps++; // Virtual time inflates with host latency again from here, which is the defect this budget exists to // contain, so an abandonment must not pass unnoticed console.warn( `MockTime abandoned a host operation pending for ${MAX_HOST_ASYNC_MS} ms; virtual time may now inflate with host latency`, ); continue; } } withholding = true; } return withholding; } function releaseCharger(waiter: object) { if (charger === waiter) { charger = undefined; } } function hasActiveDependents() { for (const dependent of dependents.values()) { if (!dependent.abandoned && dependent.graceTurns === undefined) { return true; } } return false; } const timerNames = new WeakMap(); const registry = { timers: new Set(), register(_timer: MockTimer) {}, unregister(_timer: MockTimer) {}, }; // Must match matter.js Timer interface class MockTimer { name = "Test"; systemId = 0; utility = false; readonly isPeriodic: boolean; #mockTime: MockTime; #interval = 0; #armedInterval = 0; isRunning = false; readonly #callback: TimerCallback; constructor(mockTime: MockTime, name: string, duration: number, callback: TimerCallback, isPeriodic = false) { this.name = name; this.isPeriodic = isPeriodic; this.#mockTime = mockTime; this.interval = duration; if (isPeriodic) { this.#callback = async () => { this.#mockTime.callbackAtTime(this.#mockTime.nowUs + this.#armedInterval, this.#callback); await callback(); }; } else { this.#callback = () => { this.#close(); callback(); }; } } /** * The timer's interval. * * As with the production implementation, changes have no effect until the timer restarts. */ set interval(interval: number) { if (!Number.isFinite(interval) || interval < 0) { throw new Error( `Invalid interval for timer "${this.name}": ${interval}; it must be finite and not negative`, ); } this.#interval = interval; } get interval() { return this.#interval; } start() { if (this.isRunning) { this.stop(); } registry.register(this); timerNames.set(this.#callback, `${this.name}(${this.#interval}${this.isPeriodic ? ",periodic" : ""})`); this.#armedInterval = this.#interval; this.#mockTime.callbackAtTime(this.#mockTime.nowUs + this.#armedInterval, this.#callback); this.isRunning = true; return this; } stop() { this.#close(); return this; } #close() { registry.unregister(this); this.#mockTime.removeCallback(this.#callback); this.isRunning = false; } } type InterceptResult = T extends Promise ? { resolve: Awaited; reject?: undefined } | { resolve?: undefined; reject: {} } : { resolve: T; reject?: undefined } | { resolve?: void; reject: {} }; function isAsync(fn: (...args: any) => any): fn is (...args: any) => Promise { return fn.constructor.name === "AsyncFunction"; } interface TimeLike { macrotask: Promise; sleep(name: string, duration: number): Promise; } interface StaticTimeLike { startup: { systemMs: number; processMs: number }; default: TimeLike; register(timer: MockTimer): void; unregister(timer: MockTimer): void; timers: Set; } let callbacks = new Array<{ atMs: number; callback: TimerCallback }>(); let monotonicMs = 0; let wallClockOffsetMs = 0; let real = undefined as undefined | TimeLike; let enabled = false; let defaultToMacrotasks = false; const instrumentedImplementations = new WeakSet(); /** * An arbitrary start for our mock timeline. Starting at zero causes problems with Matter dates that cannot encode back * to the UNIX epoch */ const epoch = new Date("2025-01-01 12:34:56Z"); // Must match matter.js Time interface (with extensions) export const MockTime = { epoch, get activeImplementation(): TimeLike { return enabled ? this : (real ?? this); }, /** * Revert to standard time implementation. */ disable() { enabled = false; installActiveImplementation?.(); }, /** * Enable time mocking. Reverts to disabled for each test file. */ enable() { enabled = true; installActiveImplementation?.(); }, /** * Sets mock time to specific time and enable the mock. */ reset(time: ConstructorParameters[0] = epoch) { callbacks = []; dependents.clear(); abandonedHostAsyncOps = 0; monotonicMs = new Date(time).getTime(); wallClockOffsetMs = 0; defaultToMacrotasks = false; MockTime.enable(); }, /** * Enable and reset if not already enabled. */ init() { if (!enabled) { MockTime.enable(); } }, /** * Enable macrotasks (true) or microtasks (false) as the default yield for mock time incrementation. * * Microtasks are the default and are more efficient. Macrotasks are required for e.g. most of node's crypto.subtle * methods to resolve. */ get forceMacrotasks() { return defaultToMacrotasks; }, set forceMacrotasks(value: boolean) { defaultToMacrotasks = value; }, /** * Register an operation that settles on host time rather than virtual time. {@link MockTime.resolve} withholds * virtual time for the duration of the operation, so host latency does not expire virtual timers. Time still * advances in gaps between operations and once an operation exhausts {@link MAX_HOST_ASYNC_MS}. */ requireHostAsync(dependent: Promise) { return register(dependent, true); }, requireMacrotasks(dependent: Promise) { return register(dependent, false); }, /** * Turns between visits to the host's task queue once the clock is moving. Exposed for tests of MockTime itself. */ get hostTurnInterval() { return HOST_TURNS_EVERY; }, /** * Host operations abandoned since the last {@link MockTime.reset}. Exposed for tests of MockTime itself. */ get abandonedHostAsyncOps() { return abandonedHostAsyncOps; }, /** * Operations {@link MockTime} still tracks, abandoned ones included. Exposed for tests of MockTime itself. */ get dependentCount() { return dependents.size; }, /** * Host operations still outstanding, meaning neither settled nor abandoned. A settled operation withholds virtual * time for a few turns more, so zero here does not mean the clock is free to move. Exposed for tests of MockTime * itself. */ get pendingHostAsyncOps() { let count = 0; for (const dependent of dependents.values()) { if (dependent.host && !dependent.abandoned && dependent.graceTurns === undefined) { count++; } } return count; }, /** * Run {@link actor} with the clocks set so that {@link nowMs} reads {@link time}, a wall-clock time, and restore * them afterwards. */ atTime(time: number | Date, actor: () => T): T { const revertTo = monotonicMs; let isAsync = false; try { monotonicMs = (typeof time === "number" ? time : time.getTime()) - wallClockOffsetMs; const result = actor(); if (typeof (result as any)?.then === "function") { isAsync = true; return Promise.resolve(result).finally(() => { monotonicMs = revertTo; }) as T; } return result; } finally { if (!isAsync) { monotonicMs = revertTo; } } }, get now(): Date { return new Date(monotonicMs + wallClockOffsetMs); }, get nowMs() { return monotonicMs + wallClockOffsetMs; }, /** * The monotonic clock, in milliseconds like the production `Time.nowUs`. Timers run on this clock, so * {@link stepWallClock} does not move it. */ get nowUs() { return monotonicMs; }, /** * Step the wall clock ({@link now}, {@link nowMs}) by `offsetMs`, which may be negative, as an NTP step or a * manual clock set does. The monotonic clock ({@link nowUs}) and pending timers are unaffected. */ stepWallClock(offsetMs: number) { wallClockOffsetMs += offsetMs; }, getTimer(name: string, duration: number, callback: TimerCallback): MockTimer { return new MockTimer(this, name, duration, callback); }, getPeriodicTimer(name: string, interval: number, callback: TimerCallback): MockTimer { return new MockTimer(this, name, interval, callback, true); }, /** * Time compatible sleep. * * This passes the sleep call through to the (possibly mocked) underlying time implementation. */ sleep(name: string, duration: number) { if (real === undefined) { throw new Error("Cannot sleep because time implementation is not present"); } return real.sleep(name, duration); }, /** * Use the installed time implementation to yield to the next macrotask. * * We do not mock macrotasks because it keeps tests truer to life and unlike timers it does not have a meaningful * impact on test execution. */ get macrotask() { if (real === undefined) { throw new Error("Cannot create macrotask because time implementation is not present"); } return real.macrotask; }, /** * Wait for all registered macrotask dependencies to complete. A host dependency over budget is abandoned here as * it is in {@link MockTime.resolve}, so one that never settles cannot stall the wait. */ get macrotasks() { return (async () => { const waiter = {}; try { while (hasActiveDependents()) { await MockTime.resolve(this.macrotask); withholdVirtualTime(waiter, true); } } finally { releaseCharger(waiter); } })(); }, /** * Resolve a promise with time dependency. * * Moves time forward until the promise resolves. Pass `macrotasks` to visit the host's task queue on every turn * rather than only while work is registered or, once the clock is moving, every {@link HOST_TURNS_EVERY} turns. */ async resolve( promise: PromiseLike | T, { stepMs, macrotasks }: { stepMs?: number; macrotasks?: boolean } = {}, ) { let resolved = false; let result: T | undefined; let error: any; if ( typeof promise !== "object" || promise === null || !("then" in promise) || typeof promise.then !== "function" ) { return promise; } promise.then( r => { resolved = true; result = r; }, e => { resolved = true; error = e; }, ); let timeAdvanced = 0; let turns = 0; let advanced = false; const waiter = {}; const generation = testGeneration; try { while (!resolved) { // Microtask yields keep the loop cheap, but only the host's task queue lets real work (I/O, timers // the host owns) make progress, so visit it while nothing is registered too const hostTurnTaken = (macrotasks ?? defaultToMacrotasks) || dependents.size > 0 || (advanced && turns % HOST_TURNS_EVERY === 0); if (hostTurnTaken) { await hostTurn(); } else { await MockTime.yield(); } turns++; if (resolved) { break; } if (generation !== testGeneration) { throw new TestTimeoutError("MockTime.resolve outlived the test that started it"); } // If we've advanced more than one hour, assume we've hung if (timeAdvanced > 60 * 60 * 1000) { throw new TestTimeoutError( "Promise did not resolve within one (virtual) hour, probably not going to happen", ); } // Host operations such as crypto settle on host time. Advancing while one is pending converts host // latency into virtual time, which expires protocol timers that would not expire in production if (withholdVirtualTime(waiter, hostTurnTaken)) { continue; } if (stepMs) { await this.advance(stepMs); timeAdvanced += stepMs; } else { // 100ms steps give ~200 yields before a 10-second mock timeout fires, sufficient for realistic // async chains await this.advance(100); timeAdvanced += 100; } advanced = true; if (resolved) { break; } await this.yield(); } } finally { releaseCharger(waiter); } if (error !== undefined) { throw error; } return result as T; }, /** * Move time forward. Runs tasks scheduled during this interval. */ async advance(ms: number) { const newTimeMs = monotonicMs + ms; let previousAtMs: number | undefined; let iterationsAtSameTime = 0; while (callbacks.length) { const { atMs, callback } = callbacks[0]; if (atMs > newTimeMs) break; callbacks.shift(); monotonicMs = atMs; // A timer that rearms at the current time never lets the mock clock advance, so without this guard the // loop spins indefinitely iterationsAtSameTime = atMs === previousAtMs ? iterationsAtSameTime + 1 : 0; previousAtMs = atMs; if (iterationsAtSameTime > 10000) { throw new TestTimeoutError( `Timer ${timerNames.get(callback) ?? "(unknown)"} rearms without advancing mock time`, ); } await callback(); } monotonicMs = newTimeMs; }, /** * Yield to scheduled microtasks. This means that all code paths waiting on resolved promises (including await) * will proceed before this method returns. */ async yield() { await Promise.resolve(); }, /** * Due to its implementation, an older version of yield() would actually yield to microtasks three times. Our tests * then depended on this functionality -- one yield could trigger up to three nested awaits. * * To make this clear, the version of yield() that emulates old behavior is called "yield3". */ async yield3() { await Promise.resolve(); await Promise.resolve(); await Promise.resolve(); }, /** * Hook a method and invoke a callback just before the method completes. Unhooks after completion. * * Handles both synchronous and asynchronous methods. The responseInterceptor should match the async-ness of the * intercepted method. * * The responseInterceptor can optionally access and/or replace the resolve/reject value. * The callInterceptor can be used to manipulate the call parameters of the method */ interceptOnce ReturnT }>( obj: ObjT, method: NameT, responseInterceptor: ( result: InterceptResult, ) => void | InterceptResult | Promise | Promise>, callInterceptor?: (args: Parameters) => Parameters, ) { const original = obj[method]; if (!original) { throw new Error(`Interception method ${method} is not present`); } let result: InterceptResult; if (isAsync(responseInterceptor)) { obj[method] = async function (this: any, ...args: any): Promise { if (callInterceptor) { args = callInterceptor(args); } try { const resolve = await original.apply(this, args); result = { resolve } as any; } catch (reject) { result = { reject } as any; } finally { obj[method] = original; } result = (await responseInterceptor(result)) ?? result; if (result.reject) { throw result.reject as Error; } return result.resolve; } as any; } else { obj[method] = function (this: any, ...args: any): any { if (callInterceptor) { args = callInterceptor(args); } try { const resolve = original.apply(this, args); result = { resolve } as any; } catch (reject) { result = { reject } as any; } finally { obj[method] = original; } result = (responseInterceptor(result) as any) ?? result; if (result.reject) { throw result.reject as Error; } return result.resolve; } as any; } }, /** * Count the number of registered timers with a specific name. */ timerCountFor(name: string) { return [...registry.timers].filter(timer => timer.name === name).length; }, /** * Schedule {@link callback} at {@link atMs} on the monotonic clock ({@link nowUs}). */ callbackAtTime(atMs: number, callback: TimerCallback) { // Encountered this in chromium web tests and reproduced in chrome. But adding this test fixes it, so maybe a // chrome v8 error? If it triggers again note the stack trace if (!Number.isInteger(atMs)) { throw new Error(`Callback registered at non-integer time ${atMs}`); } callbacks.push({ atMs, callback }); callbacks.sort(({ atMs: atMsA }, { atMs: atMsB }) => atMsA - atMsB); }, removeCallback(callbackToRemove: TimerCallback) { const index = callbacks.findIndex(({ callback }) => callbackToRemove === callback); if (index === -1) return; callbacks.splice(index, 1); }, }; let installActiveImplementation: undefined | (() => void); export function timeSetup(Time: StaticTimeLike) { registry.register = Time.register; registry.unregister = Time.unregister; registry.timers = Time.timers; Time.startup.systemMs = Time.startup.processMs = 0; real = Time.default; instrumentImplementation(real); installActiveImplementation = () => (Time.default = MockTime.activeImplementation); installActiveImplementation(); } function instrumentImplementation(time: TimeLike) { if (instrumentedImplementations.has(time)) { return; } let get; let obj = time; while (obj) { get = Object.getOwnPropertyDescriptor(obj.constructor.prototype, "macrotask")?.get; if (get) { break; } obj = Object.getPrototypeOf(obj); } if (!get) { throw new Error("Time instance does not define macrotask getter"); } const uninstrumented = get; uninstrumentedMacrotasks.set(time, () => uninstrumented.apply(time)); Object.defineProperty(time, "macrotask", { get() { return MockTime.requireMacrotasks(uninstrumented.apply(time)); }, }); instrumentedImplementations.add(time); } Object.assign(globalThis, { MockTime }); Boot.init(kind => { testGeneration++; if (kind === "state") { wallClockOffsetMs = 0; return; } MockTime.reset(); MockTime.disable(); });