ほとんどのAPIテストは一本道で実行されます。ログインを呼び出し、チェックアウトを呼び出し、レシートのエンドポイントを呼び出し、途中でアサートを行います。これは、次のステップが依存する形でステップが失敗するまではうまくいきます。ログインが401を返した場合、チェックアウトのリクエストを実行しても無意味です。さらに悪いことに、2番目の誤解を招く失敗の裏に本当の失敗を隠してしまいます。あなたが望むのは、ログイン応答を読み取り、続行するかどうかを判断し、どこで問題が発生したかの真実を報告するテストです。
その判断は条件ロジックであり、フロー制御で構築します。このガイドでは、ApidogのAPIテストシナリオにif/else分岐を追加して、以前の応答に基づいて実行を分岐させる方法を示します。実際のシナリオを構築します。ログインし、ステータスコードを確認し、ログインが実際に機能した場合のみチェックアウトに進みます。Apidogシナリオが初めての方は、Apidogでテストシナリオを作成する方法のウォークスルーが、この記事の基礎となる直線的な基本をカバーしています。分岐パターンの定義については、MDNの条件文に関するガイドが良い入門書です。Apidogをダウンロードして無料で試すことができます。
フロー制御とは何か、そうでないものとは何か
Apidogでは、自動テストはテストモジュールにあります。作業の単位はテストシナリオで、ドキュメントではPostmanのコレクションに似ていると説明されています。シナリオ内ではテストステップを配置します。各ステップは、個々のリクエスト、または分岐、ループ、遅延などのフロー制御要素のいずれかです。
フロー制御は、フロー制御要素のセットです。これにより、シナリオは単にリクエストを順番に実行する以上のことができます。フロー制御と条件分岐に関するApidogドキュメントは、ここで使用されているすべてのラベルの参照元です。この記事が焦点を当てるのは、Apidogでif/elseと呼ばれる条件分岐です。分岐は、与えられた値を読み取り、その値を条件と照合し、条件が成立したときに一連のステップを実行し、成立しなかったときには別のステップを実行します。
混乱しやすい点があるので、最初に一つ明確にしておきます。分岐はループではありません。分岐は、ステップのブロックが実行されるかどうかを一度決定します。ループはブロックを何度も実行します。Apidogには、ForループとForEachループと呼ばれる反復のための別の機能があり、これらは別の問題、つまり範囲または配列内の項目にわたって同じリクエストを繰り返すことに属します。注文IDの配列を順に処理する必要がある場合、それはForEachループチュートリアルでカバーされているForEachループであり、分岐ではありません。このガイドはif/elseに限定されます。
Apidogのドキュメントには、フロー制御、条件分岐、ループ、またはステップ間のデータ受け渡しに関する無料版と有料版の制限は記載されていません。これらの機能について、クラウド版と自己ホスト版の区別もありません。シナリオを構築できるなら、そこに分岐を追加できます。
ログイン応答に基づいて分岐するシナリオを構築する
目標は次のとおりです。ユーザーがログインします。ログインエンドポイントが200を返した場合、シナリオはチェックアウトの作成に進みます。それ以外を返した場合、シナリオは停止し、チェックアウトが実行されたかのように振る舞う代わりに失敗を報告します。
ステップ1: テストシナリオを作成する
Apidogを開き、テストモジュールに移動します。検索バーの横にある`+`をクリックして新しいテストシナリオを作成し、保存するディレクトリを選択し、優先度を設定して作成を完了します。これで、ステップを追加する準備ができた空のシナリオができました。
ステップ2: ログインリクエストを最初のステップとして追加する
最初のテストステップを追加します。Apidogには、リクエストを取り込むいくつかの方法があります。既存のエンドポイント仕様からインポートする、保存されたエンドポイントケースからインポートする、直接カスタムリクエストを追加する、またはcURL文字列から追加する方法です。手早く始めるには、カスタムリクエストを追加してください。それをPOSTに設定し、JSONボディと共に認証エンドポイントに向けます。
POST https://api.your-store.com/v1/login
Content-Type: application/json
{
"email": "dana@example.com",
"password": "correct-horse-battery-staple"
}
このステップを一度単独で実行し、期待どおりの結果が返されることを確認します。正常なログインは200とトークンをボディに返します。例:
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"userId": "usr_10482"
}
ステップ3: オーケストレートモードに入る
任意のステップをクリックして、オーケストレートモードに入ります。左側のパネルにはシナリオ全体のフローが表示され、右側のパネルには選択したステップの詳細が表示されます。この分割ビューで分岐を配置します。ステップを並べ替える必要がある場合は、ステップ上の`≡`アイコンをドラッグして移動します。
ステップ4: 条件分岐を追加する
`Add Step`ボタンをクリックします。これは、フロー制御要素を挿入する主要な方法です。メニューから`Conditional Branching`を選択します。これにより、If文、条件と実行するいくつかのステップを待つ空の分岐が作成されます。
次に条件を構築します。ログイン応答のステータスコードを分岐に渡す必要があります。Apidogは、固定された判断演算子のセットから条件を構築します。完全なリストは次のとおりです: 等しい、等しくない、存在する、存在しない、より小さい、以下、より大きい、以上、正規表現と一致する、含む、含まない、空である、空でない、リスト内にある、リスト内にない。
この分岐では、ログインステータスコードが200と等しくなることを望みます。したがって、条件は次のようになります: ログイン応答ステータスが`Equals` `200`。
ステップ5: 条件で前の応答を参照する
ログイン結果を条件フィールドに入れるには、2つの方法があります。
最初の方法は設定不要です。条件の値フィールドをクリックし、魔法の杖のアイコンをクリックして、「Retrieve pre-step data」を選択します。Apidogでは、以前のログインステップを直接指定し、その応答から値を取り出すことができます。内部的には、`{{$.<ステップID>.response.body.<フィールドパス>}}`という構文でプレステップ参照が使用されます。たとえば、ステータスではなくログインボディからトークンが必要な場合は、`{{$.1.response.body.token}}`を参照します。ここで`1`はログインステップのIDです。
「Retrieve pre-step data」について知っておくべきことが2つあります。これはテストモジュールでのみ機能し、APIモジュールでは機能しません。また、シナリオ全体を実行した場合にのみ解決され、単一のステップを個別に実行した場合には解決されません。単独実行中にプレステップ参照が空に見えても、それは予期された動作です。シナリオ全体を実行すれば、値が埋め込まれます。
2番目の方法は、名前付き変数を使用し、テストモジュールとAPIモジュールの両方で機能します。ログインリクエストで、ポストプロセッサを開き、「Extract Variable」アクションを追加します。JSONPath式（例：`$.token`）で関心のあるフィールドを抽出し、Apidogはそれを名前の下に保存します。その後、`{{token}}`としてどこからでも参照できます。これは、同じ値を複数のモジュールや複数の分岐で利用したい場合に、より移植性の高いアプローチです。ステップ間で値を移動する詳細なメカニズムは、テストステップ間でデータを渡す方法に関するガイドでカバーされています。
ステータスコード分岐の場合、ログインステップのステータスに対する「Retrieve pre-step data」が最短経路です。
ステップ6: Else分岐を追加する
Ifブロックにカーソルを合わせ、`+ Else`をクリックします。これにより、条件が偽の場合（つまり、ログインが200を返さなかった場合）に実行される代替パスが提供されます。
次に、両方のサイドを埋めます。
- Ifブロック内に、チェックアウトリクエストをテストステップとして追加します。これは正常なパスです。ログインが200を返した場合にのみ実行されます。チェックアウトがログイントークンを必要とする場合、ここで`{{token}}`（抽出した場合）またはログインボディへのプリステップ参照で参照します。実際のチェックアウト呼び出しは、多くの場合、`Authorization`ヘッダーにベアラートークンを運びます。Stripe APIドキュメントも認証されたリクエストで同じパターンを使用しています。
- Elseブロック内に、失敗を明確にするステップを追加します。一般的な選択肢は、ロギングまたは通知エンドポイントへのリクエスト、または常に失敗するアサーションを持つカスタムリクエストを追加して、シナリオレポートがこの実行を明確に失敗としてマークするようにすることです。
これでシナリオは、次のような明確なロジックとして読み取れます。ログインが200と等しければ、チェックアウトを実行する。そうでなければ、報告して停止する。
ステップ7: 保存
「Save All」をクリックしてシナリオを永続化します。保存されていない変更には点のインジケーターが表示されるので、その点が見える場合は、まだ作業が残っています。シナリオ全体を実行し、分岐が解決されるのを確認します。ログインを有効な認証情報に向けた場合、Ifブロックが実行されます。不正な認証情報に向けた場合、代わりにElseブロックが実行されます。
バリエーションと高度なフロー制御
基本的な分岐が機能すれば、同じ構成要素で多くのことがカバーできます。
ステータスだけでなく、ボディフィールドでも分岐する。ステータスコードは一般的なケースですが、条件は参照可能な任意の値で読み取ることができます。例えば、ログインがロックされたアカウントでも200を返し、実際の状態が`status`フィールドにあるとします。その場合、`{{$.1.response.body.status}}`を取得し、`Equals`演算子を`"active"`に対して使用するか、メッセージ文字列に対して`Contains`を使用します。演算子リストには範囲チェックもあります。返された残高に対して`Greater than`、返された役割が許可されたいくつかの値のいずれかであるかをテストするために`In List`を使用できます。
分岐とループを組み合わせる。分岐と繰り返しは組み合わせることができます。製品IDの配列に対するForEachループ内で、条件分岐ステップを使用して在庫切れの製品をスキップし、残りを処理することができます。ループインデックス参照`{{$.<ループステップID>.index}}`は0から始まり、ForEach要素は`{{$.<ループステップID>.element.<フィールドパス>}}`です。ループはそれ自体が別のトピックであり、ForEachループチュートリアルで詳しく説明されています。
Break Ifでループを早期に停止する。反復処理を行っている場合、`Break If condition`要素は条件が満たされ次第、ループを終了させます。ドラッグして位置を変更したり、ループ内で複数回追加したりできます。
On Errorでエラーを処理する。ループには、ループの開始時に固定された`On Error`要素があり、移動できません。そのオプションは、ループ内のリクエストがエラーになった場合に何が起こるかを決定します。`Ignore`は次のリクエストに進み、`Continue`は現在のサイクルで残りのリクエストをスキップし、`Break execution`はループを停止してその後に進み、`End execution`はシナリオ全体を停止します。
ステップ間に待機を追加する。場合によっては、ダウンストリームサービスが書き込みを反映するまでに少し時間が必要なことがあります。`Wait`要素はミリ秒単位の遅延を追加し、作成呼び出しとそれをチェックする読み取りの間に役立ちます。
スクリプト内で値を参照する。分岐に演算子リストでは複雑すぎるロジックが必要な場合、プリプロセッサまたはポストプロセッサースクリプトがそれを計算できます。スクリプト内では、`{{variable}}`構文を直接使用することはできません。代わりに、ステップIDとフィールドパスに一致する`pm.variables.get("$.2.response.body.token")`を使用します。1つのリクエストが次のリクエストに供給されるようにリクエストを連鎖させるというより広範なパターンについては、リクエストチェーンに関するガイドと、APIテストオーケストレーションとデータ受け渡しに関するより深い記事を参照してください。
自己参照に関する注意：シナリオは元のテストシナリオ自体を参照することはできません。このガードは、シナリオをネストしたときに誤って無限ループが発生するのを防ぎます。
Apidog CLIでワークフローを自動化する
構築したシナリオは、アプリ内だけで実行する必要はありません。Apidogは、保存されたシナリオをヘッドレスで実行するコマンドラインランナーを提供しており、これはCIでまさに望ましい機能です。インストールしてサインインします。
npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
次に、環境を指定し、レポーターを選択して、IDで分岐シナリオを実行します。
apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli
ここで`-t`はテストシナリオID、`-e`は環境ID、`-r`はレポーターです。コンソール出力には`cli`を、パイプラインで公開できる成果物には`html`や`junit`を使用します。これらを`html,cli`のようにカンマで区切ることで、複数同時に出力できます。分岐はアプリ内と同じように解決されます。ランナーはログイン応答を読み取り、IfまたはElseのパスを取り、終了コードは結果を反映するため、ログイン失敗はビルド失敗となります。完全な設定はApidog CLIインストールガイドに記載されており、パイプラインへの接続はApidog CLI GitHub Actionsガイドでカバーされています。コミットごとにではなくタイマーで同じシナリオを実行したい場合は、ApidogでAPIテストをスケジュールする方法を参照してください。
よくある質問
Apidogにおける条件分岐とループの違いは何ですか？
条件分岐は、条件に基づいて一連のステップが実行されるかどうかを一度決定します。ループは、一連のステップを繰り返し実行します。ログインが成功した場合のみチェックアウトに進むなど、どちらか一方の決定がある場合は分岐を使用します。カウントまたは配列全体でリクエストを繰り返す必要がある場合は、ForまたはForEachループを使用します。ForEachループチュートリアルで反復処理全体がカバーされています。
`Retrieve pre-step data`参照が空で返されるのはなぜですか？
2つの一般的な原因があります。まず、`Retrieve pre-step data`はテストモジュールでのみ機能し、APIモジュールでは機能しません。次に、テストシナリオ全体を実行した場合にのみ解決されます。単一のステップを個別に実行した場合、参照はまだ何も指していません。シナリオ全体を実行すると値が埋められます。
ステータスコードだけでなく、応答ボディ内のフィールドで分岐できますか？
はい、可能です。`{{$.1.response.body.status}}`のようなプレステップ式でフィールドを参照するか、名前付き変数に抽出してから、`Equals`、`Contains`、`In List`などの演算子を選択します。参照できるあらゆる値が条件を駆動できます。これらの値をやり取りする方法は、テストステップ間でデータを渡す方法で説明されています。
条件ビルダーではなくスクリプト内で変数を使用するにはどうすればよいですか？
スクリプトでは`{{variable}}`構文は受け付けられません。プレプロセッサースクリプトまたはポストプロセッサースクリプトで、必要なステップIDとフィールドパスに一致する`pm.variables.get("$.2.response.body.token")`を使用します。
分岐は追加費用がかかりますか、または自己ホスト版が必要ですか？
Apidogのドキュメントには、フロー制御、条件分岐、ループ、またはデータ受け渡しに関するプラン制限は記載されておらず、これらの機能に関するクラウド版と自己ホスト版の区別もありません。シナリオを構築できるなら、そこに分岐を追加できます。
まとめ
直線的なテストは何か問題があることを伝えます。分岐テストはどこで問題が発生したかを伝え、成功しないパスでステップを無駄にすることを止めます。条件分岐ステップを追加し、`Retrieve pre-step data`または抽出された変数で以前の応答を供給し、Ifと`+ Else`を接続することで、シナリオは実際のAPIが行うように決定を下せるようになります。アプリで機能するようになれば、1つの`apidog run`コマンドが同じロジックをCIに持ち込みます。Apidogを無料で試してください。クレジットカードは不要です。そして、直線的なテストを考えるシナリオに変えましょう。