# Clock and Time Mocking

> **When to use**: Testing time-dependent features -- countdown timers, scheduled events, expiration dates, age gates, session timeouts, or any UI that behaves differently based on the current time. Playwright's `page.clock` API lets you control time without waiting in real-time.
> **Prerequisites**: [core/assertions-and-waiting.md](assertions-and-waiting.md), [core/configuration.md](configuration.md)

## Quick Reference

```typescript
// Freeze time at a specific moment
await page.clock.install({ time: new Date("2025-03-15T10:00:00Z") })
await page.goto("/dashboard")

// Advance time by 5 minutes
await page.clock.fastForward("05:00")

// Set time to a specific point (jumps, does not tick through)
await page.clock.setFixedTime(new Date("2025-12-31T23:59:59Z"))

// Let time resume ticking from current mocked point
await page.clock.resume()
```

**Key concept**: `page.clock.install()` replaces `Date`, `setTimeout`, `setInterval`, and `requestAnimationFrame` in the page. Call it before `page.goto()` so the page loads with mocked time from the start.

## Patterns

### Frozen Time with `install()` and `setFixedTime()`

**Use when**: Your test needs time to stand still at a specific moment -- verifying what the UI shows at a particular date/time.
**Avoid when**: The feature under test depends on timers ticking (use `fastForward` instead).

**TypeScript**

```typescript
import { test, expect } from "@playwright/test"

test("dashboard shows correct greeting based on time of day", async ({ page }) => {
  // Install clock BEFORE navigating
  await page.clock.install({ time: new Date("2025-06-15T08:30:00") })
  await page.goto("/dashboard")
  await expect(page.getByText("Good morning")).toBeVisible()

  // Jump to afternoon
  await page.clock.setFixedTime(new Date("2025-06-15T14:00:00"))
  await page.reload()
  await expect(page.getByText("Good afternoon")).toBeVisible()

  // Jump to evening
  await page.clock.setFixedTime(new Date("2025-06-15T20:00:00"))
  await page.reload()
  await expect(page.getByText("Good evening")).toBeVisible()
})

test("subscription shows correct expiration status", async ({ page }) => {
  // Freeze time to a date when subscription is active
  await page.clock.install({ time: new Date("2025-06-01T12:00:00Z") })
  await page.goto("/account")

  await expect(page.getByTestId("subscription-status")).toHaveText("Active")
  await expect(page.getByTestId("days-remaining")).toContainText("29")

  // Jump to the expiration date
  await page.clock.setFixedTime(new Date("2025-06-30T12:00:00Z"))
  await page.reload()

  await expect(page.getByTestId("subscription-status")).toHaveText("Expiring today")
})

test("content displays correctly on a specific holiday", async ({ page }) => {
  await page.clock.install({ time: new Date("2025-12-25T10:00:00") })
  await page.goto("/")

  await expect(page.getByText("Happy Holidays")).toBeVisible()
  await expect(page.getByTestId("holiday-banner")).toBeVisible()
})
```

**JavaScript**

```javascript
const { test, expect } = require("@playwright/test")

test("dashboard shows correct greeting based on time of day", async ({ page }) => {
  await page.clock.install({ time: new Date("2025-06-15T08:30:00") })
  await page.goto("/dashboard")
  await expect(page.getByText("Good morning")).toBeVisible()

  await page.clock.setFixedTime(new Date("2025-06-15T14:00:00"))
  await page.reload()
  await expect(page.getByText("Good afternoon")).toBeVisible()
})

test("subscription shows correct expiration status", async ({ page }) => {
  await page.clock.install({ time: new Date("2025-06-01T12:00:00Z") })
  await page.goto("/account")

  await expect(page.getByTestId("subscription-status")).toHaveText("Active")
})
```

### Fast-Forwarding Time with `fastForward()`

**Use when**: Testing timers, countdowns, debounced actions, or any feature that reacts to elapsed time. `fastForward` fires all pending timers up to the specified duration.
**Avoid when**: You just need to check a static time-dependent display -- use `setFixedTime` instead.

**TypeScript**

```typescript
import { test, expect } from "@playwright/test"

test("countdown timer reaches zero", async ({ page }) => {
  await page.clock.install({ time: new Date("2025-03-15T10:00:00Z") })
  await page.goto("/sale")

  // Sale countdown starts at 2 hours
  await expect(page.getByTestId("countdown")).toContainText("2:00:00")

  // Fast-forward 1 hour
  await page.clock.fastForward("01:00:00")
  await expect(page.getByTestId("countdown")).toContainText("1:00:00")

  // Fast-forward remaining time
  await page.clock.fastForward("01:00:00")
  await expect(page.getByTestId("countdown")).toContainText("0:00:00")
  await expect(page.getByText("Sale ended")).toBeVisible()
})

test("auto-save triggers after 30 seconds of inactivity", async ({ page }) => {
  await page.clock.install({ time: new Date("2025-03-15T10:00:00Z") })
  await page.goto("/editor")

  // Type something
  await page.getByRole("textbox", { name: "Content" }).fill("Draft content")

  // Fast-forward past the auto-save interval
  await page.clock.fastForward("00:30")

  await expect(page.getByText("Saved")).toBeVisible()
})

test("session timeout warning appears after 25 minutes", async ({ page }) => {
  await page.clock.install({ time: new Date("2025-03-15T10:00:00Z") })
  await page.goto("/dashboard")

  // Fast-forward to just before the warning (25 min)
  await page.clock.fastForward("24:59")
  await expect(page.getByRole("dialog", { name: "Session timeout" })).not.toBeVisible()

  // One more minute triggers the warning
  await page.clock.fastForward("00:01")
  await expect(page.getByRole("dialog", { name: "Session timeout" })).toBeVisible()
  await expect(page.getByText("Your session will expire in 5 minutes")).toBeVisible()
})
```

**JavaScript**

```javascript
const { test, expect } = require("@playwright/test")

test("countdown timer reaches zero", async ({ page }) => {
  await page.clock.install({ time: new Date("2025-03-15T10:00:00Z") })
  await page.goto("/sale")

  await expect(page.getByTestId("countdown")).toContainText("2:00:00")

  await page.clock.fastForward("01:00:00")
  await expect(page.getByTestId("countdown")).toContainText("1:00:00")

  await page.clock.fastForward("01:00:00")
  await expect(page.getByText("Sale ended")).toBeVisible()
})

test("auto-save triggers after inactivity", async ({ page }) => {
  await page.clock.install({ time: new Date("2025-03-15T10:00:00Z") })
  await page.goto("/editor")

  await page.getByRole("textbox", { name: "Content" }).fill("Draft content")
  await page.clock.fastForward("00:30")

  await expect(page.getByText("Saved")).toBeVisible()
})
```

### Resuming Time with `resume()`

**Use when**: You need to start with a mocked time, then let time flow normally for interaction-dependent behavior.
**Avoid when**: The entire test should use mocked time.

**TypeScript**

```typescript
import { test, expect } from "@playwright/test"

test("notification appears in real-time after scheduled trigger", async ({ page }) => {
  // Start at a known time
  await page.clock.install({ time: new Date("2025-03-15T09:59:55Z") })
  await page.goto("/dashboard")

  // Notification is scheduled for 10:00:00 — advance to 5 seconds before
  await expect(page.getByTestId("notification-bell")).not.toHaveAttribute("data-count")

  // Let real time tick from this point
  await page.clock.resume()

  // The notification should appear within a few seconds
  await expect(page.getByTestId("notification-bell")).toHaveAttribute("data-count", "1", {
    timeout: 10000,
  })
})
```

**JavaScript**

```javascript
const { test, expect } = require("@playwright/test")

test("notification appears after scheduled trigger", async ({ page }) => {
  await page.clock.install({ time: new Date("2025-03-15T09:59:55Z") })
  await page.goto("/dashboard")

  await page.clock.resume()

  await expect(page.getByTestId("notification-bell")).toHaveAttribute("data-count", "1", {
    timeout: 10000,
  })
})
```

### Testing Date-Dependent UI

**Use when**: Features that change based on the current date -- age verification, expiration warnings, seasonal content, date pickers.
**Avoid when**: The date is passed from the server and does not depend on client-side `Date`.

**TypeScript**

```typescript
import { test, expect } from "@playwright/test"

test("age gate blocks users under 18", async ({ page }) => {
  // User born on 2010-01-15 — under 18 as of 2025-06-01
  await page.clock.install({ time: new Date("2025-06-01T12:00:00") })
  await page.goto("/age-restricted")

  await page.getByLabel("Date of birth").fill("2010-01-15")
  await page.getByRole("button", { name: "Verify age" }).click()

  await expect(page.getByText("You must be 18 or older")).toBeVisible()
})

test("age gate allows users 18 and older", async ({ page }) => {
  await page.clock.install({ time: new Date("2025-06-01T12:00:00") })
  await page.goto("/age-restricted")

  await page.getByLabel("Date of birth").fill("2005-01-15")
  await page.getByRole("button", { name: "Verify age" }).click()

  await expect(page.getByText("Welcome")).toBeVisible()
})

test("trial expiration banner shows at correct times", async ({ page }) => {
  // Day 1 of 14-day trial
  await page.clock.install({ time: new Date("2025-03-01T12:00:00Z") })
  await page.goto("/dashboard")
  await expect(page.getByTestId("trial-banner")).toContainText("13 days remaining")

  // Day 12 — warning state
  await page.clock.setFixedTime(new Date("2025-03-12T12:00:00Z"))
  await page.reload()
  await expect(page.getByTestId("trial-banner")).toContainText("2 days remaining")
  await expect(page.getByTestId("trial-banner")).toHaveCSS("background-color", /rgb\(255/) // Red/warning

  // Day 15 — expired
  await page.clock.setFixedTime(new Date("2025-03-15T12:00:00Z"))
  await page.reload()
  await expect(page.getByText("Your trial has expired")).toBeVisible()
  await expect(page.getByRole("button", { name: "Upgrade now" })).toBeVisible()
})

test("date picker defaults to current mocked date", async ({ page }) => {
  await page.clock.install({ time: new Date("2025-07-04T12:00:00") })
  await page.goto("/booking")

  await page.getByLabel("Check-in date").click()

  // Calendar should open to July 2025
  await expect(page.getByText("July 2025")).toBeVisible()

  // Today (July 4) should be highlighted
  const today = page.locator('[aria-current="date"]')
  await expect(today).toHaveText("4")
})
```

**JavaScript**

```javascript
const { test, expect } = require("@playwright/test")

test("age gate blocks users under 18", async ({ page }) => {
  await page.clock.install({ time: new Date("2025-06-01T12:00:00") })
  await page.goto("/age-restricted")

  await page.getByLabel("Date of birth").fill("2010-01-15")
  await page.getByRole("button", { name: "Verify age" }).click()

  await expect(page.getByText("You must be 18 or older")).toBeVisible()
})

test("trial expiration shows correct days remaining", async ({ page }) => {
  await page.clock.install({ time: new Date("2025-03-01T12:00:00Z") })
  await page.goto("/dashboard")
  await expect(page.getByTestId("trial-banner")).toContainText("13 days remaining")

  await page.clock.setFixedTime(new Date("2025-03-15T12:00:00Z"))
  await page.reload()
  await expect(page.getByText("Your trial has expired")).toBeVisible()
})
```

### Timezone-Dependent Features

**Use when**: Testing features that combine mocked time with specific timezones.
**Avoid when**: The feature uses only UTC and does not render local times.

**TypeScript**

```typescript
import { test, expect } from "@playwright/test"

test("business hours banner shows open/closed status", async ({ browser }) => {
  // Business hours: 9 AM - 5 PM Eastern
  const context = await browser.newContext({ timezoneId: "America/New_York" })
  const page = await context.newPage()

  // 10 AM Eastern — should show "Open"
  await page.clock.install({ time: new Date("2025-03-15T14:00:00Z") }) // 10 AM ET
  await page.goto("/contact")
  await expect(page.getByTestId("business-hours")).toContainText("Open")

  // 6 PM Eastern — should show "Closed"
  await page.clock.setFixedTime(new Date("2025-03-15T22:00:00Z")) // 6 PM ET
  await page.reload()
  await expect(page.getByTestId("business-hours")).toContainText("Closed")

  await context.close()
})

test("scheduled event shows correct local time", async ({ browser }) => {
  // Event at 2025-03-20T18:00:00Z

  // User in Tokyo (UTC+9)
  const tokyoCtx = await browser.newContext({ timezoneId: "Asia/Tokyo" })
  const tokyoPage = await tokyoCtx.newPage()
  await tokyoPage.clock.install({ time: new Date("2025-03-20T10:00:00Z") })
  await tokyoPage.goto("/events/upcoming")
  // 18:00 UTC = 03:00 AM next day in Tokyo (UTC+9)
  await expect(tokyoPage.getByTestId("event-time")).toContainText("3:00 AM")
  await tokyoCtx.close()

  // User in London (UTC+0 in March, before DST)
  const londonCtx = await browser.newContext({ timezoneId: "Europe/London" })
  const londonPage = await londonCtx.newPage()
  await londonPage.clock.install({ time: new Date("2025-03-20T10:00:00Z") })
  await londonPage.goto("/events/upcoming")
  await expect(londonPage.getByTestId("event-time")).toContainText("6:00 PM")
  await londonCtx.close()
})
```

**JavaScript**

```javascript
const { test, expect } = require("@playwright/test")

test("business hours banner shows open/closed status", async ({ browser }) => {
  const context = await browser.newContext({ timezoneId: "America/New_York" })
  const page = await context.newPage()

  await page.clock.install({ time: new Date("2025-03-15T14:00:00Z") })
  await page.goto("/contact")
  await expect(page.getByTestId("business-hours")).toContainText("Open")

  await page.clock.setFixedTime(new Date("2025-03-15T22:00:00Z"))
  await page.reload()
  await expect(page.getByTestId("business-hours")).toContainText("Closed")

  await context.close()
})
```

## Decision Guide

| Scenario                         | API                                              | Why                                                           |
| -------------------------------- | ------------------------------------------------ | ------------------------------------------------------------- |
| Check UI at a specific date/time | `clock.install()` + `clock.setFixedTime()`       | Time is frozen; no timer ticking                              |
| Test countdown or timer behavior | `clock.install()` + `clock.fastForward()`        | Fires timers as time advances without real waiting            |
| Test after a long idle period    | `clock.install()` + `clock.fastForward('30:00')` | Simulates 30 minutes without waiting 30 minutes               |
| Start mocked, then tick normally | `clock.install()` + `clock.resume()`             | Useful when you need real `requestAnimationFrame` after setup |
| Different timezone display       | `browser.newContext({ timezoneId })`             | Affects `Date` timezone rendering                             |
| Timezone + mocked time           | `newContext({ timezoneId })` + `clock.install()` | Both timezone and absolute time are controlled                |
| Test date picker defaults        | `clock.install()` with target date               | Calendar opens to the mocked "today"                          |
| Test DST transitions             | Set `timezoneId` + `install` at DST boundary     | Tests the most common timezone bugs                           |

## Anti-Patterns

| Don't Do This                                                | Problem                                                                     | Do This Instead                                           |
| ------------------------------------------------------------ | --------------------------------------------------------------------------- | --------------------------------------------------------- |
| Calling `clock.install()` after `page.goto()`                | Page already loaded with real `Date`; timers already fired                  | Call `clock.install()` BEFORE `page.goto()`               |
| Using `page.waitForTimeout(30000)` to test a 30-second timer | Wastes 30 real seconds per test run                                         | `page.clock.fastForward('00:30')` completes instantly     |
| Testing time without mocking the clock                       | Results depend on when the test runs (morning vs evening, Monday vs Sunday) | Always mock time for time-dependent assertions            |
| Using `setFixedTime` when you need timers to fire            | `setFixedTime` freezes time; `setInterval`/`setTimeout` will not trigger    | Use `fastForward` to advance time and fire pending timers |
| Mocking only `Date.now()` via `page.evaluate`                | Does not affect `setTimeout`, `setInterval`, or `requestAnimationFrame`     | Use `page.clock.install()` which mocks all time APIs      |
| Forgetting timezone when testing dates                       | Test passes locally but fails in CI (different timezone)                    | Always set `timezoneId` in context or use UTC dates       |
| Advancing time in very small increments                      | Slow test; many unnecessary timer firings                                   | Advance to the exact time of interest in one call         |
| Not calling `resume()` before real-time-dependent assertions | Mocked timers will not fire naturally; assertions time out                  | Call `clock.resume()` when you need real time to flow     |

## Troubleshooting

| Symptom                                         | Likely Cause                                                          | Fix                                                         |
| ----------------------------------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------- |
| `clock.install()` has no effect                 | Called after `page.goto()`; page already has real `Date`              | Move `clock.install()` before navigation                    |
| Timer callbacks never fire                      | Time is frozen with `setFixedTime`; timers need advancing             | Use `fastForward()` to advance past the timer delay         |
| `fastForward` does not trigger timer            | Timer was registered with a delay longer than the fast-forward amount | Fast-forward by at least the timer's delay                  |
| Date is correct but timezone display is wrong   | `clock.install` sets time in UTC; `timezoneId` not set on context     | Create context with `{ timezoneId: 'Your/Timezone' }`       |
| Animations break with mocked clock              | `requestAnimationFrame` is mocked and does not fire naturally         | Call `clock.resume()` before animation-dependent assertions |
| Test passes locally but fails in CI             | Local timezone differs from CI timezone                               | Always set `timezoneId` explicitly in the context           |
| `setFixedTime` throws "clock not installed"     | `install()` was not called first                                      | Call `page.clock.install()` before any other clock methods  |
| Page makes fetch requests with wrong timestamps | Server sees mocked `Date.now()` in request payloads                   | This is expected; mock server responses if needed           |

## Related

- [core/i18n-and-localization.md](i18n-and-localization.md) -- timezone and locale testing patterns
- [core/assertions-and-waiting.md](assertions-and-waiting.md) -- auto-waiting vs time-based assertions
- [core/error-and-edge-cases.md](error-and-edge-cases.md) -- testing timeout and expiration edge cases
- [core/performance-testing.md](performance-testing.md) -- timing-related performance measurement
- [core/websockets-and-realtime.md](websockets-and-realtime.md) -- real-time features that depend on timing