Concordの使い方
変更に関係する仕様を確認し、Git差分から検証対象を選び、結果を対応する仕様までたどります。検索APIと詳細APIがあるリポジトリを例に、日々の変更での使い方を説明します。
変更から検証までの流れ
Concordをインストールし、導入先のGitリポジトリのルートで実行します。検証ランナーとコマンドは concord.toml に、要件・契約・性質・Relationは concord/ に定義しておきます。
定義を変更する
変わる要件・契約・性質を確認し、必要な定義を更新します。例えば検索結果の公開条件を変える場合、検索APIのPropertyを見直し、Relationに対応する実装と検証方法を記録します。
定義をチェックする
YAMLの構文、IDの重複や参照先、concord.toml の設定を確認します。diagnostics にエラーがあれば先に修正し、warnings に出た未承認の定義や検証責務もレビューします。
concord checkテストと実装を更新する
変更後に期待する振る舞いを先に確認し、テストを追加・更新します。そのテストを満たすように実装を直し、テストやファイルの参照が変わったらRelationも更新します。
検証対象を確認する
main を比較元に、今のGit差分で選ばれるテスト・登録コマンドと選定理由を確認します。対象ファイルは selected_files、登録コマンドは selected_commands、その選定理由は decisions と command_decisions に出ます。定義や共有設定の変更などで検証対象が全体に広がった場合は、mode と fallback_reasons を確認します。
concord plan --base main --json検証を実行する
同じ比較元を指定し、実行時点の差分に基づいて選ばれたテストと登録コマンドを実行します。出力の status と passed、failed、skipped を見て、選択されたテストの成否と未実行を確認します。登録コマンドは command_results[] を確認します。noop の場合は検証を実行していません。
concord verify --base main --jsonテスト結果と選定理由を確認する
まず verify の出力で失敗箇所を特定し、テストIDまたはコマンドIDを explain に渡します。explain は直近に保存された選定内容を参照するので、別の plan を作る前に確認します。
cases[].test_id- cases[] で status が failed の項目を探し、その test_id を使います。test_id がない場合は、同じ出力の plan.tests[] で file と name が両方一致する項目があれば、その id を使えます。
command_results[]- 登録コマンドの結果は command_results[] に出ます。失敗したコマンドの id、終了コード、ログを確認します。Playwrightなどで個別の失敗を調べる場合は、ランナーが出した結果も参照します。
concord explain TEST_IDテストIDでは選定理由と、紐づくRelation・Contract・Propertyを確認できます。コマンドIDではそのコマンドの選定理由を確認できます。成否は verify の出力で確認し、Relationの implementations と obligations を手掛かりに実装・テスト・仕様のどこを直すか調べます。
導入後のフォルダ構成
concord.toml と concord/ のYAMLはGitで共有します。ローカルの実行結果を置く .concord/ は、リポジトリの .gitignore に /.concord/ を記載して除外します。
利用例を見るmy-repository/
├── concord.toml
├── concord/
│ ├── requirements/
│ ├── contracts/
│ ├── properties/
│ └── relations/
├── src/
├── tests/
└── .concord/