Apidog CLIチュートリアル：コマンドラインでREST APIをテストする方法（ステップバイステップ）

ほとんどのAPIテストはGUIから始まります。クリックしてアサーションを追加し、手動で実行します。これは、プッシュごとに、毎晩、あるいは誰も見ていないパイプライン内で同じテストを実行する必要があるまでは機能します。その時点で、タイプ、スクリプト、そしてCIにパイプできる単一のコマンドが必要になります。

そのコマンドがApidog CLIです。このチュートリアルでは、Apidog CLIのインストール、APIのインポート、環境設定、テストシナリオの構築、アサーション付きの実行、データの投入、レポートの収集といった、実際のREST APIをエンドツーエンドでターミナルからテストする手順を説明します。以下のすべてのコマンドと出力は、Apidog CLIバージョン2.2.2を実際の公開APIに対して実行した結果から得られたものであり、皆さんも同じように実行して同じ結果を得ることができます。

同じプラットフォームの視覚的な側面を見たい場合は、Apidogをダウンロードして、まずアプリでテストを設計することもできます。しかし、ここではすべてコマンドラインで行います。

構築するもの

restful-api.devという、/objectsリソースに対して実際のCRUD操作が可能な無料の公開REST APIをテストします。最終的に、以下のものが完成します。

OpenAPIファイルからシードされたApidogプロジェクト
オブジェクトを作成し、読み取り、削除する3ステップのテストシナリオと、各ステップでのアサーション
テストデータの行ごとにリクエストを繰り返すデータ駆動型実行
CLI、HTML、JSON、JUnitレポート、および共有可能なクラウドレポート

このフローはご自身のAPIにもスケールアップでき、CI/CDでAPIテストを実行するための基盤となります。

始める前に

Node.js 16以降とApidogアカウントが必要です。もし最初にランナーを比較しているなら、Apidog CLIは完全なテストシナリオを実行し、APIリソースをコードとして管理するという点で、NewmanやPostman CLIとは一線を画しています。

ステップ1：インストールとログイン

npmからCLIをグローバルにインストールします。

npm install -g apidog-cli@latest

インストールされていることを確認します。

apidog --version
# 2.2.2

次に認証を行います。Apidogアプリのアバター、アカウント設定、APIアクセストークンからトークンを取得し、以下を実行します。

apidog login --with-token <YOUR_TOKEN>

トークンは~/.apidog/config.tomlに保存されるため、マシンごとに一度だけ実行すれば十分です。現在のユーザーを確認します。

Apidog CLIのapidog user infoコマンドの出力スクリーンショット。ユーザー名、ID、所属チームなどの情報が表示されています。

すべてのコマンドは、successフラグと役立つagentHintsを含む構造化されたJSONを返します。これにより、出力をスクリプト化したり、jqにパイプしたりするのが簡単になります。

ステップ2：プロジェクトを作成する

プロジェクトを作成するチームを選択し、プロジェクトを作成します。

apidog team list
apidog project create --team 329562 --name "CLI Field Test"

Apidog CLIのプロジェクト作成コマンドの出力スクリーンショット。成功メッセージと新しいプロジェクトIDが表示されています。

新しいプロジェクトIDが返されます。

Apidog CLIのプロジェクトIDを取得するコマンドの出力スクリーンショット。

これをシェル変数に保存すると、このチュートリアルの残りの部分はコピー＆ペーストで実行できます。

PID=1314366   # あなたのプロジェクトIDに置き換えてください
apidog project get $PID

ステップ3：REST APIをインポートする

エンドポイントを手動で作成することもできますが、OpenAPIファイルをインポートする方が迅速であり、実際のプロジェクトの開始方法を反映しています。以下は、/objects CRUDエンドポイントを記述する小さな仕様です（objects-api.openapi.jsonとして保存してください）。

{
  "openapi": "3.0.3",
  "info": { "title": "Objects API", "version": "1.0.0" },
  "servers": [{ "url": "https://api.restful-api.dev" }],
  "paths": {
    "/objects": {
      "get":  { "summary": "List objects" },
      "post": { "summary": "Create object" }
    },
    "/objects/{id}": {
      "get":    { "summary": "Get object by id" },
      "put":    { "summary": "Update object" },
      "delete": { "summary": "Delete object" }
    }
  }
}

これをインポートします。

apidog import --project $PID --format openapi --file ./objects-api.openapi.json
# "createCount": 5  (5つのエンドポイントが作成され、エラーは0)

インポーターはopenapi、postman、har、insomnia、jmeterなどにも対応しています。インポートされた内容をリスト表示します。

apidog endpoint list --project $PID
# 37921721 get    /objects
# 37921722 post   /objects
# 37921723 get    /objects/{id}
# 37921724 put    /objects/{id}
# 37921725 delete /objects/{id}

ステップ4：環境をセットアップする

環境には、ベースURLとテストで再利用する変数が格納されます。環境を作成し、そのIDを保存します。

apidog environment create "Production" --project $PID --base-url "https://api.restful-api.dev"
apidog environment list --project $PID
# { "id": 6334917, "name": "Production", "baseUrls": { "default": "https://api.restful-api.dev" } }
ENV=6334917   # あなたの環境IDに置き換えてください

後で実行コマンドに-e $ENVを渡して、テストがリクエストをどこに送信するかを認識させます。

ステップ5：自動化書き込みゲートを通過する

これが最初のつまずきやすい点です。テストシナリオとテストデータは自動化リソースであり、外部ツールからメインブランチに書き込むことはデフォルトでブロックされています。

apidog test-scenario create --project $PID --name "x" --description "" --folder-id 0 --priority 1
# "error": { "code": "403075", "message": "Automation caller branch required" }

これはガードレールであり、バグではありません。これには2つの方法があります。

Apidogデスクトップアプリのプロジェクト設定、機能設定、AI機能設定、外部AI編集権限で直接編集権限をオンにする。
AIブランチで作業し、自動化の変更をマージするまで隔離しておく。このパスは完全にコマンドライン上で完結するため、これを使用します。

mainからブランチを作成します。

apidog branch create --project $PID --type ai \
  --name "ai/20260616-from-main-cli-field-test" --from main
BR="ai/20260616-from-main-cli-field-test"

ai/YYYYMMDD-from--という命名パターンは、CLIが期待する慣例です。import、environment create、およびエンドポイントの編集はゲートされていませんが、自動化リソースのみがゲートされていることに注意してください。

ステップ6：テストシナリオを構築する

シナリオは、リクエストの順序付きフローであり、それらの間にアサーションがあります。まずシェルを作成し、次にステップを追加します。AIブランチで作成します。

apidog test-scenario create --project $PID --branch "$BR" \
  --name "Object CRUD lifecycle" \
  --description "Create, read, then delete an object and assert each step" \
  --folder-id 0 --priority 1
SID=1836498   # 返されたシナリオID

ステップはJSONファイルを使用してupdateで追加されます。JSONの書き込みにおける黄金律は、送信する前に検証することです。これにより、不正なペイロードをプッシュすることがなくなります。

apidog cli-schema get      test-scenario-update          # 正確な形式を確認
apidog cli-schema validate test-scenario-update --file ./steps-crud.json
# "データファイルは有効です"

各ステップは、リクエストと、レスポンスをアサートし、データを次のステップに渡す短いスクリプトで構成されます。以下は、新しいオブジェクトをPOSTし、そのidを後続のステップのために保存する作成ステップの形式です。

{
  "type": "customHttp",
  "name": "Create object",
  "customHttpRequest": {
    "path": "https://api.restful-api.dev/objects",
    "method": "post",
    "requestBody": { "type": "json", "data": "{\"name\":\"Apidog CLI Field Test\",\"data\":{\"price\":42}}" },
    "postProcessors": [{
      "type": "customScript",
      "data": "pm.test('create returns 200', function () { pm.response.to.have.status(200); });\nvar body = pm.response.json();\npm.globals.set('objId', body.id);",
      "enable": true
    }],
    "projectId": 1314366
  }
}

次のステップでは、URL内の{{objId}}を再利用して、同じオブジェクトを取得し、削除します。完全な3ステップファイルを適用します。

apidog test-scenario update $SID --project $PID --branch "$BR" --file ./steps-crud.json
# "success": true

シナリオをJSONで作成する必要はありません。Apidogで視覚的に構築し、CLIから実行するのも同じくらい有効です。JSONパスが重要になるのは、テストを他のコードと同様にバージョン管理し、レビューしたい場合です。

ステップ7：コマンドラインから実行する

これが目的です。CLIレポーターでシナリオを実行します。

apidog run -t $SID --project $PID --branch "$BR" -e $ENV -r cli

❏ Object CRUD lifecycle
↳ Create object        POST .../objects [200 OK]
  ✓ create returns 200   ✓ response has an id   ✓ name was echoed back
↳ Get the created object  GET .../objects/ff80...3de [200 OK]
  ✓ get returns 200   ✓ id matches the created object   ✓ price persisted in data
↳ Delete the object    DELETE .../objects/ff80...3de [200 OK]
  ✓ delete returns 200

  Http Requests  3 / 0 failed
  Assertions     7 / 0 failed

3つのリクエスト、7つのアサーション、失敗ゼロ、そして作成されたidが最初のステップから次の2つのステップに渡されました。これが、一度もクリックせずに実行される完全なAPIテストです。

コンソール出力ではなくファイルが必要ですか？複数のレポーターを一度に要求し、フォルダを指すようにします。

apidog run -t $SID --project $PID --branch "$BR" -e $ENV \
  -r cli,html,json,junit --out-dir ./reports --out-file "crud-report"
ls ./reports
# crud-report.html  crud-report.json  crud-report.xml

JUnit XMLは、CIサーバーがビルドごとの合格/失敗を表示するために読み取るものです。HTMLレポートは、チームメイトと共有するためのものです。

ステップ8：多くの入力に対して同じテストを実行する

実際のテストスイートは、複数のケースをカバーします。データ駆動型実行は、データの行ごとにシナリオを1回繰り返すため、10個のシナリオを作成せずに10個の入力をテストできます。これは、CSVおよびJSONからのパラメータ化テストと同じ考え方です。

データをファイルに格納します。

[
  { "name": "Pixel 8 Pro", "price": 999 },
  { "name": "iPhone 15", "price": 899 },
  { "name": "Galaxy S24", "price": 799 }
]

-dでデータを参照し、シナリオが各行から{{name}}と{{price}}を読み取るようにします。

apidog run -t $DID --project $PID --branch "$BR" -e $ENV -d ./objects-data.json -r cli

Iteration 1/3 … ✓ row created (200) ✓ name matches the data row
Iteration 2/3 … ✓ row created (200) ✓ name matches the data row
Iteration 3/3 … ✓ row created (200) ✓ name matches the data row
  Iterations 3 / 0 failed   Assertions 6 / 0 failed

3行のデータが入力され、3回のイテレーションが実行されました。ファイルをCSVに置き換えても、他は何も変わりません。

ステップ9：レポートを収集する

ローカル実行はファイルを書き出します。チーム全体がブラウザで開けるレポートを取得するには、--upload-reportを追加します。

apidog run -t $SID --project $PID --branch "$BR" -e $ENV -r cli --upload-report
# Apidog CLI runs data uploaded to the cloud successfully.
# https://app.apidog.com/link/project/1314366/api-test/test-report/2605398

知っておくべき注意点が1つあります。クラウドレポートは、それが実行されたブランチでタグ付けされます。この実行はAIブランチで行われたため、プレーンなapidog test-report list --project $PID（mainを対象とする）では表示されません。代わりに、アップロードリンクからIDで取得します。

apidog test-report get 2605398 --project $PID
apidog test-report download 2605398 --project $PID --format json --output ./cloud-report.json

ステップ10：APIをドキュメントまたは仕様としてエクスポートする

CLIはデータもエクスポートします。プロジェクトをOpenAPIファイル、Markdown、またはHTMLドキュメントとしてエクスポートします。

apidog export --project $PID --format openapi --oas-version 3.0 --output ./openapi-export.json
apidog export --project $PID --format markdown --output ./api-docs.md
apidog export --project $PID --format html --output ./api-docs.html

これは、変更ごとに新しい仕様をコミットしたり、パイプラインから静的ドキュメントを公開したりするのに便利です。

ステップ11：CI/CDに組み込む

手動で実行したすべての操作は、パイプラインでは3行になります。核となるのはインストールで、次にCIサーバーが結果を読み取れるようにJUnitレポーターで実行します。

- run: npm install -g apidog-cli@latest
- run: apidog login --with-token $APIDOG_TOKEN
- run: apidog run -t $SID --project $PID -e $ENV -r junit --out-dir ./reports

トークンをシークレットとして保存し、テストが失敗した場合はビルドを失敗させます（CLIは失敗時にゼロ以外の終了コードを返します）。完全なコピー＆ペースト可能なワークフローについては、GitHub ActionsでApidog CLIテストを実行するガイド、またはパイプラインに適合するAPIテスト自動化ツールを参照してください。

まとめ

空のターミナルから、共有可能なレポートを備えた合格するデータ駆動型APIテストまで、コマンドラインから一切離れることなく作業を進めました。パターンは常に同じです。APIをインポートまたは設計し、環境を作成し、アサーションを含むシナリオを構築し、apidog runで実行します。このコマンドがローカルで機能するようになれば、CIへの組み込みは3行の変更で済みます。

ご自身のAPIに対して同じ手順を実行し、シナリオファイルをコードと一緒にコミットすれば、シェルが動作する場所ならどこでもテストが実行されます。Apidogをダウンロードして開始し、CLIでは過剰なほど迅速な単発チェックにはREST APIテスト用のcurl代替手段を手元に置いておきましょう。

button