Implementation:Microsoft Playwright Client Clock

Knowledge Sources	Microsoft_Playwright
Domains	Browser Automation, Time Simulation
Last Updated	2026-02-12 00:00 GMT

Overview

Concrete tool for controlling and simulating the passage of time in browser contexts provided by the Playwright library.

Description

The Clock class implements the api.Clock interface and provides methods for installing fake timers, advancing time, pausing and resuming the clock, and setting fixed or system time within a BrowserContext. Each method delegates to the corresponding channel method on the browser context. Time values are parsed via internal helper functions (parseTime and parseTicks) that accept numbers, strings, or Date objects and convert them to the protocol format with timeNumber/timeString or ticksNumber/ticksString discriminated unions.

Usage

Use the Clock API when you need to control time-dependent behavior in tests, such as animations, timers, or date-based logic. Access it via browserContext.clock or page.clock.

Code Reference

Source Location

• Repository: Microsoft_Playwright
• File: packages/playwright-core/src/client/clock.ts

Signature

export class Clock implements api.Clock {
  private _browserContext: BrowserContext;

  constructor(browserContext: BrowserContext);

  async install(options?: { time?: number | string | Date }): Promise<void>;
  async fastForward(ticks: number | string): Promise<void>;
  async pauseAt(time: number | string | Date): Promise<void>;
  async resume(): Promise<void>;
  async runFor(ticks: number | string): Promise<void>;
  async setFixedTime(time: string | number | Date): Promise<void>;
  async setSystemTime(time: string | number | Date): Promise<void>;
}

Import

import { Clock } from 'playwright-core/src/client/clock';

I/O Contract

Inputs

Name	Type	Required	Description
browserContext	BrowserContext	Yes	The browser context to control time for (constructor parameter)
time	string \| Date	No	The time value for install, pauseAt, setFixedTime, setSystemTime
ticks	string	Yes	The amount of time to advance for fastForward and runFor

Outputs

Name	Type	Description
All methods	Promise<void>	All clock methods return void promises after the time operation is applied

Usage Examples

// Install fake timers at a specific date
await page.clock.install({ time: new Date('2024-01-01T00:00:00Z') });

// Fast forward by 1 hour
await page.clock.fastForward(3600000);

// Pause at a specific time
await page.clock.pauseAt('2024-06-15T12:00:00Z');

// Set a fixed time (Date.now() always returns this)
await page.clock.setFixedTime(new Date('2024-03-01'));

// Resume normal time flow
await page.clock.resume();

// Run for a specific duration using string syntax
await page.clock.runFor('01:30:00');

Related Pages

• Environment:Microsoft_Playwright_Node_Runtime_Environment