要件の整理: ユーザーストーリーとユースケース
前の章の終わりで、何を受け付けて何を返すかがコードの中にしか無いと、利用者は試して確かめるしかないことを見ました。このガイドは、それを OpenAPI の仕様として先に書きます。ただ、仕様の前にもう 1 つ段があります。誰が何のためにこの API を使い、どうなれば「できた」と言えるかを、要件として書く段です。
この章では、注文の API の 1 周目 (注文の作成と取得) の要件を書きます。道具は、ユーザーストーリー・受け入れ条件・ユースケースの 3 つです。書いたものは、サンプルリポジトリの docs/requirements/ に置き、受け入れ条件はテストの名前に写します。
この章から、注文する人を購入者と呼びます。前の章で書き分けたとおり、API を使ってアプリを作る利用者とは別の人です。
仕様の前に要件を書く理由
OpenAPI の仕様は、どんなリクエストを受け付け、どんなレスポンスを返すかを書くものです。仕様の形が正しいかは、lint で確かめられます。しかし、その形で購入者の役に立つかは、仕様だけを見ても分かりません。
たとえば、注文を作る操作が、注文明細ごとに単価を受け取る形になっていたとします。仕様としては正しく書け、lint も通ります。それが誤りだと分かるのは、「注文明細の単価は、注文した時点の商品の価格を写したもの」という要件があるときだけです。クライアントが単価を送れる形では、購入者が好きな金額で注文できてしまいます。
要件は、後の段すべての物差しになります。
- ドメインモデルは、要件に出てくる語と決まりから作ります
- 仕様は、要件の操作を HTTP に写したものです。仕様を見直すときは、要件の操作がすべて仕様にあるかを確かめます
- モックと実装は、受け入れ条件を満たすかで確かめます
振る舞い駆動開発 (BDD) を提唱した Dan North は、ストーリーの振る舞いは受け入れ条件そのものであり、システムが受け入れ条件をすべて満たせば正しく振る舞っている、と書いています (Introducing BDD)。このガイドでも、受け入れ条件を「できた」の定義として使います。
要件は、購入者や店の人と確かめ合える言葉で書きます。URL・メソッド・ステータスコードは書きません。それらは、要件から設計の段で決めるものです。要件に先に書くと、設計で比べるはずの案を、比べる前に 1 つに決めてしまいます。
ユーザーストーリー
ユーザーストーリーは、誰が・何をしたいか・なぜか、の 3 つで要件を短く書く形です。よく使われるテンプレートは次の形です。
As a (役割), I want (したいこと) so that (理由)
このテンプレートは、2000 年代の初めに、英国の Connextra という会社で Rachel Davies が作ったものです。Mike Cohn は、3 つの要素を who・what・why と呼んでいます。また、テンプレートを示すときに want を入れなくなったと書いています。したいことは「したい」に限らず、「しなければならない」場合もあるからです (Why the Three-Part User Story Template Works So Well)。
このガイドでは、日本語で次の形に書きます。
- 「(役割) として、(したいこと)。(理由) ためだ。」
1 周目のストーリーは 2 つです。
## ストーリー: 注文する
購入者として、商品と数量を選んで注文したい。店に行かずに商品を買うためだ。
<!-- ... -->
## ストーリー: 注文を確かめる
購入者として、注文した内容と状態を確かめたい。注文が受け付けられたかと、何をいくらで頼んだかを後から見るためだ。
役割は購入者です。利用者ではありません。「利用者として、注文を作る API を呼びたい」と書くこともできますが、理由の欄に書けるのは「注文を作るため」くらいで、何の役に立つかが抜け落ちます。価値を受け取るのは購入者で、API はそれを支える側です。
理由の欄は、飾りではありません。「店に行かずに商品を買うためだ」と書くと、注文できたことを購入者がどう知るか (注文を確かめるストーリー) や、注文した後に何が要るか (後の周回の決済) に目が向きます。
ストーリーは、それだけで要件のすべてではありません。Ron Jeffries は、ストーリーを card・conversation・confirmation の 3 語で説明しました (User Stories)。カードに書くのは会話を始めるための短い文で、細部は会話で詰め、受け入れ条件 (confirmation) で確かめます。テンプレートも決まりではなく、別の形の方が明確なら使わなくてよい、とされています (同じページの FAQ)。
INVEST で確かめる
書いたストーリーがよいかを確かめる観点に、Bill Wake が 2003 年に示した INVEST があります (INVEST in Good Stories, and SMART Tasks)。6 つの頭文字です。
| 頭文字 | 意味 | このガイドのストーリーでは |
|---|---|---|
| Independent | 独立している。概念が重ならず、どの順でも計画し実装できる | 注文を確かめるには、受け付けた注文が要ります。完全には独立できないので、受け入れ条件の Given に「注文が受け付けられている」と書き、依存を前提の中に閉じ込めます |
| Negotiable | 交渉できる。機能の契約ではなく、細部は作りながら一緒に決める | 在庫が一部だけ足りないときの扱いは、決めずに「未決の問い」として残します |
| Valuable | 価値がある。その価値は、ストーリーを頼む側 (XP の用語で customer) にとってのもの | どちらのストーリーも、購入者にとっての価値を理由に書きます |
| Estimable | 見積もれる。正確でなくてよく、順位付けと計画に使える程度でよい | 操作が 1 つに絞れているので、設計と実装の量を見積もれます |
| Small | 小さい。多くても数人週の作業 (数人日に限るチームもある) | 取り消しや決済は別のストーリーにして、後の周回に回します |
| Testable | テストできる。ストーリーを書くことは、テストを書けるほど望みを分かっているという約束を伴う | 受け入れ条件を具体的な値で書けるかで確かめます |
INVEST が役に立つのは、大きすぎるストーリーを分けるときです。たとえば「購入者として、注文を管理したい」は、Small と Testable のどちらにも当たりません。管理が何を指すかが決まっていないからです。
分けるときは、購入者の目的で分けます。「注文する」「注文を確かめる」「注文を取り消す」のように分けると、どれも 1 つで購入者の役に立ちます。逆に、「注文の表を作る」「注文の API を作る」「注文の画面を作る」のように作る部品で分けると、どれも単独では誰の役にも立たず、Valuable に当たりません。
受け入れ条件を Given・When・Then で書く
受け入れ条件は、ストーリーが満たされたと言える条件です。このガイドでは、Dan North と Chris Matts が BDD の中で作った Given・When・Then の形で書きます (Introducing BDD)。
- Given: 振る舞いを始める前の、世界の状態 (前提)
- When: 確かめたい振る舞い (操作)
- Then: その振る舞いで期待する変化 (結果)
Martin Fowler は、この形を、システムの振る舞いを例で示す書き方として説明しています (GivenWhenThen)。前提や結果が複数あるときは、And でつなぎます。
具体的な値で書く
受け入れ条件は、具体的な値で書きます。次の 2 つを比べてください。
- 「注文すると、合計と消費税額が正しく計算される」
- 「りんご (1,080 円、8%) を 2 個と保存容器 (1,650 円、10%) を 1 個注文すると、合計は 3,810 円、消費税額は 310 円」
1 つ目は、何が正しいかを書いていないので、テストにできません。2 つ目は、そのままテストの入力と期待値になります。
値を書くと、決めていなかったことにも気づきます。消費税額の値を書くには計算が要るので、求め方を問うことになります。注文明細ごとに求めて足すのか、税率ごとに合計してから求めるのか、です。このガイドでは、消費税額を、税率ごとの合計から割り戻して求めることにします。8% の対象の合計 2,160 円からは 2,160 × 8/108 = 160 円、10% の対象の合計 1,650 円からは 1,650 × 10/110 = 150 円で、足して 310 円です。この例は税率ごとに注文明細が 1 つずつなので、どちらの求め方でも同じ式になります。結果が分かれうるのは、同じ税率の注文明細が 2 つ以上あり、1 円未満の端数が出るときです。たとえば 8% の 1,050 円の商品を 2 種類 1 個ずつ頼み、端数を切り捨てるなら、注文明細ごとでは 77 円 + 77 円 = 154 円、税率ごとでは 2,100 × 8/108 から 155 円になります。この求め方の根拠と端数の扱いは、ドメインモデルの章で国税庁の資料を引いて決めます。
値を書くために、受け入れ条件が始まる前の状態を決めておきます。リポジトリの docs/requirements/stories.md は、商品と在庫の表を前提に置き、最初の受け入れ条件をこう書いています。
## 受け入れ条件の前提
どの受け入れ条件も、次の商品と在庫が登録された状態から始める。価格は消費税を含んだ金額。
| 商品 | 価格 | 税率 | 在庫 |
| --- | --- | --- | --- |
| りんご | 1,080 円 | 8% (軽減税率) | 10 |
| 保存容器 | 1,650 円 | 10% (標準税率) | 3 |
## ストーリー: 注文する
購入者として、商品と数量を選んで注文したい。店に行かずに商品を買うためだ。
### 受け入れ条件: 在庫のある商品を注文すると、注文が受け付けられる
- **Given** 受け入れ条件の前提の商品と在庫がある
- **When** 購入者が、りんごを 2 個と保存容器を 1 個、連絡先メールアドレス `taro.test@example.com` で注文する
- **Then** 注文が受付の状態で作られ、注文 ID が返る
- **And** 注文明細は 2 つで、単価はりんごが 1,080 円、保存容器が 1,650 円
- **And** 合計は 3,810 円、消費税額は 310 円 (8% の対象の 2,160 円から 160 円、10% の対象の 1,650 円から 150 円)
- **And** 在庫は、りんごが 8、保存容器が 2 になる
Then には、外から確かめられる結果だけを書きます。在庫が減ったことも、後で在庫を見れば確かめられる結果です。
失敗も受け入れ条件にする
受け入れ条件は、うまくいく場合だけでは足りません。受け付けない場合も、それぞれ受け入れ条件にします。
### 受け入れ条件: 在庫より多い数量を頼むと、注文は受け付けられない
- **Given** 受け入れ条件の前提の商品と在庫がある
- **When** 購入者が、保存容器を 4 個注文する
- **Then** 注文は作られない
- **And** 在庫が足りない商品が保存容器だと分かる
- **And** 保存容器の在庫は 3 のまま
ここでも、409 や 422 のようなステータスコードは書きません。書くのは、注文が作られないこと、何が悪いかが購入者に分かること、在庫が変わらないことです。どのステータスコードで、どんな本文で伝えるかは、エラーの設計の章で決めます。
この章で書く受け入れ条件は、全部で 9 つです (次の章で 1 つ足します)。一覧は、この章の後半の「受け入れ条件をテストに写す」の節に、テストの名前として載せます。
ユースケース記述
ストーリーは、1 つの目的と価値を短く書きます。一方で、目的を果たすまでにどんな手順があり、どこで何が失敗しうるかは、ストーリーからは見えません。それを書くのがユースケース記述です。
このガイドは、Alistair Cockburn の Basic use case template (1996 年の技術報告。1998 年に改訂) の項目を、次のように絞って使います (Basic use case template。2014 年の Web アーカイブ)。
| このガイドの項目 | Cockburn のテンプレートの項目 | 書くこと |
|---|---|---|
| 名前 | name | 主アクターの目的 |
| 主アクター | Primary Actor | システムを使って目的を果たす人の役割 |
| 事前条件 | Preconditions | 始める時点で、すでに成り立っていると期待する状態 |
| 主な流れ | Main Success Scenario | 目的を果たすまでの手順を、番号を振って書く |
| 別の流れ | Extensions | 主な流れのどの手順で何が起きたら、どう進むか |
| 事後条件 | Success End Condition | 成功したときに成り立っていること |
| 失敗したときの保証 | Minimal Guarantee | 目的を果たせなかったときにも成り立っていること |
失敗したときの保証は、Cockburn がテンプレートの初版で Failed End Condition と呼び、著書 Writing Effective Use Cases で Minimal Guarantee に改めた項目です (同じページの 2001 年の注記)。
注文するユースケースは、こうなります。
## ユースケース: 注文する
| 項目 | 内容 |
| --- | --- |
| 主アクター | 購入者 |
| 事前条件 | 商品と在庫が登録されている |
| 事後条件 | 注文が受付の状態で記録され、注文した数量だけ在庫が減っている |
| 失敗したときの保証 | 注文は記録されず、在庫は変わらない |
### 主な流れ
1. 購入者が、商品と数量の組と、連絡先メールアドレスを送る
2. システムが、注文明細が 1 つ以上あり、どの数量も 1 以上で、連絡先メールアドレスがメールアドレスの形であることを確かめる
3. システムが、どの商品も登録されていることを確かめる
4. システムが、どの商品も在庫が数量以上あることを確かめる
5. システムが、商品の今の価格を単価として注文明細に写し、合計と消費税額を求める
6. システムが、在庫を引き当て、注文を受付の状態で記録する
7. システムが、注文 ID と注文の内容を購入者に返す
### 別の流れ
- **2a** 注文明細が無い、数量が 1 より小さい、連絡先メールアドレスが無いか形が正しくない: システムは注文を記録せず、誤りのある項目を返す
- **3a** 登録されていない商品がある: システムは注文を記録せず、その商品を返す
- **4a** 在庫が数量より少ない商品がある: システムは、足りない商品を返す。一部の商品だけが足りないときに、注文全体を断るか、足りる注文明細だけで受け付けるかは決めていない (未決の問い 1)
別の流れは、主な流れの手順を 1 つずつ見て、「ここで何が起きうるか」を問えば見つかります。手順 4 の在庫の確かめからは、在庫が足りない場合 (4a) が出てきます。Cockburn のテンプレートの記入例「Buy Goods」も、注文した品物の 1 つが在庫切れのときを拡張 3a に書いています。
別の流れと受け入れ条件を照らし合わせる
別の流れの 1 つ 1 つに、受け入れ条件があるかを確かめます。
| 別の流れ | 受け入れ条件 |
|---|---|
| 2a | 数量が 1 より小さい注文明細があると、注文は受け付けられない / 注文明細が 1 つも無いと、注文は受け付けられない / 連絡先メールアドレスが無いと、注文は受け付けられない / 連絡先メールアドレスの形が正しくないと、注文は受け付けられない |
| 3a | 登録されていない商品を頼むと、注文は受け付けられない |
| 4a | 在庫より多い数量を頼むと、注文は受け付けられない |
ストーリーから書き始めた受け入れ条件は、うまくいく場合に偏りがちです。ユースケースの別の流れは、手順ごとに失敗を探すので、漏れを見つけやすくなります。逆に、受け入れ条件は値を持つので、ユースケースの「足りない商品を返す」が具体的に何を指すかを決めます。2 つは、互いの抜けを見つける関係です。ここで洗い出した失敗は、エラーの設計の章で、失敗の一覧の出発点になります。
未決の問いを残す
4a には、決めていないことがあります。りんごと保存容器を頼み、保存容器だけ在庫が足りないとき、注文全体を断るのか、りんごだけで受け付けるのかです。
保存容器を 1 種類だけ頼む受け入れ条件では、どちらの方針でも結果は同じです (注文明細が 1 つも残らないので、注文は作られません)。違いが出るのは、2 種類以上を頼んだときだけです。
この問いは、要件を書く人が 1 人で決めてよいものではありません。在庫が一部だけ足りる注文をどう扱うかは、店の方針です。ここでは決めずに、未決の問いとして書いておきます。
## 未決の問い
1. 2 種類以上の商品を頼み、一部の商品だけ在庫が足りないとき、注文全体を断るか、足りる注文明細だけで受け付けるか
実装する人がその場で決めると、決めたことが要件のどこにも残らず、実装の中にだけ残ります。前の章で見た「コードの中にしか無い」状態が、要件の段で起きます。この問いは、次の章でドメインの出来事を並べるときにもう一度取り上げます。
注文を確かめるユースケース
もう 1 つのユースケースは、読むだけなので短くなります。
## ユースケース: 注文を確かめる
| 項目 | 内容 |
| --- | --- |
| 主アクター | 購入者 |
| 事前条件 | 購入者が注文 ID を持っている |
| 事後条件 | 何も変わらない |
| 失敗したときの保証 | 何も変わらない |
### 主な流れ
1. 購入者が、注文 ID を送る
2. システムが、その注文 ID の注文を探す
3. システムが、注文の状態・注文明細・合計・消費税額・連絡先メールアドレスを返す
### 別の流れ
- **2a** その注文 ID の注文が無い: システムは、注文が見つからないことを返す
受け入れ条件の側では、このユースケースの前提を、別の受け入れ条件の結果で書いています。INVEST の Independent の表で書いた、依存を前提に閉じ込める書き方です。
### 受け入れ条件: 受け付けた注文を、注文 ID で確かめられる
- **Given** 「在庫のある商品を注文すると、注文が受け付けられる」の注文が受け付けられている
- **When** 購入者が、その注文 ID で注文を確かめる
- **Then** 状態は受付
- **And** 注文明細は、りんご 2 個 (単価 1,080 円) と保存容器 1 個 (単価 1,650 円)
- **And** 合計は 3,810 円、消費税額は 310 円
- **And** 連絡先メールアドレスは `taro.test@example.com`
画面と API の受け持ち
購入者は API を直接は使いません。利用者が作ったアプリの画面を通して使います。ストーリーは購入者の目線で書くので、画面がすることと API がすることが混ざりがちです。要件を API の段に渡す前に、どちらが何を受け持つかを分けておきます。
| 受け持つこと | 画面 (利用者が作るアプリ) | API |
|---|---|---|
| 選んだ商品と数量を、注文するまで覚えておく | 受け持つ | 1 周目は受け持たない |
| 入力の誤りを、送る前に知らせる | 使いやすさのために受け持つ | 送られた入力を、必ず確かめ直す |
| 単価を決める | 表示するだけ | 商品の今の価格から決める |
| 合計と消費税額 | 見込みを表示してよい | 記録する値を求める |
| 在庫を確かめて引き当てる | 受け持たない | 受け持つ |
| 注文を記録する | 受け持たない | 受け持つ |
API が入力を確かめ直すのは、API を呼ぶのが利用者の画面だけとは限らないからです。curl でも、ほかの利用者のアプリでも呼べます。画面が確かめたかどうかを、API は知りません。単価を API が決めるのも同じ理由で、クライアントが送った金額を信じると、購入者が金額を選べてしまいます。
docs/requirements/ に書くのは、API が受け持つことです。ユースケースの主な流れで「システムが」と書いた手順が、それに当たります。
機能でない要件を書き留める
ストーリーと受け入れ条件は、何ができるかを書きます。それとは別に、どんな条件でも守ることや、どの程度に守るかの要件があります。これを機能でない要件と呼びます。同時に注文が来たときの在庫、予期しない誤りのときの応答、読める人の範囲などです。
機能でない要件は、確かめ方と、扱う周回を一緒に書きます。
# 機能でない要件
何ができるかではなく、どんな条件でも守ることと、どの程度に守るかの要件。確かめ方と、扱う周回を一緒に書く。確かめ方を書けない要件は、確かめられる文に書き直す。
| 要件 | 確かめ方 | 扱う周回 |
| --- | --- | --- |
| 同じ商品への注文が同時に来ても、在庫より多くは引き当てない | 在庫が 1 の商品に、1 個の注文を同時に 2 件送り、受け付けられるのが 1 件だけであることを確かめる | 1 周目 |
| 予期しない誤りの応答に、内部の情報 (スタックトレースや SQL の文) を載せない。代わりに追跡 ID を載せ、同じ追跡 ID をログにも残す | 誤りを起こしたテストで、応答の本文とログを確かめる | 1 周目 |
| 同じ注文を送り直しても、注文が 2 件にならない | 同じ注文を 2 回送り、注文が 1 件だけ記録されることを確かめる | 3 周目 |
| 注文の内容は、その注文をした会員だけが読める | 別の会員で読もうとすると、読めないことを確かめる | 4 周目 |
1 周目のあいだは、3 周目と 4 周目の要件を満たさない。とくに、注文 ID を知っていれば、誰でもその注文を、連絡先メールアドレスを含めて読める。
確かめ方を書くのは、書けない要件は守れたかどうかを判断できないからです。「速く応答する」「安全にする」と書いても、誰も確かめられません。
1 周目で満たさない要件も書きます。書いておかないと、満たしていないことに誰も気づきません。最後の段落のように、満たさないあいだに何が起きるかも書いておくと、それを知ったうえで先へ進めます。
1 周目に入れないものを決める
EC の注文システムには、商品の一覧・取り消し・会員・決済など、要件の候補がたくさんあります。1 周目にすべてを入れると、設計から実装までを回し終えるのが遠くなります。このガイドは、1 周目を注文の作成と取得に絞り、ほかは後の周回に回します。
入れないものも、ファイルに書いておきます。
# 1 周目に入れないもの
1 周目は、注文することと、注文を確かめることだけを扱う。次のものは入れない。入れないあいだの扱いも書いておく。
| 入れないもの | 扱う周回 | 1 周目のあいだの扱い |
| --- | --- | --- |
| 商品を探して見る | 2 周目 | 購入者は、商品をこの API で探せない。受け入れ条件の商品と在庫は、前もって登録しておく |
| 注文を取り消す、注文を変える | 3 周目 | 受け付けた注文は、内容も状態も変えられない |
| 会員と管理者、在庫の入荷 | 4 周目 | 誰でも注文できる。在庫は注文で減るだけで、増やす操作は無い |
| 決済、連携先への知らせ、商品画像、商品と在庫の取り込み | 5 周目 | 注文は受付の状態のまま進まない |
入れないものを書く理由は 2 つあります。1 つは、見直す人が「取り消しはどうするのか」と尋ねたときに、決めたうえで入れていないと答えられることです。もう 1 つは、入れないことで起きる穴 (在庫を増やせない、誰でも注文できる) を、知ったうえで受け入れたと残せることです。
入れないものを選ぶときは、残したストーリーだけで 1 周を回せるかを確かめます。注文の作成と取得だけでも、要件・モデル・仕様・モック・実装・保存の全段を通れます。取り消しは状態の変化を、決済は外部のサービスを持ち込むので、1 周目の後に 1 つずつ足します。
受け入れ条件をテストに写す
受け入れ条件は、実装ができたら、そのままテストになります。実装はまだ無いので、いまはテストの名前だけを書きます。Vitest の it.todo は、中身の無いテストを「これから書くもの」として数えます。
リポジトリの test/acceptance.test.ts は、ストーリーごとに describe でまとめ、受け入れ条件ごとに it.todo を 1 つ書いています。テストの名前は、受け入れ条件の見出しの文と同じです。たとえば最初のテストは it.todo('在庫のある商品を注文すると、注文が受け付けられる') です。コードは章末の「この章のテストのコード」にあります。
この章でテストの名前にした受け入れ条件は、次の 9 つです。
- 注文する
- 在庫のある商品を注文すると、注文が受け付けられる
- 在庫より多い数量を頼むと、注文は受け付けられない
- 登録されていない商品を頼むと、注文は受け付けられない
- 数量が 1 より小さい注文明細があると、注文は受け付けられない
- 注文明細が 1 つも無いと、注文は受け付けられない
- 連絡先メールアドレスが無いと、注文は受け付けられない
- 連絡先メールアドレスの形が正しくないと、注文は受け付けられない
- 注文を確かめる
- 受け付けた注文を、注文 ID で確かめられる
- 無い注文 ID では、注文が見つからない
このファイルだけを動かすと、Vitest は受け入れ条件のテストを todo として数え、失敗にはしません。
npx vitest run test/acceptance.test.ts
Test Files 1 skipped (1)
Tests 9 todo (9)
テストの名前を受け入れ条件の見出しと同じ文にしておくと、後で受け入れ条件を直したときに、どのテストを直せばよいかが文字列で分かります。ただ、同じ文を 2 か所に書くと、片方だけを直す誤りが起きます。そこで、2 つがそろっていることを別のテスト (test/requirements.test.ts) で確かめます。このテストは、次の 2 つの並びを作って比べます。
- 文書の
## ストーリー:と### 受け入れ条件:の見出しを書いた順に拾い、「ストーリーの名前 > 受け入れ条件の文」を並べる - テストのファイルの
describe('…'とit.todo('…'・it('…'を書いた順に拾い、「describe の名前 > テストの名前」を並べる
次のどれでも 2 つの並びが食い違い、テストが落ちます。
- 受け入れ条件を足したのに、テストを足し忘れる
- 見出しの文だけを直す
- テストを別のストーリーの
describeに入れる
このテストは、文書の見出しの形と、テストの書き方に頼っています。テストの名前を二重引用符で書いたり、test.todo と書いたりすると、名前を拾えずに落ちます。落ちるので気づけますが、テストを書くときはこの形に合わせてください。文書とテストの両方から何も拾えなくなったときに 0 件と 0 件で一致して通らないよう、文書から 1 件以上拾えたことも確かめます。コードは章末の「この章のテストのコード」にあります。
it.todo の中身は、第 2 部で注文の API を実装するときに書きます。そのとき it.todo は it に変わりますが、名前は変えません。
後の周回の「要件の差分」の節
要件は 1 周目で終わりではありません。2 周目からは、周回ごとにストーリーを足し、入れないものを減らしていきます。2 周目からの章は、冒頭に「要件の差分」の節を置き、次のことを示します。
- 足したストーリーと受け入れ条件
- 変えた受け入れ条件と、変えた理由
- 答えを出した未決の問い
- 入れないものの表から外した行と、足した機能でない要件
リポジトリでは、docs/requirements/ のファイルをその周回の分だけ書き換え、受け入れ条件のテストの名前も足します。前の周回の最後の章の tag と、その章の tag を git diff で比べると、要件の差分をファイルの単位で見られます。
要件の差分を先に示すのは、この章と同じ理由です。何を作るかを先に確かめてから、モデル・仕様・実装の順に進みます。
実務で効く注意点
受け入れ条件に設計の言葉を書かない
「在庫が足りないときは 409 を返す」と受け入れ条件に書くと、エラーの設計で 409 と 422 を比べる前に答えが決まります。表の名前・URL・JSON のキーも同じです。受け入れ条件には、購入者から見える結果 (注文が作られない、足りない商品が分かる) を書き、どう伝えるかは設計の段に任せます。設計を決めた後も、受け入れ条件は書き換えません。設計を変えても、満たすべき結果は変わらないからです。
前提を値で書く
「在庫が十分にある」と書いた Given からは、テストのデータを作れません。何個あれば十分かを、読む人ごとに決めることになるからです。この章のように、前提の商品・価格・税率・在庫を表で決めておくと、どの受け入れ条件も同じ状態から始められます。後でモックや実装で確かめるときも、この表がテストのデータになります。
まとめ
- 要件は、仕様・モック・実装を確かめる物差しです。仕様の形が正しくても、要件に照らさないと誤りに気づけないことがあります
- ユーザーストーリーは、誰が・何をしたいか・なぜかの 3 つで書きます。このガイドの役割は購入者です
- INVEST でストーリーを確かめます。分けるときは、作る部品ではなく購入者の目的で分けます
- 受け入れ条件は Given・When・Then の形で、具体的な値で書きます。値を書くと、決めていなかったことに気づきます
- ユースケース記述は、主な流れと別の流れで手順と失敗を書きます。別の流れと受け入れ条件を照らし合わせると、互いの抜けが見つかります
- 決めていないことは、未決の問いとして残します
- 画面と API の受け持ちを分け、API が受け持つことを要件に書きます
- 機能でない要件は、確かめ方と扱う周回を一緒に書きます。満たさない要件と、そのあいだに起きることも書きます
- 1 周目に入れないものと、入れないあいだの扱いを書きます
- 受け入れ条件はテストの名前に写し、文書とテストがそろっていることをテストで確かめます
次に読む
前の章は メソッドとステータスコード です。
次章 ドメインを探る では、注文するときに起きる出来事を時系列に並べ、要件に出てきた語から用語集を作ります。この章で残した未決の問いにも、そこで答えを出します。
練習問題
受け入れ条件に「在庫が足りないときは 409 Conflict を返す」と書きました。何がまずいでしょうか。どう書き直しますか
解答例
ステータスコードは、HTTP で結果をどう伝えるかという設計の判断です。受け入れ条件に書くと、設計の段で 409 と 422 を比べる前に、答えが決まってしまいます。また、後で設計を変えると、満たすべき結果は同じなのに受け入れ条件を書き換えることになります。
受け入れ条件には、購入者から見える結果を書きます。
- Given 保存容器の在庫が 3
- When 購入者が、保存容器を 4 個注文する
- Then 注文は作られない
- And 在庫が足りない商品が保存容器だと分かる
- And 保存容器の在庫は 3 のまま
どのステータスコードで伝えるかは、この受け入れ条件を満たす方法の 1 つとして、エラーの設計で決めます。
「購入者として、注文を管理したい。」というストーリーを受け取りました。INVEST のどれに当たらず、どう分けるとよいでしょうか
解答例
「管理」が何を指すかが決まっていないので、受け入れ条件を書けず、Testable に当たりません。注文する・確かめる・取り消す・変えるが混ざっているので、Small にも当たらず、どれだけの作業か見積もれない (Estimable に当たらない) ことにもなります。
購入者の目的で分けます。
- 購入者として、商品と数量を選んで注文したい
- 購入者として、注文した内容と状態を確かめたい
- 購入者として、受け付けられた注文を取り消したい
分けた後は、どれも 1 つで購入者の役に立ちます (Valuable)。「注文の表を作る」「注文の画面を作る」のように作る部品で分けると、どれも単独では役に立たないので避けます。分けたものから、どれを今の周回に入れるかを選びます。
この章のテストのコード
受け入れ条件のテストと、文書とテストの名前がそろっていることを確かめるテストのコードです。読まなくても本文は追えます。
受け入れ条件のテスト (test/acceptance.test.ts) です。
/*
* docs/requirements/stories.md の受け入れ条件。中身は、注文の API を実装するときに書く。
* describe の名前はストーリーの名前と、テストの名前は受け入れ条件の見出しの文と同じにする (requirements.test.ts が確かめる)。
*/
import { describe, it } from 'vitest';
describe('注文する', () => {
it.todo('在庫のある商品を注文すると、注文が受け付けられる');
it.todo('在庫より多い数量を頼むと、注文は受け付けられない');
it.todo('登録されていない商品を頼むと、注文は受け付けられない');
it.todo('数量が 1 より小さい注文明細があると、注文は受け付けられない');
it.todo('注文明細が 1 つも無いと、注文は受け付けられない');
it.todo('連絡先メールアドレスが無いと、注文は受け付けられない');
it.todo('連絡先メールアドレスの形が正しくないと、注文は受け付けられない');
});
describe('注文を確かめる', () => {
it.todo('受け付けた注文を、注文 ID で確かめられる');
it.todo('無い注文 ID では、注文が見つからない');
});
文書とテストの名前がそろっていることを確かめるテスト (test/requirements.test.ts) です。
/*
* 受け入れ条件の文書 (docs/requirements/stories.md) と、受け入れ条件のテスト (acceptance.test.ts) の名前がそろっていることを確かめる。
* 片方だけを直すと、文書とテストが別の受け入れ条件を指すようになるため。
*/
import { readFileSync } from 'node:fs';
import { fileURLToPath } from 'node:url';
import { expect, it } from 'vitest';
const stories = readFileSync(fileURLToPath(new URL('../docs/requirements/stories.md', import.meta.url)), 'utf8');
const acceptanceTests = readFileSync(fileURLToPath(new URL('./acceptance.test.ts', import.meta.url)), 'utf8');
/** 「ストーリーの名前 > 受け入れ条件の見出しの文」を、書いた順に返す。 */
function criteriaInStories(markdown: string): string[] {
const result: string[] = [];
let story = '';
for (const match of markdown.matchAll(/^## ストーリー: (.+)$|^### 受け入れ条件: (.+)$/gm)) {
if (match[1] !== undefined) story = match[1];
else result.push(`${story} > ${match[2]}`);
}
return result;
}
/** 「describe の名前 > テストの名前」を、書いた順に返す。 */
function namesInTests(source: string): string[] {
const result: string[] = [];
let suite = '';
for (const match of source.matchAll(/\bdescribe\('([^']+)'|\bit(?:\.todo)?\('([^']+)'/g)) {
if (match[1] !== undefined) suite = match[1];
else result.push(`${suite} > ${match[2]}`);
}
return result;
}
it('受け入れ条件の文書とテストが、同じストーリーの同じ受け入れ条件を同じ順に持つ', () => {
const criteria = criteriaInStories(stories);
expect(criteria.length).toBeGreaterThan(0);
expect(namesInTests(acceptanceTests)).toEqual(criteria);
});