SpecDojo Handbook

日本語

English

日本語

English

Appearance

外部結合テスト設計 全体構成 作成ルール ​

本ドキュメントは、外部結合テスト設計のうち 全体構成（etd-index） を統一形式で記述する標準ルールです。 etd-index は、外部結合テスト仕様（ETS）で定義された保証観点・代表条件を、テスト実装へ落とし込むための 共通設計方針（テスト単位/ケース分解/環境・接続/データ/実行/判定） と、個別設計（etd-<term>）への 入口（ナビゲーション） を提供します。

個別設計（etd-<term>）の記述ルールは etd-rules.md で定義します。

0. 位置づけ（必読） ​

ETD は「仕様」と「実装」の橋渡しとなる設計成果物です。

plaintext
TSP（テスト戦略・方針）
 └ ETS（外部結合テスト仕様・全体）
    └ ETS-D（外部結合テスト仕様・個別）
       └ ETD（外部結合テスト設計） ← 本書
          └ テスト実装・実行（JUnit / Newman / CI 等）
観点ETS / ETS-DETD
役割何を保証するかどうやって確認するか
主眼契約・境界・運用テスト構成・切り方・実行方法
ケース代表条件のみケース構造を設計
実装言及しない参照先を明示

1. 全体方針 ​

  • ETD は 外部結合テストの実行設計書です。
  • 「ケース一覧表＝設計」ではありません。
  • 実装コード（JUnit / Postman / スクリプト等）を直接貼ることは原則禁止です。
  • ETD の責務は以下です。
    • テスト単位の定義
    • ケース分解の軸（振る舞い × 状態 × 障害）
    • テスト環境・外部接続方式の切り替え方
    • 実行・自動化・エビデンス取得方法

2. 対象と粒度 ​

対象 ​

  • 外部結合テスト全体（ets-index に対応）
  • または、複数の ETS-D（外部連携群）を束ねた設計

粒度の原則 ​

  • ETD = 外部結合テストの共通設計
  • 個別外部システムごとの差分は、次段の ETD-D（個別設計） に委譲します。

3. ファイル命名・ID規則 ​

ファイル名（推奨） ​

sh
020-外部結合テスト設計.md

Frontmatter ​

項目ルール
idetd-index
typetest
title外部結合テスト設計: 全体構成
statusdraft / ready / deprecated

4. 推奨 Frontmatter 項目 ​

Frontmatter は共通スキーマに従います（あわせてメタ情報ルールも参照）。

項目説明必須
idetd-index（固定）○
typetest 固定○
title外部結合テスト設計: 全体構成○
statusdraft / ready / deprecated○
part_of[]（etd-index 自身は親なので通常は空配列）任意
based_on根拠となる仕様ID（ID配列。未指定時は [] を許容）任意
supersedes置き換え関係（ID配列。未指定時は [] を許容）任意

5. 本文構成（標準テンプレ） ​

ETD は以下の見出しを 必ずこの順序で記述します。

  1. 概要
  2. 対象範囲
  3. テスト単位の設計
  4. ケース分解ポリシー（観点 × 条件 → 期待結果）
  5. テスト環境・外部接続設計
  6. テストデータ設計方針
  7. 実行・自動化方針
  8. 結果確認・エビデンス取得方法
  9. 個別設計一覧（統合表）
  10. 対象外
  11. メモ / 将来課題

6. 記述ガイド詳細 ​

6.1 概要 ​

  • 本 ETD が どの外部結合テストを対象とするかを明確にします。
  • ETS / ETS-D との対応関係を文章で示します。

例:

本設計は、外部結合テスト仕様（ets-index）および決済サービス連携に関する個別仕様（ets-payment）に基づき、外部結合テストの設計方針を定義する。

6.2 対象範囲（必須） ​

推奨（表） ​

項目内容
対象外部連携決済、仕入先
対象仕様ets-payment, ets-supplier
テストレベル外部結合テスト
実行環境結合 / システム

6.3 テスト単位の設計（必須） ​

どの単位でテストを分割するかを定義します。

例:

テスト単位説明
連携単位外部API / Webhook / ファイル
パターン単位正常 / 例外 / 冪等 / 障害
業務単位発注 / 決済 / 取消

※ クラス名・関数名は禁止。論理単位で記述します。

6.4 ケース分解ポリシー（観点 × 条件 → 期待結果）（最重要） ​

外部結合のケース設計は 内部結合よりも障害軸を重視します。

推奨整理 ​

軸内容
振る舞い正常 / 契約逸脱 / 例外
障害タイムアウト / 5xx / 4xx
冪等再送 / 重複
運用手動復旧 / 再実行

ポイント:

  • ケースは「観点（保証）× 条件（状態）→ 期待結果」で表現する。
  • 「×」は網羅的な直積（全組合せ）の意味ではありません。代表条件を選び、採用理由（境界値、障害種別、運用上の重要度など）が追えるようにします。
  • 全組合せは作らない
  • ETS-D で定義した「保証観点」を必ず網羅する

6.5 テスト環境・外部接続設計（必須） ​

外部結合では 環境差異が最重要です。

項目方針
接続方式実接続 / スタブ / モック
環境切替設定値で切替可能
本番限定代替試験 or 運用リハーサル

6.6 テストデータ設計方針 ​

観点方針
データ生成テスト用データ
ID相関IDを必須
再実行冪等キー利用

6.7 実行・自動化方針 ​

項目方針
実行自動（CI）
ツールPostman / JUnit / 専用ツール
実行頻度nightly / release前
失敗時手動確認

6.8 結果確認・エビデンス取得方法 ​

観点エビデンス
応答リクエスト/レスポンス
再送再送履歴
冪等状態不変
追跡相関IDログ

6.9 個別設計一覧（統合表）（必須） ​

運用上の更新漏れを防ぐために、ETS と ETD（個別）を対応づけてリンクで辿れる対応表を 1 表に統合し、ここを単一ソース（Single Source of Truth）とします。

推奨の表（例）:

ETS（根拠）個別設計（ETD）コメント
ets-paymentetd-payment決済（外部API）の代表ケース設計
ets-supplieretd-supplier仕入先（外部ファイル）の代表ケース設計

※ 本ルール文書ではデッドリンク防止のため、例のリンクを本ファイル（自己参照）にしています。 ※ 実運用では、ETS 側は対応する ets-<term>、ETD 側は対応する etd-<term> の実ファイルへリンクしてください（実ファイル名・配置はプロジェクトに合わせます）。

6.10 対象外 / 除外理由 ​

  • 外部サービス内部処理
  • SLA 違反検証（契約対応）

6.11 メモ / 将来課題 ​

  • 外部仕様変更検知
  • 本番検証の自動化検討

7. 禁止事項 ​

項目理由
秘密情報の記載（APIキー/トークン/個人情報）セキュリティ/コンプライアンス
リクエスト/レスポンスの全文貼付秘匿/可読性/保守性の問題（要点＋マスクで記載）
SQL/JSON/ログの貼付（全文）実装依存・可読性低下
実装クラス名/テストコード全文の貼り付けドキュメントの役割外、変更に弱い
値の総当たり・ケース値の全列挙保守不能、意図が伝わらない
未定義のメタ情報プロパティ追加（例: tests）スキーマ違反（additionalProperties: false）

8. サンプル（最小） ​

yaml
---
id: etd-index
type: test
title: 外部結合テスト設計: 全体構成
status: draft
part_of: []
based_on:
  - ets-index
  - ets-payment
  - tsp-overview
supersedes: []
---

9. 生成AI向け指示テンプレート ​

  • 以下のルールに従って 外部結合テスト設計（ETD / ETD-D） を 1 ファイル作成してください。出力は Markdown。
  • 入力は ETS（ets-index と必要に応じて主要な ets-<term>）とします。
  • etd-index は共通方針・共通基準・ナビゲーションのみ（個別の大量ケースや具体値は書かない）。
  • etd-<term>（個別設計）を作る場合も、値の詳細・秘密情報・リクエスト/レスポンス全文・テストコード全文は書かない（必要なら「境界値」「代表値」レベルで方針のみ）。
  • YAML Frontmatter の未定義項目は追加しない。