SpecDojo Handbook

日本語

English

日本語

English

Appearance

外部結合テスト仕様 全体構成 作成ルール ​

本ドキュメントは、外部結合テスト仕様のうち 全体構成（ets-index） を統一形式で記述するための標準ルールです。 ets-index は、上位方針（TSP/TPC 等）や外部I/F仕様（EAPIS/EMS/EFES/ESIL 等）で整理された観点・条件を「外部結合（契約・管理範囲外を含む連携）」の責務として解釈し、個別の外部結合テスト仕様（ets-<term>）へ分配するための 入口（ナビゲーション） になります。

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

ETS は「自システムと外部システム（契約・管理範囲外）との連携が、仕様どおり成立すること」を Markdown でレビュー可能な形に落とし込み、外部連携起因の障害・手戻りを最小化します。

ETS は「テストコード」ではありません。 また ETS は「個別の手順書」でもなく、何を外部連携の観点で保証するか（What） を明確にする文書です。

0. 位置づけ（内部結合との違い） ​

plaintext
TSP（テスト戦略・方針）
 ├ ITS（内部結合テスト仕様） … 自システム内部の連携
 └ ETS（外部結合テスト仕様） … 自システム ↔ 外部システムの連携  ← 本書
観点ITS（内部結合）ETS（外部結合）
対象自組織管理範囲内契約/管理範囲外の外部を含む
連携点内部API/内部イベント等外部API/外部メッセージ/外部ファイル等
検証の主眼連携の正しさ＋内部整合契約I/F遵守・境界条件・障害時挙動・運用性
依存の扱い内部は実、外は基本スタブ外部は実接続 or 検証環境（条件を明文化）
エビデンスCIログ中心外部側の応答・監査・再送/補償の証跡も重視

1. 全体方針 ​

  • ETS は 外部システムとの連携を対象とします。

    • 例: 決済、配送、IdP、会計SaaS、仕入先システム、外部ストレージ、外部メッセージ基盤 等

  • ETS は上位方針（TSP）と整合し、based_on で根拠仕様（EAPIS / EMS / EFES / ESIL / NFR / SAC / ADR 等）を追跡可能にします。

  • 曖昧表現は禁止します。

    • 「連携できること」ではなく、入力／連携点／期待結果／観測点／リトライ・補償を記述します。

  • クリック手順の逐語列挙は避け、業務行為／入力／期待結果として要約します。

  • 実装詳細（SQL全文、内部クラス名、特定ライブラリ設定値の列挙）は書きません。

  • 1ファイル = 1 仕様（原則）です。

    • 肥大化する場合は、外部システム単位で ets-<external> に分割します。

2. 用語定義 ​

用語定義
ETS外部結合テスト仕様。外部連携で保証すべき範囲を定義する文書
外部システム自組織の管理範囲外（契約/SLA/仕様変更の影響を受ける）
連携点外部API、外部メッセージ、外部ファイル、Webhook 等
契約I/F外部と合意したI/F仕様（OpenAPI/AsyncAPI/ファイル仕様等）
観測点合否判定の根拠となる観測箇所（応答、外部側ステータス、監査ログ等）
補償失敗時の業務的回復（再送、取消、手動復旧、リカバリ手順等）

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

ファイル名（推奨） ​

  • 全体: 010-外部結合テスト仕様.md
  • 個別: 010-外部結合テスト仕様-<用語集term>.md 例: 010-外部結合テスト仕様-仕入先.md, 010-外部結合テスト仕様-決済.md

Frontmatter ​

  • id: 全体構成は ets-index 固定、個別仕様は ets-<term>（例: ets-supplier, ets-payment）
  • type: test
  • title: 外部結合テスト仕様: 全体 / 外部結合テスト仕様: 決済 など

4. 推奨 Frontmatter 項目 ​

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

項目説明必須
idETS ID（ets-...）○
typetest 固定○
title仕様名○
statusdraft / ready / deprecated○
part_of集約ドキュメントへの所属（個別仕様は ets-index）任意
based_on根拠となる仕様ID（ESIL/EAPIS/EFES/EMS/NFR/SAC/ADR 等）推奨
supersedes置き換え関係（ID配列。未指定時は [] を許容）任意

推奨:

  • 外部連携は「仕様の根拠」が重要なので、based_on に以下を優先的に入れます。

    • 連携種別ごと：eapis-*（API）, ems-*（メッセージ）, efes-*（ファイル）
    • 外部一覧：esil-*
    • 非機能：nfr-*, sac-*
    • 判断根拠：adr-*

  • part_of / based_on / supersedes は ID の配列で記載し、未指定の場合も [] として明示してよいです。

  • 未定義プロパティの追加は禁止です（additionalProperties: false）。

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

各 ETS ファイルは以下の見出しを順番に並べます。

  1. 概要
  2. 対象スコープと契約境界
  3. 連携パターン一覧
  4. 保証範囲（観点）
  5. テスト条件（代表条件）
  6. 障害・例外時の期待挙動（補償・再送・手動復旧）
  7. 合格基準とエビデンス
  8. 対象外 / 除外理由
  9. メモ / 将来課題

6. 記述ガイド詳細 ​

6.1 概要 ​

  • 1〜3文で「どの外部連携を、何のために保証するか」を書きます。
  • 外部連携の目的（業務価値）を短く言及します。

6.2 対象スコープと契約境界（必須） ​

「どこまでが自システムで、どこからが外部か」を固定します。

推奨（表） ​

項目内容例
外部システム名仕入先システム
連携種別外部API / 外部ファイル / Webhook / メッセージ
契約I/Feapis-supplier / efes-orders
接続環境sandbox / 検証環境 / 本番（要条件明記）
認証方式OAuth / API Key（方式のみ）
観測点応答、外部側受付ステータス、監査ログ

ポイント:

  • 「本番でしか検証できない」項目がある場合は、**理由と代替（運用監視/リハーサル）**を明記します。

6.3 連携パターン一覧（必須） ​

外部連携は「パターン」を押さえるのが重要です（ケース羅列ではない）。

パターンID呼称自システム → 外部連携点目的
EIT-01発注送信発注サービス → 仕入先外部API発注を送る
EIT-02受付照会発注サービス → 仕入先外部API受付結果確認
EIT-03失敗通知仕入先 → 自システムWebhook失敗を受ける

6.4 保証範囲（観点）（必須） ​

外部結合では「契約遵守」「障害時」「運用性」を観点として固定化します。

観点ID分類観点名保証内容根拠
EE-01契約リクエスト妥当契約I/Fに適合した送信を行うEAPIS/EFES
EE-02契約応答解釈外部応答を正しく解釈し状態反映EAPIS
EE-03例外タイムアウトタイムアウト時の扱いが仕様通りSAC/ADR
EE-04例外リトライリトライ条件・回数・間隔が方針通りTSP/ADR
EE-05運用冪等性再送しても二重処理にならないADR
EE-06運用監査/追跡連携ID・相関IDで追跡可能NFR
EE-07セキュリティ認証/権限認証方式に従い秘匿情報を漏らさないNFR

6.5 テスト条件（代表条件）（必須） ​

値の総当たりは禁止。方向性のみ。

観点ID条件ID条件期待結果
EE-01EC-01正常送信受付成功
EE-02EC-02応答が警告状態は警告扱い、業務継続可否が仕様通り
EE-03EC-05タイムアウトリトライ/保留/手動対応へ遷移
EE-05EC-08同一要求を再送二重登録にならない

6.6 障害・例外時の期待挙動（必須） ​

ETS のキモです（外部結合はここで差が出ます）。

推奨（表）:

事象検知方法期待挙動補償/復旧エビデンス
タイムアウト呼出結果再送 or 保留手動再送手順ログ/キュー
4xx応答コード入力不備として停止業務修正エラーログ
5xx応答コードリトライ次回再送実行履歴
仕様不一致受信データ破棄/隔離調査・連絡監査ログ

6.7 合格基準とエビデンス（必須） ​

項目合格基準例エビデンス
契約I/F主要パターンで契約逸脱なしリクエスト/レスポンス記録
例外系定義した例外の扱いが全て確認済実行ログ
運用性再送・追跡が可能相関ID付きログ
未解決不具合Critical 0不具合管理票

6.8 対象外 / 除外理由（必須） ​

例:

  • 外部サービス自体のSLA（契約に委ねる）
  • 外部側の内部仕様（ブラックボックス）

6.9 メモ / 将来課題 ​

  • 外部仕様変更リスク
  • 本番でしか確認できない項目と代替策

7. 禁止事項 ​

禁止理由
外部契約情報の機微（秘密鍵・トークンの実値）セキュリティ
SQL全文、物理名実装依存
実装クラス/関数名実装依存
個別テストケース大量列挙下位（ETD）へ
曖昧表現合否判定不能

8. サンプル（最小） ​

yaml
---
id: ets-index
type: test
title: 外部結合テスト仕様: 全体
status: draft
part_of: []
based_on:
  - tsp-overview
  - esil-supplier
  - eapis-inventory
  - nfr-security
  - sac-performance
supersedes: []
---

9. 生成AIへの指示テンプレート ​

  • 以下のルールに従って 外部結合テスト仕様（ETS） を 1 ファイル作成してください。出力は Markdown。
  • 目的: 外部連携の契約境界、連携パターン、保証観点、例外時挙動（補償/再送/手動復旧）、合格基準とエビデンスを明文化する。
  • 禁止: 秘密情報、SQL全文、実装クラス/関数名、クリック手順逐語列挙、個別ケース大量列挙。

本文見出し（この順） ​

  1. 概要
  2. 対象スコープと契約境界
  3. 連携パターン一覧
  4. 保証範囲（観点）
  5. テスト条件（代表条件）
  6. 障害・例外時の期待挙動（補償・再送・手動復旧）
  7. 合格基準とエビデンス
  8. 対象外 / 除外理由
  9. メモ / 将来課題