From 170c457a61d15d2d42cdd2860e6dd76ecedea4ce Mon Sep 17 00:00:00 2001 From: Pavel Feldman Date: Thu, 30 May 2024 09:38:27 -0700 Subject: [PATCH] feat(timers): a stab at fake timers (#31075) --- docs/src/api/class-browsercontext.md | 6 + docs/src/api/class-clock.md | 86 + docs/src/api/class-page.md | 6 + packages/playwright-core/src/client/api.ts | 1 + .../src/client/browserContext.ts | 4 + packages/playwright-core/src/client/clock.ts | 57 + packages/playwright-core/src/client/page.ts | 4 + .../playwright-core/src/protocol/validator.ts | 28 + .../src/server/browserContext.ts | 3 + packages/playwright-core/src/server/clock.ts | 79 + .../dispatchers/browserContextDispatcher.ts | 20 + .../src/server/injected/DEPS.list | 5 +- .../src/server/injected/fakeTimers.ts | 23 + .../src/third_party/fake-timers-src.js | 1776 +++++++++++++++++ packages/playwright-core/types/types.d.ts | 85 + packages/protocol/src/channels.ts | 50 + packages/protocol/src/protocol.yml | 30 + tests/page/page-clock.spec.ts | 614 ++++++ utils/doclint/documentation.js | 2 + utils/generate_injected.js | 6 + 20 files changed, 2884 insertions(+), 1 deletion(-) create mode 100644 docs/src/api/class-clock.md create mode 100644 packages/playwright-core/src/client/clock.ts create mode 100644 packages/playwright-core/src/server/clock.ts create mode 100644 packages/playwright-core/src/server/injected/fakeTimers.ts create mode 100644 packages/playwright-core/src/third_party/fake-timers-src.js create mode 100644 tests/page/page-clock.spec.ts diff --git a/docs/src/api/class-browsercontext.md b/docs/src/api/class-browsercontext.md index 511f3db10c..8cb11dbc0c 100644 --- a/docs/src/api/class-browsercontext.md +++ b/docs/src/api/class-browsercontext.md @@ -98,6 +98,12 @@ context.BackgroundPage += (_, backgroundPage) => ``` +## property: BrowserContext.clock +* since: v1.45 +- type: <[Clock]> + +Playwright is using [@sinonjs/fake-timers](https://github.com/sinonjs/fake-timers) to fake timers and clock. + ## event: BrowserContext.close * since: v1.8 - argument: <[BrowserContext]> diff --git a/docs/src/api/class-clock.md b/docs/src/api/class-clock.md new file mode 100644 index 0000000000..f119073e07 --- /dev/null +++ b/docs/src/api/class-clock.md @@ -0,0 +1,86 @@ +# class: Clock +* since: v1.45 + +Playwright uses [@sinonjs/fake-timers](https://github.com/sinonjs/fake-timers) for clock emulation. Clock is installed for the entire [BrowserContext], so the time +in all the pages and iframes is controlled by the same clock. + +## async method: Clock.install +* since: v1.45 + +Creates a clock and installs it globally. + +### option: Clock.install.now +* since: v1.45 +- `now` <[int]|[Date]> + +Install fake timers with the specified unix epoch (default: 0). + +### option: Clock.install.toFake +* since: v1.45 +- `toFake` <[Array]<[FakeMethod]<"setTimeout"|"clearTimeout"|"setInterval"|"clearInterval"|"Date"|"requestAnimationFrame"|"cancelAnimationFrame"|"requestIdleCallback"|"cancelIdleCallback"|"performance">>> + +An array with names of global methods and APIs to fake. For instance, `await page.clock.install({ toFake: ['setTimeout'] })` will fake only `setTimeout()`. +By default, `setTimeout`, `clearTimeout`, `setInterval`, `clearInterval` and `Date` are faked. + +### option: Clock.install.loopLimit +* since: v1.45 +- `loopLimit` <[int]> + +The maximum number of timers that will be run when calling [`method: Clock.runAll`]. Defaults to `1000`. + +### option: Clock.install.shouldAdvanceTime +* since: v1.45 +- `shouldAdvanceTime` <[boolean]> + +Tells `@sinonjs/fake-timers` to increment mocked time automatically based on the real system time shift (e.g., the mocked time will be incremented by +20ms for every 20ms change in the real system time). Defaults to `false`. + +### option: Clock.install.advanceTimeDelta +* since: v1.45 +- `advanceTimeDelta` <[int]> + +Relevant only when using with [`option: shouldAdvanceTime`]. Increment mocked time by advanceTimeDelta ms every advanceTimeDelta ms change +in the real system time (default: 20). + +## async method: Clock.jump +* since: v1.45 + +Advance the clock by jumping forward in time, firing callbacks at most once. Returns fake milliseconds since the unix epoch. +This can be used to simulate the JS engine (such as a browser) being put to sleep and resumed later, skipping intermediary timers. + +### param: Clock.jump.time +* since: v1.45 +- `time` <[int]|[string]> + +Time may be the number of milliseconds to advance the clock by or a human-readable string. Valid string formats are "08" for eight seconds, "01:00" for one minute and "02:34:10" for two hours, 34 minutes and ten seconds. + + +## async method: Clock.runAll +* since: v1.45 +- returns: <[int]> Fake milliseconds since the unix epoch. + +Runs all pending timers until there are none remaining. If new timers are added while it is executing they will be run as well. +This makes it easier to run asynchronous tests to completion without worrying about the number of timers they use, or the delays in those timers. +It runs a maximum of [`option: loopLimit`] times after which it assumes there is an infinite loop of timers and throws an error. + + +## async method: Clock.runToLast +* since: v1.45 +- returns: <[int]> Fake milliseconds since the unix epoch. + +This takes note of the last scheduled timer when it is run, and advances the clock to that time firing callbacks as necessary. +If new timers are added while it is executing they will be run only if they would occur before this time. +This is useful when you want to run a test to completion, but the test recursively sets timers that would cause runAll to trigger an infinite loop warning. + + +## async method: Clock.tick +* since: v1.45 +- returns: <[int]> Fake milliseconds since the unix epoch. + +Advance the clock, firing callbacks if necessary. Returns fake milliseconds since the unix epoch. + +### param: Clock.tick.time +* since: v1.45 +- `time` <[int]|[string]> + +Time may be the number of milliseconds to advance the clock by or a human-readable string. Valid string formats are "08" for eight seconds, "01:00" for one minute and "02:34:10" for two hours, 34 minutes and ten seconds. diff --git a/docs/src/api/class-page.md b/docs/src/api/class-page.md index e0ee157045..b4ee91eb1b 100644 --- a/docs/src/api/class-page.md +++ b/docs/src/api/class-page.md @@ -151,6 +151,12 @@ page.Load += PageLoadHandler; page.Load -= PageLoadHandler; ``` +## property: Page.clock +* since: v1.45 +- type: <[Clock]> + +Playwright is using [@sinonjs/fake-timers](https://github.com/sinonjs/fake-timers) to fake timers and clock. + ## event: Page.close * since: v1.8 - argument: <[Page]> diff --git a/packages/playwright-core/src/client/api.ts b/packages/playwright-core/src/client/api.ts index b41a85b854..6eab70e159 100644 --- a/packages/playwright-core/src/client/api.ts +++ b/packages/playwright-core/src/client/api.ts @@ -20,6 +20,7 @@ export { Browser } from './browser'; export { BrowserContext } from './browserContext'; export type { BrowserServer } from './browserType'; export { BrowserType } from './browserType'; +export { Clock } from './clock'; export { ConsoleMessage } from './consoleMessage'; export { Coverage } from './coverage'; export { Dialog } from './dialog'; diff --git a/packages/playwright-core/src/client/browserContext.ts b/packages/playwright-core/src/client/browserContext.ts index 3f5640789e..fcc17c4231 100644 --- a/packages/playwright-core/src/client/browserContext.ts +++ b/packages/playwright-core/src/client/browserContext.ts @@ -44,6 +44,7 @@ import { ConsoleMessage } from './consoleMessage'; import { Dialog } from './dialog'; import { WebError } from './webError'; import { TargetClosedError, parseError } from './errors'; +import { Clock } from './clock'; export class BrowserContext extends ChannelOwner implements api.BrowserContext { _pages = new Set(); @@ -58,6 +59,8 @@ export class BrowserContext extends ChannelOwner readonly request: APIRequestContext; readonly tracing: Tracing; + readonly clock: Clock; + readonly _backgroundPages = new Set(); readonly _serviceWorkers = new Set(); readonly _isChromium: boolean; @@ -82,6 +85,7 @@ export class BrowserContext extends ChannelOwner this._isChromium = this._browser?._name === 'chromium'; this.tracing = Tracing.from(initializer.tracing); this.request = APIRequestContext.from(initializer.requestContext); + this.clock = new Clock(this); this._channel.on('bindingCall', ({ binding }) => this._onBinding(BindingCall.from(binding))); this._channel.on('close', () => this._onClose()); diff --git a/packages/playwright-core/src/client/clock.ts b/packages/playwright-core/src/client/clock.ts new file mode 100644 index 0000000000..8fd9e359d8 --- /dev/null +++ b/packages/playwright-core/src/client/clock.ts @@ -0,0 +1,57 @@ +/** + * Copyright (c) Microsoft Corporation. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +import type * as api from '../../types/types'; +import type * as channels from '@protocol/channels'; +import type { BrowserContext } from './browserContext'; + +export class Clock implements api.Clock { + private _browserContext: BrowserContext; + + constructor(browserContext: BrowserContext) { + this._browserContext = browserContext; + } + + async install(options?: Omit & { now?: number | Date }) { + const now = options && options.now ? (options.now instanceof Date ? options.now.getTime() : options.now) : undefined; + await this._browserContext._channel.clockInstall({ ...options, now }); + } + + async jump(time: number | string) { + await this._browserContext._channel.clockJump({ + timeNumber: typeof time === 'number' ? time : undefined, + timeString: typeof time === 'string' ? time : undefined + }); + } + + async runAll(): Promise { + const result = await this._browserContext._channel.clockRunAll(); + return result.fakeTime; + } + + async runToLast(): Promise { + const result = await this._browserContext._channel.clockRunToLast(); + return result.fakeTime; + } + + async tick(time: number | string): Promise { + const result = await this._browserContext._channel.clockTick({ + timeNumber: typeof time === 'number' ? time : undefined, + timeString: typeof time === 'string' ? time : undefined + }); + return result.fakeTime; + } +} diff --git a/packages/playwright-core/src/client/page.ts b/packages/playwright-core/src/client/page.ts index 58f5758188..84848e433d 100644 --- a/packages/playwright-core/src/client/page.ts +++ b/packages/playwright-core/src/client/page.ts @@ -49,6 +49,7 @@ import { Video } from './video'; import { Waiter } from './waiter'; import { Worker } from './worker'; import { HarRouter } from './harRouter'; +import type { Clock } from './clock'; type PDFOptions = Omit & { width?: string | number, @@ -87,6 +88,8 @@ export class Page extends ChannelOwner implements api.Page readonly mouse: Mouse; readonly request: APIRequestContext; readonly touchscreen: Touchscreen; + readonly clock: Clock; + readonly _bindings = new Map any>(); readonly _timeoutSettings: TimeoutSettings; @@ -116,6 +119,7 @@ export class Page extends ChannelOwner implements api.Page this.mouse = new Mouse(this); this.request = this._browserContext.request; this.touchscreen = new Touchscreen(this); + this.clock = this._browserContext.clock; this._mainFrame = Frame.from(initializer.mainFrame); this._mainFrame._page = this; diff --git a/packages/playwright-core/src/protocol/validator.ts b/packages/playwright-core/src/protocol/validator.ts index 1cc57fb5a7..4d505069e1 100644 --- a/packages/playwright-core/src/protocol/validator.ts +++ b/packages/playwright-core/src/protocol/validator.ts @@ -963,6 +963,34 @@ scheme.BrowserContextUpdateSubscriptionParams = tObject({ enabled: tBoolean, }); scheme.BrowserContextUpdateSubscriptionResult = tOptional(tObject({})); +scheme.BrowserContextClockInstallParams = tObject({ + now: tOptional(tNumber), + toFake: tOptional(tArray(tString)), + loopLimit: tOptional(tNumber), + shouldAdvanceTime: tOptional(tBoolean), + advanceTimeDelta: tOptional(tNumber), +}); +scheme.BrowserContextClockInstallResult = tOptional(tObject({})); +scheme.BrowserContextClockJumpParams = tObject({ + timeNumber: tOptional(tNumber), + timeString: tOptional(tString), +}); +scheme.BrowserContextClockJumpResult = tOptional(tObject({})); +scheme.BrowserContextClockRunAllParams = tOptional(tObject({})); +scheme.BrowserContextClockRunAllResult = tObject({ + fakeTime: tNumber, +}); +scheme.BrowserContextClockRunToLastParams = tOptional(tObject({})); +scheme.BrowserContextClockRunToLastResult = tObject({ + fakeTime: tNumber, +}); +scheme.BrowserContextClockTickParams = tObject({ + timeNumber: tOptional(tNumber), + timeString: tOptional(tString), +}); +scheme.BrowserContextClockTickResult = tObject({ + fakeTime: tNumber, +}); scheme.PageInitializer = tObject({ mainFrame: tChannel(['Frame']), viewportSize: tOptional(tObject({ diff --git a/packages/playwright-core/src/server/browserContext.ts b/packages/playwright-core/src/server/browserContext.ts index cac7071a23..c1d70372a2 100644 --- a/packages/playwright-core/src/server/browserContext.ts +++ b/packages/playwright-core/src/server/browserContext.ts @@ -41,6 +41,7 @@ import { Recorder } from './recorder'; import * as consoleApiSource from '../generated/consoleApiSource'; import { BrowserContextAPIRequestContext } from './fetch'; import type { Artifact } from './artifact'; +import { Clock } from './clock'; export abstract class BrowserContext extends SdkObject { static Events = { @@ -87,6 +88,7 @@ export abstract class BrowserContext extends SdkObject { private _routesInFlight = new Set(); private _debugger!: Debugger; _closeReason: string | undefined; + readonly clock: Clock; constructor(browser: Browser, options: channels.BrowserNewContextParams, browserContextId: string | undefined) { super(browser, 'browser-context'); @@ -103,6 +105,7 @@ export abstract class BrowserContext extends SdkObject { this._harRecorders.set('', new HarRecorder(this, null, this._options.recordHar)); this.tracing = new Tracing(this, browser.options.tracesDir); + this.clock = new Clock(this); } isPersistentContext(): boolean { diff --git a/packages/playwright-core/src/server/clock.ts b/packages/playwright-core/src/server/clock.ts new file mode 100644 index 0000000000..e0ce1b64ff --- /dev/null +++ b/packages/playwright-core/src/server/clock.ts @@ -0,0 +1,79 @@ +/** + * Copyright (c) Microsoft Corporation. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +import type * as channels from '@protocol/channels'; +import type { BrowserContext } from './browserContext'; +import * as fakeTimersSource from '../generated/fakeTimersSource'; + +export class Clock { + private _browserContext: BrowserContext; + private _installed = false; + + constructor(browserContext: BrowserContext) { + this._browserContext = browserContext; + } + + async install(params: channels.BrowserContextClockInstallOptions) { + if (this._installed) + throw new Error('Cannot install more than one clock per context'); + this._installed = true; + const script = `(() => { + const module = {}; + ${fakeTimersSource.source} + globalThis.__pwFakeTimers = (module.exports.install())(${JSON.stringify(params)}); + })();`; + await this._addAndEvaluate(script); + } + + async jump(time: number | string) { + this._assertInstalled(); + await this._addAndEvaluate(`globalThis.__pwFakeTimers.jump(${JSON.stringify(time)}); 0`); + } + + async runAll(): Promise { + this._assertInstalled(); + await this._browserContext.addInitScript(`globalThis.__pwFakeTimers.runAll()`); + return await this._evaluateInFrames(`globalThis.__pwFakeTimers.runAllAsync()`); + } + + async runToLast(): Promise { + this._assertInstalled(); + await this._browserContext.addInitScript(`globalThis.__pwFakeTimers.runToLast()`); + return await this._evaluateInFrames(`globalThis.__pwFakeTimers.runToLastAsync()`); + } + + async tick(time: number | string): Promise { + this._assertInstalled(); + await this._browserContext.addInitScript(`globalThis.__pwFakeTimers.tick(${JSON.stringify(time)})`); + return await this._evaluateInFrames(`globalThis.__pwFakeTimers.tickAsync(${JSON.stringify(time)})`); + } + + private async _addAndEvaluate(script: string) { + await this._browserContext.addInitScript(script); + return await this._evaluateInFrames(script); + } + + private async _evaluateInFrames(script: string) { + const frames = this._browserContext.pages().map(page => page.frames()).flat(); + const results = await Promise.all(frames.map(frame => frame.evaluateExpression(script))); + return results[0]; + } + + private _assertInstalled() { + if (!this._installed) + throw new Error('Clock is not installed'); + } +} diff --git a/packages/playwright-core/src/server/dispatchers/browserContextDispatcher.ts b/packages/playwright-core/src/server/dispatchers/browserContextDispatcher.ts index b74a02ae25..741e49a456 100644 --- a/packages/playwright-core/src/server/dispatchers/browserContextDispatcher.ts +++ b/packages/playwright-core/src/server/dispatchers/browserContextDispatcher.ts @@ -312,6 +312,26 @@ export class BrowserContextDispatcher extends Dispatcher { + await this._context.clock.install(params); + } + + async clockJump(params: channels.BrowserContextClockJumpParams, metadata?: CallMetadata | undefined): Promise { + await this._context.clock.jump(params.timeString || params.timeNumber || 0); + } + + async clockRunAll(params: channels.BrowserContextClockRunAllParams, metadata?: CallMetadata | undefined): Promise { + return { fakeTime: await this._context.clock.runAll() }; + } + + async clockRunToLast(params: channels.BrowserContextClockRunToLastParams, metadata?: CallMetadata | undefined): Promise { + return { fakeTime: await this._context.clock.runToLast() }; + } + + async clockTick(params: channels.BrowserContextClockTickParams, metadata?: CallMetadata | undefined): Promise { + return { fakeTime: await this._context.clock.tick(params.timeString || params.timeNumber || 0) }; + } + async updateSubscription(params: channels.BrowserContextUpdateSubscriptionParams): Promise { if (params.enabled) this._subscriptions.add(params.event); diff --git a/packages/playwright-core/src/server/injected/DEPS.list b/packages/playwright-core/src/server/injected/DEPS.list index 1786754242..32da641c93 100644 --- a/packages/playwright-core/src/server/injected/DEPS.list +++ b/packages/playwright-core/src/server/injected/DEPS.list @@ -1,4 +1,7 @@ # Files in this folder are used in browser environment, they can only depend on isomorphic files. [*] ../isomorphic/ -../../utils/isomorphic \ No newline at end of file +../../utils/isomorphic + +[fakeTimers.ts] +../../third_party/fake-timers-src diff --git a/packages/playwright-core/src/server/injected/fakeTimers.ts b/packages/playwright-core/src/server/injected/fakeTimers.ts new file mode 100644 index 0000000000..3e8b1ab05b --- /dev/null +++ b/packages/playwright-core/src/server/injected/fakeTimers.ts @@ -0,0 +1,23 @@ +/** + * Copyright (c) Microsoft Corporation. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +// @ts-ignore +import SinonFakeTimers from '../../third_party/fake-timers-src'; +import type * as channels from '@protocol/channels'; + +export function install(params: channels.BrowserContextClockInstallOptions) { + return SinonFakeTimers.install(params); +} diff --git a/packages/playwright-core/src/third_party/fake-timers-src.js b/packages/playwright-core/src/third_party/fake-timers-src.js new file mode 100644 index 0000000000..9602123052 --- /dev/null +++ b/packages/playwright-core/src/third_party/fake-timers-src.js @@ -0,0 +1,1776 @@ +/* + * Copyright (c) 2010-2014, Christian Johansen, christian@cjohansen.no. All rights reserved. + * Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: + * 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. + * 3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +/ + +"use strict"; + +/* + * Local modifications: + * - removed global.process-related code. + * - removed require("@sinonjs/commons") dependency. + */ + +/** + * @typedef {object} IdleDeadline + * @property {boolean} didTimeout - whether or not the callback was called before reaching the optional timeout + * @property {function():number} timeRemaining - a floating-point value providing an estimate of the number of milliseconds remaining in the current idle period + */ + +/** + * Queues a function to be called during a browser's idle periods + * + * @callback RequestIdleCallback + * @param {function(IdleDeadline)} callback + * @param {{timeout: number}} options - an options object + * @returns {number} the id + */ + +/** + * @callback NextTick + * @param {VoidVarArgsFunc} callback - the callback to run + * @param {...*} args - optional arguments to call the callback with + * @returns {void} + */ + +/** + * @callback SetImmediate + * @param {VoidVarArgsFunc} callback - the callback to run + * @param {...*} args - optional arguments to call the callback with + * @returns {NodeImmediate} + */ + +/** + * @callback VoidVarArgsFunc + * @param {...*} callback - the callback to run + * @returns {void} + */ + +/** + * @typedef RequestAnimationFrame + * @property {function(number):void} requestAnimationFrame + * @returns {number} - the id + */ + +/** + * @typedef Performance + * @property {function(): number} now + */ + +/* eslint-disable jsdoc/require-property-description */ +/** + * @typedef {object} Clock + * @property {number} now - the current time + * @property {Date} Date - the Date constructor + * @property {number} loopLimit - the maximum number of timers before assuming an infinite loop + * @property {RequestIdleCallback} requestIdleCallback + * @property {function(number):void} cancelIdleCallback + * @property {setTimeout} setTimeout + * @property {clearTimeout} clearTimeout + * @property {NextTick} nextTick + * @property {queueMicrotask} queueMicrotask + * @property {setInterval} setInterval + * @property {clearInterval} clearInterval + * @property {SetImmediate} setImmediate + * @property {function(NodeImmediate):void} clearImmediate + * @property {function():number} countTimers + * @property {RequestAnimationFrame} requestAnimationFrame + * @property {function(number):void} cancelAnimationFrame + * @property {function():void} runMicrotasks + * @property {function(string | number): number} tick + * @property {function(string | number): Promise} tickAsync + * @property {function(): number} next + * @property {function(): Promise} nextAsync + * @property {function(): number} runAll + * @property {function(): number} runToFrame + * @property {function(): Promise} runAllAsync + * @property {function(): number} runToLast + * @property {function(): Promise} runToLastAsync + * @property {function(): void} reset + * @property {function(number | Date): void} setSystemTime + * @property {function(number): void} jump + * @property {Performance} performance + * @property {function(number[]): number[]} hrtime - process.hrtime (legacy) + * @property {function(): void} uninstall Uninstall the clock. + * @property {Function[]} methods - the methods that are faked + * @property {boolean} [shouldClearNativeTimers] inherited from config + */ +/* eslint-enable jsdoc/require-property-description */ + +/** + * Configuration object for the `install` method. + * + * @typedef {object} Config + * @property {number|Date} [now] a number (in milliseconds) or a Date object (default epoch) + * @property {string[]} [toFake] names of the methods that should be faked. + * @property {number} [loopLimit] the maximum number of timers that will be run when calling runAll() + * @property {boolean} [shouldAdvanceTime] tells FakeTimers to increment mocked time automatically (default false) + * @property {number} [advanceTimeDelta] increment mocked time every <> ms (default: 20ms) + * @property {boolean} [shouldClearNativeTimers] forwards clear timer calls to native functions if they are not fakes (default: false) + */ + +/* eslint-disable jsdoc/require-property-description */ +/** + * The internal structure to describe a scheduled fake timer + * + * @typedef {object} Timer + * @property {Function} func + * @property {*[]} args + * @property {number} delay + * @property {number} callAt + * @property {number} createdAt + * @property {boolean} immediate + * @property {number} id + * @property {Error} [error] + */ + +/** + * A Node timer + * + * @typedef {object} NodeImmediate + * @property {function(): boolean} hasRef + * @property {function(): NodeImmediate} ref + * @property {function(): NodeImmediate} unref + */ +/* eslint-enable jsdoc/require-property-description */ + +/* eslint-disable complexity */ + +/** + * Mocks available features in the specified global namespace. + * + * @param {*} _global Namespace to mock (e.g. `window`) + * @returns {FakeTimers} + */ +function withGlobal(_global) { + const maxTimeout = Math.pow(2, 31) - 1; //see https://heycam.github.io/webidl/#abstract-opdef-converttoint + const idCounterStart = 1e12; // arbitrarily large number to avoid collisions with native timer IDs + const NOOP = function () { + return undefined; + }; + const NOOP_ARRAY = function () { + return []; + }; + const timeoutResult = _global.setTimeout(NOOP, 0); + const addTimerReturnsObject = typeof timeoutResult === "object"; + const performancePresent = + _global.performance && typeof _global.performance.now === "function"; + const hasPerformancePrototype = + _global.Performance && + (typeof _global.Performance).match(/^(function|object)$/); + const hasPerformanceConstructorPrototype = + _global.performance && + _global.performance.constructor && + _global.performance.constructor.prototype; + const queueMicrotaskPresent = _global.hasOwnProperty("queueMicrotask"); + const requestAnimationFramePresent = + _global.requestAnimationFrame && + typeof _global.requestAnimationFrame === "function"; + const cancelAnimationFramePresent = + _global.cancelAnimationFrame && + typeof _global.cancelAnimationFrame === "function"; + const requestIdleCallbackPresent = + _global.requestIdleCallback && + typeof _global.requestIdleCallback === "function"; + const cancelIdleCallbackPresent = + _global.cancelIdleCallback && + typeof _global.cancelIdleCallback === "function"; + const setImmediatePresent = + _global.setImmediate && typeof _global.setImmediate === "function"; + const intlPresent = _global.Intl && typeof _global.Intl === "object"; + + _global.clearTimeout(timeoutResult); + + const NativeDate = _global.Date; + const NativeIntl = _global.Intl; + let uniqueTimerId = idCounterStart; + + /** + * @param {number} num + * @returns {boolean} + */ + function isNumberFinite(num) { + if (Number.isFinite) { + return Number.isFinite(num); + } + + return isFinite(num); + } + + let isNearInfiniteLimit = false; + + /** + * @param {Clock} clock + * @param {number} i + */ + function checkIsNearInfiniteLimit(clock, i) { + if (clock.loopLimit && i === clock.loopLimit - 1) { + isNearInfiniteLimit = true; + } + } + + /** + * + */ + function resetIsNearInfiniteLimit() { + isNearInfiniteLimit = false; + } + + /** + * Parse strings like "01:10:00" (meaning 1 hour, 10 minutes, 0 seconds) into + * number of milliseconds. This is used to support human-readable strings passed + * to clock.tick() + * + * @param {string} str + * @returns {number} + */ + function parseTime(str) { + if (!str) { + return 0; + } + + const strings = str.split(":"); + const l = strings.length; + let i = l; + let ms = 0; + let parsed; + + if (l > 3 || !/^(\d\d:){0,2}\d\d?$/.test(str)) { + throw new Error( + "tick only understands numbers, 'm:s' and 'h:m:s'. Each part must be two digits", + ); + } + + while (i--) { + parsed = parseInt(strings[i], 10); + + if (parsed >= 60) { + throw new Error(`Invalid time ${str}`); + } + + ms += parsed * Math.pow(60, l - i - 1); + } + + return ms * 1000; + } + + /** + * Get the decimal part of the millisecond value as nanoseconds + * + * @param {number} msFloat the number of milliseconds + * @returns {number} an integer number of nanoseconds in the range [0,1e6) + * + * Example: nanoRemainer(123.456789) -> 456789 + */ + function nanoRemainder(msFloat) { + const modulo = 1e6; + const remainder = (msFloat * 1e6) % modulo; + const positiveRemainder = + remainder < 0 ? remainder + modulo : remainder; + + return Math.floor(positiveRemainder); + } + + /** + * Used to grok the `now` parameter to createClock. + * + * @param {Date|number} epoch the system time + * @returns {number} + */ + function getEpoch(epoch) { + if (!epoch) { + return 0; + } + if (typeof epoch.getTime === "function") { + return epoch.getTime(); + } + if (typeof epoch === "number") { + return epoch; + } + throw new TypeError("now should be milliseconds since UNIX epoch"); + } + + /** + * @param {number} from + * @param {number} to + * @param {Timer} timer + * @returns {boolean} + */ + function inRange(from, to, timer) { + return timer && timer.callAt >= from && timer.callAt <= to; + } + + /** + * @param {Clock} clock + * @param {Timer} job + */ + function getInfiniteLoopError(clock, job) { + const infiniteLoopError = new Error( + `Aborting after running ${clock.loopLimit} timers, assuming an infinite loop!`, + ); + + if (!job.error) { + return infiniteLoopError; + } + + // pattern never matched in Node + const computedTargetPattern = /target\.*[<|(|[].*?[>|\]|)]\s*/; + let clockMethodPattern = new RegExp( + String(Object.keys(clock).join("|")), + ); + + if (addTimerReturnsObject) { + // node.js environment + clockMethodPattern = new RegExp( + `\\s+at (Object\\.)?(?:${Object.keys(clock).join("|")})\\s+`, + ); + } + + let matchedLineIndex = -1; + job.error.stack.split("\n").some(function (line, i) { + // If we've matched a computed target line (e.g. setTimeout) then we + // don't need to look any further. Return true to stop iterating. + const matchedComputedTarget = line.match(computedTargetPattern); + /* istanbul ignore if */ + if (matchedComputedTarget) { + matchedLineIndex = i; + return true; + } + + // If we've matched a clock method line, then there may still be + // others further down the trace. Return false to keep iterating. + const matchedClockMethod = line.match(clockMethodPattern); + if (matchedClockMethod) { + matchedLineIndex = i; + return false; + } + + // If we haven't matched anything on this line, but we matched + // previously and set the matched line index, then we can stop. + // If we haven't matched previously, then we should keep iterating. + return matchedLineIndex >= 0; + }); + + const stack = `${infiniteLoopError}\n${job.type || "Microtask"} - ${ + job.func.name || "anonymous" + }\n${job.error.stack + .split("\n") + .slice(matchedLineIndex + 1) + .join("\n")}`; + + try { + Object.defineProperty(infiniteLoopError, "stack", { + value: stack, + }); + } catch (e) { + // noop + } + + return infiniteLoopError; + } + + /** + * @param {Date} target + * @param {Date} source + * @returns {Date} the target after modifications + */ + function mirrorDateProperties(target, source) { + let prop; + for (prop in source) { + if (source.hasOwnProperty(prop)) { + target[prop] = source[prop]; + } + } + + // set special now implementation + if (source.now) { + target.now = function now() { + return target.clock.now; + }; + } else { + delete target.now; + } + + // set special toSource implementation + if (source.toSource) { + target.toSource = function toSource() { + return source.toSource(); + }; + } else { + delete target.toSource; + } + + // set special toString implementation + target.toString = function toString() { + return source.toString(); + }; + + target.prototype = source.prototype; + target.parse = source.parse; + target.UTC = source.UTC; + target.prototype.toUTCString = source.prototype.toUTCString; + target.isFake = true; + + return target; + } + + //eslint-disable-next-line jsdoc/require-jsdoc + function createDate() { + /** + * @param {number} year + * @param {number} month + * @param {number} date + * @param {number} hour + * @param {number} minute + * @param {number} second + * @param {number} ms + * @returns {Date} + */ + function ClockDate(year, month, date, hour, minute, second, ms) { + // the Date constructor called as a function, ref Ecma-262 Edition 5.1, section 15.9.2. + // This remains so in the 10th edition of 2019 as well. + if (!(this instanceof ClockDate)) { + return new NativeDate(ClockDate.clock.now).toString(); + } + + // if Date is called as a constructor with 'new' keyword + // Defensive and verbose to avoid potential harm in passing + // explicit undefined when user does not pass argument + switch (arguments.length) { + case 0: + return new NativeDate(ClockDate.clock.now); + case 1: + return new NativeDate(year); + case 2: + return new NativeDate(year, month); + case 3: + return new NativeDate(year, month, date); + case 4: + return new NativeDate(year, month, date, hour); + case 5: + return new NativeDate(year, month, date, hour, minute); + case 6: + return new NativeDate( + year, + month, + date, + hour, + minute, + second, + ); + default: + return new NativeDate( + year, + month, + date, + hour, + minute, + second, + ms, + ); + } + } + + return mirrorDateProperties(ClockDate, NativeDate); + } + + /** + * Mirror Intl by default on our fake implementation + * + * Most of the properties are the original native ones, + * but we need to take control of those that have a + * dependency on the current clock. + * + * @returns {object} the partly fake Intl implementation + */ + function createIntl() { + const ClockIntl = {}; + /* + * All properties of Intl are non-enumerable, so we need + * to do a bit of work to get them out. + */ + Object.getOwnPropertyNames(NativeIntl).forEach( + (property) => (ClockIntl[property] = NativeIntl[property]), + ); + + ClockIntl.DateTimeFormat = function (...args) { + const realFormatter = new NativeIntl.DateTimeFormat(...args); + const formatter = {}; + + ["formatRange", "formatRangeToParts", "resolvedOptions"].forEach( + (method) => { + formatter[method] = + realFormatter[method].bind(realFormatter); + }, + ); + + ["format", "formatToParts"].forEach((method) => { + formatter[method] = function (date) { + return realFormatter[method](date || ClockIntl.clock.now); + }; + }); + + return formatter; + }; + + ClockIntl.DateTimeFormat.prototype = Object.create( + NativeIntl.DateTimeFormat.prototype, + ); + + ClockIntl.DateTimeFormat.supportedLocalesOf = + NativeIntl.DateTimeFormat.supportedLocalesOf; + + return ClockIntl; + } + + //eslint-disable-next-line jsdoc/require-jsdoc + function enqueueJob(clock, job) { + // enqueues a microtick-deferred task - ecma262/#sec-enqueuejob + if (!clock.jobs) { + clock.jobs = []; + } + clock.jobs.push(job); + } + + //eslint-disable-next-line jsdoc/require-jsdoc + function runJobs(clock) { + // runs all microtick-deferred tasks - ecma262/#sec-runjobs + if (!clock.jobs) { + return; + } + for (let i = 0; i < clock.jobs.length; i++) { + const job = clock.jobs[i]; + job.func.apply(null, job.args); + + checkIsNearInfiniteLimit(clock, i); + if (clock.loopLimit && i > clock.loopLimit) { + throw getInfiniteLoopError(clock, job); + } + } + resetIsNearInfiniteLimit(); + clock.jobs = []; + } + + /** + * @param {Clock} clock + * @param {Timer} timer + * @returns {number} id of the created timer + */ + function addTimer(clock, timer) { + if (timer.func === undefined) { + throw new Error("Callback must be provided to timer calls"); + } + + if (addTimerReturnsObject) { + // Node.js environment + if (typeof timer.func !== "function") { + throw new TypeError( + `[ERR_INVALID_CALLBACK]: Callback must be a function. Received ${ + timer.func + } of type ${typeof timer.func}`, + ); + } + } + + if (isNearInfiniteLimit) { + timer.error = new Error(); + } + + timer.type = timer.immediate ? "Immediate" : "Timeout"; + + if (timer.hasOwnProperty("delay")) { + if (typeof timer.delay !== "number") { + timer.delay = parseInt(timer.delay, 10); + } + + if (!isNumberFinite(timer.delay)) { + timer.delay = 0; + } + timer.delay = timer.delay > maxTimeout ? 1 : timer.delay; + timer.delay = Math.max(0, timer.delay); + } + + if (timer.hasOwnProperty("interval")) { + timer.type = "Interval"; + timer.interval = timer.interval > maxTimeout ? 1 : timer.interval; + } + + if (timer.hasOwnProperty("animation")) { + timer.type = "AnimationFrame"; + timer.animation = true; + } + + if (timer.hasOwnProperty("idleCallback")) { + timer.type = "IdleCallback"; + timer.idleCallback = true; + } + + if (!clock.timers) { + clock.timers = {}; + } + + timer.id = uniqueTimerId++; + timer.createdAt = clock.now; + timer.callAt = + clock.now + (parseInt(timer.delay) || (clock.duringTick ? 1 : 0)); + + clock.timers[timer.id] = timer; + + if (addTimerReturnsObject) { + const res = { + refed: true, + ref: function () { + this.refed = true; + return res; + }, + unref: function () { + this.refed = false; + return res; + }, + hasRef: function () { + return this.refed; + }, + refresh: function () { + timer.callAt = + clock.now + + (parseInt(timer.delay) || (clock.duringTick ? 1 : 0)); + + // it _might_ have been removed, but if not the assignment is perfectly fine + clock.timers[timer.id] = timer; + + return res; + }, + [Symbol.toPrimitive]: function () { + return timer.id; + }, + }; + return res; + } + + return timer.id; + } + + /* eslint consistent-return: "off" */ + /** + * Timer comparitor + * + * @param {Timer} a + * @param {Timer} b + * @returns {number} + */ + function compareTimers(a, b) { + // Sort first by absolute timing + if (a.callAt < b.callAt) { + return -1; + } + if (a.callAt > b.callAt) { + return 1; + } + + // Sort next by immediate, immediate timers take precedence + if (a.immediate && !b.immediate) { + return -1; + } + if (!a.immediate && b.immediate) { + return 1; + } + + // Sort next by creation time, earlier-created timers take precedence + if (a.createdAt < b.createdAt) { + return -1; + } + if (a.createdAt > b.createdAt) { + return 1; + } + + // Sort next by id, lower-id timers take precedence + if (a.id < b.id) { + return -1; + } + if (a.id > b.id) { + return 1; + } + + // As timer ids are unique, no fallback `0` is necessary + } + + /** + * @param {Clock} clock + * @param {number} from + * @param {number} to + * @returns {Timer} + */ + function firstTimerInRange(clock, from, to) { + const timers = clock.timers; + let timer = null; + let id, isInRange; + + for (id in timers) { + if (timers.hasOwnProperty(id)) { + isInRange = inRange(from, to, timers[id]); + + if ( + isInRange && + (!timer || compareTimers(timer, timers[id]) === 1) + ) { + timer = timers[id]; + } + } + } + + return timer; + } + + /** + * @param {Clock} clock + * @returns {Timer} + */ + function firstTimer(clock) { + const timers = clock.timers; + let timer = null; + let id; + + for (id in timers) { + if (timers.hasOwnProperty(id)) { + if (!timer || compareTimers(timer, timers[id]) === 1) { + timer = timers[id]; + } + } + } + + return timer; + } + + /** + * @param {Clock} clock + * @returns {Timer} + */ + function lastTimer(clock) { + const timers = clock.timers; + let timer = null; + let id; + + for (id in timers) { + if (timers.hasOwnProperty(id)) { + if (!timer || compareTimers(timer, timers[id]) === -1) { + timer = timers[id]; + } + } + } + + return timer; + } + + /** + * @param {Clock} clock + * @param {Timer} timer + */ + function callTimer(clock, timer) { + if (typeof timer.interval === "number") { + clock.timers[timer.id].callAt += timer.interval; + } else { + delete clock.timers[timer.id]; + } + + if (typeof timer.func === "function") { + timer.func.apply(null, timer.args); + } else { + /* eslint no-eval: "off" */ + const eval2 = eval; + (function () { + eval2(timer.func); + })(); + } + } + + /** + * Gets clear handler name for a given timer type + * + * @param {string} ttype + */ + function getClearHandler(ttype) { + if (ttype === "IdleCallback" || ttype === "AnimationFrame") { + return `cancel${ttype}`; + } + return `clear${ttype}`; + } + + /** + * Gets schedule handler name for a given timer type + * + * @param {string} ttype + */ + function getScheduleHandler(ttype) { + if (ttype === "IdleCallback" || ttype === "AnimationFrame") { + return `request${ttype}`; + } + return `set${ttype}`; + } + + /** + * Creates an anonymous function to warn only once + */ + function createWarnOnce() { + let calls = 0; + return function (msg) { + // eslint-disable-next-line + !calls++ && console.warn(msg); + }; + } + const warnOnce = createWarnOnce(); + + /** + * @param {Clock} clock + * @param {number} timerId + * @param {string} ttype + */ + function clearTimer(clock, timerId, ttype) { + if (!timerId) { + // null appears to be allowed in most browsers, and appears to be + // relied upon by some libraries, like Bootstrap carousel + return; + } + + if (!clock.timers) { + clock.timers = {}; + } + + // in Node, the ID is stored as the primitive value for `Timeout` objects + // for `Immediate` objects, no ID exists, so it gets coerced to NaN + const id = Number(timerId); + + if (Number.isNaN(id) || id < idCounterStart) { + const handlerName = getClearHandler(ttype); + + if (clock.shouldClearNativeTimers === true) { + const nativeHandler = clock[`_${handlerName}`]; + return typeof nativeHandler === "function" + ? nativeHandler(timerId) + : undefined; + } + warnOnce( + `FakeTimers: ${handlerName} was invoked to clear a native timer instead of one created by this library.` + + "\nTo automatically clean-up native timers, use `shouldClearNativeTimers`.", + ); + } + + if (clock.timers.hasOwnProperty(id)) { + // check that the ID matches a timer of the correct type + const timer = clock.timers[id]; + if ( + timer.type === ttype || + (timer.type === "Timeout" && ttype === "Interval") || + (timer.type === "Interval" && ttype === "Timeout") + ) { + delete clock.timers[id]; + } else { + const clear = getClearHandler(ttype); + const schedule = getScheduleHandler(timer.type); + throw new Error( + `Cannot clear timer: timer created with ${schedule}() but cleared with ${clear}()`, + ); + } + } + } + + /** + * @param {Clock} clock + * @param {Config} config + * @returns {Timer[]} + */ + function uninstall(clock, config) { + let method, i, l; + const installedHrTime = "_hrtime"; + const installedNextTick = "_nextTick"; + + for (i = 0, l = clock.methods.length; i < l; i++) { + method = clock.methods[i]; + if (method === "performance") { + const originalPerfDescriptor = Object.getOwnPropertyDescriptor( + clock, + `_${method}`, + ); + if ( + originalPerfDescriptor && + originalPerfDescriptor.get && + !originalPerfDescriptor.set + ) { + Object.defineProperty( + _global, + method, + originalPerfDescriptor, + ); + } else if (originalPerfDescriptor.configurable) { + _global[method] = clock[`_${method}`]; + } + } else { + if (_global[method] && _global[method].hadOwnProperty) { + _global[method] = clock[`_${method}`]; + } else { + try { + delete _global[method]; + } catch (ignore) { + /* eslint no-empty: "off" */ + } + } + } + } + + if (config.shouldAdvanceTime === true) { + _global.clearInterval(clock.attachedInterval); + } + + // Prevent multiple executions which will completely remove these props + clock.methods = []; + + // return pending timers, to enable checking what timers remained on uninstall + if (!clock.timers) { + return []; + } + return Object.keys(clock.timers).map(function mapper(key) { + return clock.timers[key]; + }); + } + + /** + * @param {object} target the target containing the method to replace + * @param {string} method the keyname of the method on the target + * @param {Clock} clock + */ + function hijackMethod(target, method, clock) { + clock[method].hadOwnProperty = Object.prototype.hasOwnProperty.call( + target, + method, + ); + clock[`_${method}`] = target[method]; + + if (method === "Date") { + const date = mirrorDateProperties(clock[method], target[method]); + target[method] = date; + } else if (method === "Intl") { + target[method] = clock[method]; + } else if (method === "performance") { + const originalPerfDescriptor = Object.getOwnPropertyDescriptor( + target, + method, + ); + // JSDOM has a read only performance field so we have to save/copy it differently + if ( + originalPerfDescriptor && + originalPerfDescriptor.get && + !originalPerfDescriptor.set + ) { + Object.defineProperty( + clock, + `_${method}`, + originalPerfDescriptor, + ); + + const perfDescriptor = Object.getOwnPropertyDescriptor( + clock, + method, + ); + Object.defineProperty(target, method, perfDescriptor); + } else { + target[method] = clock[method]; + } + } else { + target[method] = function () { + return clock[method].apply(clock, arguments); + }; + + Object.defineProperties( + target[method], + Object.getOwnPropertyDescriptors(clock[method]), + ); + } + + target[method].clock = clock; + } + + /** + * @param {Clock} clock + * @param {number} advanceTimeDelta + */ + function doIntervalTick(clock, advanceTimeDelta) { + clock.tick(advanceTimeDelta); + } + + /** + * @typedef {object} Timers + * @property {setTimeout} setTimeout + * @property {clearTimeout} clearTimeout + * @property {setInterval} setInterval + * @property {clearInterval} clearInterval + * @property {Date} Date + * @property {Intl} Intl + * @property {SetImmediate=} setImmediate + * @property {function(NodeImmediate): void=} clearImmediate + * @property {function(number[]):number[]=} hrtime + * @property {NextTick=} nextTick + * @property {Performance=} performance + * @property {RequestAnimationFrame=} requestAnimationFrame + * @property {boolean=} queueMicrotask + * @property {function(number): void=} cancelAnimationFrame + * @property {RequestIdleCallback=} requestIdleCallback + * @property {function(number): void=} cancelIdleCallback + */ + + /** @type {Timers} */ + const timers = { + setTimeout: _global.setTimeout, + clearTimeout: _global.clearTimeout, + setInterval: _global.setInterval, + clearInterval: _global.clearInterval, + Date: _global.Date, + }; + + if (setImmediatePresent) { + timers.setImmediate = _global.setImmediate; + timers.clearImmediate = _global.clearImmediate; + } + + if (performancePresent) { + timers.performance = _global.performance; + } + + if (requestAnimationFramePresent) { + timers.requestAnimationFrame = _global.requestAnimationFrame; + } + + if (queueMicrotaskPresent) { + timers.queueMicrotask = true; + } + + if (cancelAnimationFramePresent) { + timers.cancelAnimationFrame = _global.cancelAnimationFrame; + } + + if (requestIdleCallbackPresent) { + timers.requestIdleCallback = _global.requestIdleCallback; + } + + if (cancelIdleCallbackPresent) { + timers.cancelIdleCallback = _global.cancelIdleCallback; + } + + if (intlPresent) { + timers.Intl = _global.Intl; + } + + const originalSetTimeout = _global.setImmediate || _global.setTimeout; + + /** + * @param {Date|number} [start] the system time - non-integer values are floored + * @param {number} [loopLimit] maximum number of timers that will be run when calling runAll() + * @returns {Clock} + */ + function createClock(start, loopLimit) { + // eslint-disable-next-line no-param-reassign + start = Math.floor(getEpoch(start)); + // eslint-disable-next-line no-param-reassign + loopLimit = loopLimit || 1000; + let nanos = 0; + const adjustedSystemTime = [0, 0]; // [millis, nanoremainder] + + if (NativeDate === undefined) { + throw new Error( + "The global scope doesn't have a `Date` object" + + " (see https://github.com/sinonjs/sinon/issues/1852#issuecomment-419622780)", + ); + } + + const clock = { + now: start, + Date: createDate(), + loopLimit: loopLimit, + }; + + clock.Date.clock = clock; + + //eslint-disable-next-line jsdoc/require-jsdoc + function getTimeToNextFrame() { + return 16 - ((clock.now - start) % 16); + } + + //eslint-disable-next-line jsdoc/require-jsdoc + function hrtime(prev) { + const millisSinceStart = clock.now - adjustedSystemTime[0] - start; + const secsSinceStart = Math.floor(millisSinceStart / 1000); + const remainderInNanos = + (millisSinceStart - secsSinceStart * 1e3) * 1e6 + + nanos - + adjustedSystemTime[1]; + + if (Array.isArray(prev)) { + if (prev[1] > 1e9) { + throw new TypeError( + "Number of nanoseconds can't exceed a billion", + ); + } + + const oldSecs = prev[0]; + let nanoDiff = remainderInNanos - prev[1]; + let secDiff = secsSinceStart - oldSecs; + + if (nanoDiff < 0) { + nanoDiff += 1e9; + secDiff -= 1; + } + + return [secDiff, nanoDiff]; + } + return [secsSinceStart, remainderInNanos]; + } + + /** + * A high resolution timestamp in milliseconds. + * + * @typedef {number} DOMHighResTimeStamp + */ + + /** + * performance.now() + * + * @returns {DOMHighResTimeStamp} + */ + function fakePerformanceNow() { + const hrt = hrtime(); + const millis = hrt[0] * 1000 + hrt[1] / 1e6; + return millis; + } + + if (intlPresent) { + clock.Intl = createIntl(); + clock.Intl.clock = clock; + } + + clock.requestIdleCallback = function requestIdleCallback( + func, + timeout, + ) { + let timeToNextIdlePeriod = 0; + + if (clock.countTimers() > 0) { + timeToNextIdlePeriod = 50; // const for now + } + + const result = addTimer(clock, { + func: func, + args: Array.prototype.slice.call(arguments, 2), + delay: + typeof timeout === "undefined" + ? timeToNextIdlePeriod + : Math.min(timeout, timeToNextIdlePeriod), + idleCallback: true, + }); + + return Number(result); + }; + + clock.cancelIdleCallback = function cancelIdleCallback(timerId) { + return clearTimer(clock, timerId, "IdleCallback"); + }; + + clock.setTimeout = function setTimeout(func, timeout) { + return addTimer(clock, { + func: func, + args: Array.prototype.slice.call(arguments, 2), + delay: timeout, + }); + }; + + clock.clearTimeout = function clearTimeout(timerId) { + return clearTimer(clock, timerId, "Timeout"); + }; + + clock.nextTick = function nextTick(func) { + return enqueueJob(clock, { + func: func, + args: Array.prototype.slice.call(arguments, 1), + error: isNearInfiniteLimit ? new Error() : null, + }); + }; + + clock.queueMicrotask = function queueMicrotask(func) { + return clock.nextTick(func); // explicitly drop additional arguments + }; + + clock.setInterval = function setInterval(func, timeout) { + // eslint-disable-next-line no-param-reassign + timeout = parseInt(timeout, 10); + return addTimer(clock, { + func: func, + args: Array.prototype.slice.call(arguments, 2), + delay: timeout, + interval: timeout, + }); + }; + + clock.clearInterval = function clearInterval(timerId) { + return clearTimer(clock, timerId, "Interval"); + }; + + if (setImmediatePresent) { + clock.setImmediate = function setImmediate(func) { + return addTimer(clock, { + func: func, + args: Array.prototype.slice.call(arguments, 1), + immediate: true, + }); + }; + + clock.clearImmediate = function clearImmediate(timerId) { + return clearTimer(clock, timerId, "Immediate"); + }; + } + + clock.countTimers = function countTimers() { + return ( + Object.keys(clock.timers || {}).length + + (clock.jobs || []).length + ); + }; + + clock.requestAnimationFrame = function requestAnimationFrame(func) { + const result = addTimer(clock, { + func: func, + delay: getTimeToNextFrame(), + get args() { + return [fakePerformanceNow()]; + }, + animation: true, + }); + + return Number(result); + }; + + clock.cancelAnimationFrame = function cancelAnimationFrame(timerId) { + return clearTimer(clock, timerId, "AnimationFrame"); + }; + + clock.runMicrotasks = function runMicrotasks() { + runJobs(clock); + }; + + /** + * @param {number|string} tickValue milliseconds or a string parseable by parseTime + * @param {boolean} isAsync + * @param {Function} resolve + * @param {Function} reject + * @returns {number|undefined} will return the new `now` value or nothing for async + */ + function doTick(tickValue, isAsync, resolve, reject) { + const msFloat = + typeof tickValue === "number" + ? tickValue + : parseTime(tickValue); + const ms = Math.floor(msFloat); + const remainder = nanoRemainder(msFloat); + let nanosTotal = nanos + remainder; + let tickTo = clock.now + ms; + + if (msFloat < 0) { + throw new TypeError("Negative ticks are not supported"); + } + + // adjust for positive overflow + if (nanosTotal >= 1e6) { + tickTo += 1; + nanosTotal -= 1e6; + } + + nanos = nanosTotal; + let tickFrom = clock.now; + let previous = clock.now; + // ESLint fails to detect this correctly + /* eslint-disable prefer-const */ + let timer, + firstException, + oldNow, + nextPromiseTick, + compensationCheck, + postTimerCall; + /* eslint-enable prefer-const */ + + clock.duringTick = true; + + // perform microtasks + oldNow = clock.now; + runJobs(clock); + if (oldNow !== clock.now) { + // compensate for any setSystemTime() call during microtask callback + tickFrom += clock.now - oldNow; + tickTo += clock.now - oldNow; + } + + //eslint-disable-next-line jsdoc/require-jsdoc + function doTickInner() { + // perform each timer in the requested range + timer = firstTimerInRange(clock, tickFrom, tickTo); + // eslint-disable-next-line no-unmodified-loop-condition + while (timer && tickFrom <= tickTo) { + if (clock.timers[timer.id]) { + tickFrom = timer.callAt; + clock.now = timer.callAt; + oldNow = clock.now; + try { + runJobs(clock); + callTimer(clock, timer); + } catch (e) { + firstException = firstException || e; + } + + if (isAsync) { + // finish up after native setImmediate callback to allow + // all native es6 promises to process their callbacks after + // each timer fires. + originalSetTimeout(nextPromiseTick); + return; + } + + compensationCheck(); + } + + postTimerCall(); + } + + // perform process.nextTick()s again + oldNow = clock.now; + runJobs(clock); + if (oldNow !== clock.now) { + // compensate for any setSystemTime() call during process.nextTick() callback + tickFrom += clock.now - oldNow; + tickTo += clock.now - oldNow; + } + clock.duringTick = false; + + // corner case: during runJobs new timers were scheduled which could be in the range [clock.now, tickTo] + timer = firstTimerInRange(clock, tickFrom, tickTo); + if (timer) { + try { + clock.tick(tickTo - clock.now); // do it all again - for the remainder of the requested range + } catch (e) { + firstException = firstException || e; + } + } else { + // no timers remaining in the requested range: move the clock all the way to the end + clock.now = tickTo; + + // update nanos + nanos = nanosTotal; + } + if (firstException) { + throw firstException; + } + + if (isAsync) { + resolve(clock.now); + } else { + return clock.now; + } + } + + nextPromiseTick = + isAsync && + function () { + try { + compensationCheck(); + postTimerCall(); + doTickInner(); + } catch (e) { + reject(e); + } + }; + + compensationCheck = function () { + // compensate for any setSystemTime() call during timer callback + if (oldNow !== clock.now) { + tickFrom += clock.now - oldNow; + tickTo += clock.now - oldNow; + previous += clock.now - oldNow; + } + }; + + postTimerCall = function () { + timer = firstTimerInRange(clock, previous, tickTo); + previous = tickFrom; + }; + + return doTickInner(); + } + + /** + * @param {string|number} tickValue number of milliseconds or a human-readable value like "01:11:15" + * @returns {number} will return the new `now` value + */ + clock.tick = function tick(tickValue) { + return doTick(tickValue, false); + }; + + if (typeof _global.Promise !== "undefined") { + /** + * @param {string|number} tickValue number of milliseconds or a human-readable value like "01:11:15" + * @returns {Promise} + */ + clock.tickAsync = function tickAsync(tickValue) { + return new _global.Promise(function (resolve, reject) { + originalSetTimeout(function () { + try { + doTick(tickValue, true, resolve, reject); + } catch (e) { + reject(e); + } + }); + }); + }; + } + + clock.next = function next() { + runJobs(clock); + const timer = firstTimer(clock); + if (!timer) { + return clock.now; + } + + clock.duringTick = true; + try { + clock.now = timer.callAt; + callTimer(clock, timer); + runJobs(clock); + return clock.now; + } finally { + clock.duringTick = false; + } + }; + + if (typeof _global.Promise !== "undefined") { + clock.nextAsync = function nextAsync() { + return new _global.Promise(function (resolve, reject) { + originalSetTimeout(function () { + try { + const timer = firstTimer(clock); + if (!timer) { + resolve(clock.now); + return; + } + + let err; + clock.duringTick = true; + clock.now = timer.callAt; + try { + callTimer(clock, timer); + } catch (e) { + err = e; + } + clock.duringTick = false; + + originalSetTimeout(function () { + if (err) { + reject(err); + } else { + resolve(clock.now); + } + }); + } catch (e) { + reject(e); + } + }); + }); + }; + } + + clock.runAll = function runAll() { + let numTimers, i; + runJobs(clock); + for (i = 0; i < clock.loopLimit; i++) { + if (!clock.timers) { + resetIsNearInfiniteLimit(); + return clock.now; + } + + numTimers = Object.keys(clock.timers).length; + if (numTimers === 0) { + resetIsNearInfiniteLimit(); + return clock.now; + } + + clock.next(); + checkIsNearInfiniteLimit(clock, i); + } + + const excessJob = firstTimer(clock); + throw getInfiniteLoopError(clock, excessJob); + }; + + clock.runToFrame = function runToFrame() { + return clock.tick(getTimeToNextFrame()); + }; + + if (typeof _global.Promise !== "undefined") { + clock.runAllAsync = function runAllAsync() { + return new _global.Promise(function (resolve, reject) { + let i = 0; + /** + * + */ + function doRun() { + originalSetTimeout(function () { + try { + runJobs(clock); + + let numTimers; + if (i < clock.loopLimit) { + if (!clock.timers) { + resetIsNearInfiniteLimit(); + resolve(clock.now); + return; + } + + numTimers = Object.keys( + clock.timers, + ).length; + if (numTimers === 0) { + resetIsNearInfiniteLimit(); + resolve(clock.now); + return; + } + + clock.next(); + + i++; + + doRun(); + checkIsNearInfiniteLimit(clock, i); + return; + } + + const excessJob = firstTimer(clock); + reject(getInfiniteLoopError(clock, excessJob)); + } catch (e) { + reject(e); + } + }); + } + doRun(); + }); + }; + } + + clock.runToLast = function runToLast() { + const timer = lastTimer(clock); + if (!timer) { + runJobs(clock); + return clock.now; + } + + return clock.tick(timer.callAt - clock.now); + }; + + if (typeof _global.Promise !== "undefined") { + clock.runToLastAsync = function runToLastAsync() { + return new _global.Promise(function (resolve, reject) { + originalSetTimeout(function () { + try { + const timer = lastTimer(clock); + if (!timer) { + runJobs(clock); + resolve(clock.now); + } + + resolve(clock.tickAsync(timer.callAt - clock.now)); + } catch (e) { + reject(e); + } + }); + }); + }; + } + + clock.reset = function reset() { + nanos = 0; + clock.timers = {}; + clock.jobs = []; + clock.now = start; + }; + + clock.setSystemTime = function setSystemTime(systemTime) { + // determine time difference + const newNow = getEpoch(systemTime); + const difference = newNow - clock.now; + let id, timer; + + adjustedSystemTime[0] = adjustedSystemTime[0] + difference; + adjustedSystemTime[1] = adjustedSystemTime[1] + nanos; + // update 'system clock' + clock.now = newNow; + nanos = 0; + + // update timers and intervals to keep them stable + for (id in clock.timers) { + if (clock.timers.hasOwnProperty(id)) { + timer = clock.timers[id]; + timer.createdAt += difference; + timer.callAt += difference; + } + } + }; + + /** + * @param {string|number} tickValue number of milliseconds or a human-readable value like "01:11:15" + * @returns {number} will return the new `now` value + */ + clock.jump = function jump(tickValue) { + const msFloat = + typeof tickValue === "number" + ? tickValue + : parseTime(tickValue); + const ms = Math.floor(msFloat); + + for (const timer of Object.values(clock.timers)) { + if (clock.now + ms > timer.callAt) { + timer.callAt = clock.now + ms; + } + } + clock.tick(ms); + }; + + if (performancePresent) { + clock.performance = Object.create(null); + clock.performance.now = fakePerformanceNow; + } + + return clock; + } + + /* eslint-disable complexity */ + + /** + * @param {Config=} [config] Optional config + * @returns {Clock} + */ + function install(config) { + console.log('INSTALL', config); + if ( + arguments.length > 1 || + config instanceof Date || + Array.isArray(config) || + typeof config === "number" + ) { + throw new TypeError( + `FakeTimers.install called with ${String( + config, + )} install requires an object parameter`, + ); + } + + if (_global.Date.isFake === true) { + // Timers are already faked; this is a problem. + // Make the user reset timers before continuing. + throw new TypeError( + "Can't install fake timers twice on the same global object.", + ); + } + + // eslint-disable-next-line no-param-reassign + config = typeof config !== "undefined" ? config : {}; + config.shouldAdvanceTime = config.shouldAdvanceTime || false; + config.advanceTimeDelta = config.advanceTimeDelta || 20; + config.shouldClearNativeTimers = + config.shouldClearNativeTimers || false; + + if (config.target) { + throw new TypeError( + "config.target is no longer supported. Use `withGlobal(target)` instead.", + ); + } + + let i, l; + const clock = createClock(config.now, config.loopLimit); + clock.shouldClearNativeTimers = config.shouldClearNativeTimers; + + clock.uninstall = function () { + return uninstall(clock, config); + }; + + clock.methods = config.toFake || []; + + if (clock.methods.length === 0) { + // do not fake nextTick by default - GitHub#126 + clock.methods = Object.keys(timers).filter(function (key) { + return key !== "nextTick" && key !== "queueMicrotask"; + }); + } + + if (config.shouldAdvanceTime === true) { + const intervalTick = doIntervalTick.bind( + null, + clock, + config.advanceTimeDelta, + ); + const intervalId = _global.setInterval( + intervalTick, + config.advanceTimeDelta, + ); + clock.attachedInterval = intervalId; + } + + if (clock.methods.includes("performance")) { + const proto = (() => { + if (hasPerformanceConstructorPrototype) { + return _global.performance.constructor.prototype; + } + if (hasPerformancePrototype) { + return _global.Performance.prototype; + } + })(); + if (proto) { + Object.getOwnPropertyNames(proto).forEach(function (name) { + if (name !== "now") { + clock.performance[name] = + name.indexOf("getEntries") === 0 + ? NOOP_ARRAY + : NOOP; + } + }); + } else if ((config.toFake || []).includes("performance")) { + // user explicitly tried to fake performance when not present + throw new ReferenceError( + "non-existent performance object cannot be faked", + ); + } + } + + for (i = 0, l = clock.methods.length; i < l; i++) { + const nameOfMethodToReplace = clock.methods[i]; + hijackMethod(_global, nameOfMethodToReplace, clock); + } + + return clock; + } + + /* eslint-enable complexity */ + + return { + timers: timers, + createClock: createClock, + install: install, + withGlobal: withGlobal, + }; +} + +/** + * @typedef {object} FakeTimers + * @property {Function} install + * @property {withGlobal} withGlobal + */ + +/* eslint-enable complexity */ + +/** @type {FakeTimers} */ +const defaultImplementation = withGlobal(globalThis); +exports.install = defaultImplementation.install; diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.ts index 54d79f9ca1..38cdd75a58 100644 --- a/packages/playwright-core/types/types.d.ts +++ b/packages/playwright-core/types/types.d.ts @@ -4863,6 +4863,11 @@ export interface Page { */ accessibility: Accessibility; + /** + * Playwright is using [@sinonjs/fake-timers](https://github.com/sinonjs/fake-timers) to fake timers and clock. + */ + clock: Clock; + /** * **NOTE** Only available for Chromium atm. * @@ -8980,6 +8985,11 @@ export interface BrowserContext { waitForEvent(event: 'weberror', optionsOrPredicate?: { predicate?: (webError: WebError) => boolean | Promise, timeout?: number } | ((webError: WebError) => boolean | Promise)): Promise; + /** + * Playwright is using [@sinonjs/fake-timers](https://github.com/sinonjs/fake-timers) to fake timers and clock. + */ + clock: Clock; + /** * API testing helper associated with this context. Requests made with this API will use context cookies. */ @@ -17224,6 +17234,81 @@ export interface BrowserServer { [Symbol.asyncDispose](): Promise; } +/** + * Playwright uses [@sinonjs/fake-timers](https://github.com/sinonjs/fake-timers) for clock emulation. Clock is + * installed for the entire {@link BrowserContext}, so the time in all the pages and iframes is controlled by the same + * clock. + */ +export interface Clock { + /** + * Creates a clock and installs it globally. + * @param options + */ + install(options?: { + /** + * Relevant only when using with `shouldAdvanceTime`. Increment mocked time by advanceTimeDelta ms every + * advanceTimeDelta ms change in the real system time (default: 20). + */ + advanceTimeDelta?: number; + + /** + * The maximum number of timers that will be run when calling + * [clock.runAll()](https://playwright.dev/docs/api/class-clock#clock-run-all). Defaults to `1000`. + */ + loopLimit?: number; + + /** + * Install fake timers with the specified unix epoch (default: 0). + */ + now?: number|Date; + + /** + * Tells `@sinonjs/fake-timers` to increment mocked time automatically based on the real system time shift (e.g., the + * mocked time will be incremented by 20ms for every 20ms change in the real system time). Defaults to `false`. + */ + shouldAdvanceTime?: boolean; + + /** + * An array with names of global methods and APIs to fake. For instance, `await page.clock.install({ toFake: + * ['setTimeout'] })` will fake only `setTimeout()`. By default, `setTimeout`, `clearTimeout`, `setInterval`, + * `clearInterval` and `Date` are faked. + */ + toFake?: Array<"setTimeout"|"clearTimeout"|"setInterval"|"clearInterval"|"Date"|"requestAnimationFrame"|"cancelAnimationFrame"|"requestIdleCallback"|"cancelIdleCallback"|"performance">; + }): Promise; + + /** + * Advance the clock by jumping forward in time, firing callbacks at most once. Returns fake milliseconds since the + * unix epoch. This can be used to simulate the JS engine (such as a browser) being put to sleep and resumed later, + * skipping intermediary timers. + * @param time Time may be the number of milliseconds to advance the clock by or a human-readable string. Valid string formats are + * "08" for eight seconds, "01:00" for one minute and "02:34:10" for two hours, 34 minutes and ten seconds. + */ + jump(time: number|string): Promise; + + /** + * Runs all pending timers until there are none remaining. If new timers are added while it is executing they will be + * run as well. This makes it easier to run asynchronous tests to completion without worrying about the number of + * timers they use, or the delays in those timers. It runs a maximum of `loopLimit` times after which it assumes there + * is an infinite loop of timers and throws an error. + */ + runAll(): Promise; + + /** + * This takes note of the last scheduled timer when it is run, and advances the clock to that time firing callbacks as + * necessary. If new timers are added while it is executing they will be run only if they would occur before this + * time. This is useful when you want to run a test to completion, but the test recursively sets timers that would + * cause runAll to trigger an infinite loop warning. + */ + runToLast(): Promise; + + /** + * Advance the clock, firing callbacks if necessary. Returns fake milliseconds since the unix epoch. + * @param time Time may be the number of milliseconds to advance the clock by or a human-readable string. Valid string formats are + * "08" for eight seconds, "01:00" for one minute and "02:34:10" for two hours, 34 minutes and ten seconds. + */ + tick(time: number|string): Promise; +} + /** * {@link ConsoleMessage} objects are dispatched by page via the * [page.on('console')](https://playwright.dev/docs/api/class-page#page-event-console) event. For each console message diff --git a/packages/protocol/src/channels.ts b/packages/protocol/src/channels.ts index 986fb3a8dd..8ad202ca16 100644 --- a/packages/protocol/src/channels.ts +++ b/packages/protocol/src/channels.ts @@ -1460,6 +1460,11 @@ export interface BrowserContextChannel extends BrowserContextEventTarget, EventT harExport(params: BrowserContextHarExportParams, metadata?: CallMetadata): Promise; createTempFile(params: BrowserContextCreateTempFileParams, metadata?: CallMetadata): Promise; updateSubscription(params: BrowserContextUpdateSubscriptionParams, metadata?: CallMetadata): Promise; + clockInstall(params: BrowserContextClockInstallParams, metadata?: CallMetadata): Promise; + clockJump(params: BrowserContextClockJumpParams, metadata?: CallMetadata): Promise; + clockRunAll(params?: BrowserContextClockRunAllParams, metadata?: CallMetadata): Promise; + clockRunToLast(params?: BrowserContextClockRunToLastParams, metadata?: CallMetadata): Promise; + clockTick(params: BrowserContextClockTickParams, metadata?: CallMetadata): Promise; } export type BrowserContextBindingCallEvent = { binding: BindingCallChannel, @@ -1748,6 +1753,51 @@ export type BrowserContextUpdateSubscriptionOptions = { }; export type BrowserContextUpdateSubscriptionResult = void; +export type BrowserContextClockInstallParams = { + now?: number, + toFake?: string[], + loopLimit?: number, + shouldAdvanceTime?: boolean, + advanceTimeDelta?: number, +}; +export type BrowserContextClockInstallOptions = { + now?: number, + toFake?: string[], + loopLimit?: number, + shouldAdvanceTime?: boolean, + advanceTimeDelta?: number, +}; +export type BrowserContextClockInstallResult = void; +export type BrowserContextClockJumpParams = { + timeNumber?: number, + timeString?: string, +}; +export type BrowserContextClockJumpOptions = { + timeNumber?: number, + timeString?: string, +}; +export type BrowserContextClockJumpResult = void; +export type BrowserContextClockRunAllParams = {}; +export type BrowserContextClockRunAllOptions = {}; +export type BrowserContextClockRunAllResult = { + fakeTime: number, +}; +export type BrowserContextClockRunToLastParams = {}; +export type BrowserContextClockRunToLastOptions = {}; +export type BrowserContextClockRunToLastResult = { + fakeTime: number, +}; +export type BrowserContextClockTickParams = { + timeNumber?: number, + timeString?: string, +}; +export type BrowserContextClockTickOptions = { + timeNumber?: number, + timeString?: string, +}; +export type BrowserContextClockTickResult = { + fakeTime: number, +}; export interface BrowserContextEvents { 'bindingCall': BrowserContextBindingCallEvent; diff --git a/packages/protocol/src/protocol.yml b/packages/protocol/src/protocol.yml index 14c6e73052..34020e1212 100644 --- a/packages/protocol/src/protocol.yml +++ b/packages/protocol/src/protocol.yml @@ -1196,6 +1196,36 @@ BrowserContext: - requestFailed enabled: boolean + clockInstall: + parameters: + now: number? + toFake: + type: array? + items: string + loopLimit: number? + shouldAdvanceTime: boolean? + advanceTimeDelta: number? + + clockJump: + parameters: + timeNumber: number? + timeString: string? + + clockRunAll: + returns: + fakeTime: number + + clockRunToLast: + returns: + fakeTime: number + + clockTick: + parameters: + timeNumber: number? + timeString: string? + returns: + fakeTime: number + events: bindingCall: diff --git a/tests/page/page-clock.spec.ts b/tests/page/page-clock.spec.ts new file mode 100644 index 0000000000..c3e2aaeb54 --- /dev/null +++ b/tests/page/page-clock.spec.ts @@ -0,0 +1,614 @@ +/** + * Copyright (c) Microsoft Corporation. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +import { test, expect } from './pageTest'; + +declare global { + interface Window { + stub: (param?: any) => void + } +} + +const it = test.extend<{ calls: { params: any[] }[] }>({ + calls: async ({ page }, use) => { + const calls = []; + await page.exposeFunction('stub', async (...params: any[]) => { + calls.push({ params }); + }); + await use(calls); + } +}); + +it.describe('tick', () => { + it('triggers immediately without specified delay', async ({ page, calls }) => { + await page.clock.install(); + await page.evaluate(async () => { + setTimeout(window.stub); + }); + + await page.clock.tick(0); + expect(calls).toEqual([{ params: [] }]); + }); + + it('does not trigger without sufficient delay', async ({ page, calls }) => { + await page.clock.install(); + await page.evaluate(async () => { + setTimeout(window.stub, 100); + }); + await page.clock.tick(10); + expect(calls).toEqual([]); + }); + + it('triggers after sufficient delay', async ({ page, calls }) => { + await page.clock.install(); + await page.evaluate(async () => { + setTimeout(window.stub, 100); + }); + await page.clock.tick(100); + expect(calls).toEqual([{ params: [] }]); + }); + + it('triggers simultaneous timers', async ({ page, calls }) => { + await page.clock.install(); + await page.evaluate(async () => { + setTimeout(window.stub, 100); + setTimeout(window.stub, 100); + }); + await page.clock.tick(100); + expect(calls).toEqual([{ params: [] }, { params: [] }]); + }); + + it('triggers multiple simultaneous timers', async ({ page, calls }) => { + await page.clock.install(); + await page.evaluate(async () => { + setTimeout(window.stub, 100); + setTimeout(window.stub, 100); + setTimeout(window.stub, 99); + setTimeout(window.stub, 100); + }); + await page.clock.tick(100); + expect(calls.length).toBe(4); + }); + + it('waits after setTimeout was called', async ({ page, calls }) => { + await page.clock.install(); + await page.evaluate(async () => { + setTimeout(window.stub, 150); + }); + await page.clock.tick(50); + expect(calls).toEqual([]); + await page.clock.tick(100); + expect(calls).toEqual([{ params: [] }]); + }); + + it('triggers event when some throw', async ({ page, calls }) => { + await page.clock.install(); + await page.evaluate(async () => { + setTimeout(() => { throw new Error(); }, 100); + setTimeout(window.stub, 120); + }); + + await expect(page.clock.tick(120)).rejects.toThrow(); + expect(calls).toEqual([{ params: [] }]); + }); + + it('creates updated Date while ticking', async ({ page, calls }) => { + await page.clock.install(); + await page.evaluate(async () => { + setInterval(() => { + window.stub(new Date().getTime()); + }, 10); + }); + await page.clock.tick(100); + expect(calls).toEqual([ + { params: [10] }, + { params: [20] }, + { params: [30] }, + { params: [40] }, + { params: [50] }, + { params: [60] }, + { params: [70] }, + { params: [80] }, + { params: [90] }, + { params: [100] }, + ]); + }); + + it('passes 8 seconds', async ({ page, calls }) => { + await page.clock.install(); + await page.evaluate(async () => { + setInterval(window.stub, 4000); + }); + + await page.clock.tick('08'); + expect(calls.length).toBe(2); + }); + + it('passes 1 minute', async ({ page, calls }) => { + await page.clock.install(); + await page.evaluate(async () => { + setInterval(window.stub, 6000); + }); + + await page.clock.tick('01:00'); + expect(calls.length).toBe(10); + }); + + it('passes 2 hours, 34 minutes and 10 seconds', async ({ page, calls }) => { + await page.clock.install(); + await page.evaluate(async () => { + setInterval(window.stub, 10000); + }); + + await page.clock.tick('02:34:10'); + expect(calls.length).toBe(925); + }); + + it('throws for invalid format', async ({ page, calls }) => { + await page.clock.install(); + await page.evaluate(async () => { + setInterval(window.stub, 10000); + }); + await expect(page.clock.tick('12:02:34:10')).rejects.toThrow(); + expect(calls).toEqual([]); + }); + + it('returns the current now value', async ({ page }) => { + await page.clock.install(); + const value = 200; + await page.clock.tick(value); + expect(await page.evaluate(() => Date.now())).toBe(value); + }); +}); + +it.describe('jump', () => { + it(`ignores timers which wouldn't be run`, async ({ page, calls }) => { + await page.clock.install(); + await page.evaluate(async () => { + setTimeout(() => { + window.stub('should not be logged'); + }, 1000); + }); + await page.clock.jump(500); + expect(calls).toEqual([]); + }); + + it('pushes back execution time for skipped timers', async ({ page, calls }) => { + await page.clock.install(); + await page.evaluate(async () => { + setTimeout(() => { + window.stub(Date.now()); + }, 1000); + }); + + await page.clock.jump(2000); + expect(calls).toEqual([{ params: [2000] }]); + }); + + it('supports string time arguments', async ({ page, calls }) => { + await page.clock.install(); + await page.evaluate(async () => { + setTimeout(() => { + window.stub(Date.now()); + }, 100000); // 100000 = 1:40 + }); + await page.clock.jump('01:50'); + expect(calls).toEqual([{ params: [110000] }]); + }); +}); + +it.describe('runAllAsyn', () => { + it('if there are no timers just return', async ({ page }) => { + await page.clock.install(); + await page.clock.runAll(); + }); + + it('runs all timers', async ({ page, calls }) => { + await page.clock.install(); + await page.evaluate(async () => { + setTimeout(window.stub, 10); + setTimeout(window.stub, 50); + }); + await page.clock.runAll(); + expect(calls.length).toBe(2); + }); + + it('new timers added while running are also run', async ({ page, calls }) => { + await page.clock.install(); + await page.evaluate(async () => { + setTimeout(() => { + setTimeout(window.stub, 50); + }, 10); + }); + await page.clock.runAll(); + expect(calls.length).toBe(1); + }); + + it('new timers added in promises while running are also run', async ({ page, calls }) => { + await page.clock.install(); + await page.evaluate(async () => { + setTimeout(() => { + void Promise.resolve().then(() => { + setTimeout(window.stub, 50); + }); + }, 10); + }); + await page.clock.runAll(); + expect(calls.length).toBe(1); + }); + + it('throws before allowing infinite recursion', async ({ page, calls }) => { + await page.clock.install(); + await page.evaluate(async () => { + const recursiveCallback = () => { + window.stub(); + setTimeout(recursiveCallback, 10); + }; + setTimeout(recursiveCallback, 10); + }); + await expect(page.clock.runAll()).rejects.toThrow(); + expect(calls).toHaveLength(1000); + }); + + it('throws before allowing infinite recursion from promises', async ({ page, calls }) => { + await page.clock.install(); + await page.evaluate(async () => { + const recursiveCallback = () => { + window.stub(); + void Promise.resolve().then(() => { + setTimeout(recursiveCallback, 10); + }); + }; + setTimeout(recursiveCallback, 10); + }); + await expect(page.clock.runAll()).rejects.toThrow(); + expect(calls).toHaveLength(1000); + }); + + it('the loop limit can be set when creating a clock', async ({ page, calls }) => { + await page.clock.install({ loopLimit: 1 }); + await page.evaluate(async () => { + setTimeout(window.stub, 10); + setTimeout(window.stub, 50); + }); + await expect(page.clock.runAll()).rejects.toThrow(); + expect(calls).toHaveLength(1); + }); + + it('should settle user-created promises', async ({ page, calls }) => { + await page.clock.install(); + await page.evaluate(async () => { + setTimeout(() => { + void Promise.resolve().then(() => window.stub()); + }, 55); + }); + await page.clock.runAll(); + expect(calls).toHaveLength(1); + }); + + it('should settle nested user-created promises', async ({ page, calls }) => { + await page.clock.install(); + await page.evaluate(async () => { + setTimeout(() => { + void Promise.resolve().then(() => { + void Promise.resolve().then(() => { + void Promise.resolve().then(() => window.stub()); + }); + }); + }, 55); + }); + await page.clock.runAll(); + expect(calls).toHaveLength(1); + }); + + it('should settle local promises before firing timers', async ({ page, calls }) => { + await page.clock.install(); + await page.evaluate(async () => { + void Promise.resolve().then(() => window.stub(1)); + setTimeout(() => window.stub(2), 55); + }); + await page.clock.runAll(); + expect(calls).toEqual([ + { params: [1] }, + { params: [2] }, + ]); + }); +}); + +it.describe('runToLast', () => { + it('returns current time when there are no timers', async ({ page }) => { + await page.clock.install(); + const time = await page.clock.runToLast(); + expect(time).toBe(0); + }); + + it('runs all existing timers', async ({ page, calls }) => { + await page.clock.install(); + await page.evaluate(async () => { + setTimeout(window.stub, 10); + setTimeout(window.stub, 50); + }); + await page.clock.runToLast(); + expect(calls.length).toBe(2); + }); + + it('returns time of the last timer', async ({ page, calls }) => { + await page.clock.install(); + await page.evaluate(async () => { + setTimeout(window.stub, 10); + setTimeout(window.stub, 50); + }); + const time = await page.clock.runToLast(); + expect(time).toBe(50); + }); + + it('runs all existing timers when two timers are matched for being last', async ({ page, calls }) => { + await page.clock.install(); + await page.evaluate(async () => { + setTimeout(window.stub, 10); + setTimeout(window.stub, 10); + }); + await page.clock.runToLast(); + expect(calls.length).toBe(2); + }); + + it('new timers added with a call time later than the last existing timer are NOT run', async ({ page, calls }) => { + await page.clock.install(); + await page.evaluate(async () => { + setTimeout(() => { + window.stub(); + setTimeout(window.stub, 50); + }, 10); + }); + await page.clock.runToLast(); + expect(calls.length).toBe(1); + }); + + it('new timers added with a call time earlier than the last existing timer are run', async ({ page, calls }) => { + await page.clock.install(); + await page.evaluate(async () => { + setTimeout(window.stub, 100); + setTimeout(() => { + setTimeout(window.stub, 50); + }, 10); + }); + await page.clock.runToLast(); + expect(calls.length).toBe(2); + }); + + it('new timers cannot cause an infinite loop', async ({ page, calls }) => { + await page.clock.install(); + await page.evaluate(async () => { + const recursiveCallback = () => { + window.stub(); + setTimeout(recursiveCallback, 0); + }; + setTimeout(recursiveCallback, 0); + setTimeout(window.stub, 100); + }); + await page.clock.runToLast(); + expect(calls.length).toBe(102); + }); + + it('should support clocks with start time', async ({ page, calls }) => { + await page.clock.install({ now: 200 }); + await page.evaluate(async () => { + setTimeout(function cb() { + window.stub(); + setTimeout(cb, 50); + }, 50); + }); + await page.clock.runToLast(); + expect(calls.length).toBe(1); + }); + + it('new timers created from promises cannot cause an infinite loop', async ({ page, calls }) => { + await page.clock.install(); + await page.evaluate(async () => { + const recursiveCallback = () => { + void Promise.resolve().then(() => { + setTimeout(recursiveCallback, 0); + }); + }; + setTimeout(recursiveCallback, 0); + setTimeout(window.stub, 100); + }); + await page.clock.runToLast(); + expect(calls.length).toBe(1); + }); + + it('should settle user-created promises', async ({ page, calls }) => { + await page.clock.install(); + await page.evaluate(async () => { + setTimeout(() => { + void Promise.resolve().then(() => window.stub()); + }, 55); + }); + await page.clock.runToLast(); + expect(calls.length).toBe(1); + }); + + it('should settle nested user-created promises', async ({ page, calls }) => { + await page.clock.install(); + await page.evaluate(async () => { + setTimeout(() => { + void Promise.resolve().then(() => { + void Promise.resolve().then(() => { + void Promise.resolve().then(() => window.stub()); + }); + }); + }, 55); + }); + await page.clock.runToLast(); + expect(calls.length).toBe(1); + }); + + it('should settle local promises before firing timers', async ({ page, calls }) => { + await page.clock.install(); + await page.evaluate(async () => { + void Promise.resolve().then(() => window.stub(1)); + setTimeout(() => window.stub(2), 55); + }); + await page.clock.runToLast(); + expect(calls).toEqual([ + { params: [1] }, + { params: [2] }, + ]); + }); + + it('should settle user-created promises before firing more timers', async ({ page, calls }) => { + await page.clock.install(); + await page.evaluate(async () => { + setTimeout(() => { + void Promise.resolve().then(() => window.stub(1)); + }, 55); + setTimeout(() => window.stub(2), 75); + }); + await page.clock.runToLast(); + expect(calls).toEqual([ + { params: [1] }, + { params: [2] }, + ]); + }); +}); + +it.describe('stubTimers', () => { + it('sets initial timestamp', async ({ page, calls }) => { + await page.clock.install({ now: 1400 }); + expect(await page.evaluate(() => Date.now())).toBe(1400); + }); + + it('replaces global setTimeout', async ({ page, calls }) => { + await page.clock.install(); + await page.evaluate(async () => { + setTimeout(window.stub, 1000); + }); + await page.clock.tick(1000); + expect(calls.length).toBe(1); + }); + + it('global fake setTimeout should return id', async ({ page, calls }) => { + await page.clock.install(); + const to = await page.evaluate(() => setTimeout(window.stub, 1000)); + expect(typeof to).toBe('number'); + }); + + it('replaces global clearTimeout', async ({ page, calls }) => { + await page.clock.install(); + await page.evaluate(async () => { + const to = setTimeout(window.stub, 1000); + clearTimeout(to); + }); + await page.clock.tick(1000); + expect(calls).toEqual([]); + }); + + it('replaces global setInterval', async ({ page, calls }) => { + await page.clock.install(); + await page.evaluate(async () => { + setInterval(window.stub, 500); + }); + await page.clock.tick(1000); + expect(calls.length).toBe(2); + }); + + it('replaces global clearInterval', async ({ page, calls }) => { + await page.clock.install(); + await page.evaluate(async () => { + const to = setInterval(window.stub, 500); + clearInterval(to); + }); + await page.clock.tick(1000); + expect(calls).toEqual([]); + }); + + it('replaces global performance.now', async ({ page }) => { + await page.clock.install(); + const promise = page.evaluate(async () => { + const prev = performance.now(); + await new Promise(f => setTimeout(f, 1000)); + const next = performance.now(); + return { prev, next }; + }); + await page.clock.tick(1000); + expect(await promise).toEqual({ prev: 0, next: 1000 }); + }); + + it('fakes Date constructor', async ({ page }) => { + await page.clock.install({ now: 0 }); + const now = await page.evaluate(() => new Date().getTime()); + expect(now).toBe(0); + }); + + it('does not fake methods not provided', async ({ page }) => { + await page.clock.install({ + now: 0, + toFake: ['Date'], + }); + + // Should not stall. + await page.evaluate(() => { + return new Promise(f => setTimeout(f, 1)); + }); + }); +}); + +it.describe('shouldAdvanceTime', () => { + it('should create an auto advancing timer', async ({ page, calls }) => { + const testDelay = 29; + const now = new Date('2015-09-25'); + await page.clock.install({ now, shouldAdvanceTime: true }); + const pageNow = await page.evaluate(() => Date.now()); + expect(pageNow).toBe(1443139200000); + + await page.evaluate(async testDelay => { + return new Promise(f => { + const timeoutStarted = Date.now(); + setTimeout(() => { + window.stub(Date.now() - timeoutStarted); + f(); + }, testDelay); + }); + }, testDelay); + + expect(calls).toEqual([ + { params: [testDelay] } + ]); + }); + + it('should test setInterval', async ({ page, calls }) => { + const now = new Date('2015-09-25'); + await page.clock.install({ now, shouldAdvanceTime: true }); + + const timeDifference = await page.evaluate(async () => { + return new Promise(f => { + const interval = 20; + const cyclesToTrigger = 3; + const timeoutStarted = Date.now(); + let intervalsTriggered = 0; + const intervalId = setInterval(() => { + if (++intervalsTriggered === cyclesToTrigger) { + clearInterval(intervalId); + const timeDifference = Date.now() - timeoutStarted; + f(timeDifference - interval * cyclesToTrigger); + } + }, interval); + }); + }); + + expect(timeDifference).toBe(0); + }); +}); diff --git a/utils/doclint/documentation.js b/utils/doclint/documentation.js index b93998bd33..7972ba507e 100644 --- a/utils/doclint/documentation.js +++ b/utils/doclint/documentation.js @@ -865,6 +865,8 @@ function csharpOptionOverloadSuffix(option, type) { case 'function': return 'Func'; case 'Buffer': return 'Byte'; case 'Serializable': return 'Object'; + case 'int': return 'Int'; + case 'Date': return 'Date'; } throw new Error(`CSharp option "${option}" has unsupported type overload "${type}"`); } diff --git a/utils/generate_injected.js b/utils/generate_injected.js index eccd7ddcad..a39583ab38 100644 --- a/utils/generate_injected.js +++ b/utils/generate_injected.js @@ -50,6 +50,12 @@ const injectedScripts = [ path.join(ROOT, 'packages', 'playwright-core', 'src', 'generated'), true, ], + [ + path.join(ROOT, 'packages', 'playwright-core', 'src', 'server', 'injected', 'fakeTimers.ts'), + path.join(ROOT, 'packages', 'playwright-core', 'lib', 'server', 'injected', 'packed'), + path.join(ROOT, 'packages', 'playwright-core', 'src', 'generated'), + true, + ], [ path.join(ROOT, 'packages', 'playwright-ct-core', 'src', 'injected', 'index.ts'), path.join(ROOT, 'packages', 'playwright-ct-core', 'lib', 'injected', 'packed'),