DEV Community

Cover image for GitHub CopilotでのApidog CLIの使い方
Akira
Akira

Posted on • Originally published at apidog.com

GitHub CopilotでのApidog CLIの使い方

GitHub Copilotのエージェントモードは、ファイルを編集し、ターミナルコマンドを実行し、出力を読み取り、次の操作を判断するループで動作します。APIテストもこのループに組み込めば、GUIで誰かが手動実行するのを待たずに、コード変更後の検証までCopilotに実行させられます。

今すぐApidogを試す

解決策は、リポジトリに1つの指示ファイルを追加することです。npmパッケージのapidog-cliを使うと、Apidogで作成したテストシナリオをターミナルから実行できます。CopilotがCLIコマンドを認識すれば、ユニットテストと同じようにapidog runを実行し、終了コードを確認し、失敗時は修正と再実行を繰り返せます。

まだCLIをインストールしていない場合は、先にセットアップしてください。AIコーディングエージェントを使用してApidog CLIをインストールする方法では、npmインストール、ログイン、初回実行を説明しています。この記事では、以下が成立していることを前提にします。

apidog --version
Enter fullscreen mode Exit fullscreen mode

また、apidog loginによるApidogアカウントの認証も完了しているものとします。

この記事の対象となるCopilot

GitHub Copilotには複数の実行形態があります。ここで対象にするのは、シェルコマンドを実行できるVS CodeのAgentモードです。

Copilot Chatを開き、モードをAgentに切り替えると、Copilotは複数ファイルの編集、ターミナルコマンドの実行、結果に基づく反復修正を行えます。コマンド実行前には内容が表示され、承認を求められます。このフローにapidog runを追加します。

関連する機能との違いも整理しておきます。

  • Copilot コーディングエージェント: GitHub Actions上で非同期に動作し、課題からプルリクエストを作成します。
  • Copilot CLI: ターミナルから使用する別のクライアントです。
  • VS Code Agentモード: エディター内で編集・テスト・修正を繰り返します。本記事の主な対象です。

以下で作成する指示ファイルは、同じファイルを読むCopilotコーディングエージェントにも利用できます。Copilotのエージェント機能については、GitHub Copilotの新しいコーディングエージェントも参照してください。

ステップ1：ApidogのルールをCopilotの指示ファイルに追加する

Copilotは、リポジトリルートの.github/copilot-instructions.mdからカスタム指示を読み込みます。GitHubのリポジトリカスタム指示ドキュメントによると、Agentモード、Copilot Chat、コードレビュー、コーディングエージェントがこのファイルを利用できます。

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

.github/copilot-instructions.md
Enter fullscreen mode Exit fullscreen mode

次に、Apidog CLIを実行するルールを追加します。

## API testing with the Apidog CLI

APIエンドポイントを変更する際は、タスク完了を宣言する前にApidog CLIで検証してください。以下を実行します。

    apidog run -t 812345 -e 671234 -r cli

- `apidog run`は、すべてのアサーションが成功した場合は終了コード0を、いずれかの失敗があった場合は0以外の終了コードを返します。
  サマリーテキストが問題ないように見えても、0以外の終了コードはテスト失敗として扱ってください。
- マシンは`apidog login`経由で既に認証されています。`--access-token`フラグを追加しないでください。また、このファイルにトークンを記述しないでください。
- 「unknown option」エラーが発生した場合は、`apidog run --help`を実行し、実際のフラグを使用してください。推測で入力しないでください。
Enter fullscreen mode Exit fullscreen mode

次のステップで、-tと-eを実際のシナリオID・環境IDに置き換えます。

チャットで一度だけシナリオIDを伝えるのではなく、指示ファイルに書くことが重要です。チャットの内容はセッション終了後に残らない場合がありますが、.github/copilot-instructions.mdはリポジトリに残ります。以後、チームメイト、Agentモード、コーディングエージェントが同じルールを利用できます。

特定のパスにだけルールを適用したい場合は、.github/instructions/NAME.instructions.mdによるパス固有の指示も利用できます。このケースでは、リポジトリ全体に適用する単一ファイルで十分です。

ステップ2：Apidogから正しいコマンドを取得する

apidog runコマンドを手書きする必要はありません。Apidogでテストシナリオを開き、CI/CDタブからコマンドをコピーしてください。

コピーしたコマンドには、以下が含まれます。

  • シナリオID: -t
  • 環境ID: -e
  • レポーターフラグ: -r

例:

apidog run -t 812345 -e 671234 -r cli
Enter fullscreen mode Exit fullscreen mode

このコマンドを、そのまま.github/copilot-instructions.mdへ貼り付けます。

Copilotの指示とApidogのCI/CDタブに表示された値が異なる場合は、Apidogが生成したコマンドを正としてください。利用できるフラグとレポーターの詳細は、apidog runコマンドリファレンスを参照してください。

ステップ3：Agentモードでテストを実行する

VS CodeでCopilot Chatを開き、モードをAgentに切り替えます。Agentモードは起動時に.github/copilot-instructions.mdを読み込むため、設定済みのApidog CLIコマンドを参照できます。

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

Apidog APIテストシナリオを実行して結果を教えてください。
Enter fullscreen mode Exit fullscreen mode

Copilotは指示ファイルにあるapidog runコマンドを提案します。実行前にコマンド内容を確認し、問題なければ承認してください。

apidog run -t 812345 -e 671234 -r cli
Enter fullscreen mode Exit fullscreen mode

-r cliを指定すると、統合ターミナルに各リクエスト、アサーション、実行結果の概要が出力されます。確認すべきポイントは次の2つです。

  1. 実際にapidog run ...が実行されていること
  2. Copilotが概要だけでなく終了コードも確認していること

一度承認したコマンドは、VS Codeがワークスペース内で選択を記憶する場合があります。ステージング環境に対する読み取り専用テストシナリオは、継続実行を許可しやすいコマンドです。

ステップ4：Copilot内でレポートを読む

テストが失敗した場合、-r cliの出力から失敗箇所を確認できます。通常は以下を特定できます。

  • 失敗したリクエスト
  • 失敗したアサーション
  • 期待したステータスコードと実際のステータスコード
  • 欠落しているフィールド
  • 期待値と実際値の差分

この情報があれば、Copilotは修正対象を判断し、コードを変更して再実行できます。

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

apidog run -t 812345 -e 671234 -r cli,html
Enter fullscreen mode Exit fullscreen mode

htmlレポーターは、自己完結型のレポートファイルを./apidog-reportsへ出力します。Copilotが次のアクションを判断するためのターミナル出力も必要なので、cliは残してください。

JUnitを含むレポーター形式については、Apidog CLI完全ガイドとApidog CLIテストレポートの読み方を参照してください。

Copilot自身のループ内でテストする

この設定の目的は、あなたが毎回「テストを実行して」と依頼しなくても、CopilotがAPI変更後の検証を行うことです。

たとえば、Copilotがチェックアウトレスポンスを返すハンドラーを編集する場合、次のループになります。

  1. ハンドラーのコードを編集する
  2. apidog runでステージング環境に対するシナリオを実行する
  3. 終了コードを確認する
  4. 成功なら次の作業へ進む
  5. 失敗なら、レポートから失敗したステータスコード・フィールド・値を確認する
  6. コードを修正して再実行する

つまり、APIテストがユニットテストと同じ編集・テスト・修正ループに入ります。

これは、エージェントワークフローにおける「委任と検証」の形です。Copilotにコマンド実行と結果の読み取りを任せつつ、テストシナリオはApidog上で視覚的に管理し、必要に応じて実行結果を確認します。より広いパターンについては、APIテストにAIエージェントを使用する方法とApidog AIテストハーネスを参照してください。

Copilotが実際にCLIを実行していることを確認する

エージェントが、実際には実行していない作業を完了したと報告する可能性はあります。次の順番で確認してください。

1. ターミナルにコマンドと出力があるか確認する

Agentモードは、実行したコマンドと出力をターミナルに表示します。次のような行と、その直後の結果があるかを確認してください。

apidog run -t 812345 -e 671234 -r cli
Enter fullscreen mode Exit fullscreen mode

Copilotが「テストを実行しました」と言っていても、コマンドや生の出力が表示されていなければ、実行結果を要約しただけの可能性があります。その場合は、生の出力を表示するよう再度依頼してください。

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

次のように質問します。

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

apidog runは、すべてのアサーションが成功すると0、いずれかが失敗すると0以外で終了します。

Copilotの文章が「テストに合格した」としていても、終了コードが0以外なら失敗です。終了コードを優先してください。

3. 実際のシナリオIDと環境IDを確認する

scenario not foundが出た場合、Copilotが誤ったIDを使った可能性があります。以下を再確認してください。

  • .github/copilot-instructions.mdの-tと-e
  • ApidogのCI/CDタブからコピーしたコマンド

シナリオIDと環境IDは、Apidogが生成したコマンドを正とします。

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

copilot-instructions.mdからapidog runを実行するだけでも、テスト実行の自動化には十分です。さらに、API仕様をCopilotに参照させたい場合はApidog MCPサーバーを接続します。

VS CodeのAgentモードは、リポジトリルートにある.vscode/mcp.jsonからMCPサーバー設定を読み込みます。設定方法は、MCPでCopilotを拡張するGitHubドキュメントを参照してください。

Apidog MCPサーバーを使うと、CopilotはMCP経由でAPI仕様を読み取れます。

役割は明確です。

  • Apidog CLI: テストシナリオを実行する
  • Apidog MCP: API仕様をCopilotへ提供する

GitHub Actions上のCopilotコーディングエージェントでMCPを使う場合、設定場所は異なります。リポジトリのSettings → Copilot → Cloud agentでJSONを追加し、秘密情報はCOPILOT_MCP_プレフィックス付きのActionsシークレットとして保存します。.vscode/mcp.jsonは、VS CodeのAgentモード用です。

Copilotが間違った場合

セットアップ時によくある問題と対処方法をまとめます。

指示ファイルを無視する

Copilotが汎用コマンドを提案したり、何も実行しなかったりする場合は、指示ファイルが読み込まれていない可能性があります。

以下を確認してください。

  • ファイル名が.github/copilot-instructions.mdである
  • ファイルがリポジトリルート配下の.githubにある
  • VS Codeでカスタム指示が有効になっている

パスが異なると、Copilotは指示を読み込みません。

--access-tokenを追加しようとする

Copilotが--access-tokenを追加しようとする場合、公開例を元に推測している可能性があります。apidog loginで認証済みなら、トークンをコマンドや指示ファイルへ書く必要はありません。

指示ファイルには、トークンを追加しないルールを明記してください。認証方式の詳細は、Apidog CLIの認証を参照してください。

存在しないフラグを推測する

unknown optionエラーは、インストール済みバージョンに存在しないフラグをCopilotが推測したことを意味します。

次のコマンドを実行します。

apidog run --help
Enter fullscreen mode Exit fullscreen mode

表示されたヘルプから、実際に利用できるフラグをコピーしてください。推測よりも、ローカル環境のヘルプを優先します。

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

最もコストが高い問題です。概要表示が成功に見えても、終了コードが0以外ならテストは失敗です。

このルールを指示ファイルに書き、実行後も終了コードを確認してください。

日常的なエージェントからテスト済みのループへ

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

  1. インストールガイドに従ってapidog-cliをインストールする
  2. Apidogでテストシナリオを作成する
  3. CI/CDタブからapidog runコマンドをコピーする
  4. .github/copilot-instructions.mdにコマンドと終了コードのルールを書く
  5. VS CodeのAgentモードでAPI変更を実装する

これでCopilotは、コード編集に使っているのと同じループ内でAPIテストを実行し、結果を読み取れるようになります。壊れたエンドポイントをデプロイ後に見つけるのではなく、変更作業中に検出できます。

GUI内のテストは、人間がクリックしたときに実行されます。一方、CLIコマンドとして定義したテストは、Copilotが変更を検証するタイミングで実行できます。Apidogでシナリオを作成し、apidog runをリポジトリの指示ファイルに追加して、次のAPI変更からテストループへ組み込んでください。

Apidogをダウンロードして1つのシナリオから始めることもできます。Copilotを使わないCIパイプラインで同じコマンドを実行する場合は、GitHub ActionsでのApidog CLIを参照してください。

Top comments (0)