Concordの仕組み

要件・仕様と、実装コード・テストの対応をGitに記録します。変更が入ると、Concordはその関係をたどり、影響する仕様と確認すべきテストを示します。

一つの要件と、一つの性質を二つのAPIで共有する

公式サンプルでは、検索APIと詳細APIは同じRequirementを参照します。APIごとの応答はそれぞれのContractで定義し、どちらのContractも「他人の非公開文書を読めない」という同じPropertyを要求します。

Requirement R-PRIVATE

非公開文書は所有者だけが閲覧できる。

Contract C-SEARCH

検索APIは、閲覧できる文書のタイトルだけを検索結果に含める。

REL-SEARCH-PRIVATE要求する
Contract C-DETAIL

詳細APIは、閲覧できない文書を指定するとHTTP 404を返す。

REL-DETAIL-PRIVATE要求する
Property P-PRIVATE

認証済みの利用者は、自分が所有していない非公開文書を読めない。

Requirement・Contract・Property・Relationは、concord/ 配下に1件ずつYAMLで定義し、Gitで管理します。

Relationで仕様・実装・テストをつなぐ

Relationは、どのContractがどのPropertyを要求するかを記録し、その振る舞いを担うコードと、確かめる方法を結び付けます。

上流 · 要件と仕様

Contractは要件IDを参照し、RelationはContractとPropertyの組を指定する。

Relation

下流 · 実装と検証

実装コード implementations
振る舞いを実現するコードのパスを指定する。
テスト・検証コマンド obligations
振る舞いを確かめるテストや検証コマンドを登録する。

変更があったときに、どこを確認するか

実装コードを変更したとき

検索APIだけを変更したら、差分に含まれる実装に紐づくRelationをたどり、影響する仕様と検証対象を確認します。共通の閲覧判定を実装する src/access.ts は共有Propertyに登録されているため、このファイルを変更すると両方のテストが対象になります。

要件・仕様を変更したとき

閲覧制限の要件を更新したら、検索・詳細のどの契約と性質に影響するかをたどります。実装を直す前に、変更後の振る舞いを確かめるために何をテストへ追加・更新するかをレビューし、関係するコードを把握できます。

利用例を見る