Skip to main content
The Clock class allows you to control time in your tests by manipulating browser timers. This is useful for testing time-dependent behavior without actually waiting.

​
Overview

Access the clock through the browser context: 
const clock = await context.clock;

​
Methods

​
install

Installs fake timers and controls time. 
await clock.install();
await clock.install({ time: new Date('2024-01-01T00:00:00') });
await clock.install({ time: 1000 });
await clock.install({ time: '2024-01-01' });
​
options.time
number | string | Date
Time to initialize the clock. Can be:
  • number: Unix timestamp in milliseconds
  • string: Date string
  • Date: Date object
If not specified, the clock starts at the current time.
Returns: Promise<void>

​
fastForward

Advances the clock by the specified amount of time. 
// Advance by 1000ms
await clock.fastForward(1000);

// Advance by duration string
await clock.fastForward('01:00:00'); // 1 hour
​
ticks
number | string
required
Amount of time to advance. Can be:
  • number: Time in milliseconds
  • string: Duration string (e.g., ‘01:00:00’ for 1 hour)
Returns: Promise<void>

​
pauseAt

Pauses time at the specified moment. 
await clock.pauseAt(new Date('2024-12-31T23:59:59'));
await clock.pauseAt(1000);
await clock.pauseAt('2024-06-15');
​
time
number | string | Date
required
Time to pause at. Can be:
  • number: Unix timestamp in milliseconds
  • string: Date string
  • Date: Date object
Returns: Promise<void>

​
resume

Resumes normal time flow after it was paused. 
await clock.resume();
Returns: Promise<void>

​
runFor

Advances the clock by running all pending timers for the specified duration. 
// Run timers for 1000ms
await clock.runFor(1000);

// Run timers for duration string
await clock.runFor('00:05:00'); // 5 minutes
​
ticks
number | string
required
Amount of time to run. Can be:
  • number: Time in milliseconds
  • string: Duration string (e.g., ‘00:05:00’ for 5 minutes)
Returns: Promise<void>

​
setFixedTime

Sets the clock to a fixed time. All subsequent time queries return this time. 
await clock.setFixedTime(new Date('2024-01-01T12:00:00'));
await clock.setFixedTime(1000);
await clock.setFixedTime('2024-01-01');
​
time
number | string | Date
required
Time to fix the clock at. Can be:
  • number: Unix timestamp in milliseconds
  • string: Date string
  • Date: Date object
Returns: Promise<void>

​
setSystemTime

Sets the current system time without affecting timers. 
await clock.setSystemTime(new Date('2024-01-01T00:00:00'));
await clock.setSystemTime(1000);
await clock.setSystemTime('2024-01-01');
​
time
number | string | Date
required
Time to set. Can be:
  • number: Unix timestamp in milliseconds
  • string: Date string
  • Date: Date object
Returns: Promise<void>

​
Examples

​
Testing time-dependent UI

import { test, expect } from '@playwright/test';

test('shows correct time', async ({ page, context }) => {
  await clock.install({ time: new Date('2024-01-01T12:00:00') });
  
  await page.goto('https://example.com');
  await expect(page.locator('.current-time')).toHaveText('12:00:00');
  
  // Advance by 1 hour
  await clock.fastForward(60 * 60 * 1000);
  await expect(page.locator('.current-time')).toHaveText('13:00:00');
});

​
Testing countdown timer

test('countdown timer', async ({ page, context }) => {
  await clock.install();
  
  await page.goto('https://example.com/countdown');
  await page.click('#start-countdown');
  
  // Fast forward 30 seconds
  await clock.fastForward(30000);
  await expect(page.locator('.countdown')).toHaveText('00:30');
  
  // Fast forward to completion
  await clock.fastForward(30000);
  await expect(page.locator('.countdown')).toHaveText('00:00');
  await expect(page.locator('.status')).toHaveText('Complete!');
});

​
Testing scheduled tasks

test('scheduled notification', async ({ page, context }) => {
  await clock.install();
  
  await page.goto('https://example.com');
  await page.click('#schedule-notification');
  
  // Run timers for 5 minutes
  await clock.runFor('00:05:00');
  
  await expect(page.locator('.notification')).toBeVisible();
});

​
Pausing and resuming time

test('pause and resume', async ({ page, context }) => {
  await clock.install();
  
  // Pause at a specific time
  await clock.pauseAt(new Date('2024-12-31T23:59:59'));
  
  await page.goto('https://example.com');
  await expect(page.locator('.date')).toContainText('Dec 31, 2024');
  
  // Resume normal time flow
  await clock.resume();
});

Build docs developers (and LLMs) love

Get started for freeTalk to us