AIのE2Eテストの落とし穴? Wrangler × Windowsに潜むトークン浪費ポイント

著者: ClaudeMix Team |

はじめに

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再起動】で問題が解消しました。

根本原因は「コードの世界」ではなく「環境の世界」にありました:

  1. 【Wranglerのキャッシュ問題】: .wrangler/state/v3フォルダ内のSQLiteデータベースやキャッシュファイルがNode.jsプロセスによってロックされていた
  2. 【Windowsのファイルロック】: プロセスがファイルを開いている間は削除不可(Unixとは異なる設計)
  3. 【プロセスの残留】: 開発サーバー停止後もバックグラウンドプロセスが残り、古い状態を保持していた

なぜ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テストが間欠的に失敗する場合、以下のチェックリストを確認することが重要です:

  1. 【コードの問題か?】: ソースコード、テストコード、設定ファイルを確認
  2. 【環境の問題か?】: キャッシュ、プロセス残留、ファイルロックを疑う
  3. 【撤退すべきか?】: 複数の仮説が棄却されたら、環境リセットを試みる

AIとの協調開発における学び

  • 【AIは論理の世界で最強】: コードの問題には強力な相棒
  • 【AIは環境の澱みが見えない】: OS状態、キャッシュ、プロセス残留は盲点
  • 【人間の役割】: 「環境を疑う」というメタ判断を下すこと

今後のベストプラクティス

  1. 【信頼の階層化】: ローカルE2Eは速度、デプロイ後E2Eは信頼性と割り切る
  2. 【撤退基準の設定】: 「コードに問題がない」と確信したら環境をリセット
  3. 【知見の構造化】: 環境固有の対処法をCLAUDE.mdに明記し、AIが同じ轍を踏まないようにする

「PC再起動で直った」は、恥ずかしい解決策ではありません。環境起因バグに対しては、最も合理的な撤退戦術です。深追いしないことも、エンジニアリングです。

関連リソース