E2Eテストの「とりあえず待つ」を、今は小さいうちに止める理由
E2Eテストの待機を、「N秒待つ」ではなく「状態が成立するまで待つ」書き方に統一し、散らばった時間定数を共通の定数へ集約する。今のスイートは固定待機を実行していないが、今のうちに止める。
問題提起
E2Eテストは、ブラウザ・ネットワーク・実行マシンの状態という、コードの外の不確実性に左右される。今のスイートは、その不確実性への備えを、次の形で払っている。
- 【時間定数が20箇所に散っている】: 「状態の反映を待つ上限500ms」が、共通ヘルパーには定数(
SETTLE_TIMEOUT)として定義されている。ところが、spec側では同じ値が{ timeout: 500 }というリテラルで19箇所に直接書かれている。値を変えるには、20箇所を探して直す必要がある。 - 【使われていない待機ヘルパーが残っている】:
waitForDialogOpenTransitionは600msの固定待機で、呼び出し元は0件だ。それなのに、E2Eの注意事項(.claude/rules/testing/e2e-browser-quirks.mdの11)は、今もこのヘルパーを使うよう勧めている。 - 【CSSとの値の同期が手作業】: この600msは、CSSの
--transition-duration-slow: 0.6sと、手で揃える前提だ。CSSの値を変えても、テスト側は何も教えてくれない。
今のスイートが実行する固定待機は0件である。だから実行時間は伸びていない。ただし、固定待機を足す入り口は、塞がれていない。waitForTimeout を禁止するリントも、ルールの文書もない。
なぜそう作っていたのか
固定の待ち時間は、その場では合理的な選択だった。
| 当初解決しようとした問題 | 生まれた副産物 |
|---|---|
| 非同期処理が終わる前にアサーションが走って落ちる。待てば通る | 待機の値に根拠がなく、環境の速度が変わると足りなくなる |
| 落ちたテストを、その場で通したい。AIは「テストを通す」ことを目的に、最短の手段を選ぶ | スイート全体の実行時間や、長期の健全性は見られない。個別には最適でも、全体では待ちが積み上がる |
| 「タイムアウトしたら2秒待つ」は、たいてい効く。タイムアウトが、その日は正しいこともある | 待機を足しても、コミットしなければ消える。再発して足してコミットすると、理由のわからない待機が残る |
ここで、事実を1つ置く。2026-02-09時点のE2Eスイートには、waitForTimeout が7箇所あった。1回の実行につき、下限で19.3秒を待っていた。理由のコメントが付いていたのは、そのうち1箇所だけだった。
その後、待機は一度は減った。しかし、禁止の方針が .claude/ 配下に入ったあとの2026-03-18に、6箇所から7箇所へ戻った。禁止は、文書に書くだけでは止まらない。
やったこと
Before: 今の状態。時間定数が、共通ヘルパーには定数で、specにはリテラルで、二重に書かれている。
// tests/utils/e2e-helpers.ts
const SETTLE_TIMEOUT = 500;
const DIALOG_OPEN_TRANSITION_MS = 600; // CSSの0.6sと手動同期
export async function waitForDialogOpenTransition(page: Page): Promise<void> {
await page.waitForTimeout(DIALOG_OPEN_TRANSITION_MS);
}// tests/e2e/life/structure.spec.ts(19箇所のうちの1つ)
await h.clickAndWaitFor(trigger, () => expect(swatch).toBeVisible({ timeout: 500 }));After: 待機を、観測できる状態の成立で表す。時間定数は、共通ヘルパーの定数だけを参照する。固定待機を呼ぶヘルパーは、アニメーションの完了を待つ形へ置き換えるか、削除する。waitForTimeout の使用は、リントで検出する。この作業は、Issue #372 で扱う。
await h.clickAndWaitFor(trigger, () => expect(swatch).toBeVisible({ timeout: SETTLE_TIMEOUT }));flowchart LR
subgraph 固定待機
A1[操作] --> B1["N秒待つ
根拠なし"] --> C1[検証]
end
subgraph 状態を待つ
A2[操作] --> B2["状態が成立するまで
自動でリトライ"] --> C2[検証]
end待ちたいものごとの、状態ベースの手段は次のとおり。
| 待ちたいこと | 状態ベースの手段 |
|---|---|
| 要素の表示 / 非表示 | expect(el).toBeVisible() / .not.toBeVisible() |
| フォーカス | expect(el).toBeFocused() |
| テキスト | expect(el).toContainText('...') |
| URL遷移 | page.waitForURL('/path') |
| APIレスポンス | page.waitForResponse(url) |
選んだ方針と手放したもの
「とりあえず待つ」は、設計として成り立つ。1行で書け、何を待つべきかの分析が要らない。実行も、今のところ速い。一方で、状態で待つ書き方は、「何が完了の証拠か」を、毎回特定する手間を払う。それでも、保守コストを優先する側を選んだ。
- 【A: 今の状態】: 時間定数が散り、固定待機を足せる入り口が開いている。足されなければ、実行時間は伸びない。
- 【B: 統一後の状態】: 待機は状態で表し、時間定数は共通の定数だけに置き、固定待機の追加はリントで止める。
- 【優先した価値】: 保守コスト。待機の追加と時間定数の変更が、テストの増加に比例して、変更1回あたりに払う量を増やすことを防ぐ。
- 【犠牲にした価値】: 技術の言葉では、コード1行で通せる手軽さ。経営の言葉では、新規開発に割ける工数を、この整理に割くこと。売上につながる機会を、その分だけ後ろへ回す。
この判断が適用されるのは、待つ対象が状態として観測できる場合である。時間の経過そのものが待ちの内容になる場合(アニメーションの途中の割り込みなど)は、状態の完了を取れるかを先に調べる。取れないときだけ、例外として名前付きヘルパーに閉じ込め、根拠を添える。
経営翻訳
営業時間の変更が、本部の規程に1か所、各店のマニュアルに19冊、同じ数字として書き写されている会社を考える。営業時間を変えるたびに、20か所を探して書き換える必要がある。どれかを直し忘れても、気づく仕組みはない。
今は、この手間が発生するのは、営業時間を変えるときだけだ。頻度は低く、損失は小さい。ただ、マニュアルは増え続ける。
営業時間の変更が、本部の規程に1か所、各店のマニュアルに19冊、同じ数字として書き写されている。営業時間を変えるたびに、20か所を探して書き換える必要がある。
待ちの上限時間(500ms)を変更するとき、書き換えが要る箇所の数: 20箇所
保守コスト
- 【今払っている保守コスト】: 待ちの上限時間(500ms)を1つ変えるとき、書き換えが要る箇所が20箇所ある。統一後は、定数の定義1箇所になる。これが、変更1回あたりに払う量である。計数(代理指標): 20箇所 → 1箇所(95%の削減)。数え方:
tests/e2e/の spec で{ timeout: 500 }をgrepすると19件、tests/utils/e2e-helpers.tsのSETTLE_TIMEOUTの定義が1件で、合計20箇所。統一後の1箇所は、集約後に定義だけが残る構造上の値である(Issue #372 で実施予定)。この20箇所が余計なのは、定数を参照すれば払わなかったはずの分である。 - 【断つ連鎖】: 主に、前例の伝播を断つ。今の時間定数のリテラルは19箇所あり、AIは、それを作法と読み取って、新しいテストにも
{ timeout: 500 }を書き写しやすい。定数への集約と、固定待機の追加を止めるリントで、真似できる地点を減らす。副次的に、診断の反復も断つ。固定待機がなければ、落ちたときに「待ちが足りない」のか「壊れている」のかを、切り分けられる。断たなければ、診断の反復から、人の介入、検証コストへ進む。このうち、実測できたのは前例の伝播だけで、後ろのリンクは想定の場面である(起こりうる可能性)。 - 【放置した場合の増え方】: 今の損失は、増える方向にしかならない。新機能が増えるたびに、同じ書き方が前例になって広がり、落ちたテストにも固定待機が足される。ここでは、経営が動かせる「新機能を入れる速さ」だけを変えて、1年後の待機の数と、実行時間への影響を見積もる。
シナリオの前提を先に書く。次の値は、実測である。
| 項目 | 値 | 数え方 |
|---|---|---|
| E2Eのテストファイル(spec)の数 | 12本 | tests/e2e/*/*.spec.ts。サービスのセクション(例: blogの記事詳細、lifeのInspector)ごとに1本 |
| 待ちが入りうる地点の数 | 525 | ブラウザに「何かをする・確かめる」呼び出しの合計。操作198(spec内の h.tap / h.fill / h.goto などのヘルパー呼び出しと、直接の .click( など)と、アサート327(expect()を足した値 |
| 1機能(spec1本)あたりの地点数 | 約44 | 525 ÷ 12本 |
| 待機が入る頻度 | 90地点に1か所 | 2026-02-09時点で、地点630(操作269+アサート361)に対し、固定待機7箇所 |
| 待機1箇所の、1回の実行あたりの時間 | 約2.76秒 | 同じ時点で、7箇所の合計が1回の実行につき下限19.3秒。19.3 ÷ 7。ループやフックで繰り返される分を含む |
| 今の1回のE2E実行 | 約96秒 | このブログの検証環境で、1ワーカーで実行したときの1回の観測値 |
次の値は、仮定である。
- 開発は週1回で、年48回。1回の開発で、E2Eを10回実行する。
- 1機能は、1セクション(spec1本)とする。
- 今の固定待機は、実行されるものが0箇所から始まる。
待機の頻度は、新機能の書き込みと、落ちたテストの修正の両方で入った結果の合計であり、2つには分けられない。そのため、増える地点のすべてに、同じ頻度を当てる。また、この実績は、2026-02-09時点の1つの標本(7箇所)であり、その時点の実績をそのまま前提にした見積りである。
| 現状ペース(月1機能) | 加速ペース(月2機能) | |
|---|---|---|
| 増える地点(44 × 機能数) | 528 | 1056 |
| 1年後の待機の数(÷ 90) | 約6箇所 | 約12箇所 |
| 1回のE2E実行に足される時間(× 2.76秒) | 約16秒 | 約32秒 |
| 1回の開発(E2E 10回)に足される時間 | 約2.7分 | 約5.4分 |
| 今の1回の実行(96秒)に対する増加 | 約17% | 約34% |
この見積りは、未来の予測ではなく、可能性の大きさである。それでも、どちらのペースでも、待機は減らず、増える方向にしか動かない。そして、事業が速く進むほど、増え方も速くなる。売上のために機能を速く入れる判断は、この損失の増え方を、同じ割合で速める。
時期のトレードオフはない。今整理しても、後で整理しても、整理にかかる手間は変わらない(むしろ、箇所が増えるほど増える)。後回しにすれば、同じ作業の量が増えるだけである。
- 【新たに負う保守コスト】: 固定待機の追加をリントで止めるため、状態で表せない待ちは、例外として1箇所に閉じ込める必要が出る。歯止め: 例外は名前付きヘルパー1箇所に限り、根拠を文書に残す。リントは、品質ゲートの3契機に自動で載るので、禁止が文書だけに頼る状態にはならない。
蛇口の水漏れに例えると、今は、1滴ずつ落ちているだけである。水道代には、まだ表れない。担当者が、毎回、布で拭いている。ただ、漏れは増える方向にしかならず、いつかは蛇口ごと取り替える必要がある。取り替えの手間は、後に回しても減らない。「売上を優先するので、今は見送る」という判断は、損失を減らすのではなく、積み上げる。
さらに、水漏れが誰の目にも明らかな現場では、新しく来た人が、既存のエンジニアを信頼できない。そこで長居できず、「今が良ければ良し」と考える人だけが残るかもしれない。これは、そうなるという主張ではなく、起こりうる可能性である。人が定着しなければ、採用に間接的な費用がかかる。
この問題は、AIがテストを書き直す運用で、特に起こりやすい。AIは「テストを通す」ことを目的に、最短の手段を選ぶ。待機を足せば、その場では通るからである。だから、人が1件ずつ審査しなければ、固定待機は、気づかないうちに増える。
同じくAIがテストを「とりあえず通す」ために生む問題として、ハードコードされたデータ依存はspec.yamlをSSOTとしてE2Eテストデータを一元管理した記録で、UI文言の変更でテストが壊れる問題はextractTestIdパターンで扱っている。