コンテンツにスキップ

Design

背景

現状、E2E補助コードはルート直下の e2e-helpers/ に配置され、利用側の e2e/ とは分離されている。実際の参照元は e2e/ 配下（spec、global setup、global teardown）のみであり、テスト実装の責務境界とディレクトリ境界が一致していない。

この不一致により、次の課題が発生している。 - E2E関連の変更時に探索起点が複数になり、影響範囲の把握に時間がかかる。 - import パスが ../e2e-helpers/... となり、E2E内部の依存関係として読み取りづらい。 - e2e-helpers という名称が、対象（E2E専用）と責務（何を補助するか）を十分に表現できていない。

制約は以下である。 - 既存のE2E挙動を維持する（機能追加はしない）。 - アプリ本体（src/）や公開APIには影響を与えない。 - 変更対象はテスト資産の配置・命名・参照経路に限定する。

目標 / 非目標

目標: - e2e-helpers/ を e2e/helpers/ へ再配置し、E2E資産を1つのドメイン配下に集約する。 - 補助モジュール名を責務が推測できる形へ変更する。 - 参照側 import を新配置へ統一し、E2E実行結果を変えずに移行する。

非目標: - 補助関数のロジック改善やアルゴリズム変更。 - E2Eシナリオ自体の追加・削除。 - 単体テスト（tests/）との共通化設計までをこの変更に含めること。

技術的決定

決定1: 補助コードは e2e/helpers/ に配置する

  • 決定内容

  • 新しい配置先を e2e/helpers/ とし、E2Eテストに閉じた補助コードを同一ツリーに置く。

  • 理由

  • 利用側が e2e/ のみであるため、コロケーションにより探索性と可読性が向上する。

  • import が ./helpers/... になり、E2E内部依存であることが明確になる。

  • 代替案

  • tests/helpers/ に統合する案： 将来の共通化余地はあるが、現時点で利用実態がなく責務を拡散させるため不採用。
  • ルート直下を維持する案： 現状課題を解消できないため不採用。

決定2: モジュール名を責務ベースへ再命名する

  • 決定内容
  • fixture-manager.js → fixture-lifecycle.js

  • test-helpers.js → route-fixtures.js

  • 理由

  • 前者はバックアップ・復元・後始末というライフサイクル責務を表現する。

  • 後者はルーティング経由でフィクスチャを供給する責務を表現する。

  • 代替案

  • 既存ファイル名を維持する案： 変更量は少ないが、命名の曖昧さが残るため不採用。

決定3: export 関数名は互換性優先で維持する

  • 決定内容

  • backupIndexJson、restoreIndexJson、restoreFromGit、cleanupBackup、getIndexFixture、registerIndexRoute は現状維持する。

  • 理由

  • 本変更の主目的は再配置と命名整理であり、API変更を伴うとレビュー範囲と回帰リスクが不必要に拡大する。

  • 呼び出し側の変更を import パス更新に限定できる。

  • 代替案

  • 関数名も同時リネームする案： 一貫性は上がるが、差分が増えて失敗時切り戻しが難しくなるため不採用。

決定4: 互換 shim は作らない

  • 決定内容

  • 旧 e2e-helpers/ に再エクスポート用の互換ファイルは残さない。

  • 理由

  • 一時的な互換層は二重構造を生み、再発防止より先送りを招く。

  • 参照元が限定されており、一括更新で安全に移行できる。

  • 代替案

  • 互換 shim を置く案： 段階移行は容易だが、不要な保守対象を増やすため不採用。

リスク / トレードオフ

  • [Risk]import 更新漏れにより Cannot find module が発生する

  • Mitigation: rg "e2e-helpers|fixture-manager|test-helpers" で残存参照を検出し、pnpm run test:e2e で実行確認する。

  • [Risk]パス固定の周辺スクリプトやドキュメントが古いまま残る

  • Mitigation: package.json、playwright.config.js、docs/ を検索し、必要な参照のみ更新する。

  • [Trade-off]関数名を維持するため命名統一はモジュール名中心になる

  • Mitigation: 影響最小で再配置を完了し、関数名の再命名は別 change で要否判断する。

移行計画

  1. e2e/helpers/ ディレクトリを作成する。
  2. e2e-helpers/ 配下ファイルを git mv で再配置・再命名する。
  3. e2e/*.spec.js、e2e/global-setup.js、e2e/global-teardown.js の import を新パスへ更新する。
  4. 参照残存チェック（rg）を実施する。
  5. pnpm run test:e2e を実行し、回帰がないことを確認する。

ロールバック方針： - 変更を1コミットに集約し、問題時は当該コミットを git revert して復旧する。

未解決事項

  • fixture-lifecycle.js と route-fixtures.js の命名妥当性を最終レビューで確定する。
  • 将来的に tests/ との共通ユーティリティ化を行うかは、利用実績が出た段階で別 change として判断する。