フロントエンドのテスト基盤構築計画

[KentaHizume]

はじめに

計画のための壁打ちの記録を残します。

モノレポのアプリ dressca-frontend に対して、
Vitest、Vitest のブラウザーモード、MockServiceWorker、Playwright、Playwright-cli を用いて、
・単体テスト：Vitest
・コンポーネントテスト：Vitest ブラウザーモード
・VRTテスト：Vitest
・E2E テスト：Playwright
・これらのCI/CDでの実行：GitHub Actions
による自動テスト環境を構築します。

テストの方針としては、 テスティングトロフィーを重視します。

どのような計画で構築を進めていくべきか、 GitHub issue として作成できるような形で計画を立案してください。

Claude Opus 4.6

Plan: dressca-frontend 自動テスト環境構築

テスティングトロフィー（静的解析 → 単体テスト → コンポーネント/統合テスト（最大比重） → E2E テスト）の方針に基づき、Vitest Browser Mode + Playwright + MSW による多層テスト環境を段階的に構築する。

現状

項目	状態
単体テスト (Vitest + jsdom)	✅ 導入済み（consumer: 7件, admin: 6件）
カバレッジ (@vitest/coverage-v8)	✅ 導入済み
MSW モック	⚠️ admin のみ Node セットアップあり。consumer はブラウザのみ
Cypress	⚠️ 導入済みだが example テストのみ
CI (GitHub Actions)	✅ lint + type-check + build + unit test
Vitest Browser Mode	❌ 未導入
Playwright	❌ 未導入
VRT	❌ 未導入

---

Issue #1: [基盤] Vitest ブラウザーモードの導入と設定

概要: コンポーネントテスト・VRT の基盤として @vitest/browser を導入する。

作業内容:

1. パッケージインストール（consumer, admin 両方）: @vitest/browser, playwright
2. ルートに vitest.workspace.ts を作成し、4 プロジェクト定義:
   • consumer:unit / admin:unit — jsdom 環境（既存テスト）
   • consumer:browser / admin:browser — Playwright chromium 環境
3. 各アプリの vitest.config.ts を更新してブラウザー設定追加（browser.provider: 'playwright', browser.instances: [{ browser: 'chromium' }]）
4. tsconfig.vitest.json に @vitest/browser 型定義追加
5. テストファイル命名規約: 単体 *.spec.ts（既存）、コンポーネント *.browser.spec.ts、VRT *.vrt.spec.ts
6. vitest.setup.browser.ts 作成（MSW setupWorker 用セットアップ）
7. package.json に test:component, test:vrt スクリプト追加

関連ファイル:

• vitest.config.ts — ブラウザーモード設定追加
• vitest.config.ts — 同上
• tsconfig.vitest.json — 型定義追加
• tsconfig.vitest.json — 同上
• ルート package.json — ワークスペーススクリプト追加

---

Issue #2: [基盤] Playwright の導入と E2E テスト環境構築

概要: Cypress に代わる E2E テストフレームワークとして @playwright/test を導入する。

作業内容:

1. @playwright/test をインストール
2. 各アプリに playwright.config.ts を作成:
   • webServer で npm run mock を自動起動（MSW モックモード）
   • baseURL: consumer → http://localhost:5173, admin → http://localhost:6173
   • testDir: './e2e'
   • projects: chromium（CI では firefox/webkit 追加可能）
   • retries: CI 環境では 2
3. 各アプリに e2e/ ディレクトリ作成
4. package.json に test:e2e, test:e2e:ui スクリプト追加
5. eslint.config.ts に Playwright テスト用ルール追加

関連ファイル:

• 新規: consumer/playwright.config.ts, admin/playwright.config.ts
• 新規: consumer/e2e/, admin/e2e/
• eslint.config.ts — Playwright ルール追加

---

Issue #3: [基盤] Consumer アプリの MSW Node セットアップ

概要: Consumer に node.ts と vitest.setup.ts の MSW サーバー起動を追加し、admin とのパリティを確保する。

作業内容:

1. consumer/mock/node.ts を作成（setupServer(...handlers) パターン、node.ts を参照）
2. vitest.setup.ts を更新: server.listen() / server.resetHandlers() / server.close() 追加（vitest.setup.ts を参照）
3. 既存テスト 7 件がすべてパスすることを確認

関連ファイル:

• 新規: consumer/mock/node.ts
• vitest.setup.ts — MSW サーバー起動追加
• index.ts — 既存ハンドラー（変更不要）

---

Issue #4: [テスト実装] コンポーネントテストの作成（Vitest ブラウザーモード）

前提: Issue #1, #3 完了

概要: テスティングトロフィーの最大比重であるコンポーネントテストを実ブラウザ上で実装する。

作業内容:

アプリ	対象コンポーネント	テスト観点
Consumer	CatalogView	カタログ表示、フィルタリング
Consumer	BasketView	カート操作、数量変更
Consumer	CheckoutView	注文フロー
Consumer	CarouselSlider	ユーザーインタラクション
Admin	ItemsView	一覧表示、ページネーション
Admin	ItemsAddView	アイテム追加フォーム、バリデーション
Admin	ItemsEditView	アイテム編集、削除確認モーダル
Admin	LoginView	認証フロー、ロールベース表示

テスト方針:

• MSW ハンドラー（既存の handlers）でバックエンド API をモック
• ユーザー視点のインタラクション（クリック、入力、ナビゲーション）をテスト
• 既存 jsdom テストとの役割分担: jsdom=ロジック中心、ブラウザーモード=統合動作中心

---

Issue #5: [テスト実装] VRT（Visual Regression Testing）の構築

前提: Issue #1 完了

概要: Vitest ブラウザーモードのスクリーンショット機能を活用し、UI の意図しない視覚的変更を検出する。

作業内容:

1. VRT 用設定: toMatchImageSnapshot() またはカスタムマッチャーの構成
2. ベースラインスナップショットの管理方針: .vrt-snapshots/ ディレクトリに格納、Git にコミット
3. VRT テスト作成:
   • Consumer: カタログ一覧、カート画面、チェックアウト画面
   • Admin: ログイン画面、アイテム一覧、アイテム追加/編集画面
4. test:vrt:update コマンドでスナップショット更新
5. 差分しきい値（許容差分率）の設定
6. .gitignore に差分画像出力ディレクトリを追加

---

Issue #6: [テスト実装] E2E テストの作成（Playwright）

前提: Issue #2 完了

概要: テスティングトロフィーの方針に基づき、最も重要なユーザーフローに絞って E2E テストを実装する。

作業内容:

アプリ	テストシナリオ
Consumer	カタログ閲覧 → カートに追加 → チェックアウト完了
Consumer	カート内商品の数量変更・削除
Admin	ログイン → アイテム一覧表示
Admin	アイテム追加 → 一覧で確認
Admin	アイテム編集 → 変更確認

テスト方針:

• MSW モックモード（npm run mock）でアプリ起動（バックエンド不要）
• Page Object Model パターンで構造化
• テスト間の独立性確保

---

Issue #7: [CI/CD] GitHub Actions ワークフローの更新

前提: Issue #4, #5, #6 完了

概要: 新テストタイプを既存 CI パイプラインに統合する。

作業内容:

1. 既存ワークフロー（samples-dressca-consumer-frontend.ci.yml, samples-dressca-admin-frontend.ci.yml）を更新:
   • npx playwright install --with-deps chromium ステップ追加
   • コンポーネントテスト実行ステップ追加
   • VRT テスト実行ステップ追加
   • E2E テスト実行ステップ追加
   • 各テスト結果を Job Summary に出力
2. Artifact アップロード:
   • Playwright HTML レポート
   • VRT 差分画像（失敗時のみ）
3. ワークフロー最適化:
   • 単体テスト + コンポーネントテスト + VRT → 並列実行可能
   • E2E → ビルド成功後に実行
   • paths フィルター更新（新テストファイル対応）

関連ファイル:

• .github/workflows/samples-dressca-consumer-frontend.ci.yml
• .github/workflows/samples-dressca-admin-frontend.ci.yml

---

Issue #8: [クリーンアップ] Cypress の削除

前提: Issue #6, #7 完了（Playwright E2E が CI で安定稼働）

概要: Cypress 関連の依存関係と設定をすべて削除する。

作業内容:

1. パッケージ削除: cypress, eslint-plugin-cypress, start-server-and-test
2. ファイル削除: cypress.config.ts（各アプリ）、cypress ディレクトリ（各アプリ）
3. tsconfig.node.json から cypress.config.* 参照削除
4. eslint.config.ts から Cypress ルール設定削除（pluginCypress インポート・設定）
5. package.json から Cypress スクリプト削除（test:e2e, test:e2e:ci, prepare）

---

依存関係と実行順序

Phase 1: 基盤構築（並列実行可能）
  Issue #1 (Vitest Browser Mode) ──┐
  Issue #2 (Playwright E2E 基盤)  ──┤
  Issue #3 (Consumer MSW Node)  ───┘

Phase 2: テスト実装（Phase 1 完了後、並列可能）
  Issue #4 (コンポーネントテスト) ── depends on #1, #3
  Issue #5 (VRT)                  ── depends on #1
  Issue #6 (E2E テスト)           ── depends on #2

Phase 3: CI/CD 統合
  Issue #7 (GitHub Actions)       ── depends on #4, #5, #6

Phase 4: クリーンアップ
  Issue #8 (Cypress 削除)         ── depends on #6, #7

技術判断

判断事項	決定	理由
Browser Mode プロバイダー	Playwright	E2E ツールと統一、エコシステムの一貫性
VRT アプローチ	Vitest + toMatchImageSnapshot	追加ツール不要、Vitest エコシステム内で完結
E2E の API モック	MSW モックモード（npm run mock）	既存のモックハンドラーをそのまま活用
テスト比重	コンポーネント > 単体 > E2E > VRT	テスティングトロフィーに準拠

さらなる検討事項

1. コンポーネントテストで @testing-library/vue を採用するか？ — 現状は @vue/test-utils を使用中。ブラウザーモードでは @testing-library/vue のユーザー中心のアプローチがテスティングトロフィーとより親和性が高い。推奨: ブラウザーモードのコンポーネントテストには @testing-library/vue を新規採用し、既存 jsdom テストはそのまま維持

2. VRT のスナップショットを OS 間で安定させるための対策 — フォントレンダリングの差異により、ローカル (Windows) と CI (Ubuntu) で VRT が不安定になる可能性がある。推奨: VRT のベースライン生成・比較は Docker コンテナまたは CI 環境のみで実施し、ローカルでは test:vrt:update を手動実行するフローとする

3. Playwright E2E テストの対象ブラウザー数 — テスティングトロフィーでは E2E は最小限が望ましい。推奨: CI では chromium のみ、必要に応じて firefox/webkit を段階的に追加

[KentaHizume]

Codex5.3

レビュー結果（Findings 優先）

1. High: VRT 実装案の技術前提が曖昧

• 計画では「Vitest で VRT」「toMatchImageSnapshot ベース」となっていますが、Vitest Browser Mode でどの API/ matcher を標準採用するかが未確定です。
• ここが曖昧なまま進むと、Issue サンプルAPの実行までの流れをチュートリアルで示したクイックスタートのドキュメントを作成する #5 で実装方式の再設計が発生し、スケジュール遅延の可能性が高いです。
• 対応案: Issue 利用規約を記載する #1 の完了条件に「最小 VRT PoC（1画面、CI で再現可能）」を追加し、Issue サンプルAPの実行までの流れをチュートリアルで示したクイックスタートのドキュメントを作成する #5 着手前に方式を確定。

2. High: 「Playwright-cli」要件の明示が不足

• ユーザー要件に Playwright-cli が含まれていますが、計画では実質的に Playwright 本体の導入に留まっており、CLI 運用方針（codegen, show-report, trace viewer, install 手順）が不足しています。
• 対応案: 専用 Issue を追加して、CLI コマンド体系・運用ルール・CI 連携（report/trace artifact）を明文化。

3. High: Cypress 廃止のゲート条件が弱い

• 削除 Issue はありますが、移行完了判定の定量基準（同等シナリオ網羅、一定期間の安定稼働、失敗率閾値）が不足しています。
• 先に削除すると、E2E カバレッジが一時的に低下するリスクがあります。
• 対応案: 「2週間連続で Playwright CI 安定」「旧 Cypress 主要シナリオの 100% 置換」を削除前提に追加。

4. Medium: テスティングトロフィー準拠の“比率”が定量化されていない

• 方針は正しいですが、単体・コンポーネント・E2E の目標配分がないため、実装時に E2E 過多や単体過多になりやすいです。
• 対応案: 例として「新規 UI 機能はコンポーネントテスト必須、E2E はクリティカルパスのみ」などの判定基準を Definition of Done に追加。

5. Medium: CI 実行時間増大への対策が弱い

• テスト種別増加に対し、並列化以外の対策（キャッシュ最適化、sharding、changed-path ベースの実行制御）が不足しています。
• 対応案: CI Issue に「目標所要時間（例: PR あたり 15 分以内）」と、超過時の打ち手を追加。

6. Medium: consumer 側 MSW Node 追加は妥当だが、既存モック方針との整合ルールが必要

• browser モックと node モックの責務分担（どのテストでどちらを使うか）を明文化しないと、テスト実装者ごとに揺れます。
• 対応案: テストガイドライン Issue（短い運用規約）を追加。

---

Open Questions / Assumptions

1. VRT は CI 環境のみを正としてベースライン管理する前提でよいか。
2. Playwright の対象ブラウザは初期段階で Chromium のみに限定してよいか。
3. E2E で MSW モック中心運用にするか、将来的に実バックエンド接続ジョブを別途設けるか。

---

総評

• 計画全体はかなり妥当で、段階分割・依存関係・移行順序も良いです。
• ただし、実行時に詰まりやすいポイントは「VRT 方式確定」「Playwright-cli 明文化」「Cypress 廃止ゲートの定量化」です。
• ここを先に補強すれば、実装フェーズでの手戻りは大きく減らせます。

必要なら次のステップとして、上記 3 点を反映した「Issue テンプレート文面（そのまま起票できる版）」を作成します。

[KentaHizume]

テストの理論

• フォルダーとテスト手法を対応付ける。
• テスティングトロフィー
  • コンポーネントテストをたくさんしましょう
  • 結合テストという概念がフロント側と相性よくないのかも

単体テスト（Vitest(jsdom)）

• バックエンドに比べて重要ではない、components に対しては基本やらない
• ロジックに対して実施
  • composables
  • services
• mock を使う。 msw でも vi.mock でもよい
  • vi.mock のほうが楽か
  • axios interceptor 周りだけは msw のほうが都合がよくはある

結合テスト（コンポーネントテスト）（ Vitest /Vitest Browser ）

• バックエンドに比べて重要（テスティングトロフィー）
• Vitest (jsdom) か、 Vitest (browser) かの判断がむずかしい
• インタラクションがあるものは browser
• 実アプリはjsodmではなくブラウザで動くので全部 browser で走らせたほうがもちろんベターだが、そうすると特に品質向上につながらないのに遅くなる、というトレードオフがある

VRT（Vitest）

• views の画面単位でやる

E2E（Playwright）

• （重要な）ユースケース単位でやる

カバレッジ指標

• ロジック
  • 計測できる、バックエンドと同じくらいほしい
• コンポーネント
  • 計測できる、バックエンドほどいるのか？は微妙
• ユースケースの網羅率
  • 要件と照らし合わせて計測、CI で数字は取れないが
  • Spec 駆動とかだとレビュー観点になるかも