Playwrightのretriesで不安定なテストを見つける方法

​​Playwright​CI,E2Eテスト,TypeScript

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 のどこかでランダムに応答します。

js
// 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つ目は、期待する文言をわざとまちがえた、いつも落ちるテストです。

ts
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 を指定しています。

ts
// 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回落ちました。

bash
npx playwright test -g '保存しました' --repeat-each=20 --reporter=list
text
  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 レポートの節に載せています。

bash
npx playwright test -c playwright.report.config.ts --repeat-each=3
text
  ✓  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回くり返しました(最後の集計だけを載せています)。

bash
npx playwright test -g '保存しました' --retries=2 --repeat-each=10 --reporter=list
text
  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つを指定しました。

ts
// 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 だけを抜き出すと次のとおりです。

json
{
 "status": "flaky",
 "expectedStatus": "passed",
 "results": [
  {
   "retry": 0,
   "status": "failed",
   "duration": 1101
  },
  {
   "retry": 1,
   "status": "passed",
   "duration": 510
  }
 ]
}

report.json を読んで、flaky なテストと1回ごとの結果を書き出すスクリプトです。

js
// 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));
text
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 と入りました。

Playwright の HTML レポートの一覧画面。上の「Flaky 1」が選ばれ、検索欄に s:flaky と入り、「保存すると「保存しました」が出る」のテストが1件だけ、黄色の三角の注意アイコン付きで表示されている
「Flaky」で絞り込んだ HTML レポートの一覧

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

HTML レポートでテストを開いた画面。「Run 1.1s」には赤い×、「Retry #1 510ms」には緑のチェックが付き、Run のタブに Expected: "保存しました"、Received: ""、Timeout: 1000ms のエラーが表示されている
flaky なテストの詳細。1回目(Run)とリトライが別のタブになる

–fail-on-flaky-tests で、flaky があれば失敗にする

flaky なテストを見逃したくないときは、--fail-on-flaky-tests を付けます。公式ドキュメントのコマンドラインの説明では「flaky と判定されたテストがあれば失敗にする(初期値は false)」とされています。

次のコマンドで、応答待ちのテストだけを動かしました。

bash
npx playwright test -g '保存しました' --retries=2 --repeat-each=10 --reporter=list --fail-on-flaky-tests

10回のうち6回が flaky で、落ちたテストはありませんでしたが、終了コードは1になりました。

text
  6 flaky
(テスト名の6行は省略)
  4 passed (23.6s)

設定ファイルでは、failOnFlakyTests(バージョン1.52で追加)で同じ指定ができます。公式ドキュメントの例は failOnFlakyTests: !!process.env.CI で、CI のときだけ有効にしています。検証では、リトライも CI のときだけ有効にしました。

ts
// 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」になりました。

bash
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 が出た実行を失敗にします。

​Posted by 86