flaky test（フレーキーテスト）とは、コードを変えていないのに通ったり落ちたりする、結果の揺れる試験です。
- Playwright が試験を passed・flaky・failed に分ける決まりと、Jest のタイムアウト・GitHub Actions の撃ち直しの道具
- merge queue でだけ赤になった E2E 試験の真因が「遅い作業員」ではなく「速い作業員」だった記録と、作りで塞いだ直し方
- 撃ち直し 1 回で済ませる揺れ、直す揺れ、揺れではない赤（古い試験・本当の欠陥）の見分け方と、「終わり」を回数で決める決まり
AI に開発の仕事を任せる考え方は AIエージェント の頁に、試験を書く席と見る席の分け方は AI テスト自動化 の頁にまとめています。この頁は、書いた試験が揺れた時の扱いだけを扱います。
flaky の区分と、揺れを扱う公式の道具
Playwright Test は、retry（失敗した試験の再試行）を設定すると、試験を 3 つに分けます。最初の実行で通った物は passed、最初は落ちて再試行で通った物は flaky、最初も再試行も全部落ちた物は failed です。既定では、落ちた試験は再試行されません（Playwright「Retries」・2026-10-31 に開いて確かめた）。つまり「playwright flaky」と出るのは、再試行を有効にしていて、1 回目に落ちた試験です。
| 道具 | 公式の決まり | 当社での使い方 |
|---|---|---|
| Playwright の retries | --retries=3 か設定の retries: 3 で有効。既定は再試行なし。1 回目に落ちて再試行で通れば flaky。試験が落ちると作業員のプロセスをブラウザごと捨てて新しく立てる。実行中の試行回数は testInfo.retry で分かる | flaky の札が付いた試験を「揺れの候補」として数える。retry の回数を増やして赤を隠すことはしない |
Jest の beforeAll(fn, timeout) | 省いてよい timeout（ミリ秒）で待つ上限を決める。既定は 5 秒 | 重い準備をする beforeAll には明示のタイムアウトを付ける（下の節） |
| GitHub Actions の撃ち直し | 「Re-run all jobs」か「Re-run failed jobs」。CLI は gh run rerun RUN_ID --failed。元の run と同じ GITHUB_SHA・GITHUB_REF を使う。最初の run から 30 日まで | 形の分かった揺れに限り、落ちた job を 1 回だけ撃ち直す |
出典: Playwright「Retries」・Jest「Globals」・GitHub Docs「Re-running workflows and jobs」（どれも 2026-10-31 に開いて確かめた）。当社での使い方の列は 出典: 社の記録 2026-10-11・社の実測 2026-09-26・社の実測 2026-10-26。
撃ち直しは同じコミットで同じ試験をもう一度走らせるだけなので、通ったからといって揺れの原因が消えたわけではありません。当社では、揺れる試験は merge queue を赤にして撃ち直し（1 回 11 分）を呼ぶ物として、「門が嘘をつく」側に数えています。席が見つけたら起票して直す決まりです（出典: 社の記録 2026-10-11）。列の仕組みは GitHub merge queue の頁に書いています。
当社の記録: merge queue でだけ赤になる試験は、速い作業員で落ちていた
VS Code 拡張の E2E 試験の 1 本が、merge queue でだけ赤になっていました。直前の queue 15 回のうち赤は 3 回です（出典: 社の実測 2026-09-27）。queue の作業員は込み合うので「遅いから落ちる」と考えがちですが、時間を並べると逆でした。赤の 2 回は各試験 6〜7 秒、緑の回は約 10 秒で、落ちていたのは速く走った回でした（出典: 社の実測 2026-09-27）。
真因は、拡張の起動時に置かれた「+2 秒のタイマー」です。このタイマーが、既に開いているパネルへ、同じ道で設定を撃ち直していました。速い作業員では、試験が一覧に印を付けた後にタイマーが鳴り、一覧が作り直されて印が消えます。遅い作業員では印を付ける前にタイマーが鳴るので、緑になります。これは試験だけの問題ではなく、製品の側でも無駄な描き直しと、焦点（フォーカス）の奪い返しを起こしていました（出典: 社の実測 2026-09-27）。
| 直した所 | 中身 |
|---|---|
| 製品の側 | パネルが既に在れば、起動時の自動の起動をしない |
| 試験の側（印を付ける時） | 初期化への返事を待ってから印を付ける |
| 試験の側（描き直しを見る時） | 描き直しは、クリックの後に来た着信を条件にして待つ |
| 変えなかった所 | 判定（assert）は変えない。直しが効く事は陽性対照 2 本で確かめた |
出典: 社の実測 2026-09-27（当社の CI の記録）。
待ち時間を延ばすのではなく、「早く撃ちすぎる」道そのものを作りで塞いだのが要です。終わりの定義は「その後の merge_group で同じ試験が 10 回続けて緑」にし、定期の便で数えて 10 回続けて緑を確かめてから閉じました（出典: 社の実測 2026-09-28）。
タイムアウトの際で揺れる: beforeAll の 5 秒
結合試験の 1 本で、beforeAll（利用者とテナントを作る準備）が Jest 既定の 5 秒のタイムアウトを越え、その後に続く外部キーのエラーで 14 本がまとめて赤になりました。同じ suite は別の run では 6.1 秒で通っていました。準備が 5 秒の前後で終わるため、タイムアウトの際で揺れていた形です（出典: 社の実測 2026-09-26）。
14 本の赤を 1 本ずつ追うと、外部キーのエラーという見かけに引きずられます。当社では次の 3 つで見分けます（出典: 社の実測 2026-09-26）。
- FAIL の行に出る suite の名前が 1 つに揃っているか
- ログに
Exceeded timeout of 5000 ms for a hookが出ているか - 同じ suite の、直近の通った回の所要時間が 5 秒の近くか
手当ては、落ちた job を 1 回だけ撃ち直すことです。直すなら beforeAll に明示のタイムアウトを付けます（出典: 社の実測 2026-09-26）。Jest の beforeAll は 2 番目の引数でミリ秒のタイムアウトを取り、省くと 5 秒です（Jest「Globals」・2026-10-31 に開いて確かめた）。
込み合った作業員で揺れる: 撃ち直しは 1 回まで
管理画面の E2E が、差分と関係の無い画面の試験で 4 failed・2 flaky になりました。落ち方は「タブが 5 秒で出ない」で、込み合った作業員の上で、開発サーバの初回の変換（ビルド）が間に合わない揺れでした。手元では同じ試験が 7 回中 7 回緑、失敗した物だけの撃ち直しの 2 回目で成功しています（出典: 社の実測 2026-10-26）。
この形には直す物がありません。決まりは「同じ形を見たら、先に撃ち直しを 1 回。2 回続けて同じ試験が落ちたら、試験の持ち主へ渡す」です（出典: 社の実測 2026-10-26）。撃ち直しを何回も重ねると、本当の欠陥まで「揺れ」として流してしまうので、回数を 1 回に決めています。作業員の込み具合そのものを見る時の数え方は self-hosted runner の頁に渡します。
「直った」を回数で決める
揺れる試験は、1 回緑になっただけでは直ったと言えません。当社では、件ごとに「何回続けて緑なら閉じるか」を先に決めています。
| 件 | 揺れの形 | 終わりの定義 | 出典 |
|---|---|---|---|
| merge queue でだけ赤の E2E | 速い作業員で起動時のタイマーと重なる | その後の merge_group で同じ試験が 10 回続けて緑 | 社の実測 2026-09-28 |
| 1 時間に 1 回の試験 | 時々揺れる | 自分で 30 回の繰り返しを 2 本撃って 60/60 緑 | 社の記録 2026-10-11 |
| 別の結合試験 | 時刻で揺れる | 使い捨ての DB で 10 回続けて緑 | 社の記録 2026-10-15 |
| 別の試験 | lte: now の時刻の精度で揺れる | —（揺れの形だけを記録） | 社の記録 2026-09-28 |
出典: 社の実測 2026-09-28・社の記録 2026-09-28・2026-10-11・2026-10-15（当社の CI と作業の記録）。
同じ決まりに「skip（飛ばす）と閾値の水増しで緑にしない」と明記しています（出典: 社の記録 2026-10-11）。試験を飛ばしても、待ち時間や許す幅を広げても、緑は出せます。けれどもそれは門を黙らせただけで、揺れの原因は残ります。
揺れではない赤を、揺れと呼ばない
ずっと赤のままの試験は「どうせ flaky」と扱われがちです。検証の環境で走らせた全部の E2E のうち、前から赤だった 3 本を調べると、どれも揺れではありませんでした（出典: 社の実測 2026-10-21）。
- 2 本は試験が古かった。仕様が変わったのに、試験が前の仕様のままでした
- 1 本は画面の本当の欠陥でした。日付の送りを連打すると、1 回分を落としていました
緩めて緑にはせず、古い試験は今の仕様に合わせ、欠陥は画面の側を直しました。結果は 141 passed・1 flaky・0 failed で、消した試験は 0 本です（出典: 社の実測 2026-10-21）。
赤を見た時の見分け方
当社の記録を、赤を見た時に確かめる順に並べ直すと次のとおりです。
| 見えた事 | 疑う物 | 当社の手当て |
|---|---|---|
| queue でだけ赤・落ちた回の方が速い | 起動や初期化と試験の操作の重なり（早撃ち） | 作りで塞ぐ。判定は変えず、10 回続けて緑で閉じる（2026-09-27〜28） |
同じ suite が束で赤・Exceeded timeout of 5000 ms for a hook | 準備がタイムアウトの際 | 1 回だけ撃ち直す。直すなら beforeAll に明示のタイムアウト（2026-09-26） |
| 差分と無関係な画面が赤・手元では緑 | 込み合った作業員での初回の変換 | 撃ち直し 1 回。2 回続けて同じ試験なら持ち主へ（2026-10-26） |
| ずっと同じ試験が赤 | 試験が古い、か本当の欠陥 | 揺れと呼ばずに調べ、緩めずに直す（2026-10-21） |
出典: 社の実測 2026-09-26・2026-09-27・2026-09-28・2026-10-21・2026-10-26（当社の CI の記録）。
よくある質問
flaky test とは何ですか？
コードを変えていないのに、通ったり落ちたりする試験です。Playwright では、retry を有効にした時に、1 回目に落ちて再試行で通った試験に flaky の札が付きます（Playwright「Retries」・2026-10-31 に開いて確かめた）。
Playwright の retries を増やせば flaky は解決しますか？
赤は隠れますが、揺れの原因は残ります。当社では retry の回数を増やして緑にすることはせず、「skip と閾値の水増しで緑にしない」を決まりに書いています（出典: 社の記録 2026-10-11）。直したかどうかは、30 回の繰り返しを 2 本で 60/60 緑のように、回数で確かめます。
flaky な試験は撃ち直してよいですか？
形の分かった揺れなら、落ちた job を 1 回だけ撃ち直します。GitHub Actions では「Re-run failed jobs」か gh run rerun RUN_ID --failed で、同じコミットのまま走らせ直せます（GitHub Docs・2026-10-31 に開いて確かめた）。当社では 2 回続けて同じ試験が落ちたら、撃ち直さずに試験の持ち主へ渡します（出典: 社の実測 2026-10-26）。
Jest で「Exceeded timeout of 5000 ms for a hook」が出たら、何を見ればよいですか？
beforeAll などの準備が、既定の 5 秒を越えています。当社では FAIL の行の suite 名、このメッセージ、同じ suite の直近の通った時間（別の run では 6.1 秒）を並べて、タイムアウトの際の揺れだと見分けました（出典: 社の実測 2026-09-26）。直すなら beforeAll の 2 番目の引数に明示のタイムアウトを付けます（Jest「Globals」・2026-10-31 に開いて確かめた）。
出典
- Playwright「Retries」 https://playwright.dev/docs/test-retries（2026-10-31 に開いて確かめた・passed／flaky／failed の区分・既定は再試行なし・
--retriesと設定のretries・testInfo.retry・失敗時に作業員のプロセスを捨てる事） - Jest「Globals」 https://jestjs.io/docs/api（2026-10-31 に開いて確かめた・
beforeAll(fn, timeout)の timeout はミリ秒・既定 5 秒） - GitHub Docs「Re-running workflows and jobs」 https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/re-running-workflows-and-jobs（2026-10-31 に開いて確かめた・Re-run all jobs／Re-run failed jobs・
gh run rerun --failed・同じGITHUB_SHAとGITHUB_REF・30 日まで） - 社の実測 2026-09-26（当社の CI の記録・
beforeAllの 5 秒越えで 14 本が赤・別の run で 6.1 秒・見分け方と手当て） - 社の実測 2026-09-27（当社の CI の記録・queue 15 回で赤 3 回・赤は 6〜7 秒、緑は約 10 秒・起動時の +2 秒のタイマー・直し方と陽性対照 2 本）
- 社の実測 2026-09-28（当社の CI の記録・
merge_groupで 10 回続けて緑） - 社の記録 2026-09-28（
lte: nowの時刻の精度で揺れた試験） - 社の記録 2026-10-11（60/60 緑の終わりの定義・skip と閾値の水増しで緑にしない決まり・撃ち直し 1 回 11 分・席が見つけたら起票して直す決まり）
- 社の記録 2026-10-15（時刻で揺れた結合試験・使い捨ての DB で 10 回続けて緑）
- 社の実測 2026-10-21（検証の環境の全 E2E・既存の赤 3 本の内訳・141 passed・1 flaky・0 failed・消した試験 0 本）
- 社の実測 2026-10-26（当社の CI の記録・4 failed・2 flaky・手元で 7/7 緑・撃ち直しの 2 回目で成功・撃ち直し 1 回の決まり）