Playwrightのretriesで不安定なテストを見つける方法
Playwright の retries を設定すると、1回目に落ちてリトライで通ったテストは「flaky」として、通ったテストや落ちたテストとは別に数えられます。CI で E2E テストが「たまに落ちて、再実行すると通る」ときに、どのテストが不安定なのかを洗い出すのに使えます。
検証環境で、通るか落ちるかが実行のたびに変わるテストを作り、リトライの有無、レポートの出方、終了コードを確かめました。数字はすべて、検証環境で出た結果をそのまま載せています。
検証環境は Ubuntu 24.04、Node.js 22.23.4、@playwright/test 1.63.0 です。テストは TypeScript で書き、ブラウザは Chromium(ヘッドレス)だけ、worker は1つで動かしました。テスト用のページは、Node.js の http モジュールで書いたサーバーを、設定ファイルの webServer で 127.0.0.1:3000 に立てています。GitHub Actions などの CI サービス上での実行、Firefox と WebKit、並列実行(worker が2つ以上)は試していません。
通ったり落ちたりするテストを用意する
検証用のページは、「保存」ボタンを押すと /api/save を呼び、応答が来たら「保存しました」と表示します。サーバーは、0〜1600ms のどこかでランダムに応答します。
// server.mjs(一部)
if (req.url === '/api/save' && req.method === 'POST') {
const delay = Math.floor(Math.random() * 1600);
setTimeout(() => {
res.writeHead(200, { 'content-type': 'application/json' });
res.end(JSON.stringify({ ok: true, delay }));
}, delay);
return;
}
テストファイル tests/save.spec.ts には、テストを3つ書きました。2つ目は表示を1秒しか待たないので、応答が1秒より遅い回だけ落ちます。3つ目は、期待する文言をわざとまちがえた、いつも落ちるテストです。
import { test, expect } from '@playwright/test';
test('保存ボタンがある', async ({ page }) => {
await page.goto('/');
await expect(page.getByRole('button', { name: '保存' })).toBeVisible();
});
test('保存すると「保存しました」が出る', async ({ page }, testInfo) => {
console.log(`[試行] retry=${testInfo.retry}`);
await page.goto('/');
await page.getByRole('button', { name: '保存' }).click();
// 応答は0〜1600msのどこかで返るが、待つのは1秒だけ
await expect(page.locator('#message')).toHaveText('保存しました', { timeout: 1000 });
});
test('保存すると「保存済み」と出る(期待する文言がまちがっている)', async ({ page }) => {
await page.goto('/');
await page.getByRole('button', { name: '保存' }).click();
await expect(page.locator('#message')).toHaveText('保存済み', { timeout: 2000 });
});
設定ファイルでは、このサーバーを webServer で立ち上げ、baseURL を指定しています。
// playwright.config.ts
import { defineConfig } from '@playwright/test';
export default defineConfig({
testDir: './tests',
workers: 1,
use: { baseURL: 'http://127.0.0.1:3000' },
projects: [{ name: 'chromium', use: { browserName: 'chromium' } }],
webServer: {
command: 'node server.mjs',
url: 'http://127.0.0.1:3000',
reuseExistingServer: false,
},
});
testInfo.retry には、何回目のリトライかが入ります。1回目の実行は0です。公式ドキュメントのリトライの説明では、リトライの前にサーバー側の状態を片づけたいときなどに使えると紹介されています。
リトライなしで、2つ目のテストだけを --repeat-each=20 で20回くり返したところ、15回通って5回落ちました。
npx playwright test -g '保存しました' --repeat-each=20 --reporter=list
5 failed
15 passed (25.7s)
retries を付けると、passed・flaky・failed の3つに分かれる
リトライの回数は、コマンドの --retries=2 か、設定ファイルの retries: 2 で指定します。公式ドキュメントでは、リトライを有効にしたときのテストを次の3つに分けています。
- passed:1回目で通ったテスト
- flaky:1回目に落ち、リトライで通ったテスト
- failed:1回目に落ち、リトライでもすべて落ちたテスト
retries: 2 にして、3つのテストを --repeat-each=3 で3回ずつ動かしました(console.log の行は省いています)。設定ファイル playwright.report.config.ts の中身は、あとの JSON レポートの節に載せています。
npx playwright test -c playwright.report.config.ts --repeat-each=3
✓ 1 [chromium] › tests/save.spec.ts:3:1 › 保存ボタンがある (84ms)
✘ 2 [chromium] › tests/save.spec.ts:8:1 › 保存すると「保存しました」が出る (1.1s)
✓ 3 [chromium] › tests/save.spec.ts:8:1 › 保存すると「保存しました」が出る (retry #1) (510ms)
✘ 4 [chromium] › tests/save.spec.ts:16:1 › 保存すると「保存済み」と出る(期待する文言がまちがっている) (2.1s)
✘ 5 [chromium] › tests/save.spec.ts:16:1 › 保存すると「保存済み」と出る(期待する文言がまちがっている) (retry #1) (2.1s)
✘ 6 [chromium] › tests/save.spec.ts:16:1 › 保存すると「保存済み」と出る(期待する文言がまちがっている) (retry #2) (2.1s)
✓ 7 [chromium] › tests/save.spec.ts:3:1 › 保存ボタンがある (102ms)
✓ 8 [chromium] › tests/save.spec.ts:8:1 › 保存すると「保存しました」が出る (297ms)
(9〜16 は省略)
3 failed
[chromium] › tests/save.spec.ts:16:1 › 保存すると「保存済み」と出る(期待する文言がまちがっている) ──────────────────────────
[chromium] › tests/save.spec.ts:16:1 › 保存すると「保存済み」と出る(期待する文言がまちがっている) ──────────────────────────
[chromium] › tests/save.spec.ts:16:1 › 保存すると「保存済み」と出る(期待する文言がまちがっている) ──────────────────────────
1 flaky
[chromium] › tests/save.spec.ts:8:1 › 保存すると「保存しました」が出る ─────────────────────────────────────────
5 passed (27.3s)
3回のうち最初の回では、応答待ちのテストが1回目に落ち、(retry #1) の実行で通りました。この回は最後の集計で「1 flaky」に入り、テスト名が別に並びます。いつも落ちるテストは retry #2 まで3回とも落ち、「failed」に入りました。
1回の実行では、flaky なテストが見つからないこともあります。--retries=2 で3つのテストを1回だけ動かしたときは、応答待ちのテストが1回目で通り、集計は「1 failed」「2 passed」でした。flaky が出なかったからといって、そのテストが安定しているとは限りません。疑わしいテストは、上のように --repeat-each と組み合わせて何度か動かすと見つけやすくなります。
flaky だけなら、終了コードは0のまま
応答待ちのテストだけを、--retries=2 で10回くり返しました(最後の集計だけを載せています)。
npx playwright test -g '保存しました' --retries=2 --repeat-each=10 --reporter=list
4 flaky
[chromium] › tests/save.spec.ts:8:1 › 保存すると「保存しました」が出る ─────────────────────────────────────────
[chromium] › tests/save.spec.ts:8:1 › 保存すると「保存しました」が出る ─────────────────────────────────────────
[chromium] › tests/save.spec.ts:8:1 › 保存すると「保存しました」が出る ─────────────────────────────────────────
[chromium] › tests/save.spec.ts:8:1 › 保存すると「保存しました」が出る ─────────────────────────────────────────
6 passed (17.4s)
10回のうち4回が1回目に落ちていますが、終了コードは0でした。終了コードで成否を決める CI では、ジョブは成功になります。ジョブの結果だけを見ていると、不安定なテストがあることに気づけません。flaky の件数は、ログの集計やレポートで確かめる必要があります。
JSON レポートから flaky なテストを書き出す
flaky の件数やテスト名を記録に残すなら、JSON のレポートが扱いやすいです。公式ドキュメントのレポーターの説明のとおり、レポーターは複数を同時に使えます。検証では、画面に出す list と、JSON、HTML の3つを指定しました。
// playwright.report.config.ts
import { defineConfig } from '@playwright/test';
import base from './playwright.config';
// list・JSON・HTML の3つのレポーターを同時に使う
export default defineConfig(base, {
retries: 2,
reporter: [
['list'],
['json', { outputFile: 'report.json' }],
['html', { open: 'never' }],
],
});
さきほどの3回ずつの実行は、この設定で動かしたものです。できた report.json では、flaky になったテストの status が "flaky" になり、results に1回ごとの結果が入っていました。そのテストから、status、expectedStatus と、results の retry・status・duration だけを抜き出すと次のとおりです。
{
"status": "flaky",
"expectedStatus": "passed",
"results": [
{
"retry": 0,
"status": "failed",
"duration": 1101
},
{
"retry": 1,
"status": "passed",
"duration": 510
}
]
}
report.json を読んで、flaky なテストと1回ごとの結果を書き出すスクリプトです。
// list-flaky.mjs
import { readFileSync } from 'node:fs';
const report = JSON.parse(readFileSync(process.argv[2] ?? 'report.json', 'utf8'));
console.log('stats:', JSON.stringify(report.stats, ['expected', 'unexpected', 'flaky', 'skipped']));
const walk = (suite, path = []) => {
const here = suite.title ? [...path, suite.title] : path;
for (const spec of suite.specs ?? []) {
for (const t of spec.tests) {
if (t.status !== 'flaky') continue;
const tries = t.results.map((r) => `retry${r.retry}:${r.status}`).join(' → ');
console.log(`flaky: ${[...here, spec.title].join(' › ')} (${spec.file}:${spec.line}) ${tries}`);
}
}
for (const child of suite.suites ?? []) walk(child, here);
};
report.suites.forEach((s) => walk(s));
stats: {"expected":5,"unexpected":3,"flaky":1,"skipped":0}
flaky: save.spec.ts › 保存すると「保存しました」が出る (save.spec.ts:8) retry0:failed → retry1:passed
この例では、stats の expected が通った数、unexpected が落ちた数にあたり、flaky が flaky の数で、list の集計(5 passed、3 failed、1 flaky)と同じでした。CI でこの出力を毎回残しておけば、同じテストが何度も flaky になっていないかを後から確かめられます。
HTML レポートで flaky なテストを開く
HTML レポートでは、上の「Flaky」を押すと、flaky なテストだけに絞り込めます。検索欄には s:flaky と入りました。

テストを開くと、1回目の実行(Run)とリトライ(Retry #1)がタブに分かれていて、1回目に落ちたときのエラーを読めます。この例では、toHaveText が1000ms待っても #message が空のままだったことが分かります。

–fail-on-flaky-tests で、flaky があれば失敗にする
flaky なテストを見逃したくないときは、--fail-on-flaky-tests を付けます。公式ドキュメントのコマンドラインの説明では「flaky と判定されたテストがあれば失敗にする(初期値は false)」とされています。
次のコマンドで、応答待ちのテストだけを動かしました。
npx playwright test -g '保存しました' --retries=2 --repeat-each=10 --reporter=list --fail-on-flaky-tests
10回のうち6回が flaky で、落ちたテストはありませんでしたが、終了コードは1になりました。
6 flaky
(テスト名の6行は省略)
4 passed (23.6s)
設定ファイルでは、failOnFlakyTests(バージョン1.52で追加)で同じ指定ができます。公式ドキュメントの例は failOnFlakyTests: !!process.env.CI で、CI のときだけ有効にしています。検証では、リトライも CI のときだけ有効にしました。
// playwright.ci.config.ts
import { defineConfig } from '@playwright/test';
import base from './playwright.config';
export default defineConfig(base, {
retries: process.env.CI ? 2 : 0,
failOnFlakyTests: !!process.env.CI,
});
この設定で、応答待ちのテストを10回くり返しました。環境変数 CI を設定しないとリトライがないので、集計は「4 failed」「6 passed」でした。CI=1 を設定すると、リトライが働いて、集計は「2 failed」「2 flaky」「6 passed」になりました。
CI=1 npx playwright test -c playwright.ci.config.ts -g '保存しました' --repeat-each=10 --reporter=list
リトライは、不安定なテストを直す仕組みではなく、見つける仕組みとして使います。retries を付けたら、集計の flaky の件数を必ず見ます。--repeat-each で何度か動かして flaky を洗い出し、見逃したくなければ --fail-on-flaky-tests か failOnFlakyTests で、flaky が出た実行を失敗にします。





