@assertrx/dino 1.0.0

package/skills/playwright-core/clock-and-time-mocking.md

@@ -0,0 +1,427 @@
+# 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