PlaywrightのwaitForTimeoutが遅く不安定な理由
Playwright のテストで、ボタンを押したあとの表示を page.waitForTimeout() で決まった時間だけ待つと、表示が早く出ても最後まで待つので遅くなります。表示が待ち時間より遅れると、テストは落ちます。expect(locator).toHaveText() のような自動で待つアサーションに任せると、表示が出たところで先に進むので、速くて安定します。「保存しました」の表示や画面の切り替えを待つ E2E テストが、たまに落ちる(いわゆる flaky な)テストになっているときに、まず見直したいところです。
検証環境で、表示までの時間を変えたページを用意し、2つの書き方でかかった時間と失敗の回数を比べました。
検証環境は Ubuntu 24.04、Node.js 22.23.4、@playwright/test 1.63.0 です。テストは TypeScript で書き、ブラウザは Chromium(ヘッドレス)だけ、worker は1つで動かしました。テストするページは page.setContent() でその場に作り、サーバーには接続していません。Firefox と WebKit、Python などほかの言語の Playwright、CI のサービス上での実行は試していません。
比べた2つの書き方
テストに使ったのは、「保存」を押すと、決まった時間のあとに「保存しました」と出るページです。表示までの時間は引数で変えられるようにしました。
// tests/page.ts
export const savePage = (delay: number) => `
<button id="save">保存</button>
<p id="status"></p>
<script>
document.querySelector('#save').addEventListener('click', () => {
setTimeout(() => {
document.querySelector('#status').textContent = '保存しました';
}, ${delay});
});
</script>
`;
1つめは、waitForTimeout() で決まった時間だけ待ってから、表示の文字を取り出して比べる書き方です。待つ時間は2秒と3秒の2通りにしました。
// tests/fixed-wait.spec.ts
import { test, expect } from '@playwright/test';
import { savePage } from './page';
import { report } from './measure';
for (const wait of [2000, 3000]) {
for (const delay of [200, 1000, 2500]) {
test(`waitForTimeout(${wait})・表示まで ${delay}ms`, async ({ page }) => {
await page.setContent(savePage(delay));
const start = Date.now();
await page.getByRole('button', { name: '保存' }).click();
await page.waitForTimeout(wait);
expect(await page.locator('#status').textContent()).toBe('保存しました');
report(`waitForTimeout(${wait}) 表示まで${delay}ms`, start);
});
}
}
2つめは、waitForTimeout() を使わず、toHaveText() に待ち合わせを任せる書き方です。
// tests/auto-wait.spec.ts
import { test, expect } from '@playwright/test';
import { savePage } from './page';
import { report } from './measure';
for (const delay of [200, 1000, 2500]) {
test(`toHaveText・表示まで ${delay}ms`, async ({ page }) => {
await page.setContent(savePage(delay));
const start = Date.now();
await page.getByRole('button', { name: '保存' }).click();
await expect(page.locator('#status')).toHaveText('保存しました');
report(`toHaveText 表示まで${delay}ms`, start);
});
}
report() は、「保存」を押す直前から、表示を確かめ終わるまでの時間をミリ秒で出す関数です。ページを作る時間やブラウザを起動する時間を含めずに比べるために用意しました。
// tests/measure.ts
import { test } from '@playwright/test';
export const report = (label: string, start: number) => {
const ms = Date.now() - start;
console.log(`[計測] ${label} ${ms}ms`);
test.info().annotations.push({ type: 'ms', description: String(ms) });
};
それぞれ --repeat-each=5 で5回ずつ動かしました。
npx playwright test tests/fixed-wait.spec.ts tests/auto-wait.spec.ts --repeat-each=5 --reporter=list
表示までの時間ごとの結果
5回の中央値を表にしました。かっこの中は5回のうちの最小と最大です。
| 表示までの時間 | toHaveText に任せる | waitForTimeout(2000) | waitForTimeout(3000) |
|---|---|---|---|
| 200ms | 362ms(282〜368) | 2065ms(2056〜2071) | 3076ms(3071〜3084) |
| 1000ms | 1352ms(1344〜1365) | 2070ms(2058〜2076) | 3068ms(3066〜3076) |
| 2500ms | 2869ms(2858〜2875) | 5回とも失敗 | 3065ms(3062〜3076) |

toHaveText() に任せた場合は、表示までの時間が短いほど早く終わりました。表示まで200msのページなら362msです。
waitForTimeout() は、表示がいつ出ても、指定した時間がたつまで次に進みません。表示まで200msのページでも、waitForTimeout(2000) なら2065ms、waitForTimeout(3000) なら3076msかかりました(中央値)。テストの数が増えるほど、この差が積み重なります。テストの実行全体の時間で比べると、toHaveText() のファイル(3件)は5.4秒でした。fixed-wait.spec.ts から waitForTimeout(3000) の3件だけを選んで動かすと、10.1秒でした。
$ npx playwright test tests/auto-wait.spec.ts --reporter=dot
3 passed (5.4s)
$ npx playwright test tests/fixed-wait.spec.ts --grep 'waitForTimeout\(3000\)' --reporter=dot
3 passed (10.1s)
この節と次の節の出力は、passed と failed の行などを抜き出して載せています。
待ち時間より表示が遅いと、テストが落ちる
表示まで2500msのページを waitForTimeout(2000) で待つと、5回とも落ちました。2秒たった時点では、まだ表示が空だったためです。
Error: expect(received).toBe(expected) // Object.is equality
Expected: "保存しました"
Received: ""
10 | await page.getByRole('button', { name: '保存' }).click();
11 | await page.waitForTimeout(wait);
> 12 | expect(await page.locator('#status').textContent()).toBe('保存しました');
| ^
このエラーからは、「表示が出なかった」のか「出るのが遅かった」のかが分かりません。待ち時間を3秒に延ばせば通りますが、どのページでも3秒かかるようになります。
サーバーの応答を待つ画面などでは、表示までの時間が毎回同じとは限りません。そこで、押すたびに表示までの時間が1.5〜2.5秒の間でばらつくページを作り、それぞれ20回動かしました(ページの中で Math.random() を使って時間を決めています)。
$ npx playwright test tests/uneven/fixed.spec.ts --repeat-each=20 --reporter=dot
Running 20 tests using 1 worker
FF···F·F·F··F·F···FF
9 failed
11 passed (56.5s)
$ npx playwright test tests/uneven/auto.spec.ts --repeat-each=20 --reporter=dot
Running 20 tests using 1 worker
····················
20 passed (59.5s)
waitForTimeout(2000) の書き方は、20回のうち9回落ちました(F が失敗、· が成功)。同じテストが、通ったり落ちたりします。toHaveText() に任せた書き方は、20回とも通りました。表示までの時間を乱数で決めているので、失敗の回数は動かすたびに変わりえます。9回は、今回1回だけ動かしたときの結果です。
公式ドキュメントでの waitForTimeout の扱い
page.waitForTimeout() のリファレンスには、本番のテストで時間を待たないように、とはっきり書かれています。時間を待つテストは本質的に不安定なので、自動で待つ locator の操作とアサーションを使うように、という説明です。デバッグのためだけに使うもの、という位置づけです。
toHaveText() のように自動で待つアサーションは、アサーションの説明によると、条件を満たすまで要素を取り直して確かめ続けます。初期設定の制限時間は5秒です。一方、toBe() のように値をそのまま比べるアサーションは、確かめ直しません。今回の1つめの書き方は、textContent() で取り出した文字を toBe() で1回だけ比べているので、待ち合わせが waitForTimeout() にしかありませんでした。
自動の待ち合わせでも、少し遅れて気づく
表を見ると、toHaveText() に任せた場合でも、表示が出てから確かめ終わるまでに少し間があります。表示まで1000msのページで1352ms、2500msのページで2869msでした。この時間には「保存」をクリックする時間も入っています。
Playwright 1.63.0 のソースコード(frames.ts)を見ると、toHaveText() などのアサーションを処理する expect() は、最初に1回確かめたあと、間隔をあけて確かめ直します。その間隔は20ms、50ms、100ms、100ms、500msと広がり、そのあとは500msごとです。この間隔どおりなら、確かめ直す時刻は確かめ始めてから0、20、70、170、270、770、1270ms…となり、表示まで1000msのページでは1270ms後の確認で初めて表示が見つかる計算になります。測った1352msは、これにクリックなどの時間が加わった値として説明がつきます。それでも、表示まで1000msのページでは、waitForTimeout(2000) より0.7秒ほど早く終わりました。
click() も、押せるようになるまで待つ
自動の待ち合わせは、アサーションだけではありません。click() などの操作も、要素が操作できる状態になるまで待ちます。自動の待ち合わせ(Auto-waiting)の説明によると、click() の前には、要素が見えていること、動いていないこと、ほかの要素に隠れていないこと、無効(disabled)でないことを確かめます。
ページを開いてから800msたつまで「保存」ボタンが disabled になっているページで、waitForTimeout() を入れずにすぐ click() を呼びました。
// tests/page.ts(続き)
export const disabledPage = `
<button id="save" disabled>保存</button>
<p id="status"></p>
<script>
setTimeout(() => document.querySelector('#save').disabled = false, 800);
document.querySelector('#save').addEventListener('click', () => {
document.querySelector('#status').textContent = '保存しました';
});
</script>
`;
// tests/disabled/click.spec.ts
import { test, expect } from '@playwright/test';
import { disabledPage } from '../page';
import { report } from '../measure';
test('押せるようになるのを click() が待つ', async ({ page }) => {
await page.setContent(disabledPage);
const start = Date.now();
await page.getByRole('button', { name: '保存' }).click();
report('click() が終わるまで', start);
await expect(page.locator('#status')).toHaveText('保存しました');
});
5回とも通り、click() が終わるまでの時間は874〜887msでした。下の出力は、[計測] の行と passed の行だけを抜き出しています。ボタンが押せるようになるのを click() が待ってから押したので、「押せるようになるまで1秒待つ」のような waitForTimeout() は要りません。
[計測] click() が終わるまで 874ms
[計測] click() が終わるまで 883ms
[計測] click() が終わるまで 884ms
[計測] click() が終わるまで 887ms
[計測] click() が終わるまで 882ms
5 passed (8.2s)
waitForTimeout() を消すときは、その次の行が待ち合わせをするかを見ます。textContent() などで値を取り出して toBe() で比べている行は、toHaveText() や toBeVisible() のような await expect(locator) の形に書き換えます。click() や fill() は、公式ドキュメントの、操作ごとに待つ条件をまとめた表にあるとおり操作の前に自動で待つので、その前に入れた waitForTimeout() は要りません。





