Playwrightのclockで、時刻を進めてテストする方法

​​Playwright​E2Eテスト,TypeScript

「5分間操作しないとログアウトする」セッションタイムアウトや、日付によって表示が変わる画面は、E2E テストで実際にその時間や日付になるまで待つわけにはいきません。Playwright の clock を使うと、ページの中の時刻を好きな時刻に固定したり、一気に進めたりできます。検証環境で試したところ、5分のタイムアウトを確かめるテストの中で測った実際の時間は、62〜80ミリ秒でした。

補足

検証環境は Ubuntu 24.04、Node.js 22.23.4、@playwright/test 1.63.0 です。テストは TypeScript で書き、ブラウザは Chromium(ヘッドレス)だけで動かしました。テスト用のページは Node.js の http モジュールで 127.0.0.1 から返し、設定の timezoneId でブラウザのタイムゾーンを Asia/Tokyo にしています。resume()、setSystemTime()、requestAnimationFrame を使うアニメーション、Firefox と WebKit は試していません。

clock で置き換わるもの

page.clock は、ページの中の Date、setTimeout、setInterval、requestAnimationFrame、performance などを、Playwright が操作できる偽物に置き換えます。テストを動かしている Node.js の側の時刻は変わりません。この記事のテストで、かかった実時間を Date.now() で測れているのはそのためです。

例として、次のページを使います。今日の日付と現在時刻を出し、1秒ごとに経過秒数を数えます。ボタンを押さないまま5分たつと「操作がなかったため、ログアウトしました」と表示します。

html
<p>今日の日付:<span id="today"></span></p>
<p>現在時刻:<span id="now"></span></p>
<p>経過秒数:<span id="ticks">0</span></p>
<button type="button">操作する</button>
<p id="status" role="status">ログイン中</p>
<script>
  // (日付・時刻の表示と、1秒ごとの setInterval は省略)

  // 5分間操作がなければログアウトする
  const LIMIT = 5 * 60 * 1000;
  let timer;
  const resetTimer = () => {
    clearTimeout(timer);
    timer = setTimeout(() => {
      document.getElementById('status').textContent =
        '操作がなかったため、ログアウトしました';
    }, LIMIT);
  };
  document.querySelector('button').addEventListener('click', resetTimer);
  resetTimer();
</script>

日付を決めておくだけなら setFixedTime

「12月24日だけ表示が変わる」のように、決まった日時で画面を見たいだけなら、setFixedTime() で足ります。Date.now() と new Date() がいつも同じ時刻を返し、タイマーはふつうに動きます。

ts
test('setFixedTime で今日の日付を固定する', async ({ page }) => {
  await page.clock.setFixedTime(new Date('2026-12-24T10:00:00+09:00'));
  await page.goto('/');
  await expect(page.locator('#today')).toHaveText('2026/12/24');
  await expect(page.locator('#now')).toHaveText('10:00:00');
});

日時は +09:00 のようにタイムゾーンを付けて書きました。付けないと、テストを動かしているマシンのタイムゾーンで解釈されます。CI のマシンと手元のマシンで結果が変わらないように、ブラウザの側も設定の timezoneId でそろえています。

5分後のログアウトを install と fastForward で確かめる

時刻を進めたいときは、先に install() を呼び、そのあとで fastForward() を使います。fastForward() には、ミリ秒の数か、'08'(8秒)、'01:00'(1分)、'02:34:10'(2時間34分10秒)のような文字列を渡せます。

ts
test('5分操作しないとログアウトする', async ({ page }) => {
  const started = Date.now();
  await page.clock.install({ time: new Date('2026-12-24T10:00:00+09:00') });
  await page.goto('/');
  const status = page.getByRole('status');

  await page.clock.fastForward('04:59');
  await expect(status).toHaveText('ログイン中');

  await page.clock.fastForward(1000);
  await expect(status).toHaveText('操作がなかったため、ログアウトしました');
  await expect(page.locator('#now')).toHaveText('10:05:00');
  console.log(`  実際にかかった時間: ${Date.now() - started}ms`);
});

4分59秒の時点ではまだ「ログイン中」で、あと1秒進めるとログアウトの表示に変わることを、境目の前後で確かめています。

途中で操作するとタイマーが最初から数え直しになることも、同じ書き方で確かめられます。4分進めてボタンを押し、また4分進めてもログイン中のまま、さらに1分進めるとログアウトします。

ts
test('操作すると5分の数え直しになる', async ({ page }) => {
  await page.clock.install({ time: new Date('2026-12-24T10:00:00+09:00') });
  await page.goto('/');
  const status = page.getByRole('status');

  await page.clock.fastForward('04:00');
  await page.getByRole('button', { name: '操作する' }).click();
  await page.clock.fastForward('04:00');
  await expect(status).toHaveText('ログイン中');

  await page.clock.fastForward('01:00');
  await expect(status).toHaveText('操作がなかったため、ログアウトしました');
});

この記事のテスト6件を、次のコマンドで3回続けて実行しました。1回目の出力を載せます。

bash
npx playwright test tests/clock.spec.ts --workers=1
text
Running 6 tests using 1 worker

  ✓  1 tests/clock.spec.ts:3:1 › setFixedTime で今日の日付を固定する (130ms)
  実際にかかった時間: 62ms
  ✓  2 tests/clock.spec.ts:10:1 › 5分操作しないとログアウトする (101ms)
  ✓  3 tests/clock.spec.ts:25:1 › 操作すると5分の数え直しになる (151ms)
  fastForward 後の経過秒数: 1
  fastForward 後の現在時刻: 10:00:10
  ✓  4 tests/clock.spec.ts:39:1 › fastForward で10秒進める (115ms)
  runFor 後の経過秒数: 10
  runFor 後の現在時刻: 10:00:10
  ✓  5 tests/clock.spec.ts:47:1 › runFor で10秒進める (123ms)
  ✓  6 tests/clock.spec.ts:55:1 › pauseAt で止めてから1秒ずつ進める (123ms)

  6 passed (1.5s)

ページの中では5分たっていても、テストの中で Date.now() を使って測った「実際にかかった時間」は62ミリ秒です。3回の実行では62、80、70ミリ秒で、6件全体は1.5〜1.6秒でした。

fastForward と runFor は、setInterval の動く回数が違う

時刻を進めるメソッドには runFor() もあります。違いは、途中のタイマーを動かすかどうかです。fastForward() は一気に時刻を飛ばし、期限が来たタイマーを多くても1回だけ動かします。runFor() は時刻を進めながら、途中のタイマーをすべて動かします。

1秒ごとに経過秒数を数えるページで、それぞれ10秒進めてみました(テスト4と5)。

ts
await page.clock.fastForward(10_000);
// または
await page.clock.runFor(10_000);

上の出力のとおり、どちらも現在時刻は 10:00:10 になりましたが、経過秒数は fastForward() が1、runFor() が10でした。3回の実行とも同じ値です。

fastForward では10秒の間に setInterval が1回だけ、runFor では1秒ごとに10回動いたことを示す図
10秒進めたときに、1秒ごとの setInterval が動いた回数

公式ドキュメントの、操作がない状態を確かめる例では、fastForward() を「ノートパソコンのふたを閉じて、5分後に開いたようなもの」とたとえています。期限が来たタイマーは、本物のブラウザと同じように、すぐに1回だけ動きます。ログアウトのように「時間がたったあとの状態」を見たいときは fastForward()、カウントダウンのように「1秒ごとの変化」を数えたいときは runFor() が合います。

pauseAt で止めて、1秒ずつ進める

時刻の表示を1秒単位で確かめたいときは、pauseAt() で時刻を止めてから runFor() で少しずつ進めます。止めたあとは、runFor() や fastForward() などで進めるまで、ページの中のタイマーは動きません。

ts
test('pauseAt で止めてから1秒ずつ進める', async ({ page }) => {
  await page.clock.install({ time: new Date('2026-12-24T09:59:50+09:00') });
  await page.goto('/');
  await page.clock.pauseAt(new Date('2026-12-24T10:00:00+09:00'));
  await expect(page.locator('#now')).toHaveText('10:00:00');

  await page.clock.runFor(1000);
  await expect(page.locator('#now')).toHaveText('10:00:01');
  await page.clock.runFor(1000);
  await expect(page.locator('#now')).toHaveText('10:00:02');
});

install() で 9時59分50秒から始め、pauseAt() で 10時ちょうどまで進めて止めています。このテストも上の出力のとおり通りました。

install はページを開く前に呼ぶ

公式ドキュメントでは、テストの中で install() を呼ぶなら、clock のほかのメソッドより前に呼ぶように書かれています。順番を守らないと、結果が予測できないとされています。

試しに、page.goto() の後で install() を呼び、5分進めてみました。

ts
test('ページを開いてから install する', async ({ page }) => {
  await page.goto('/');
  await page.clock.install({ time: new Date('2026-12-24T10:00:00+09:00') });
  await page.clock.fastForward('05:00');
  await expect(page.getByRole('status')).toHaveText(
    '操作がなかったため、ログアウトしました',
    { timeout: 3000 },
  );
});

結果は失敗でした。fastForward('05:00') で進めても、表示は「ログイン中」のままです。エラー出力のうち、期待した値と実際の値の部分を載せます。

text
    Error: expect(locator).toHaveText(expected) failed

    Locator:  getByRole('status')
    Expected: "操作がなかったため、ログアウトしました"
    Received: "ログイン中"
    Timeout:  3000ms
ポイント

page.clock.install() は page.goto() より前に書きます。この記事のほかのテストは、どれもこの順番で通りました。

​Posted by 86