Documentation Index
Fetch the complete documentation index at: https://mintlify.com/microsoft/playwright/llms.txt
Use this file to discover all available pages before exploring further.
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' });
Time to initialize the clock. Can be:
number: Unix timestamp in millisecondsstring: Date stringDate: Date object
If not specified, the clock starts at the current time. 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
Amount of time to advance. Can be:
number: Time in millisecondsstring: Duration string (e.g., ‘01:00:00’ for 1 hour)
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 millisecondsstring: Date stringDate: Date object
Promise<void>
resume
Resumes normal time flow after it was paused.
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
Amount of time to run. Can be:
number: Time in millisecondsstring: Duration string (e.g., ‘00:05:00’ for 5 minutes)
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 millisecondsstring: Date stringDate: Date object
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 millisecondsstring: Date stringDate: Date object
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();
});
