testing-criteria

name	testing_criteria
description	ロジックの変更とUIの変更に対するテスト戦略と基準を定義する。

テスト基準

開発スピードとアプリケーションの安定性のバランスを取るため、本プロジェクトでは的を絞ったテスト戦略を採用しています。

1. ビジネスロジックとデータ変換（単体テスト必須）

• 対象範囲: lib/, hooks/, types/, および複雑なAPIルートハンドラ内のファイル。
• ルール: 計算ロジック（例：価格計算、権限チェック等）やデータ変換ロジック（例：モックジェネレータ）を変更・追加する場合は、対応する単体テスト（Unit Tests）を必ず作成または更新しなければなりません。
• ツール: vitest を使用します。
• コマンド: コミットする前に npm run test を実行し、すべてのテストがパスすることを確認します。

2. UIコンポーネントとページ（視覚的QA必須、単体テストは非推奨）

• 対象範囲: components/ および app/ 内のファイル。
• ルール: 標準的なReactコンポーネントやページレイアウトに単体テストは不要です（複雑な独立したロジックを含む場合を除く）。その代わり、UIの変更は必ず視覚的に検証する必要があります。
• ツール: browser_subagent を使用します。
• アクション: UIを変更した後は、browser_subagent に指示して対象のページに移動し、新しい要素とインタラクション（ツールチップのホバー、該当セクションへのスクロール等）を行い、スクリーンショットをキャプチャします。
• ドキュメント化: 変更が視覚的に正しく機能していることを証明するため、これらのスクリーンショットは必ず walkthrough.md アーティファクトに埋め込んでください。

3. コミット前チェックとE2Eテスト（必須）

• 数式・ロジックを変更したか？ -> __tests__/*.test.ts を作成/修正し、npm run test を実行して確認する。
• UI要素のテスト追加・変更時 -> 【重要】 E2Eテスト（e2e/*.spec.ts）において、.locator('text=...') などのUI表示テキストに依存した要素検索は翻訳や文言変更に極めて弱いため禁止とします。必ず対象のコンポーネントに data-testid を付加し、getByTestId で検索してください。
• UIテキストや翻訳（辞書）を変更したか？ -> 文言変更によるテスト崩壊の心配は（data-testidを使っていれば）ありませんが、念のためPushする前にローカルで npm run test:e2e を実行し、全てパスするか検証すること。
• スタイリングやレイアウトを変更したか？ -> browser_subagent を実行し、スクリーンショットを撮影して確認する。
• すべてのコミットにおいて -> npm run lint と npm run typecheck を実行し、エラーが0件であることを確認する。

4. テストカバレッジ目標

• lib/ 配下の関数は最低限の単体テストを持つことを目標とします。
• __tests__/ にファイルごとのテストが存在しない場合、ロジック変更時にテストを追加します。
• テストファイルの命名規約: __tests__/[対象ファイル名].test.ts

5. テストの Source of Truth（最重要原則）

[!CAUTION] テストの期待値（アサーション）は「現在のコードの挙動」ではなく「blueprint.md / README.md の仕様」から導出すること。

禁止パターン: コードからの逆引きテスト

// ❌ 危険: 「コードがこう動いているから、これが正しい」
const data = await db.getCreatorData('any-id');
expect(data.supporters.length).toBeGreaterThan(0); // ← コードを見て書いた期待値

正しいパターン: 仕様からの順引きテスト

// ✅ 安全: blueprint.md の仕様「非デモIDは空データで開始」から導出
const data = await db.getCreatorData('any-id');
expect(data.supporters).toHaveLength(0); // ← 仕様書から書いた期待値

テスト作成前のチェックリスト

1. このテストの期待値は、どの仕様書のどの記述に基づいているか？
2. 仕様書に該当する記述がない場合 → テストを書く前にユーザーに仕様を確認する
3. 既存テストを修正する場合 → 元のテストが間違っていたのか、コードが間違っていたのか、両方を検討する

6. AIネイティブTDDフロー（仕様→テスト→実装）

[!IMPORTANT] 実装の前にテストの「期待値」を仕様から確定させる。これにより、AIが仕様にない挙動を勝手に実装し、それを"正解"としたテストを書いてしまう問題（トートロジー）を防ぐ。

正しい順序

1. Architect が仕様を blueprint.md に起案する
2. Documenter がテストシナリオ（アサーション条件のみ）を blueprint.md に先行言語化する
3. ユーザーに仕様+テストシナリオをレビューしてもらい合意を取る
4. 合意後にテストコード→実装の順で進める

禁止フロー

実装 → テスト（コードを見て期待値を書く）← トートロジーの温床

7. コンテキストの維持（Re-anchoring）

LLMはコンテキストが長くなると中間の指示を忘却する（Lost in the Middle）。以下のタイミングでスキルファイルを再読み込みし、重要ルールをリフレッシュする：

• タスク開始時: AGENTS.mdのトリガーテーブルから該当スキルを再読み込み
• コミット直前: core_commit_standard と core_testing_criteria を再読み込み
• バグ修正時: core_bug_fix_protocol を再読み込み

8. テスト内の環境変数操作

テストで環境変数を操作する際は、vitest の vi.stubEnv() / vi.unstubAllEnvs() を必ず使用する。process.env への直接代入は禁止。

// ✅ 正しい
beforeEach(() => {
  vi.stubEnv('NEXT_PUBLIC_USE_MOCKS', 'true');
});
afterEach(() => {
  vi.unstubAllEnvs();
});

// ❌ 禁止（テスト間で環境変数がリークする）
process.env.NEXT_PUBLIC_USE_MOCKS = 'true';

理由: process.env の直接代入はテスト間で状態がリークし、テスト実行順序に依存した不安定なテスト（Flaky Test）の原因となる。