不安定なAPIは、誰かがテストを忘れたために失敗することはめったにありません。テストが間違ったものを確認したか、200ステータスコード以外何も確認しなかったために失敗します。適切に書かれたAPIテストケースは、リリース前に契約の破損を検知できるか、それとも後で障害を説明することになるかの違いを生みます。
このガイドでは、APIテストケースとは何か、優れたテストケースに必要なフィールド、そしてゼロからテストケースを作成する方法を説明します。ログインエンドポイントの完全な作業例を見てから、スクリプトを書かずにApidogで同じテストを構築します。
APIテストケースとは何か
APIテストケースとは、特定のエンドポイントが特定の条件下で正しく動作することを確認するために使用される、定義された入力、アクション、および期待される結果のセットです。これはテストシナリオよりも範囲が狭いです。シナリオは「ユーザーログインを確認する」と言いますが、テストケースは「/auth/loginに有効な認証情報をPOSTし、800ミリ秒以内にボディにJWTを含む200レスポンスを確認する」と言います。
各ケースは単一の動作をターゲットとします。この焦点が重要です。広範で多目的なテストが失敗した場合、どの部分が壊れたのかを調査する必要があります。焦点を絞ったケースが失敗した場合、失敗の名前がその答えを教えてくれます。ケースがシナリオやスクリプトとどのように関連しているかまだ把握できていない場合は、テストシナリオ vs テストケースとテストケース vs テストスクリプトが明確に線引きしています。
APIテストは通常、5つの側面をカバーし、あなたのケースはそれらすべてにわたって広がるべきです。
- 機能性: エンドポイントは有効な入力に対して正しいデータを返すか？
- ネガティブ: 誤った入力に対して適切なエラーとステータスコードで拒否するか？
- パフォーマンス: 許容可能な時間内に応答するか？
- セキュリティ: 認証、認可、入力制限を強制するか？
- 契約: レスポンスは文書化されたスキーマと一致するか？
ハッピーパスのみをチェックするテストスイートは、実際のユーザーが空のパスワードフィールドを送信するまでは合格し続けます。
テストケーステンプレートが必要な理由
白紙の状態から各ケースを作成すると、一貫性のないカバレッジが生じます。あるエンジニアは期待されるステータスコードを記録し、別のエンジニアはレスポンスボディを記録し、3人目は「動作するはずだ」と書きます。テンプレートは、毎回同じ構造を強制することでこれを解決します。
共有テンプレートは、4つの具体的な利点をもたらします。すべてのケースが同じフィールドを持ち、ギャップが可視化されるため、カバレッジは監査可能になります。新しいテスターが5つの異なる形式ではなく1つの形式を読むため、オンボーディングが加速します。構造化されたケースは複製や調整が容易であるため、ケースはリリース間で再利用可能になります。そして、各ケースが要件やエンドポイントにリンクしているため、トレーサビリティが維持されます。
テンプレートは自動化も現実的にします。構造化されたケースは自動テストステップにきれいにマッピングされますが、曖昧なケースは機械が実行する前に書き直す必要があります。
強力なAPIテストケースの構成要素
完全なAPIテストケーステンプレートは、以下のフィールドを持ちます。すべてのケースでこれらすべてが必要なわけではありませんが、コアとなるセットは譲れません。
| フィールド | 目的 |
|---|---|
| テストケースID | 一意の参照、例: AUTH-LOGIN-001 |
| タイトル | テスト対象の動作を説明する1行 |
| エンドポイント | メソッドとパス、例: POST /auth/login |
| 事前条件 | 実行前に必要な状態、例: 「ユーザーが存在する」 |
| ヘッダー | 必須のリクエストヘッダー |
| リクエストボディ / パラメータ | 正確な入力ペイロード |
| 期待されるステータス | 期待するHTTPコード |
| 期待されるレスポンス | アサートするボディフィールド、スキーマ、または値 |
| 期待される応答時間 | レイテンシーの予算 |
| 優先度 | 重要、高、中、低 |
| テストタイプ | 機能、ネガティブ、セキュリティ、パフォーマンス |
チームが最も省略しがちなフィールドは、期待される応答時間と期待されるレスポンスボディです。これらを省略すると、空のペイロードで200が返されたり、正しいペイロードが3秒も遅れて返されたりしてもテストが「合格」してしまいます。
APIテストケースの作成手順
まずAPIドキュメントを読みます。必須パラメータ、認証方法、文書化されたステータスコード、レスポンススキーマをメモします。すべてのテストケースは文書化された動作に関する主張であるため、ドキュメントがあなたの信頼できる情報源です。OpenAPI仕様を読み込んでテストコレクションを生成するツールは、最初の骨格を提供できます。
テストに値する条件をリストアップします。単一のエンドポイントの場合、通常は次のようになります。有効な入力、それぞれ欠落している必須フィールド、それぞれ不正な形式のフィールド、未承認のリクエスト、期限切れのトークン、過大なペイロード。それぞれの条件が1つのケースになります。
明確なテストデータを準備します。ネガティブケースには、厳密に1つの方法で誤っているデータが必要です。ケース間で同じペイロードを再利用すると、常に1つのパスしか実行しないため、バグが隠れてしまいます。
期待される結果を正確に記述します。「成功を返す」はアサーションではありません。「200を返し、ボディに空でないtoken文字列が含まれ、expires_inが3600に等しい」がアサーションです。ここでの精度が、ケースを実行する価値を高めます。
実行可能なスイートにケースを追加します。スプレッドシート内のケースは意図を文書化しますが、テストツール内のケースは合否を生成します。関連するケースをグループ化して、エンドポイント全体がワンクリックで実行されるようにします。テストスイートはまさにこのために存在します。
ケースを最新の状態に保ちます。APIが変更された場合、ケースもそれに合わせて変更されます。古いスキーマをアサートする古いケースは、存在しないケースよりも悪いものです。なぜなら、間違った理由で失敗し、チームに赤いビルドを無視するように仕向けるからです。
作業例: ログインエンドポイントのテスト
標準的な認証エンドポイントを例にとります: POST /auth/login。これはメールアドレスとパスワードを受け取り、JWTを返します。以下に、これを適切にカバーする4つのケースを示します。
AUTH-LOGIN-001: 有効な認証情報 (機能、重要)
- エンドポイント:
POST /auth/login - 事前条件:
dana@example.comというメールアドレスを持つユーザーが存在する - ボディ:
{"email": "dana@example.com", "password": "Correct-Horse-9"} - 期待されるステータス:
200 - 期待されるレスポンス: ボディに空でない
token（文字列）が含まれ、token_typeがBearerに等しく、expires_inが3600に等しい - 期待される応答時間: 800ミリ秒未満
AUTH-LOGIN-002: 間違ったパスワード (ネガティブ、重要)
- ボディ:
{"email": "dana@example.com", "password": "wrong"} - 期待されるステータス:
401 - 期待されるレスポンス:
errorがinvalid_credentialsに等しく、tokenフィールドが存在しない - 注: メッセージはメールアドレスが存在するかどうかを明かしてはならない
AUTH-LOGIN-003: パスワードフィールドの欠落 (ネガティブ、高)
- ボディ:
{"email": "dana@example.com"} - 期待されるステータス:
400 - 期待されるレスポンス:
errorがvalidation_errorに等しく、detailsがpasswordフィールドの名前を指す
AUTH-LOGIN-004: 不正な形式のメールアドレス (ネガティブ、中)
- ボディ:
{"email": "not-an-email", "password": "Correct-Horse-9"} - 期待されるステータス:
400 - 期待されるレスポンス:
errorがvalidation_errorに等しい
4つのケースで1つのエンドポイントに対し、契約、エラーの形状、ステータスコード、レイテンシー予算をすでにチェックしています。メールフィールドにSQLインジェクション文字列を含むセキュリティケースを追加すれば、コミットごとに実行する価値のあるスイートが完成します。
Apidogで同じテストケースを作成する
上記の4つのケースは、一行のスクリプトも書かずにすべて実行できます。Apidogでは、APIテストケースは視覚的に構築されます。
- エンドポイントをインポートまたは定義します。OpenAPIファイル、Postmanコレクションから
POST /auth/loginを取り込むか、直接定義します。リクエストスキーマがすべてのアサーションの基礎となります。 - リクエストデータを追加します。ケースAUTH-LOGIN-001のボディを入力します。データ駆動型のカバレッジについては、CSVまたはJSONファイルを添付することで、1つのケースがすべての認証情報行に対して実行されます。これが、データ駆動型APIテストがほぼ同じ4つのケースを1つに置き換える方法です。
- アサーションを視覚的に設定します。クリックして、ステータスが200に等しいこと、
tokenが存在し空でない文字列であること、expires_inが3600に等しいこと、および応答時間が800ミリ秒未満であることをアサートします。スクリプトは不要です。 - ケースをテストシナリオにグループ化します。4つのログインケースすべてを1つのシナリオに追加し、エンドポイントが単一の実行で完全にテストされるようにします。
- 実行してレポートを読みます。Apidogはシナリオを実行し、ケースごとの合否レポートを生成し、問題が発生した正確なアサーションを特定します。シナリオはローカルで、スケジュールで、またはCI内で実行できます。
スクリプト作成が間違っているということではありません。構造化された視覚的なケースの方が、作成が速く、レビューが容易で、微妙な間違いが起こりにくいということです。コードが必要な場合でも、Apidogではカスタムスクリプトを記述できます。完全にスクリプト不要のワークフローについては、PostmanなしのAPIテストでより広範なアプローチを説明しています。
避けるべきよくある間違い
ステータスコードのみをアサートすること。200はリクエストが処理されたことを意味し、レスポンスが正しかったことを意味しません。常にボディフィールドをアサートしてください。
エンドポイントごとに1つの巨大なケースを作成すること。失敗しても何も学習できません。条件ごとに分割してください。
テストデータを再利用すること。すべてのネガティブケースで同じペイロードを送信すると、テストするのは1つの失敗モードだけになります。
レイテンシーのアサーションがないこと。応答時間を測定しないと、パフォーマンスの回帰が静かにすり抜けてしまいます。
自動化されないケース。ランナーが実行しない文書化されたケースは、テストではなくコメントです。ケースを実行するスイートに移動させ、すべてのビルドで実行されるようにしてください。OpenAPI仕様からテストスクリプトを生成するのは、そのスイートを迅速にブートストラップする方法です。
例に従って4つのログインケースを自分で構築したい場合は、Apidogをダウンロードしてください。
よくある質問
1つのエンドポイントにはいくつのテストケースが必要ですか？ハッピーパス、すべての必須フィールドの失敗、1つの認証失敗、1つのセキュリティプローブをカバーするのに十分な数です。シンプルなエンドポイントであれば4〜6ケース、複雑なエンドポイントであればそれ以上になることもあります。
APIが構築される前にケースを作成すべきですか？はい。設計に対して、デザインファーストでケースを作成することで、契約のギャップを早期に発見できます。これをAIアシストによるテストケース生成と組み合わせることで、最初のセットを迅速に作成し、手動で洗練させることができます。
ケースを保存するにはスプレッドシートとテストツールのどちらが良いですか？スプレッドシートは意図を文書化しますが、実行することはできません。ケースは実行して結果を報告するツールに保存し、常にケースがグリーンまたはレッドになるようにしてください。
テストケースとテストシナリオの違いは何ですか？シナリオは高レベルの目標（「ログインを確認する」）であり、ケースはその中の具体的で実行可能な1つのチェックです。テストシナリオ vs テストケースを参照してください。