AIのE2Eテストの落とし穴? Wrangler × Windowsに潜むトークン浪費ポイント
はじめに
E2Eテストでこんなことありませんか?
E2Eテストを書いた。コードは完璧だ。レビューも通った。AIと一緒に確認もした。
しかし、テストを実行すると失敗する。エラーメッセージを読んでも、コードに問題は見つからない。
AIと一緒にデバッグを繰り返す。仮説は次々と出てくる。修正もする。でも解決しない。気づけば数時間が経過し、トークンだけが溶けていた。
この記事をお勧めしない人
- E2Eテストが失敗しても、とりあえずローカルで動けば本番も大丈夫だと考える人。
- AIのデバッグ提案を、すべて正しいと無条件で信じている人。
- 「PC再起動で直った」という解決策を、技術者として恥ずかしいと感じる人。
もし一つでも当てはまらないなら、読み進める価値があるかもしれません。
環境起因バグを放置すると危険です
新しいツールチェーン(Wrangler、Viteなど)は、特定のOS環境で不安定な挙動を見せることがあります。この「環境の澱み」は、コードレビューでもAIでも発見できません。
やがて、「もう少しで解決できるはず」という錯覚に陥り、論理的に正しいはずの修正を何度も繰り返すことになります。
ついに、数時間のデバッグと大量のトークン消費の末、進捗ゼロで疲弊だけが残る事態に陥ります。
こんな未来が手に入ります
この記事を読めば、「コードは正しいのにテストが落ちる」問題への撤退基準と、環境起因バグを切り分ける判断力が手に入ります。
具体的には、ローカルE2Eとデプロイ後E2Eの「信頼の階層化」という設計図を手に入れられます。これにより、環境問題に時間を溶かすことなく、開発を前に進められます。
この方法は、机上の空論ではありません。まさにこのブログ自身の開発で実際に遭遇し、解決した問題から得られた実践知です。
この情報は、公式ドキュメントには書かれていない、Windows × Wrangler × Playwrightという特定の組み合わせで発生する問題への対処法です。
このブログもそうでした
このブログの開発中、まさに同じ問題で数時間を失いました。AIと一緒にコードを何度も調査し、フォーカストラップ、ハイドレーション、Remixのルーティングと、論理的に正しい仮説を次々と検証しました。しかし解決せず、最終的にPC再起動という「泥臭い」対処で問題が消えたのです。
この記事で、環境起因バグの見切り方と、信頼の階層化というテスト戦略を持ち帰れるように書きました。
さらに深掘りして、AIとの協調開発で「論理では届かない領域」をどう扱うか知りたい方は、その詳細な考え方を確認できます。
概要
Windows × Wrangler × PlaywrightでE2Eテストを実行すると、コードは正しいのにテストが間欠的に失敗する現象に遭遇しました。この記事では、問題の発見から、AIとのデバッグの限界、そして「撤退」という判断に至るまでのプロセスを記録します。
さらに、この具体的な事例から、環境起因バグへの普遍的な対処パターンを抽出します。
発生環境
- 【OS】: Windows 11
- 【フレームワーク】: Remix v2
- 【ホスティング】: Cloudflare Pages/Workers
- 【ローカル開発】: Wrangler (miniflare)
- 【E2Eテスト】: Playwright
問題の発見と症状
E2Eテスト(tests/e2e/account/common.spec.ts)で、ナビゲーションリンクをクリックしてもページ遷移が発生しないという問題が発生しました。
【特徴的だったのは、その間欠性です】:
- 初回のテスト実行: 成功
- サーバー再起動後の2回目以降: 失敗
【エラーメッセージ:】
Expected: "http://127.0.0.1:8788/account/settings"
Received: "http://127.0.0.1:8788/account"【症状:】
- 「設定」リンクをクリックしてもURLが変化しない
- Remixのクライアントサイドナビゲーションが動作していない
- コンポーネントのレンダリング自体は正常(リンクは表示されている)
調査と試行錯誤のプロセス
仮説1: フォーカストラップがナビゲーションを阻害している?
直前にEmailChangeModalにフォーカストラップを実装していたため、グローバルなキーボードイベントリスナーがナビゲーションに干渉している可能性を疑いました。
// EmailChangeModal.tsx
useEffect(() => {
if (!isOpen) return;
document.addEventListener('keydown', handleTabKey);
return () => document.removeEventListener('keydown', handleTabKey);
}, [isOpen]);【検証結果】: /accountページではモーダルは閉じた状態(isOpen = false)なので、イベントリスナーは登録されていない。この仮説は棄却。
仮説2: Remixのハイドレーション問題?
サーバーサイドとクライアントサイドでレンダリング結果が異なり、ハイドレーションエラーが発生している可能性を検討しました。
【検証結果】: ブラウザコンソールにハイドレーションエラーは表示されていない。この仮説も棄却。
仮説3: useRouteLoaderDataの使用が影響?
親ルートの認証データをuseRouteLoaderDataで取得するよう変更した直後だったため、この変更が影響している可能性を疑いました。
// account.settings.tsx
const parentData = useRouteLoaderData<typeof accountLoader>('routes/account');【検証結果】: 空のloaderを追加しても、loaderを削除しても、問題は解決せず。この仮説も棄却。
パターン認識: AIが出す仮説の共通点
ここで気づいたことがあります。【AIが出す仮説はすべて「コードの世界」の話でした】。
- フォーカストラップのイベントリスナー
- ハイドレーションの整合性
- Remixのルーティング設定
- TypeScriptの型定義
すべて論理的に正しい仮説です。しかし、どれも問題を解決しませんでした。
根本原因の特定
最終的に、【PC再起動】で問題が解消しました。
根本原因は「コードの世界」ではなく「環境の世界」にありました:
- 【Wranglerのキャッシュ問題】:
.wrangler/state/v3フォルダ内のSQLiteデータベースやキャッシュファイルがNode.jsプロセスによってロックされていた - 【Windowsのファイルロック】: プロセスがファイルを開いている間は削除不可(Unixとは異なる設計)
- 【プロセスの残留】: 開発サーバー停止後もバックグラウンドプロセスが残り、古い状態を保持していた
なぜAIはこの原因に到達できなかったのか?
AIは「与えられた情報の中で論理的に正しい仮説」を出します。しかし、OSのプロセス状態、ファイルシステムのロック状況、キャッシュの腐敗といった「環境の澱み」は、コードを読むだけでは見えません。
これは【AIの限界】ではなく、【AIへの入力の限界】です。人間が「環境を疑う」という判断をしなければ、AIはその方向に思考を向けられません。
解決策
具体的対処(この事例)
【ステップ1: キャッシュクリーンアップスクリプトの作成】
{
"scripts": {
"clean:wrangler": "node scripts/clean-wrangler.js && npm run db:migrate",
"dev:wrangler:clean": "npm run clean:wrangler && npm run dev:wrangler"
}
}// scripts/clean-wrangler.js
const fs = require('fs');
const path = require('path');
const wranglerPath = path.join(process.cwd(), '.wrangler', 'state', 'v3');
if (fs.existsSync(wranglerPath)) {
try {
fs.rmSync(wranglerPath, { recursive: true, force: true });
console.log('Wrangler cache cleaned successfully');
} catch (error) {
console.error('Failed to clean cache. Try closing all Node processes.');
process.exit(1);
}
}【ステップ2: CLAUDE.mdへの知見追記】
#### Windows/Wrangler固有の注意事項
**症状**: 以下のいずれかが発生した場合
- テストが `ERR_CONNECTION_REFUSED` で全て失敗
- ナビゲーションテストが予期せず失敗
- コード変更が反映されない
**解決策**:
1. `npm run dev:wrangler:clean` を実行
2. 解決しない場合はPC再起動汎用パターン(他の環境でも適用可能)
この事例から抽出した、環境起因バグへの普遍的な対処パターンです:
パターン1: 撤退基準を設ける
IF コードに問題が見つからない
AND 複数の論理的仮説がすべて棄却された
THEN 環境を疑い、リセットを試みる深追いしない勇気が、時間とトークンを守ります。
パターン2: 信頼の階層化
| 環境 | 役割 | 信頼度 |
|---|---|---|
| ローカルE2E | 高速フィードバック | ベストエフォート |
| デプロイ後E2E | マージ前ゲート | 信頼できる |
ローカルE2Eは「速度」のため、デプロイ後E2Eは「信頼性」のため。目的を分けることで、ローカルの不安定さに振り回されなくなります。
パターン3: 核オプションを用意する
環境起因バグに対しては、「論理的に正しい修正」より「環境リセット」の方が効果的な場合があります。
- 【即時対処】: PC再起動、Docker再起動、キャッシュ全削除
- 【自動化】: クリーンスクリプトの用意
- 【心理的ハードル除去】: 「再起動で直った」を恥じない
学んだこと・まとめ
技術的な学び
E2Eテストが間欠的に失敗する場合、以下のチェックリストを確認することが重要です:
- 【コードの問題か?】: ソースコード、テストコード、設定ファイルを確認
- 【環境の問題か?】: キャッシュ、プロセス残留、ファイルロックを疑う
- 【撤退すべきか?】: 複数の仮説が棄却されたら、環境リセットを試みる
AIとの協調開発における学び
- 【AIは論理の世界で最強】: コードの問題には強力な相棒
- 【AIは環境の澱みが見えない】: OS状態、キャッシュ、プロセス残留は盲点
- 【人間の役割】: 「環境を疑う」というメタ判断を下すこと
今後のベストプラクティス
- 【信頼の階層化】: ローカルE2Eは速度、デプロイ後E2Eは信頼性と割り切る
- 【撤退基準の設定】: 「コードに問題がない」と確信したら環境をリセット
- 【知見の構造化】: 環境固有の対処法をCLAUDE.mdに明記し、AIが同じ轍を踏まないようにする
「PC再起動で直った」は、恥ずかしい解決策ではありません。環境起因バグに対しては、最も合理的な撤退戦術です。深追いしないことも、エンジニアリングです。
関連リソース
- Cloudflare Pages Preview Deployments - デプロイ後E2Eの基盤
- Playwright Best Practices - E2Eテスト設計の指針