Accepted（設計合意済み、未実装）。Issue #40 と合意記録に基づく。§5「実行証跡と適用可能性」は0020により置き換えられた。§1〜4（所属・共通手順・Case revision・分割統合）はそのまま有効。
この ADR は将来の契約を記録する。現在のコード・スキーマが対応済みであること、Issue #40 の受け入れ条件がすべて完了したことを意味しない。
従来は Requirement 配下に Feature が所属し、Condition と独立した ExpectedResult 群からケースを生成する。構成要素の UID 集合から導出する case_uid は、期待結果の追加や所属変更で変わる。一方、実行証跡に用いる Feature tree SHA だけでは、Feature 外の実効入力や、実行対象のビルド・環境を表せない。
目的はテストケースの管理と版を軸にした変更検知である。実行コードの生成・実行エンジン・リトライ判定を markharness に追加することではない。意味の明確さ、決定性、証跡の正確さ、編集しやすさ、実装の単純さを優先し、旧形式との互換性を制約にしない。
Feature を Requirement の保存階層から独立させ、Feature の requirement_uids により複数要件へ対等に関連付ける。関係の正本は Feature 側のみとし、逆方向の一覧は派生させる。この関係は「実現に寄与する」を意味し、Feature 単独で要件全体を満たすという証明ではない。
Requirement の axis は Feature へ自動継承しない。Feature の分類は自身に記述し、要件による検索は関連をたどる。汎用グラフや多重所属は導入しない。Requirement 同士の関係は別の未決定事項である。
Requirement ← Feature が複数参照
└ Behavior：共通手順を定義
└ Scenario：共通手順を明示参照
└ Phase 配列：操作と確認を実行順に記述
Condition と ExpectedResult を Scenario に統合する。Scenario は順序付き Phase 配列を所有し、各 Phase は操作と期待結果を持つ。実行順の正本は配列順であり、ファイル名順ではない。Phase は Scenario の一部であり、独立 UID・独立ライフサイクルを持たない。
Behavior は関連する Scenario をまとめ、共通手順を定義する。Scenario は必要な位置から共通手順を明示参照する。先頭への自動挿入はしない。参照は所属する Behavior 内に限定し、共通手順から別の共通手順を呼ぶ入れ子は認めない。生成時に操作列へ展開する。
以下は意味を示す例であり、最終スキーマではない。
# Behavior の共通手順
procedures:
login:
steps:
- 認証情報を入力する
- ログインボタンを押す
# Scenario の Phase 配列
phases:
- steps:
- use: login
results:
- マイページが表示される
- steps:
- action: ログアウトする
- use: login
results:
- 再びマイページが表示される
将来の外部手順管理は妨げないが、そのための汎用参照機構・外部取得機構は先回りして追加しない。
1 Scenario = 1 TestCase を正式な契約とする。TestCase は共通手順等を展開した生成物である。Case UID は Scenario UID から型を区別して決定的に導出し、生成時のランダム発行や別のケース登録台帳を必要としない。
FeatureUid、ScenarioUid、CaseUid、ExecutionUid、表示 ID、版参照は意味の異なる型とする。表示 ID と UID を同じ照合キーとして扱わず、入力境界で形式・必須性・参照を検証する。
| 変更 | Case UID | Case revision |
|---|---|---|
| 表示名・説明・実装メモ・出典 | 維持 | 維持 |
| 操作・事前条件・期待結果・テストデータ | 維持 | 実効内容が変われば変更 |
| Phase の追加・削除・並べ替え | 維持 | 実効内容・順序が変われば変更 |
| 共通手順の変更 | 維持 | 参照して実効内容が変わるケースのみ変更 |
| 別 Feature / Behavior への移動 | 維持 | 実効内容が変われば変更 |
| 分類・要件との関連 | 維持 | 維持。計画・関連の変更として扱う |
| 別テストとして複製 | 新規 | 複製先の実効内容から計算 |
Case revision は準備操作・事前条件、展開後の共通手順、操作、期待結果、順序、テストデータという実効入力から決定的に計算する。実行者が守る条件を説明文だけに書かない。保存内容の変更は Git OID で監査する。対象ビルド・実行環境は Case revision に含めず、証跡の適用条件として分離する。
canonicalization の規則とその識別方法は実装設計で定義する。自然言語の意味が同一であることをハッシュ一致が証明するとは扱わず、比較できない規則を暗黙に同一扱いしない。ケース版を比較するだけでなく、実効入力の変更が対象ケースの変更検知に届く必要がある。
| 操作 | UID の扱い |
|---|---|
| 既存 Scenario の改訂 | 維持 |
| 一部を別 Scenario に切り出す | 元は維持、切り出し先は新規 |
| 元を廃止して複数へ分割 | 分割先はすべて新規 |
| 複数を廃止して一つに統合 | 統合先は新規 |
改訂か新規作成かを編集者が明示し、本文の類似から推測しない。由来は記録するが、新しいケースへ合格結果を引き継がない。由来の保存形式は未決定である。
実行結果（pass/fail/skip）、適用可能性（適合・ケース旧版・対象違い・環境違い等）、証跡の有無を分ける。過去の fail を stale という値で消さない。
計画には採用する実行結果を明示的に関連付け、Case UID、Case revision、対象ビルド、要求環境が適合するときだけ採用する。対象・環境が不明な記録は保存できても合格を満たさない。欠落・破損・未解決の証跡を合格と扱わない。日時だけで独立した結果を上書き・優先しない。
外部ツールが実行・リトライ・集約・最終結果を決定し、markharness は保存と適用可能性の検証を担当する。Run/Attempt モデル、flaky 判定、リトライ後の成功を独自に不合格とする規則は導入しない。手動の実行記録にも同じ参照・適用契約を用いる。
記録はケースごとに独立させる。物理的な1ファイル当たりの件数は想定規模を踏まえて決め、1記録1ファイルは本 ADR では確定しない。
実行に使った実効ケース定義を Case UID + Case revision ごとに Git 内へ不変の記録として保存し、証跡から参照する。同一定義は共有する。表示名等は revision 対象外なので、同じキーの定義をそれらの変更で上書きしない。実行時の表示情報や出典 snapshot の監査情報は別に扱い、具体形式は実装設計で決める。
本 ADR は内部データモデルを対象とし、実行記録の識別と、ケース・版・対象・環境への関連付けを定める。インポート機能の担当ツールや統合方式は本 ADR では定めず、具体的な連携要件に基づく別の ADR で扱う。Gherkin／Playwright は想定ユースケースであり、統合契約を確定するものではない。
現時点は利用者のいないプロトタイプである。形式バージョンを更新せず新モデルへ直接置き換え、互換レイヤー・旧形式 reader・移行・専用の旧形式識別機構を追加しない。入力は新スキーマで検証する。正式リリース後の形式バージョン運用は安定時に確定する。Case revision による検証内容の追跡とは区別する。
論文との関係は統合版第3.8節を参照する。従来実装の動作確認は本 ADR の実装検証ではない。Case revision の変化と、要件・実装変更による意味上の再検討範囲は同義ではなく、その候補抽出規則は未決定である。内部の過去比較に必要な入力は Git の snapshot に固定する必要がある。
| 代替案 | 採否と理由 |
|---|---|
| 要件配下の Feature に追加参照を足す | 不採用。主たる親と対等な参照の二重規則を避ける |
| ExpectedResult を独立ファイル・UID で維持 | 不採用。独立追跡の具体的な用途がなく、順序と所有を単純化できる |
| 共通手順を全 Scenario の先頭へ自動追加 | 不採用。途中で使う要件を満たさず、実行位置が見えにくい |
| 構成要素の集合をケース identity にする | 不採用。同じテストの改訂と履歴が分断される |
| Feature tree SHA だけで検証版を表す | 不採用。実効入力全体やケース単位の変更を表せない |
| markharness で自動実行・リトライを管理 | 不採用。テスト管理と変更検知の責務を超える |
参照解決、ケース版計算、固定定義の保存は増える。一方、Phase の identity 管理と実行順のファイル名管理が不要になる。Phase 単独の履歴は保証しない。性能上の優位性は未測定である。
必須の検証例は、rename での UID 維持、操作・順序・共通手順変更の版更新、説明だけの変更での版維持、分割・統合時の新規 identity、別版・別ビルド・環境不明・skip を合格に使わないこと、並行記録での整合性、実行時の版を最新値で置換しないことである。
記録の原子的な保存・破損保全、訂正、時刻の比較、対象・環境の型、版の正規化、参照欠落・空 Phase の検証、各派生モデルの厳密な形式は実装前に決定する。本 ADR だけをもって実装可能な全スキーマが確定したとは扱わない。実装順序・タスク分割は、着手時にchecklist-<task>.mdとして別途管理する(checklist-workflow)。