frontend-review-testing

フロントエンドレビュー — テスト

フロントエンドプロジェクトのテスト体制を監査します。フェーズは第 2 週です。合成カバレッジを用いて vitest と playwright を導入します。次の点に留意してください。

• E2E の粒度：最初は Router／サーバーコントローラーの分岐ごとに 1 ケース（網羅性よりも、まず骨組みを整えることを優先します）。
• ユニットテストの粒度：コンポーネントのカバレッジを優先します。
• カバレッジの統合：vitest V8 と playwright V8 を monocart-coverage-reports または istanbul-merge で統合します。

手順

1. scripts/audit-coverage.sh --repo <client-repo> を実行します。
2. coverage/coverage-summary.json が存在する場合は読み込みます。
3. 次の項目を調査します。
   • vitest.config.* — カバレッジは設定されていますか？プロバイダーは v8 ですか？
   • playwright.config.* — projects、webServer、sharding
   • tests/、e2e/、__tests__/ — 現在のテスト数と構成
   • package.json の scripts — test、test:coverage、test:e2e

出力

<client-repo>/.frontend-review/report/latest/md/testing-review.md に、次の内容を記載します。

• 現在の状態：vitest は設定されていますか？playwright は設定されていますか？テストはいくつありますか？カバレッジは何％ですか？
• 不足点：設定の不足、スクリプトの不足、カバレッジの未統合
• 推奨 PR（最大 3～5 件）：それぞれのタイトル、対象ファイル、期待されるカバレッジの増加量
• 分岐カバレッジのチェックリスト：最初の E2E テストで対象にすべき Router／コントローラーの分岐

コンポーネントテスト — Testing Library を優先

React コンポーネントのテストでは、内部実装のテストよりも @testing-library/react を優先します。

• クラス名やコンポーネントの内部ではなく、ロール／ラベル／テキストでクエリします（getByRole、getByLabelText、getByText）。
• ユーザー操作には @testing-library/user-event の userEvent.click、userEvent.type を使用し、DOM イベントを直接ディスパッチしないでください。
• 非同期処理後の状態更新のアサーションには、waitFor／findBy* を使用します。

// Bad: testing implementation details
const wrapper = render(<LoginForm />);
wrapper.find('button.submit').simulate('click');
expect(wrapper.state('isLoading')).toBe(true);

// Good: testing observable behaviour
render(<LoginForm />);
await userEvent.type(screen.getByLabelText('Email'), '[email protected]');
await userEvent.click(screen.getByRole('button', { name: /sign in/i }));
expect(await screen.findByText('Welcome')).toBeInTheDocument();

@testing-library/react が package.json にない場合は、不足点として指摘し、@testing-library/user-event と @testing-library/jest-dom（または @testing-library/vitest-dom）と併せて追加することを推奨します。

atom／ストアのテストには、コンポーネントをレンダリングするのではなく、ライブラリ独自のテストユーティリティ（例：Jotai の createStore()）を使用します。コンポーネントテストと状態ロジックのテストは分けてください。

ソース内テストのパターン

ロジックの多い .ts ファイルでは、テストを同じファイル内に配置する方法（Vite プロジェクトでの if (import.meta.vitest)、またはビルド時に同等のデッドコード除去を行う方法）が、別ファイルに分けるより適していることがよくあります。

• AI エージェントがソースと仕様を 1 つのファイルのコンテキストで読み取れるため、生成の精度が向上します。
• 純粋関数を、その不変条件の近くに保てます。
• "import.meta.vitest": "undefined" define によって、本番ビルドではテストブロックが除去されます。

ユーティリティ／lib ファイルに新しいユニットテストを提案する場合は、このパターンを推奨してください。

テスト失敗のトリアージ手順

テストが失敗したとき、機械的にテストを書き換えて通すのは正しい対応ではありません。人間に、次のどれに該当するか判断してもらいます。

1. 仕様が変更された — 実装が正しくなったため、テストを更新します。
2. 実装にバグがある — テストは正しいため、実装を修正します。
3. テストが誤っていた — テストが意図した仕様に合致していなかったため、テストを書き直します。

このトリアージを出力レポートに記録してください。「実装の反映」にとどまるテスト（観測可能な動作ではなく、内部の処理経路そのものをテストしているもの）が既存テストにあれば、ケース 3 の候補として指摘してください。

MSW（Mock Service Worker）の原則

コードベースが外部 API を呼び出す場合は、jest 形式のモジュールモックよりも MSW を推奨します。

• モックするのはネットワーク境界のみです（http.get、http.post のハンドラー）。
• 実際の状態管理とコンポーネントの接続は維持し、HTTP レスポンスだけをスタブ化します。
• 共通ハンドラーは src/test-utils/handlers.ts または同等の場所に配置します。

これにより、統合契約が壊れていてもテストが通ってしまう事態を避けられます。

カバレッジの指針

• 目標：純粋な lib／ユーティリティファイルでは80％以上、UIコンポーネントでは60％以上です。
• 避けること：100％に到達するためにテストを水増ししないでください。実装の詳細を列挙するだけのテストを増やすより、実際の仕様を反映した少数のテストを優先してください。
• 生成されたUIコンポーネント（shadcn/uiの出力など）は、カバレッジの対象外です。

VRTの安定性に関するヒント

• マシン間でのフォント描画やアンチエイリアスの差をなくすため、（CIと同じOSである）Linuxコンテナ内で参照スナップショットを生成してください。
• フォントが使用できないとピクセル差分の誤検出が発生するため、Webフォントはテストごとではなく、共有フィクスチャを通じてグローバルに読み込んでください。

境界

• 実際のテストコードは書かず、構成と数のみ提案してください。
• このスキルから vitest や playwright を実行しないでください。スクリプトはテストを実行せず、既存のレポートを読み取るだけです。

参考資料

• チェックリスト：07-unit-test.md、08-e2e-playwright.md、15-vrt.md、13-kpi-tracking.md
• フェーズ：week-2-testing.md、week-3-security-vrt.md