9.1 Clock과 시간 제어

시간 기반 UI를 실제로 기다리면 suite가 느리고 불안정해집니다. Playwright Clock은 Date, timer, animation frame과 performance clock을 context 범위에서 제어합니다.

한눈에 보기

• 날짜 표시만 고정하려면 setFixedTime()부터 사용합니다.
• Timer 진행까지 제어하려면 page script보다 먼저 clock.install()을 호출합니다.
• fastForward()는 건너뛴 구간의 due timer를 최대 한 번 즉시 실행하는 “노트북을 닫았다 여는” 모델입니다.
• 모든 interval tick을 재현하려면 runFor()를 검토합니다.
• Clock은 같은 context의 page와 iframe 전체에 영향을 줍니다.

고정된 현재 시각

test('정해진 날짜를 표시한다', async ({ page }) => {
  await page.clock.setFixedTime(new Date('2026-09-01T09:00:00+09:00'));
  await page.goto('/');
  await expect(page.getByTestId('current-time')).toContainText('2026');
});

setFixedTime()은 Date.now()와 new Date()를 고정하지만 timer는 자연스럽게 흐르게 둡니다. 날짜에 따라 banner를 노출하는 test에 적합합니다.

Timer까지 통제하기

test('5분 뒤 offer가 만료된다', async ({ page }) => {
  await page.clock.install({ time: new Date('2026-09-01T00:00:00Z') });
  await page.goto('/');
  await expect(page.getByTestId('offer-status')).toHaveText('진행 중');

  await page.clock.fastForward('05:00');
  await expect(page.getByTestId('offer-status')).toHaveText('만료됨');
});

install()은 application이 timer API를 처음 참조하기 전에 호출해야 합니다. Page load 뒤 설치하면 기존 timer는 native 함수와 mocked 함수 사이에 걸쳐 undefined behavior를 만들 수 있습니다.

fastForward와 runFor

API	시간 모델	적합한 사례
setFixedTime	현재 날짜만 교체	날짜 label, campaign start
fastForward	긴 공백 뒤 due timer를 즉시 처리	idle timeout, session expiry
runFor	구간을 진행하며 timer를 순차 실행	countdown, animation, polling
pauseAt	특정 시각에 멈춤	boundary 직전/직후 비교
resume	실제 흐름 재개	mock 구간 이후 상호작용

Timezone도 별도 입력이다

Clock이 instant를 고정해도 locale과 timezone이 다르면 표시 문자열은 달라집니다.

test.use({ locale: 'ko-KR', timezoneId: 'Asia/Seoul' });

문자열 snapshot보다 semantic date value와 명시된 timezone을 함께 검증하는 편이 좋습니다.

실습

1. Lab offer가 5분 뒤 만료되는 test를 1초 이내에 실행합니다.
2. 만료 1ms 전과 정확한 boundary를 별도 case로 만듭니다.
3. fastForward()와 runFor()에서 countdown 중간 DOM 변화가 어떻게 다른지 기록합니다.
4. Asia/Seoul과 UTC project를 만들어 date label을 비교합니다.

흔한 실수

• Application이 timer를 만든 뒤 clock.install() 호출
• Clock을 쓰면서 server clock도 같은 방식으로 바뀐다고 가정
• Locale과 timezone을 고정하지 않은 visual snapshot
• Business timeout과 Playwright test timeout을 같은 개념으로 취급

참고: Playwright Clock, 공식 Clock examples