backend-testing

バックエンドテスト

このスキルは、パケット優先のバックエンドテストルーターとして使用します。

目的は、あらゆるフレームワーク向けの定型コードを大量に提示することではありません。目的は次のとおりです。

1. リクエストを適切なバックエンドテストパケットに分類する
2. 信頼できる最小限のテストレイヤーの組み合わせを選ぶ
3. 依存関係の実環境への近さとデータ制御を明確にする
4. ローカル、PR、時間のかかるレーンを適切に分ける
5. 実際の作業がポリシー、契約の形状、認証実装である場合は、そちらへ振り分ける

必要に応じて、次を参照してください。

• references/intake-packets-and-route-outs.md
• references/test-layer-matrix.md
• references/stability-checklist.md

このスキルを使用する場面

• API、サービス、リポジトリ、ワーカー、インテグレーション、認証フローのバックエンドカバレッジを追加または修正する
• バックエンドの変更にユニット、インテグレーション、コントラクト/API、または限定的なスモークテストが必要か判断する
• フィクスチャ、ファクトリー、シード／リセット、認証のブートストラップ、環境制御の戦略を設計する
• モック、フェイク、コンテナ、実際の依存関係のどれを使うか判断する
• 不安定なバックエンドテストスイート、特にCIのみで発生する失敗やローカルとCIの差異を安定させる
• バックエンドテストスイートが広すぎる、遅すぎる、モックに依存しすぎている、または重要なレイヤーが欠けているかをレビューする

このスキルを使用しない場面

• 主な作業が組織全体のテストポリシー、ゲート設計、リリースの証跡、または全社的なQAの考え方である場合 → testing-strategies を使用する
• テストを誠実にスコープできるようにする前に、API契約の形状、バージョニング、スキーマ設計が主な作業となる場合 → api-design を使用する
• テストではなく、認証／セッション／プロバイダーの動作実装が主な作業である場合 → authentication-setup を使用する
• 主な作業がフロントエンド／ブラウザーテストまたはUIワークフローのカバレッジである場合
• 具体的なバックエンドの動作や回帰対象がまだない場合。この場合、テスト計画が確定したかのように扱うのではなく、まず不足している動作パケットを定義する

手順

ステップ 1：リクエストを 1 つのパケットに分類する

アドバイスを提示する前に、最適なエントリーパケットを 1 つ選びます。

パケット

• coverage-plan — 具体的なバックエンド変更にどのレイヤーを追加するか
• fixture-and-reset-plan — データ／認証状態をシード、分離、リセット、またはブートストラップする方法
• contract-and-api-checks — インターフェースがすでに存在する場合に、レスポンス／イベント／スキーマの互換性を保護する方法
• flake-stabilization — CIのみで発生する、または断続的に発生するバックエンドの失敗を安定させる方法
• execution-lane-split — ローカルで高速に実行するチェック、PR、夜間、リリース限定のバックエンドチェックを分ける方法

リクエストに複数の懸念事項が含まれる場合は、主パケットと副次的な懸念事項を 1 つ示します。

ステップ 2：バックエンドの対象範囲とリスクを明確にする

必要最小限の有用なコンテキストを把握します。

• 対象：エンドポイント、サービス、リポジトリ、ワーカー、キューコンシューマー、認証フロー、インテグレーション、またはマイグレーション
• 最もリスクの高い動作：検証、権限、永続化、再試行、冪等性、順序付け、シリアライズ、副作用、互換性
• すでに存在するカバレッジ
• 関連する外部依存関係：DB、キャッシュ、キュー、メール、決済、サードパーティAPI、IDプロバイダー、ファイルシステム
• ランタイム／言語スタック
• 証跡を維持する必要がある場所：ローカル実行、PR CI、スケジュールされたCI、リリーススモーク

リクエストが曖昧な場合は、最初に保護する価値のある最小の回帰範囲を選びます。

ステップ 3：適切なテストレイヤーを選ぶ

パケットとリスクに基づいて、信頼できる最も軽量なレイヤーの組み合わせを選びます。

ユニット／サービス

主なリスクが分岐ロジック、検証、オーケストレーション、または純粋に近いビジネスルールである場合に優先します。

インテグレーション

データベースの動作、フレームワークの配線、ミドルウェア、トランザクション、キュー、キャッシュ、またはシリアライズが重要な場合に優先します。

コントラクト／API

クライアントがレスポンスの形状、ステータスコード、スキーマ、またはイベントに依存しており、インターフェースがすでに存在する場合に優先します。

スモーク／選択的なエンドツーエンド

リリース上重要な一連の処理が複数のバックエンド境界をまたぎ、下位レイヤーでは中心的なリスクを検出できない場合に限り、優先します。

対象範囲、対象外、その理由を明示します。

Step 4: 依存関係の現実性を意図的に決める

依存関係ごとに、次のいずれかを選びます。

• モック／スタブ — テスト対象の動作に対して、コストが高い、不安定、または無関係なもの
• フェイク／シミュレーター — 動作は重要ですが、軽量な代替手段で十分なもの
• コンテナー化した実際の依存関係 — クエリ、マイグレーション、メッセージのセマンティクス、またはワイヤー上の動作が重要で、差異が問題になるもの
• 共有外部環境 — 避けられない場合のみ使用し、脆弱性のコストを明示します

適切なデフォルト：

• リポジトリー、マイグレーション、トランザクション、またはシリアライゼーションの動作が中心となる場合は、実際の DB の動作を優先します
• 統合コントラクト自体がテスト対象でない限り、外部向けのサードパーティ API にはモックを優先します
• PR ごとにすべての依存関係を用意する巨大な構成より、範囲を絞ったコンテナー化を優先します
• 本番環境との一致がリスクのすべてである場合、フェイクと実際の依存関係が同等だと主張してはいけません

Step 5: フィクスチャー、データ、認証、環境の制御を定義する

状態が曖昧なバックエンドテストスイートは、信頼性を失います。

以下を明確にします。

• フィクスチャー／ファクトリーの方針
• シード／リセット／ロールバックの計画
• ユーザー、ロール、テナント、トークン、セッション向けの認証／ブートストラップ用ヘルパー
• 必要に応じた時間／乱数／冪等性の制御
• 分離ルール：テストごと、ファイルごと、テストスイートごと、または環境ごと
• 失敗時に取得するデバッグ情報

テストスイートが実行順序、残存データ、またはスリープに依存する場合は、その脆弱性を明示してください。

Step 6: 実行レーンを分ける

ローカル、PR、時間のかかるレーンは、それぞれ別のジョブとして扱います。

以下を定義します。

• ローカル高速パス — 開発者が繰り返し実行するもの
• PR パス — マージの必須条件となるもの
• スケジュール実行／夜間パス — 対象範囲が広い、または現実性の検証にコストがかかるもの
• リリース／インシデントパス — 必要に応じた、範囲を絞った信頼性チェックや回帰防止策

テストスイートの実行に時間がかかる場合は、分割してください。どこでも実用的に使える、巨大で唯一の正式な実行パスがあるかのように装ってはいけません。

Step 7: バックエンドテストのパケットを1つ作成する

一般論の説明ではなく、簡潔なパケットを1つ返します。

推奨するパケット形式：

• coverage-plan → カバレッジ表＋依存関係の方針＋対象外項目
• fixture-and-reset-plan → フィクスチャー／リセットのメモ＋認証／ブートストラップの注意点
• contract-and-api-checks → 互換性パケット＋コンシューマー／プロバイダーの対象範囲＋適切な振り分け先
• flake-stabilization → 原因の候補、分離の修正、準備状況のチェック、デバッグ情報を含む不安定テストのメモ
• execution-lane-split → ローカル／PR／スケジュール実行／リリースの役割を示すレーン表

パケットに最低限含める内容：

• 変更箇所と主なリスク
• 選択したパケットと、関連する追加の懸念事項
• 選択したレイヤーとその理由
• 依存関係の現実性に関する判断
• フィクスチャー／データ／認証／環境の制御
• 実行レーンの分割
• 依頼の一部が別の担当範囲に属する場合の、明確な振り分け先

Step 8: 最終化する前にスコープの境界を確認する

以下を確認します。

• パケットは、一般的なカバレッジの見栄えではなく、実際のバックエンドの回帰リスクを防いでいますか？
• 組織全体の検証ポリシーを testing-strategies に委ねましたか？
• コントラクトの形状に関する判断は api-design に委ね、インターフェースが既に存在する場合に限り、コントラクトの保護をここで扱いましたか？
• 認証の実装作業を authentication-setup に委ねましたか？
• 依存関係をモック、フェイク、コンテナー化、または実際のものとして扱う理由を、メンテナーが理解できますか？

出力形式

## Backend Test Packet: [Surface or Change]

### Packet choice
- Primary packet: coverage-plan | fixture-and-reset-plan | contract-and-api-checks | flake-stabilization | execution-lane-split
- Secondary concern: optional
- Confidence: high | medium | low

### Change framing
- Surface: ...
- Main risks: ...
- Runtime: ...
- Existing coverage: ...

### Layer decisions
| Layer | In scope? | What it protects | Notes |
|------|-----------|------------------|-------|
| Unit / service | yes/no | ... | ... |
| Integration | yes/no | ... | ... |
| Contract / API | yes/no | ... | ... |
| Smoke / selective E2E | yes/no | ... | ... |

### Dependency realism
| Dependency | Strategy | Why |
|------------|----------|-----|
| Database / queue / cache | ... | ... |
| External API | ... | ... |
| Auth provider | ... | ... |

### Data and environment control
- Fixtures / factories: ...
- Seed / reset: ...
- Auth bootstrap: ...
- Isolation rule: ...
- Debug signals: ...

### Execution lanes
- Local-fast: ...
- PR CI: ...
- Scheduled / nightly: ...
- Release / incident: ...

### Route-outs
- `testing-strategies`: ...
- `api-design`: ...
- `authentication-setup`: ...

例

例 1: 認証を重視した API の変更

入力: 「Express API にリフレッシュトークンのローテーションと、管理者専用の新しいエンドポイントを追加しました。CI を巨大なエンドツーエンドテストスイートにすることなく、認証の失敗、トークンのリプレイ、DB の永続化に関するバグを検出できるバックエンドテストが必要です。」

適切な応答形式：

• メインのパケットとして coverage-plan を選択する
• 1つの巨大な E2E テストスイートではなく、ユニット／サービステストと統合／API テストを組み合わせる
• トークン／セッションの動作が重要な箇所では、実際の DB またはコンテナー化した永続化を使用する
• 認証のブートストラップ用ヘルパーとリセット方法を定義する
• スモークテストを、リリースに不可欠な狭い範囲に絞る

例 2：サービススイートで CI のみ発生する不安定なテスト

入力：「FastAPI のテストはローカルでは通りますが、CI では Postgres のシード状態やバックグラウンドジョブに関連して失敗します。安定化計画を提案してください。」

望ましい回答の形：

• flake-stabilization を主要パケットとして選択する
• シード／リセットの不整合、準備完了の確認、非同期処理のタイミング、または残存状態を原因候補として挙げる
• 単に再試行するのではなく、より強い分離、準備完了チェック、デバッグ用シグナルを推奨する
• ローカルで高速に実行する場合と、CI で正式に検証する場合の動作を明確に分ける

例 3：API の提供開始後のコントラクト保護

入力：「決済サービスと Webhook コンシューマーで、レスポンスフィールドの不整合が続いています。API の再設計は必要なく、互換性の低下を検出するバックエンドテストが必要です。」

望ましい回答の形：

• contract-and-api-checks を主要パケットとして選択する
• インターフェースはすでに存在するため、ここでコントラクト保護を行う
• スキーマの再設計やバージョニングに関する議論は api-design に引き継ぐ
• スモークテストをむやみに拡充するのではなく、コンシューマー／プロバイダー間のテストやスキーマ互換性のテストを推奨する

例 4：範囲が広すぎるポリシーに関する依頼

入力：「フロントエンド、バックエンド、モバイル、QA を対象とした、エンジニアリング組織全体のテスト戦略を設計してください。」

望ましい回答の形：

• 主なタスクは testing-strategies に属すると認識する
• バックエンド固有の助言は、引き継ぎとしての範囲にとどめる
• backend-testing を汎用的な QA ガバナンススキルにしない

ベストプラクティス

1. フレームワークではなく、パケットを起点にする。
2. カバレッジ率を追いかける前に、実際に発生するバックエンドのリグレッションリスクに備える。
3. 巨大で壊れやすいエンドツーエンドテストスイートより、階層化されたバックエンドのテストを優先する。
4. フィクスチャ、シード、認証のブートストラップ戦略を明確にする。隠れた状態が信頼を損なう原因になる。
5. ローカル高速実行、PR、定期実行、リリースの各レーンを意図的に分ける。
6. 通信上の動作が重要な場合は実際の依存関係を使う一方、コストの高いリアリティは適切な範囲に抑える。
7. 不安定なテストは、単なる煩わしさではなく、信頼に関わる問題として扱う。
8. ポリシー、コントラクトの形状、認証の実装に関する責任は、自ら取り込まず、適切な担当に引き継ぐ。

参考資料

• 実践的なテストピラミッド
• pytest：優れた統合プラクティス
• Testcontainers
• Pact ドキュメント
• GitHub Actions：Python のビルドとテスト