Playwrightで、すぐには変わらない値を待つ方法
Playwright の expect.poll() と toPass() を使うと、画面の要素ではない値でも、条件を満たすまで取り直して待てます。toHaveText() のような自動で待つアサーションは画面の要素などを確かめるもので、関数が返す値には使えません。この2つは、値を取り出す関数そのものを何度も呼び直してくれます。「ボタンを押すとバックグラウンドで処理が始まり、少したってから API の status が done になる」のような、非同期の処理の完了を E2E テストで確かめたいときに使います。
検証環境で、少したつと status が running から done に変わる API を作り、何ms目に取り直したのか、どこで止まるのかを測りました。
検証環境は Ubuntu 24.04、Node.js 22.23.4、@playwright/test 1.63.0 です。テストは TypeScript で書き、ブラウザは Chromium(ヘッドレス)だけ、worker は1つで動かしました。API は Node.js の http モジュールで書いたサーバーを、設定ファイルの webServer で 127.0.0.1:3000 に立てました。外部のサービスの API、Firefox と WebKit、Python などほかの言語の Playwright、CI のサービス上での実行は試していません。
1回取得して比べるだけでは、まだ running のまま
検証用のサーバーは、POST /jobs?doneAfter=1800 で仕事を1つ作り、その id を返します。GET /jobs/:id は、仕事を作ってから doneAfter ミリ秒たつまでは {"status":"running","items":0} を、そのあとは {"status":"done","items":3} を返します。テストからは、次の createJob() で仕事を作ります。
// tests/helpers.ts(一部)
import type { APIRequestContext } from '@playwright/test';
export async function createJob(request: APIRequestContext, doneAfter: number) {
const res = await request.post(`/jobs?doneAfter=${doneAfter}`);
return (await res.json()).id as string;
}
まず、取得した値を1回だけ toBe() で比べました。
// tests/no-wait.spec.ts
import { test, expect } from '@playwright/test';
import { createJob } from './helpers';
test('1回だけ取得して比べる', async ({ request }) => {
const id = await createJob(request, 1800);
const job = await (await request.get(`/jobs/${id}`)).json();
expect(job.status).toBe('done');
});
テストは42msで落ちました。toBe() は、渡された値をその場で1回比べるだけで、待ちません。
Error: expect(received).toBe(expected) // Object.is equality
Expected: "done"
Received: "running"
expect.poll で、done になるまで取り直す
expect.poll() には、値を返す関数を渡します。Playwright はその関数を呼んで toBe() などで比べ、条件を満たさなければ、少しあけてまた呼びます。何ms目に呼ばれたかを記録するため、関数の中で sw.tick() を呼んでいます(stopwatch() は、呼ばれた時刻を配列にためるだけの関数です)。
// tests/poll.spec.ts(一部)
test('expect.poll で done になるまで取り直す', async ({ request }) => {
const id = await createJob(request, 1800);
const sw = stopwatch();
await expect.poll(async () => {
sw.tick();
const job = await (await request.get(`/jobs/${id}`)).json();
return job.status;
}).toBe('done');
console.log(`[計測] 呼ばれた時刻(ms): ${sw.calls.join(', ')} / 終わるまで ${sw.elapsed()}ms`);
});
仕事が1800msで done になる設定で動かすと、関数は5回呼ばれ、1876msで通りました。
[計測] 呼ばれた時刻(ms): 1, 104, 359, 863, 1872 / 終わるまで 1876ms
呼ばれた時刻の間隔は、およそ100ms、250ms、500ms、1000msです。公式ドキュメントの expect.poll の説明によると、取り直す間隔の初期値は [100, 250, 500, 1000] で、配列を使い切ったあとは最後の値をくり返します。done になってから最初の確認が1872msだったので、待ち時間の大半は、done になる時刻(1800ms)までの待ちです。
間隔は intervals で変えられます。intervals: [200] にすると、約200msごとに10回呼ばれ、1846msで通りました。
await expect.poll(async () => {
// 中身は上と同じ
}, { intervals: [200] }).toBe('done');
[計測] 呼ばれた時刻(ms): 1, 207, 412, 616, 821, 1025, 1230, 1434, 1638, 1842 / 終わるまで 1846ms
![expect.poll が値を取りに行った時刻を2行で比べた図。初期設定の間隔では1、104、359、863、1872msの5回で、5回目に成功。intervals: [200] では約200msごとに10回呼ばれ、1842msの10回目に成功。どちらも done になる1800msの直後に成功している](https://neko-note.org/wp-content/uploads/2026/11/playwright-expect-poll-to-pass-poll-intervals.png)
done になる1800msから、それに気づいた確認までの差は、初期設定の間隔で72ms、[200] で42msでした。そのかわり、[200] は API を2倍の10回呼んでいます。初期設定の間隔は、最初は短く、だんだん長くなります。間隔を短くするほど早く気づきますが、そのぶん呼び出しが増えます。
expect.poll の制限時間は初期設定で5秒
expect.poll() は、初期設定では5秒で諦めます。7000msで done になる仕事を待たせると、8回呼んだところで落ちました。message を渡すと、エラーの先頭にその文が出ます。
// tests/poll-timeout.spec.ts(一部)
await expect.poll(async () => {
sw.tick();
return (await (await request.get(`/jobs/${id}`)).json()).status;
}, { message: '仕事が done になる' }).toBe('done');
[計測] 呼ばれた回数 8 / 終わるまで 4911ms
Error: 仕事が done になる
仕事が done になる
expect(received).toBe(expected) // Object.is equality
Expected: "done"
Received: "running"
Call Log:
- Timeout 5000ms exceeded while waiting on the predicate
{ timeout: 10_000 } を渡して、同じく7000msで done になる仕事を待たせると、11回目の呼び出しで done が返り、7939msで通りました。設定ファイルの expect: { timeout: 2000 } も expect.poll() に効きます。そう設定し、timeout を書かずに終わらない仕事を待たせると、5回呼んで1895msで止まり、エラーには Timeout 2000ms exceeded と出ました。
toPass で、処理のまとまりごと再試行する
toPass() は、expect() に渡した関数を、中のアサーションがすべて通るまで呼び直します。公式ドキュメントの toPass の説明では、「コードのまとまりを、通るまで再試行する」ものとされています。値を1つ返すだけの expect.poll() とちがい、中にアサーションを2つ以上書けます。
// tests/to-pass.spec.ts(一部)
await expect(async () => {
sw.tick();
const job = await (await request.get(`/jobs/${id}`)).json();
expect(job.status).toBe('done');
expect(job.items).toBe(3);
}).toPass();
[計測] 呼ばれた時刻(ms): 3, 111, 367, 873, 1880 / 終わるまで 1888ms
呼ばれた時刻は expect.poll() とほぼ同じでした。取り直す間隔の初期値も同じ [100, 250, 500, 1000] です。
toPass() の中では、ページの操作もくり返せます。「更新」を押したときだけ API を取り直して「処理中」か「完了」を表示するページで、「更新」を押してから表示を確かめる処理を toPass() で囲みました。表示はボタンを押さない限り変わらないので、toHaveText() だけで待っても「完了」にはなりません。
await expect(async () => {
sw.tick();
await page.getByRole('button', { name: '更新' }).click();
await expect(page.locator('#status')).toHaveText('完了');
}).toPass();
この書き方では、仕事が1500msで完了になるのに、通るまで5242msかかりました。押したのは2回だけです。
[計測] 押した時刻(ms): 20, 5193 / 終わるまで 5242ms
中の toHaveText() も自動で待つアサーションなので、1回目に押したあと「処理中」のまま、初期設定の制限時間の5秒いっぱい待ってから失敗していました。そのあいだ toPass() は次の再試行に進めません。中の toHaveText() に { timeout: 500 } を付けると、6回動かして1535〜2528msで通りました。3回押して通ったのが2回、4回押して通ったのが4回です。中の toHaveText() を初期設定のまま6回動かした結果は、5231〜5242msでした。
await expect(page.locator('#status')).toHaveText('完了', { timeout: 500 });

toPass は初期設定では制限時間がない
toPass() の制限時間は、初期設定では0(制限なし)です。公式ドキュメントにも、toPass は初期設定で timeout が0で、設定ファイルの expect の timeout にも従わない、と書かれています。
設定ファイルを expect: { timeout: 2000 } にして、終わらない仕事を timeout なしの toPass() で待たせました。テストの制限時間は test.setTimeout(10_000) で10秒にしています。
[計測] 呼ばれた回数 12 / 8942ms で止まった
Error: expect(received).toBe(expected) // Object.is equality
Expected: "done"
Received: "running"
Call Log:
- Test timeout of 10000ms exceeded
同じ設定で expect.poll() は2秒で止まりましたが、toPass() はテストの制限時間まで呼び直し続けました。テストの制限時間は初期設定で30秒なので、何も設定しなければ、通らない toPass() はテストの制限時間(30秒)に達するまで呼び直し続けます。
toPass() に制限時間を付けるには、toPass({ timeout: 3000 }) のように引数で渡すか、設定ファイルの expect.toPass.timeout に書きます。
// playwright.config.ts(一部)
export default defineConfig({
expect: { toPass: { timeout: 3000 } },
});
この設定にすると、timeout を書いていない toPass() も6回呼んだところで止まり(2895ms)、エラーは Timeout 3000ms exceeded while waiting on the predicate になりました。引数で { timeout: 3000 } を渡したときも、6回呼んで2878msで止まっています。
画面の要素なら、まず toHaveText() などの locator のアサーションで待ちます。公式ドキュメントも、できるだけ自動で待つアサーションを使い、より複雑な待ち合わせに expect.poll() と toPass() を使うように案内しています。値を1つ取り出して比べるなら expect.poll()、ボタンの操作や複数のアサーションをまとめてくり返すなら toPass() を使い、toPass() には制限時間を付けます。





