ブログ記事
仕様変更のたびにテストが壊れるのをやめる──『Web APIテスト技法』が示す設計戦略
Web API のテスト自動化に取り組んでいるのに、仕様変更のたびにテストコードが一斉に壊れて修正作業に追われる——そういう状況は、テストの設計自体に問題がある。
Mark Winteringham 著、長尾高弘訳の『Web APIテスト技法』（翔泳社、2023年）は、Postman や curl の操作方法を説明する本ではない。「何をテストするか」の選定基準から、壊れにくいテストコードの構造設計、マイクロサービス間の依存関係の検証まで、APIテストの戦略を扱う。
1. 「品質」をリスクから定義してテスト対象を絞る
本書は品質を「特定の人にとってのある時点での価値」として捉える。仕様書への適合という固定的な基準ではなく、誰にとって何が価値なのかを起点にする考え方だ。
この定義をテスト設計に適用すると、「何でもテストする」から「何を優先してテストするか」へと発想が変わる。本書はリスクを「発生確率」と「ビジネスへの影響度」の 2 軸でマッピングする手法を示す。リスクが高い領域に時間とリソースを集中し、変化が少なく影響が小さい箇所はテストの粒度を下げるという判断を根拠付きで行えるようになる。
2. Tests・Requests・Payloads の 3 層でテストの壊れやすさを下げる
自動テストが仕様変更のたびに壊れる原因の多くは、テストの検証ロジック・リクエスト処理・データ構造が 1 か所に混在していることだ。エンドポイントのパスが変わった、あるいはリクエストパラメータの名前が 1 つ変わっただけで、大量のテストが赤くなる。
本書はテストコードを「Tests（検証）・Requests（通信処理）・Payloads（データ構造）」の 3 つの層に分離する構造を提案する。リクエスト送信やペイロード構築をカプセル化することで、変更が起きたときの修正箇所を最小限に絞れる。Swagger や GraphQL のスキーマからデータ定義を自動生成する手法も取り上げており、手動での定義ミスを減らす実務的な工夫も含まれる。
flowchart TD
T["Tests（検証ロジック）\n何を確認するか"] --> R["Requests（通信処理）\nAPI を呼び出す方法"]
R --> P["Payloads（データ構造）\nリクエスト・レスポンスの形"]
CHG1["エンドポイントのパスが変わった"] -->|"Requests 層だけ修正"| R
CHG2["パラメータ名が変わった"] -->|"Payloads 層だけ修正"| P
style T fill:#e8f4fd,stroke:#4a9eda
style R fill:#fff8e1,stroke:#f5a623
style P fill:#e8f8e8,stroke:#4caf50
style CHG1 fill:#fce8e8,stroke:#e53935
style CHG2 fill:#fce8e8,stroke:#e53935
3. 契約テストでサービス間の依存を検証する
マイクロサービス構成では、あるサービスの API 仕様変更が別サービスの動作を壊す。これを重いエンドツーエンドテストで検知しようとすると、実行が遅く、環境依存で不安定なテストに頼ることになる。
本書が提案するのが契約テスト（Consumer-driven contract test）だ。Pact などのツールを使い、API を提供するサービス（プロバイダー）と利用するサービス（コンシューマー）の間の合意したインターフェース要件を、コードレベルで継続的に検証する。全サービスを起動することなく、インターフェースの整合性を確認できる。
本書後半では、ビジネス側の合意をテストの期待値として記述する ATDD（受入テスト駆動開発）も扱う。テストコードを仕様の受動的な確認ではなく、チームの意思疎通を促すドキュメントにする考え方だ。
4. どんな詰まりに効くか
「テストを自動化したはずなのに、API の仕様が変わるたびにスクリプトが一斉に赤くなり、その修正だけで一日が終わる」——本書が最も効くのはこの状況だ。3 層設計を導入すると、変更の波及が Requests・Payloads の層で吸収され、直す箇所が一気に縮む。「テストが多いほど安心」から「壊れにくい構造で少なく守る」へ発想が変わる。
もう一つは、テストにもっと時間を割きたいのに、開発チームやプロダクトオーナーに協力を求める根拠を持てない QA リードの状況だ。リスクを発生確率とビジネス影響の 2 軸で示せるようになると、「なんとなく不安だから」ではなく「ここが高リスクだから先に守る」と会話を組み立てられる。
5. 向いている人・向いていない人
向いている人：
- 自動テストが API の仕様変更のたびに壊れ、保守コストの増加に直面している SDET・テックリード
- テスト計画のマネジメントを担い、何を優先して検証するかを開発チームやプロダクトオーナーに説明する必要がある QA リード
- モックを多用した単体テストに違和感があり、サービス間の連携バグを重い E2E に頼らず捉えたいバックエンド開発者
向いていない人：
- 単体テストの書き方をまだ固めきれていない段階の人。本書はサービス境界をまたぐテスト戦略が主題で、テストの基礎は前提になる。先に『単体テストの考え方/使い方』のような原則書で足場を作る方が早い
- 外部に公開しない小規模なプライベート API だけを扱うチーム。リスク分析や契約テストの導入工数が、得られる効果に見合わないオーバーヘッドになりやすいという指摘がある
6. 導入が割に合わない場面
本書のコード例は Java を中心に組まれている。動的型付け言語で開発するチームには、サンプルを自分の言語へ読み替える手間が生じる。設計の考え方そのものは言語に依存しないので、原則を抜き出して読む分には困らないが、写経してそのまま動かす読み方には向かない。
もう一つは規模の問題だ。Tests・Requests・Payloads の 3 層設計は、大量のエンドポイントに対してデータクラスを手作業で定義しはじめると、その定義自体が工数になる。本書も Swagger や GraphQL のスキーマからの自動生成を併用する前提で書かれており、手書きだけで押し切ろうとすると 3 層分離の利点が薄れる。ツールの前提を外さずに読むのが実態に合う。
7. 読んだ後の最初の一歩
次の本を急ぐより、本書の枠組みを手元のプロジェクトで一度動かす方が定着が早い。最初の一歩は、担当している API のエンドポイントを発生確率とビジネス影響の 2 軸で並べ、上位のいくつかだけを「先に守る対象」として選ぶこと。すべてをテストしようとする発想を一度手放すのが狙いだ。
次に、既存のテストコードから通信処理とデータ構造を 1 つ切り出し、Requests・Payloads の層へ寄せてみる。仕様を 1 か所変えたときに壊れる範囲がどれだけ縮むかを、小さく確かめられる。契約テストは、サービス境界をまたぐ連携で実際に痛い目を見ている箇所から試すと、効果が見えやすい。
筆者の体験から
toBの業務システムでAPI自動テストを増やしていた時期、仕様変更のたびにテストが軒並み赤くなり、修正だけで一日が潰れる状態が続いていた。カバレッジは伸びても不具合が減った実感はなく、判断基準を持てないまま本書を読み始めた。
読んでからは、担当するAPI群を発生確率とビジネス影響の2軸で棚卸しし、全部を同じ熱量でテストするのをやめた。テストコードを検証・通信処理・データ構造に分ける考え方も、既存コードから通信処理を1つ切り出すところから試した。ただしコード例はJava中心で、Node/TypeScript環境への読み替えの手間はかかり、写経してそのまま動かす読み方はできなかった。
差を実感したのは、あるエンドポイント名が変更になったときだ。3層設計を導入済みの箇所は通信処理を切り出していたため直す場所が1箇所で済んだが、まだ分けていない別のエンドポイントでは従来どおりテストが広範囲に赤くなった。全部を一度にやり切れていなかったからこそ、その差がはっきり見えた出来事だった。
DevBookPath のマップで確認する
この本の学習パス上の位置づけ・前後の読書順は、DevBookPath のグラフで辿れます。
本記事のリンクには Amazon アソシエイト等の広告が含まれる場合があります。リンク経由の購入で運営者に紹介料が支払われることがあります。
この記事を共有
この地図を共有