DEV Community

Cover image for AntigravityでApidog CLIの使い方
Akira
Akira

Posted on • Originally published at apidog.com

AntigravityでApidog CLIの使い方

Antigravityは、ファイルを編集し、ターミナルコマンドを実行し、出力を読み取り、次のアクションを判断するエージェント型の開発ループです。APIテストをこのループに組み込めば、GUIで手動実行していたApidogのテストシナリオを、コード変更後にエージェントが自動で実行・検証できるようになります。

今すぐApidogを試す

解決策は、プロジェクトルールに1つの設定ブロックを追加することです。apidog-cli は、Apidogで作成したテストシナリオをターミナルから実行するnpmパッケージです。AntigravityがCLIの実行方法をルールとして認識すれば、単体テストと同じようにAPIテストを実行できます。

  • コマンドを実行する
  • 終了コードを確認する
  • 失敗した場合はレポートを読んでコードを修正する
  • 修正後に再実行する

まだCLIを導入していない場合は、先にセットアップしてください。AIコーディングエージェントを使ったApidog CLIのインストール方法では、npmによるインストール、認証、初回実行を説明しています。

この記事では、次の状態を前提にします。

apidog --version
Enter fullscreen mode Exit fullscreen mode

上記コマンドでバージョン番号が表示され、apidog login による認証が完了していることを確認してください。

ここでいうAntigravityとは

Antigravityは、Gemini 3をベースに構築され、2025年後半にリリースされたGoogleのエージェント型開発プラットフォームです。エージェントマネージャーを通じて、タスクの計画、リポジトリ全体のファイル編集、ターミナルやブラウザでのコマンド実行を行います。

重要なのは、Antigravityがプロジェクト固有のルールを読み取れる点です。一度だけチャットで「テストを実行して」と伝えるのではなく、ルールファイルに実行手順を書いておくことで、以後のタスクでもエージェントが同じ手順を適用できます。

Antigravityの概要は、Google Antigravityとは何か、その使用方法も参照してください。

ステップ1: Antigravity用のルールファイルを作成する

Antigravityは、ワークスペースのルートにある .agents/ ディレクトリを認識します。GoogleのAntigravityで自律型開発パイプラインを構築するコードラボでも、ワークスペースルールを .agents/rules/ に配置する方法が示されています。

まず、次のファイルを作成します。

.agents/rules/apidog.md
Enter fullscreen mode Exit fullscreen mode

すでにプロジェクトルートに AGENTS.md を置いている場合は、そこへ追記しても構いません。AGENTS.md はクロスツールで利用しやすく、CodexがApidog CLI用に読み取るファイルと同じです。

ファイルには、実行コマンドと判断基準を明示します。

## API testing with the Apidog CLI

- APIをテストする場合は、GUIを操作せずApidogシナリオを実行する。
- コマンド: `apidog run -t <scenario_id> -e <env_id> -r cli`
- 終了コードが`0`なら、すべてのアサーションが成功している。
- 終了コードが`0`以外なら失敗。CLI出力またはレポートを確認し、コードを修正して再実行する。
- マシンは`apidog login`で認証済み。`--access-token`を追加せず、このファイルにもトークンを書かない。
Enter fullscreen mode Exit fullscreen mode

この内容はチャットではなく、リポジトリ内のルールファイルに保存してください。チャットで伝えたシナリオIDや実行手順はセッション終了後に失われる可能性があります。一方、ルールファイルに保存すれば、チームメイトと以後のAntigravityタスクが同じ設定を利用できます。

ステップ2: Apidogから正しい実行コマンドをコピーする

シナリオIDや環境IDを推測してはいけません。

Apidogで対象のテストシナリオを開き、CI/CD タブから生成済みのコマンドをコピーします。例えば次の形式です。

apidog run -t 123456 -e 789012 -r cli
Enter fullscreen mode Exit fullscreen mode

各フラグの意味は次のとおりです。

フラグ 用途
-t テストシナリオID
-e 実行する環境ID
-r cli 結果をターミナルへ出力するレポーター

コピーした実際のコマンドを .agents/rules/apidog.md または AGENTS.md に貼り付けます。

- コマンド: `apidog run -t 123456 -e 789012 -r cli`
Enter fullscreen mode Exit fullscreen mode

利用可能なフラグは、apidog runコマンドリファレンスで確認できます。

ステップ3: Antigravityにテストを実行させる

ルールファイルを配置したら、Antigravityでタスクを開始します。エージェントはタスク開始時にルールを読み込むため、Apidog CLIの使い方を認識できます。

たとえば、APIに影響する変更後に次のように依頼します。

Apidogテストシナリオを実行し、終了コードと失敗したアサーションを報告してください。
Enter fullscreen mode Exit fullscreen mode

エージェントはルールに記載したコマンドをターミナルで実行します。

apidog run -t 123456 -e 789012 -r cli
Enter fullscreen mode Exit fullscreen mode

コマンド実行前に承認が必要かどうかは、Antigravityのパーミッション設定によります。GoogleのAntigravity入門コードラボで説明されているセキュリティプリセットにより、ターミナル実行やファイルアクセスをレビューするかどうかが決まります。

ステージング環境に対する読み取り専用のテストシナリオであれば、通常は承認対象として扱いやすいコマンドです。

エージェントには、要約だけでなく以下を報告するよう求めてください。

  • 実行した apidog run コマンド
  • CLIの生出力
  • 終了コード
  • 失敗したアサーション
  • 修正した内容と再実行結果

ステップ4: CLI出力とレポートを読む

-r cli を指定すると、エージェントはターミナル上で次のような情報を確認できます。

  • 実行されたリクエスト
  • アサーションの成否
  • 期待値と実際値
  • 失敗したフィールド
  • ステータスコード

失敗時は、これらの情報をもとに修正対象を特定します。たとえば、期待した 200 に対して 500 が返った場合や、レスポンスに必須フィールドが存在しない場合、エージェントは対象ハンドラやレスポンス生成処理を確認できます。

ブラウザで共有・確認できるHTMLレポートも必要なら、html レポーターを追加します。

apidog run -t 123456 -e 789012 -r cli,html
Enter fullscreen mode Exit fullscreen mode

html レポーターは、自己完結型のHTMLファイルを ./apidog-reports に出力します。

エージェントが次のアクションを判断するには、ターミナル出力も必要です。そのため、HTMLレポートを追加する場合でも cli は残してください。

# エージェント向けのインライン出力と、人間向けのHTMLレポートを両方生成する
apidog run -t 123456 -e 789012 -r cli,html
Enter fullscreen mode Exit fullscreen mode

レポーターの詳細は、Apidog CLI完全ガイドおよびApidog CLIテストレポートの読み方を参照してください。

編集・テスト・修正のループに組み込む

この設定の目的は、毎回「Apidogを実行して」と依頼することではありません。APIに関連する変更後、エージェントがルールに従ってテストを実行する状態を作ることです。

たとえば、チェックアウトレスポンスを生成するハンドラを編集する場合、エージェントのループは次のようになります。

  1. ハンドラを編集する
  2. Apidogシナリオをステージング環境に対して実行する
  3. 終了コードを確認する
  4. 0 の場合は次のタスクへ進む
  5. 0 以外の場合は失敗したアサーションを確認する
  6. コードを修正する
  7. シナリオを再実行する

単体テストで行っている編集・テスト・修正のループに、APIテストを追加するイメージです。

この運用では、Apidogでテストシナリオを視覚的に管理し、AntigravityがCLIを通じて実行します。エージェントの報告をそのまま信頼せず、終了コードとCLI出力を定期的に確認してください。

AIエージェントを利用したAPIテストの考え方は、APIテストにAIエージェントを使用する方法およびApidog AIテストハーネスも参考になります。

Antigravityが実際にCLIを実行したことを確認する

エージェントが「テストに成功しました」と報告しても、実際にはコマンドを実行していない可能性があります。次の3点を確認してください。

1. apidog run の実行ログを確認する

Antigravityのターミナル出力で、実際のコマンドとその結果を探します。

apidog run -t 123456 -e 789012 -r cli
Enter fullscreen mode Exit fullscreen mode

エージェントが成功を報告していても、このコマンドやCLI出力が表示されていなければ、実行されていない可能性があります。その場合は、生出力を表示するよう明示して再実行させます。

Apidog CLIの実行コマンド、標準出力、終了コードを省略せずに表示してください。
Enter fullscreen mode Exit fullscreen mode

2. 終了コードを確認する

終了コードを直接確認します。

その`apidog run`コマンドの終了コードは何でしたか？
Enter fullscreen mode Exit fullscreen mode

apidog run は次のように終了します。

  • 0: すべてのアサーションが成功
  • 0 以外: いずれかのアサーションまたは実行処理が失敗

文章による要約と終了コードが矛盾する場合は、終了コードを正としてください。

3. 正しいシナリオIDと環境IDを使っているか確認する

次のようなエラーが出る場合は、エージェントがIDを推測している可能性があります。

Scenario not found
Enter fullscreen mode Exit fullscreen mode

その場合は、ApidogのCI/CDタブで生成されたコマンドとルールファイルを比較し、-t と -e の値を確認してください。

apidog run -t <scenario_id> -e <env_id> -r cli
Enter fullscreen mode Exit fullscreen mode

ルールファイルには、Apidogが生成した実際のIDだけを記載します。

オプション: Apidog MCPサーバーを接続する

apidog run をルールファイルから実行するだけでも、APIテストの自動化には十分です。さらに、実装中にAPI仕様を参照させたい場合はMCPサーバーを接続します。

AntigravityはModel Context Protocolをサポートしています。Googleの入門コードラボによると、MCPサーバーは次のファイルで設定します。

$HOME/.gemini/config/mcp_config.json
Enter fullscreen mode Exit fullscreen mode

mcpServers オブジェクトに、command、args、env を持つサーバー設定を追加し、Antigravity側でMCP設定を更新します。

Apidog MCPサーバーを利用すると、エージェントはMCP経由でAPI仕様を参照できます。

役割を分けると分かりやすくなります。

  • Apidog CLI: テストシナリオを実行し、終了コードとレポートを返す
  • Apidog MCPサーバー: エージェントにAPI仕様のコンテキストを提供する

よくある問題と対処法

ルールファイルが無視される

エージェントが一般的なコマンドを実行したり、Apidog CLIを実行しなかったりする場合、ルールがロードされていない可能性があります。

確認項目:

  • .agents/rules/apidog.md のパスが正しいか
  • ファイルが対象ワークスペースのルート配下にあるか
  • AGENTS.md を使う場合、ワークスペースルートにあるか
  • ルール変更後に新しいタスクを開始したか

ルールを変更した後は、新しいAntigravityタスクを開始して再読み込みさせてください。

エージェントが --access-token を追加する

すでに apidog login で認証している場合、ルールファイルにトークンを書く必要はありません。

次のルールを明示してください。

- `--access-token`を使用しない。
- 認証情報や実際のトークンをルールファイルへ保存しない。
- 認証は`apidog login`によるローカルログイン状態を使用する。
Enter fullscreen mode Exit fullscreen mode

認証の詳細は、Apidog CLI認証を確認してください。

存在しないフラグを使う

次のエラーは、エージェントが利用可能なフラグを推測したことを示します。

unknown option
Enter fullscreen mode Exit fullscreen mode

この場合は、インストール済みバージョンのヘルプを確認します。

apidog run --help
Enter fullscreen mode Exit fullscreen mode

エージェントにも、ヘルプ出力に存在するフラグだけを使うよう指示してください。

`apidog run --help`の出力を確認し、そのバージョンで利用可能なフラグだけを使用してください。
Enter fullscreen mode Exit fullscreen mode

失敗した実行を成功として報告する

最も重要なのは終了コードです。エージェントの要約ではなく、実行結果で判定してください。

- `apidog run`の終了コードが`0`以外の場合、テストは失敗。
- 要約文が成功と書いていても、終了コードが`0`以外なら失敗として扱う。
Enter fullscreen mode Exit fullscreen mode

まとめ

セットアップはシンプルです。

  1. インストールガイドに従って apidog-cli をインストールする
  2. ApidogのCI/CDタブから正しい apidog run コマンドをコピーする
  3. .agents/rules/apidog.md または AGENTS.md に実行ルールを書く
  4. API変更後にエージェントがCLIを実行するよう依頼する
  5. 終了コードとCLI出力を確認する

これにより、APIテストはGUIで人がクリックしたときだけ実行されるものではなくなります。エージェントは、コード編集に使うのと同じループの中でシナリオを実行し、失敗を検出して修正できます。

Apidogでシナリオを作成し、その apidog run コマンドをルールファイルに追加してください。エージェントを使わないCIパイプラインでも同じコマンドを実行したい場合は、GitHub ActionsでのApidog CLIを参照してください。

Top comments (0)