Apidog CLIからAPIテストを実行する方法

あなたのAPIテストはラップトップ上では合格しました。しかし、誰かが午前2時に変更をマージすると、ステージング環境のエンドポイントが不正なペイロードを返すようになり、翌朝顧客からチケットが届くまで誰も気づきません。テストは存在していたのです。ただ、それが本当に重要な場所、つまりパイプライン内で、プッシュのたびに、人間がボタンをクリックすることなく実行されることはありませんでした。

「存在するテスト」と「自動的に実行されるテスト」の間のギャップを埋めるのが、まさにコマンドラインランナーです。Apidog CLIは、Apidogのデスクトップまたはウェブアプリで既に構築したテストシナリオを、ターミナルからヘッドレスで実行します。GUIも手動クリックも不要です。npmコマンド一つでインストールし、テストシナリオを指定するだけで、クリーンなステータスコードと、任意のCIシステムで公開できるレポートを出力します。これにより、ビジュアルテストビルダーとCI/CDプラットフォームの間の架け橋となります。

要点

• Apidog CLIは、`apidog-cli`というnpmパッケージです。`npm install -g apidog-cli`でグローバルにインストールし、`apidog run`コマンドでシナリオを実行します。
• Apidogで設計したテストシナリオを実行します。テストをコードとして書き直す必要はなく、CLIは認証用のアクセストークンを使用して、IDで同じシナリオを実行します。
• 基本的な実行方法：`apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenarioId> -e <environmentId> -n 1 -r html,cli`。
• レポーターは`cli`、`html`、`json`、`junit`に対応しています。JUnit XMLはCIテストダッシュボードに直接連携できます。
• テスト失敗時のゼロ以外の終了コードが、CLIを真の品質ゲートにします。デフォルトでは、失敗したテストはビルドを失敗させます。
• Node.jsがインストールされているあらゆるCIランナーで動作します：GitHub Actions、GitLab CI、Jenkins、CircleCI、Azure Pipelinesなど。

Apidog CLIとは何か

ApidogはオールインワンのAPIプラットフォームです。単一のワークスペースで、スキーマ設計、リクエストデバッグ、自動テストシナリオ構築、エンドポイントモック、ドキュメント公開が可能です。そのほとんどの作業はビジュアルインターフェースで行われます。リクエストをテストシナリオにチェーンし、アサーションを追加し、あるレスポンスから次のレスポンスへ値を取り込み、データファイルをループ処理します。

CLIは、これらのシナリオのヘッドレスな実行エンジンです。独自のテスト形式を持つわけではありません。Apidogプロジェクトにアクセスし、IDで指定されたシナリオを見つけ、アプリが実行するのと全く同じように実行し、結果を報告します。これはビルドツールとソースコードの関係に似ています。真の情報源はプロジェクト内にあり、CLIは人が関与することなくそれを実行するものです。

これが重要なのは、APIテストが陳腐化する最も一般的な原因を取り除くからです。テストがデスクトップアプリのクリック可能なステップとしてのみ存在する場合、誰かが思い出したときにしか実行されません。しかし、1行のコマンドから実行できるようになれば、パイプラインに組み込み、コミットごと、マージごと、毎晩のスケジュールで実行できます。ビジュアルビルダーは迅速な作成を可能にし、CLIは自動化を提供します。これら両方を、どちらかを選ぶことなく手に入れることができます。

Postmanのユーザーであれば、この考え方はスムーズに理解できるでしょう。Apidog CLIは、Postman CLIやNewmanがPostmanコレクションに対して果たす役割を担いますが、Apidogテストシナリオを実行し、単一パッケージとして提供されます。Postman CLIとNewmanの比較についてはPostman CLI vs Newmanで詳しく、移行中の場合はNewmanなしでCIでコレクションを実行するというより広範な疑問についても取り上げています。

前提条件

コマンドを実行する前に、3つのものが必要です。

1. Node.js v16以降。CLIはnpmパッケージとして提供されるため、Nodeランタイムが唯一のシステム依存です。`node -v`でバージョンを確認してください。Node 16+を搭載したCIイメージであればどれでも利用可能です。
2. Apidogテストシナリオ。CLIは単独のリクエストではなく、シナリオを実行します。まずApidogアプリでシナリオを構築してください。リクエストをチェーンし、アサーションを追加し、必要に応じてデータ駆動型イテレーションを設定します。アサーションの作成が初めての場合は、APIアサーション：実践ガイドでレスポンスの検証方法を解説しています。
3. アクセストークン。これはCLIをApidogアカウントに認証させ、シナリオを取得・実行できるようにするためのものです。テストシナリオのCI/CDタブ内で生成します。詳細は以下をご覧ください。

それだけです。CI環境にApidogを別途インストールする必要も、GUIもライセンスファイルも不要です。パッケージとトークンがあれば十分です。

Apidog CLIのインストール

npmでグローバルにインストールします。

npm install -g apidog-cli

次に、すべてが正しく解決されたことを確認します。

node -v && apidog -v && which node && which npm && which apidog

バージョン番号とパスが表示されれば完了です。バイナリは`apidog`なので、すべてのコマンドは`apidog run`で始まります。

開発者のマシンでは、グローバルインストールで問題ありません。CIでは、2つの合理的なパターンがあります。1つ目は、各パイプライン実行で新たにインストールする方法で、常に最新バージョンであることを保証します。

npm install -g apidog-cli
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli

2つ目は、`npx`を介して永続的なグローバルインストールなしで実行する方法で、ランナーのグローバルパッケージを変更することを回避します。

npx apidog-cli run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli

どちらも動作します。`npx`アプローチは、一時的なCIランナーにとってはよりクリーンです。グローバルインストールは、実行間でキャッシュされる場合、わずかに高速です。

アクセストークンとシナリオIDの取得

CLIは、どのシナリオを実行するか、そしてそれを実行する権限があるかの2つのことを知る必要があります。Apidogが両方を生成してくれるため、UIを探し回る必要はありません。

自動化したいテストシナリオを開きます。CI/CDタブに切り替えます。コマンドラインオプションを選択し、「アクセストークンを追加」と「トークンを生成」をクリックします。Apidogは、アクセストークン、シナリオID、環境IDが既に入力された完全な`apidog run`コマンドを生成します。そのコマンドをクリックしてコピーしてください。

生成されたコマンドが正規の開始点です。次のようになります。

apidog run --access-token YOUR_ACCESS_TOKEN -t 605067 -e 1629989 -n 1 -r html,cli

これらの数字はプロジェクトの実際のIDです。`605067`はテストシナリオID、`1629989`は環境IDです。これらを手動で入力することはほとんどありません。一度CI/CDタブからコピーし、その後トークンをパラメータ化します。

早期に述べておくべき一つのルール：アクセストークンはパスワードのように扱ってください。コミットされた設定ファイルや公開されたパイプライン定義に貼り付けないでください。CIシステムにシークレットとして保存し、環境変数として参照してください。以下のすべての例で`$APIDOG_ACCESS_TOKEN`を使用しているのは、まさにこのためです。

apidog runコマンド、フラグごとの解説

CLI全体は一つのコマンドを中心に展開されます。ここでは、各グループが制御するものごとに分類された完全なオプション一覧を示します。

実行対象の選択

スコープに応じて、`-t`、`-f`、または`--test-suite`のいずれかを選択します。集中的なスモークテストには単一のシナリオ、特定の機能領域にはフォルダ、キュレーションされたシナリオセットを一つの論理的なジョブとして実行したい場合にはテストスイートを使用します。

認証

これはすべてのCIコマンドに必要な唯一のフラグです。シークレットから渡すようにし、インラインでは決して使用しないでください。

環境とイテレーション

環境フラグは、シナリオを複製することなく、プルリクエストチェックでステージング環境を、デプロイ後のスモークテストで本番環境を対象とする方法です。イテレーションデータは、一つのシナリオを50行の入力データで実行し、各行を別々のパスとして扱う方法です。テストスイートで自動APIテストをスケーリングするガイドで、データ駆動型パターンについて詳しく解説しています。

レポート

ここがCLIがパイプライン内でその価値を発揮する場所です。複数の形式をカンマ区切りで一度に渡すことができます。

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -r html,junit --out-dir ./test-reports

`cli`は、ビルドログを読む人間にとって読みやすいターミナル出力を提供します。`html`は、ビルドアーティファクトとしてアーカイブし、ブラウザで開くことができる自己完結型レポートを生成します。`junit`は標準のJUnit形式でXMLを出力し、ほとんどすべてのCIダッシュボードがこれをパースして合否ツリーに表示できます。`json`は、後処理が必要な場合に生の構造化された結果を提供します。

エラー処理と終了時の動作

`--on-error`は、シナリオ実行中に何が起こるかを制御します。`end`は最初の失敗で実行を停止し、これは高速に失敗するスモークテストで通常望まれる動作です。`continue`はすべてのステップを実行するため、すべての失敗を一つのレポートで確認できます。`ignore`は、ステップが不安定であることが分かっており、実行を中断させたくない稀なケースで使用します。

TLSと証明書

相互TLSの背後にあるエンドポイントや内部CAチェーンを持つエンドポイントをテストする際にこれらを使用してください。`-k`は、証明書が自己署名されている信頼された内部ホストに対してのみ、最後の手段として使用し、公開されたものには決して使用しないでください。

出力と診断

`--verbose`は、ローカルではテストがパスするのにCIで失敗する場合の最初の対処法です。ランナーが送信した正確なリクエストと受け取った正確なレスポンスが表示されます。`--silent`は、終了コードと保存されたレポートのみに関心がある、騒がしい夜間ジョブ向けです。

終了コード：CIを機能させる部分

テストランナーは、テストがパスしたかどうかをパイプラインに伝える場合にのみ、パイプラインで役立ちます。Apidog CLIは、すべての適切に動作するコマンドラインツールと同様に、すべてのアサーションがパスした場合はコード0で終了し、何かが失敗した場合はゼロ以外のコードで終了します。

この一つの挙動が、`apidog run`を品質ゲートに変えます。CIシステムは各ステップの終了コードを読み取ります。ゼロ以外の終了コードはステップを失敗とマークし、それがジョブを失敗させ、マージやデプロイをブロックします。追加の設定は不要です。`apidog run`ステップがパイプラインにある限り、テストの失敗はプロセスを停止させます。

これは`--on-error`で調整できます。デフォルトの動作では最初のアサーション失敗で失敗し、迅速なフィードバックを維持します。ビルドが赤くなる前にすべての失敗を一つのレポートで確認したい場合は、`--on-error continue`に切り替えてください。いずれの方法でも、何かが失敗すれば実行はゼロ以外の終了コードで終了するため、ゲートは機能します。

GitHub Actionsでの実行

すべてのプルリクエストでApidogシナリオを実行し、レポートをアーティファクトとして公開する完全なワークフローです。

name: API tests

on:
 pull_request:
 branches: [main]

jobs:
 api-tests:
 runs-on: ubuntu-latest
 steps:
 - name: Checkout
 uses: actions/checkout@v4

 - name: Set up Node.js
 uses: actions/setup-node@v4
 with:
 node-version: '20'

 - name: Install Apidog CLI
 run: npm install -g apidog-cli

 - name: Run API test scenario
 run: |
 apidog run \
 --access-token "$APIDOG_ACCESS_TOKEN" \
 -t 605067 \
 -e 1629989 \
 -n 1 \
 -r html,junit \
 --out-dir ./apidog-reports
 env:
 APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}

 - name: Upload report
 if: always()
 uses: actions/upload-artifact@v4
 with:
 name: apidog-report
 path: ./apidog-reports

トークンはリポジトリのシークレットに保存され、環境変数としてステップに渡されます。アップロードステップの`if: always()`は、テストが失敗した場合でもレポートを取得できることを意味し、まさにその時にレポートを読みたいものです。テストが失敗すると、`apidog run`ステップはゼロ以外のコードで終了し、ジョブが失敗（赤色表示）となり、PRには失敗したチェックが表示されます。

GitLab CIでの実行

`.gitlab-ci.yml`での同じパターンです。

stages:
 - test

api-tests:
 stage: test
 image: node:20
 script:
 - npm install -g apidog-cli
 - >
 apidog run
 --access-token "$APIDOG_ACCESS_TOKEN"
 -t 605067
 -e 1629989
 -r junit,cli
 --out-dir ./apidog-reports
 artifacts:
 when: always
 paths:
 - apidog-reports/
 reports:
 junit: apidog-reports/*.xml

2つの注意点があります。`APIDOG_ACCESS_TOKEN`は、ファイル内ではなく、Settingsの下でマスクされ保護されたCI/CD変数として保存してください。また、`reports: junit:`ブロックは、GitLabにJUnit XMLをパースして、マージリクエストウィジェットに結果を表示するよう指示するため、レビュー担当者は何もダウンロードすることなく、どのアサーションが失敗したかを確認できます。

Jenkinsでの実行

宣言型パイプラインでは、トークンをJenkinsのクレデンシャルまたはグローバル環境変数として保存し、ステージ内でCLIを呼び出します。

pipeline {
 agent any
 environment {
 APIDOG_ACCESS_TOKEN = credentials('apidog-access-token')
 }
 stages {
 stage('API tests') {
 steps {
 sh 'npm install -g apidog-cli'
 sh 'apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -n 1 -r html,junit --out-dir apidog-reports'
 }
 }
 }
 post {
 always {
 junit 'apidog-reports/*.xml'
 archiveArtifacts artifacts: 'apidog-reports/', allowEmptyArchive: true
 }
 }
}

ビルドエージェントにCLIが既にインストールされキャッシュされている場合は、`npm install`行を削除して`apidog run`を直接呼び出してください。`post`ブロックの`junit`ステップは、XMLをJenkinsのテストトレンドグラフに供給し、`archiveArtifacts`はHTMLレポートをビルドに添付します。Jenkinsと他のランナーを比較検討している場合は、ReadyAPI Jenkins CIセットアップとよりシンプルな代替案でトレードオフについて説明しています。

一般的なパターンとレシピ

デプロイ後のスモークテスト。リリース直後に本番環境を対象として、一つの高速なシナリオを実行します。

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e <prodEnvId> -r cli --on-error end

夜間フル回帰テスト。スケジュールに基づいてシナリオのフォルダ全体を実行し、すべての失敗を一つのレポートにまとめます。

apidog run --access-token $APIDOG_ACCESS_TOKEN -f <folderId> -r html,junit --on-error continue --out-dir ./nightly-reports

データ駆動型実行。テストケースのCSVファイルに対して一つのシナリオをループ実行します。

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -d ./test-data.csv -r junit

ブランチ固有のチェック。`main`ではなく、フィーチャーブランチ上に存在するシナリオを実行します。

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 --branch feature-payments -e 1629989 -r cli

CIのみの失敗をデバッグする。ローカルではシナリオがパスするのにパイプラインで失敗する場合、`--verbose`を追加して、ランナーが生成した正確なワイヤレベルのリクエストとレスポンスを確認します。

トラブルシューティング

認証エラー。認証エラーで実行が失敗する場合、トークンが間違っているか、期限切れか、またはコマンドに届いていません。マスクされたチェック（完全なトークンは決して表示しない）で確認し、CIシークレットが実際に設定されていることを確認してください。必要であれば、シナリオのCI/CDタブからトークンを再生成してください。

「シナリオが見つかりません」。シナリオID、プロジェクトID、またはブランチが一致していません。CI/CDタブからコマンドを再コピーしてIDが最新であることを保証し、`--branch`が意図した場所を指していることを確認してください。

ローカルではテストがパスするのにCIで失敗する。ほとんどの場合、環境の違いが原因です。CIランナーが異なる`-e`環境をターゲットにしているか、到達できないホストにアクセスしているか、シナリオが依存する変数が不足している可能性があります。`--verbose`で実行し、CIランナーが送信したリクエストとローカルで送信したものを比較してください。

内部ホストに対するネットワークまたはTLSの失敗。エンドポイントが内部CAを使用している場合、`--ssl-extra-ca-certs`を渡してください。`-k`は、証明書が自己署名されている信頼された内部ホストに対してのみ、最後の手段として使用してください。

テストが失敗するはずなのにビルドがグリーンなまま。`apidog run`ステップの終了コードが実際にCIに到達しているか確認してください。シェルパイプラインでラップしたり、`|| true`を追加したりしている場合、ゼロ以外の終了コードが隠蔽され、ゲートが機能しなくなります。終了コードをマスクするものはすべて削除してください。

Apidog CLIが実際のワークフローにどのように適合するか

CLIはループの一部です。Apidogアプリでリクエストを設計・デバッグします。それらをアサーションとともにシナリオにチェーンします。作業をコミットすると、CLIは変更のたびにCIでそのシナリオを実行します。何かが壊れた場合、レポートはどのアサーションが失敗したかを伝え、終了コードがデプロイを停止します。修正し、再度プッシュすると、同じゲートが修正を確認します。

テストを視覚的に構築し、ヘッドレスで実行する利点は、誰も同じテストの2つの表現を維持する必要がないことです。プロジェクト内のシナリオがテストそのものです。CLIは人間がいない場所でそれを実行するだけです。これは、テストとその実行が同じ脆弱なファイルであるスクリプトファーストのランナーとは異なるモデルであり、チームがAPIテストのためのPostmanの代替としてApidogに移行する大きな理由の一部です。

まだテストを構築していない場合は、アプリから始めて、一つのシナリオを合格させ、その後CI/CDタブからCLIコマンドを設定してください。Apidogをダウンロードして最初の自動化シナリオを設定すれば、その日のうちにパイプラインをゲートできるようになります。

よくある質問

Apidog CLIは無料ですか？CLI自体は無料のnpmパッケージです。`npm install -g apidog-cli`でインストールできます。Apidogプロジェクトのテストシナリオを実行するため、実行できる内容はApidogプランに依存しますが、コマンドラインランナーは別途有料の製品ではありません。

CLIを使用するためにテストをコードとして書き直す必要がありますか？いいえ、その必要はありません。これがスクリプトファーストのランナーとの主な違いです。Apidogでシナリオを視覚的に構築し、CLIはそれらをIDで実行します。シナリオがテストであり、CLIは単なる実行エンジンです。

Apidog CLIとNewmanの違いは何ですか？NewmanはコマンドラインからPostmanコレクションを実行します。Apidog CLIはApidogテストシナリオを実行します。役割は似ていますが、ApidogランナーはApidogアプリで作成したシナリオを実行し、単一の`apidog-cli`パッケージとして提供されます。この比較のPostman側の詳細については、Postman CLI vs Newmanをご覧ください。

CIではどのレポート形式を使用すべきですか？CIダッシュボードが合否ツリーにパースする機械可読な結果には`junit`を使用し、ビルドアーティファクトとして保存されるブラウザで閲覧可能なレポートが必要な場合は`html`を追加してください。一般的な選択肢は`-r html,junit`です。ビルドログに読みやすい出力が必要な場合は、`cli`もオンにしておいてください。

CLIはどのようにビルドを失敗させますか？その終了コードを介して行われます。いずれかのアサーションが失敗すると、`apidog run`はゼロ以外のコードで終了します。CIシステムはその終了コードを読み取り、ステップを失敗とマークし、マージやデプロイをブロックします。これを機能させるために特別な設定は不要です。

CLIをグローバルインストールせずに実行できますか？はい。永続的なグローバルインストールなしで実行するには`npx apidog-cli run ...`を使用します。これは一時的なCIランナーで便利です。

必要なNode.jsのバージョンは何ですか？Node.js v16以降が必要です。Node 16+がインストールされている現代のCIイメージであれば、この要件を満たします。

アクセストークンとシナリオIDはどこで入手できますか？** 両方ともApidogのテストシナリオのCI/CDタブから取得できます。コマンドラインオプションを選択し、アクセストークンを生成し、ApidogがIDを記入して作成した完全な`apidog run`コマンドをコピーしてください。その後、トークンをCIシークレットに移動します。