testing-excellence git:20261002.c0e127dA

Immutable. This exact content never changes and is served at /api/v1/blob/2c2d2eac3979f568.

---
name: testing-excellence
description: >
  アプリのテストはすべてこのスキルを使う。開発中のTDD（テストファースト）から、
  ユーザー目線のE2E・受入テスト、インフラ/デプロイ検証、リリース前の網羅テストまでを1つに統合。
  「テストを書いて」「テストして」「動作確認して」「TDDで進めて」「カバレッジを確認」
  「E2Eテスト」「リリース前にちゃんとテストしたい」「本番で動くか確認」「回帰テスト」
  などの文脈で必ず使用する。§0「適用段階」に従い、たたき台〜v1 では「壊れたら困る順」の最小テスト、
  固定化段階(v1 到達後のブラッシュアップ)ではユーザーがテストと明示しなくてもTDDサイクルを適用する。
  セキュリティ・コスト・パフォーマンスの監査は Skill launch-security を併用する。
---

# Testing Excellence — 開発中TDDからリリース前網羅テストまで

テストは「書いたコードの確認」ではなく「アプリがユーザーの目的を果たすことの証明」。
開発中はTDDで守り、リリース前は4層（ユニット→統合→E2E→インフラ/受入）で網羅する。

## 0. 適用段階（先に読む）

本スキルは mvp-first-development §9「たたき台 → 確認 → 固定化」と app-orchestrator 裁定ルール4に従って段階的に適用する。

| 段階 | 書くテスト | 本スキルの適用範囲 |
|---|---|---|
| たたき台〜確認（v0 まで） | 計算ロジック・パーサー・集計と、理由表示など「文言が出ること」の固定だけ | §4 のインフラ検証（デプロイ後のスモーク）のみ必須。§2 の TDD サイクルと §5 は使わない |
| v1 までに | 上に加え、最頻業務と必須業務フローの E2E を「壊れたら困る順」に最小本数 | §3 を最小本数で。カバレッジは v0・v1 いずれのゲートにもしない |
| 固定化（v1 到達後のブラッシュアップ） | OK が出た主要フローの回帰テスト。以後の新機能・バグ修正は §2 の TDD サイクル | §1〜§6 を全て適用。カバレッジ 80% はこの段階の目標 |

リリース可否は INV-5 の3判定だけで決まり、本スキルのチェックリスト（§5）は公開を止める理由にならない（`INVARIANTS.md`）。

## 1. テスト戦略の全体像（4層）

| 層 | 対象 | ツール | 目安 |
|---|---|---|---|
| ユニット | 関数・ユーティリティ・コンポーネント | Vitest/Jest | 多数・高速 |
| 統合 | APIエンドポイント・DB操作・認可 | Vitest + ローカルD1/モック | 主要API全部 |
| E2E（ユーザー目線） | クリティカルユーザーフロー | Playwright | 主要フロー3〜10本 |
| インフラ/受入 | 本番相当環境での実動確認 | curl・wrangler・実ブラウザ | リリース毎 |

ユニット・統合は `pnpm test`、E2E・受入は `pnpm run preview` で立てたローカル本番相当環境（既定は `http://localhost:8787`）に対して実行する。

カバレッジ目標は固定化段階で80%以上（§0）。ただし数字合わせより「壊れたら困る順」にテストする。

## 2. 開発中: TDDサイクル

新機能・バグ修正は必ずこの順で進める（詳細パターンは `references/tdd-and-patterns.md`）:

```text
1. RED    : ユーザージャーニーからテストケースを書く → 実行して失敗を確認
2. GREEN  : テストを通す最小実装
3. REFACTOR: テストが通ったまま整理（immutability・小さい関数）
4. 検証   : カバレッジ確認（固定化段階では80%+）
```

- テストは**ユーザーに見える振る舞い**を検証する。実装詳細（内部state・呼び出し回数）に依存させない。
- セレクタはセマンティック（role/label/text）を使う。CSSクラス依存は禁止。
- 各テストは独立させる（beforeEachでリセット。実行順依存禁止）。
- バグ修正はまず**再現テスト**を書き、失敗を確認してから直す。テストを直して逃げない（テスト自体が誤りの場合のみ修正）。
- モック方針・ファイル配置・CI設定も `references/tdd-and-patterns.md` 参照。

## 3. ユーザー目線テスト（E2E・受入）

- クリティカルフローを**ユーザーの言葉**でシナリオ化する（例:「ログイン→商品を検索→カートに入れ→注文確定→完了メールが届く」）。
- 実装は Playwright。`pnpm run preview` で本番相当のローカル環境を起動し、そのURLに対して実行する。ハッピーパスだけでなく:
  - 入力ミス時に**どう直せばいいか分かるエラー**が出るか
  - 二重送信・戻るボタン・リロードで壊れないか
  - 空データ状態（初回ユーザー）と大量データ状態の両方
  - モバイル幅（375px）での操作可能性（レスポンシブ崩れがないか。基準は Skill jp-web-design / ux-design）
- 受入基準は要件定義（app-excellence の手順ゲート）の「ユーザーができること」と1対1で対応させる。

## 4. インフラ・デプロイ検証（本番相当）

デプロイ後（またはプレビューURL）で必ず実行:

```bash
# スモークテスト: トップ・主要API・認証が生きているか
curl -sf "$ORIGIN/" -o /dev/null && echo "OK: top"
curl -s "$ORIGIN/api/health" | head -c 200
# SPA配信時: APIがフォールバックに横取りされていないか
curl -H "Accept: text/html" -H "Sec-Fetch-Mode: navigate" "$ORIGIN/api/me" | head -c 100
```

- [ ] D1 migrationが本番に適用済み（`wrangler d1 migrations list`で未適用ゼロ）
- [ ] Secretsが本番に存在する（値は表示しない。cloudflare-secure-deploy の手順）
- [ ] 認証フローの実動確認（許可ユーザー成功・拒否ユーザー失敗。better-auth-google-gate の受入テスト）
- [ ] `wrangler tail`でエラーログが出ていない
- [ ] 実ブラウザで主要フロー1周（Browserペインでの目視確認を含む）

## 5. 固定化段階の網羅チェックリスト（v1 到達後）

- [ ] ユニット・統合テスト全パス、カバレッジ80%+
- [ ] E2Eクリティカルフロー全パス（デスクトップ+モバイル幅）
- [ ] 回帰: 既存機能の主要フローが壊れていない
- [ ] エラー系: 不正入力・権限なし・404・ネットワーク断で適切な表示
- [ ] 空状態・ローディング状態・大量データ状態の表示確認
- [ ] インフラ検証（§4）全項目
- [ ] セキュリティ・コスト・パフォーマンス監査 → **Skill launch-security で GO 判定**

本チェックリストは固定化段階の品質目標であり、v0・v1 の公開可否は INV-5 の3判定（launch-security の段階別ゲートを含む）で決まる。未達項目は残課題リストへ記録する。

## 6. 報告形式

```text
テスト結果:
  ユニット/統合: X件 pass / Y件 fail（failの内容と対処）
  E2E: シナリオ別の結果
  カバレッジ: XX%
  インフラ検証: 各項目の実測結果（コマンド出力の要点）
未実施・未確認: 残っている事実だけを明示（「たぶん動く」で完了報告しない）
```

## 関連

- TDD詳細パターン・モック・CI・よくある失敗パターン: `references/tdd-and-patterns.md`
- ローカル本番相当環境の起動・デプロイ手順: Skill wrangler / cloudflare-secure-deploy
- セキュリティ・コスト・パフォーマンス: Skill launch-security