DEV Community

Cover image for Apidog CLIの新機能：テストランナーからエージェントワークフローレイヤーへの進化
Akira
Akira

Posted on • Originally published at apidog.com

Apidog CLIの新機能：テストランナーからエージェントワークフローレイヤーへの進化

Apidog CLIは長年にわたり、ターミナル、CIパイプライン、自動化ワークフロー、または外部システムからAPIテストを実行するためのコマンドラインエントリポイントとして使われてきました。

今すぐApidogを試す 

apidog run --project <projectId> --test-scenario <scenarioId> --environment <environmentId>
Enter fullscreen mode Exit fullscreen mode

この基盤は今も重要です。チームには、APIテストを実行し、レポートを生成し、CI内で品質ゲートを維持するための再現可能な方法が必要です。一方で、API開発の現場では、AIエージェントがAPI設計、テスト生成、デバッグ、移行、メンテナンスに参加するようになっています。

そのためCLIは、既存テストを最後に実行するだけのツールでは不十分です。エージェントがAPIアセットを読み取り、テストアセットを作成または更新し、構造化された変更を検証し、Apidogへ書き戻し、結果を確認できる安定したワークフローが必要になります。

アップグレードされたApidog CLIは、従来のテスト実行機能を維持しながら、開発者、スクリプト、AIエージェントが使えるワークフローレイヤーへ拡張されています。この記事では、AIエージェント時代にCLIが重要になる理由、Apidog CLIで変わった点、APIテスト自動化にどう導入するかを実装目線で説明します。

AIエージェント時代にCLIがより重要になる理由

GUIは人間向けに設計されています。視覚的で探索しやすく、レビューや共同作業に適しています。

一方でAIエージェントは、次のような条件がそろったインターフェースで安定して動作します。

  • 構造化されたコマンド
  • 予測可能な入力
  • 予測可能な出力
  • 明確な検証ステップ
  • 読み戻し可能なリソース

CLIはこの要件に合います。Apidog CLIを使うことで、エージェントやスクリプトは、Apidogで管理されている次のようなリソースに対して再現可能な操作を実行できます。

  • API
  • 環境
  • 変数
  • テストケース
  • テストシナリオ
  • テストスイート
  • レポート
  • インポート/エクスポートデータ

実際の運用では、人間はApidogのUIで設計、デバッグ、レビュー、共同作業を続けます。そのうえで、エージェントや自動化ワークフローはCLIを使って、同じプロジェクトアセットに対する制御された操作を実行できます。

apidog run から完全なAPIおよびテストワークフローへ

以前のCLI体験は、主にテスト実行に焦点を当てていました。そのため、apidog run はCI品質ゲートとして有用でしたが、CLIが登場するのはワークフローの終盤でした。

アップグレードされたCLIでは、より多くのApidogコアリソースを扱えるようになり、自動化やエージェントが開発ループの早い段階から参加できます。たとえば、次のような流れをCLIで扱えます。

  1. プロジェクトコンテキストを読み取る
  2. API定義や既存テストを参照する
  3. テストアセットを準備する
  4. JSON構造を検証する
  5. Apidogへ書き込む
  6. 保存済みリソースを読み戻す
  7. テストを実行して結果を確認する

アップグレードされたCLIにより、ユーザーとエージェントは次のようなリソースを操作できます。

  • プロジェクトおよびプロジェクトメタデータ
  • APIおよびAPI定義
  • 環境および変数
  • テストケース
  • テストシナリオ
  • テストスイート
  • レポート
  • インポートおよびエクスポートワークフロー
  • アカウント、ブランチ、ランナー、および関連するプロジェクトリソース

これにより、Apidog CLIの役割は変わります。すべてが完了した後にテストを実行するだけでなく、エージェントがプロジェクトを理解し、テストアセットを生成または更新し、変更を検証し、検証を実行するための実行基盤になります。

エージェント主導型テストのためのより安全なループ

AIエージェントがAPI開発やテストを支援する場合、リスクが高いのは「コンテンツを生成すること」だけではありません。より大きなリスクは、生成されたコンテンツを、十分な構造や検証なしに実際のプロジェクトへ書き込むことです。

アップグレードされたCLIでは、次のような安全なループを組みやすくなります。

このループが重要なのは、多くのApidogリソースが構造化されているためです。テストケースやテストシナリオには、次のような要素が含まれる場合があります。

  • リクエストデータ
  • アサーション
  • 変数抽出
  • プリプロセッサ
  • ポストプロセッサ
  • ステップ順序
  • 環境への参照
  • その他の実行設定

エージェントが構造を推測すると、小さな誤りが次の問題につながります。

  • 書き込みに失敗する
  • UIで不完全に表示される
  • テストが期待どおりに動作しない
  • 不要な再試行ループが発生する

そこで重要になるのが cli-schema です。複雑なJSONファイルをApidogに書き込む前に、フィールドと構造が期待されるスキーマに一致するか検証できます。

apidog cli-schema validate test-case-create --file ./test-case-create.json
apidog cli-schema validate test-scenario-update --file ./scenario-update.json
Enter fullscreen mode Exit fullscreen mode

実装時の基本方針はシンプルです。

  1. エージェントにJSONを生成させる
  2. cli-schema で検証する
  3. 検証に通ったものだけを書き込む
  4. 書き込み後に読み戻す
  5. 必要に応じてテストを実行する

つまり、生成はエージェントに任せ、書き込み前の検証はCLIに任せます。

CLIは、コマンド出力でエージェント向けのヒントを提供することもできます。リソースが作成または更新された後、次にやるべきことは「完了」ではなく、保存済みリソースの読み戻し、構造確認、必要に応じたテスト実行です。これにより、エージェントは盲点を減らしながらワークフローを進められます。

スキルはエージェントに操作判断を与える

CLIコマンドはエージェントに実行能力を与えます。スキルはエージェントに操作判断を与えます。

SKILLは単なるコマンドリファレンスではありません。AIエージェント向けの操作ガイドに近いものです。たとえば、次の判断を補助します。

  • いつどのコマンドを使うべきか
  • どのコマンドを先に実行すべきか
  • どのフィールドを推測すべきでないか
  • いつスキーマ検証を実行すべきか
  • いつ保存済みリソースを読み戻すべきか
  • いつテストを実行すべきか

たとえば、信頼性の高いエージェントは、大規模なテストシナリオをゼロから一度に手書きすべきではありません。より安全なパターンは次のとおりです。

  1. 基本的なシナリオを作成する
  2. APIまたは既存のテストケースからステップをインポートする
  3. 完全なシナリオ構造を読み戻す
  4. アサーション、変数抽出、プロセッサを小さな単位で更新する
  5. シナリオを検証して実行する

スキルはこのようなパターンを明確にします。これにより、エージェントは次のような失敗を避けやすくなります。

  • 誤ったフィールド名を使う
  • 誤った列挙値を選ぶ
  • スキーマ検証をスキップする
  • 書き込み成功だけで最終リソースが正しいと判断する
  • 読み戻し確認を省略する

Apidogは、エージェントがCLIコマンド、リソース構造、タスクワークフローを理解するための8つの補助スキルを提供します。CLIとスキルを組み合わせることで、AIアシストによるAPI開発とテストをより実用的にできます。

AIブランチによるより安全なプロジェクト変更

エージェントがプロジェクトリソースを変更する場合、安全性とレビュー可能性が重要です。そのため、アップグレードされたCLIは AIブランチ と組み合わせて使えます。

安全な運用パターンは次のとおりです。

  1. エージェントは隔離されたブランチで変更する
  2. チームが差分を確認する
  3. 必要に応じて修正する
  4. 結果を承認する
  5. ターゲットブランチへマージする

これにより、自動化された変更がメインブランチや共有コラボレーションブランチに直接影響することを防げます。

実際のワークフローでこれがもたらすもの

アップグレードされたCLIの価値は、具体的なワークフローで考えると理解しやすくなります。

API定義からのテスト生成

エージェントは、プロジェクトからAPI定義を読み取り、テストケースを生成し、生成されたJSONを cli-schema で検証し、テストケースをApidogに書き込み、読み戻して検証を実行できます。

実装フローは次のようになります。

  1. API定義を取得する
  2. テストケースJSONを生成する
  3. cli-schema で検証する
  4. Apidogに書き込む
  5. 書き込んだテストケースを読み戻す
  6. テストを実行する

これにより、テスト生成は一時的な提案ではなく、検証可能なワークフローになります。

複雑なテストシナリオのメンテナンス

多段階のシナリオでは、エージェントにすべてを一度に生成させるより、既存のAPIやテストケースからステップをインポートし、その後に小さく更新する方が安全です。

apidog test-scenario import-steps <scenarioId> --project <projectId> --source endpoint --ids <endpointIds> --sync manual
apidog test-scenario get <scenarioId> --project <projectId> --with-case-detail
Enter fullscreen mode Exit fullscreen mode

推奨フローは次のとおりです。

  1. APIまたは既存のテストケースからステップをインポートする
  2. test-scenario get で完全な構造を読み戻す
  3. アサーション、変数、プロセッサを必要な箇所だけ更新する
  4. 更新内容を検証する
  5. シナリオを実行する

これにより、大規模なシナリオを一度に誤って構築するリスクを減らせます。

プロジェクトアセットの移動と再現

アップグレードされたCLIは、Apidogネイティブデータのインポートおよびエクスポートワークフローも改善します。

これは次のような場面で役立ちます。

  • プロジェクト移行
  • 顧客環境の再現
  • テスト設定のコピー
  • プロジェクト間でのAPI、スキーマ、テストケース、シナリオの移動 
apidog export --project <projectId> --format apidog --output ./project.apidog.json
apidog import --project <projectId> --format apidog --file ./project.apidog.json
Enter fullscreen mode Exit fullscreen mode

CI品質ゲートの維持

新しいエージェント対応機能はCIを置き換えるものではありません。既存のCIワークフローを補完します。

チームは引き続き apidog run を、自動テスト実行とレポート生成のコアエントリポイントとして使えます。

apidog run --project <projectId> --test-scenario <scenarioId> --environment <environmentId> -r "cli,html,junit" --out-dir ./apidog-reports
Enter fullscreen mode Exit fullscreen mode

CIでは、たとえば次の用途に使えます。

  • Pull RequestごとのAPIテスト実行
  • HTML/JUnitレポートの生成
  • 品質ゲートとしてのテスト失敗検知
  • エージェントが更新したテストアセットの最終検証

始めに

すでにApidog CLIをインストールしている場合は、まず現在のバージョンを確認します。

apidog -v
Enter fullscreen mode Exit fullscreen mode

Apidog CLIのバージョン が2.2.5より前の場合は、新機能を使用する前にCLIを更新してください。このバージョン番号はApidogアプリではなく、Apidog CLIを指します。

使用しているAIエージェントに、次のプロンプトをコピーして、Apidog CLIと付属スキルのインストールを依頼できます。

指示を読み、Apidog CLIのインストールを手伝ってください:
https://apidog.com/apidog-cli-installation-guide.md?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation
Enter fullscreen mode Exit fullscreen mode

手動でインストールまたは更新する場合は、次を実行します。

npm install -g apidog-cli@latest
Enter fullscreen mode Exit fullscreen mode

コマンドの完全なリファレンスについては、Apidog CLIオプションを参照してください。

最初のAgentタスクを試す

CLIとスキルをインストールしたら、最初は小さくリスクの低いAPIタスクから始めるのがおすすめです。

たとえば、Apidogプロジェクトに単純なヘルスチェックエンドポイントを作成し、その後に読み戻して結果を確認させます。

次のプロンプトをAIエージェントにコピーしてください。

Apidog CLIを使って、Apidogで最初のAPIエンドポイントを作成するのを手伝ってください。まず、Apidog CLIの設定を確認し、アクセス可能なプロジェクトを一覧表示してください。どのプロジェクトを使用するか私に尋ねてください。私が確認した後、シンプルなGET /health エンドポイントを「Health Check」という名前で、200のレスポンス例を付けて作成してください。書き込み前に構造化された入力をすべて検証し、その後エンドポイントを読み戻して、何が作成されたかを要約してください。
Enter fullscreen mode Exit fullscreen mode

このプロンプトでは、エージェントに次の流れを強制できます。

  1. CLI設定を確認する
  2. アクセス可能なプロジェクトを一覧表示する
  3. 書き込み先プロジェクトをユーザーに確認する
  4. 小さなAPI定義を作成する
  5. 書き込み前に構造を検証する
  6. 保存後に読み戻す
  7. 作成内容を要約する

最初のタスクとしては、低リスクでありながら、CLI、スキル、検証、読み戻しの基本ループを確認できます。

次のステップ：

  • 1つのワークスペースでAPIを設計、デバッグ、テスト、文書化するためにApidogをダウンロードしてください。
  • コマンドラインAPIテスト、CI自動化、AIエージェントワークフローについては、Apidog CLIの詳細をご覧ください。

よくある質問

Apidog CLIとは何ですか？

Apidog CLIは、APIテストの実行、Apidogプロジェクトリソースの操作、ApidogのAPIおよびテストアセットと自動化ワークフローの接続に使用するコマンドラインツールです。

Apidog CLIはCIでAPIテストを実行できますか？

はい。チームはCIパイプラインで apidog run を使用して、APIテストを実行し、レポートを生成し、テストワークフローに自動品質ゲートを維持できます。

Apidog CLIはAIエージェントにどのように役立ちますか？

Apidog CLIは、AIエージェントがAPI情報を読み取り、テストアセットを生成または更新し、変更を検証し、それらをApidogに書き込み、結果を読み戻し、検証のためにテストを実行するための構造化された方法を提供します。

Apidog CLIの cli-schema とは何ですか？

cli-schema は、複雑なJSONファイルをApidogに書き込む前に検証するための機能です。これにより、エージェントがテストケースやテストシナリオを作成または更新する際の書き込み失敗、無効なフィールド、不要な再試行ループを減らせます。

Apidog CLIをインストールするにはどうすればよいですか？

AIエージェントにApidog CLIのインストールガイドに従ってCLIと付属スキルをインストールするよう依頼するか、次のコマンドで手動インストールできます。


bash
npm install -g apidog-cli@latest
Enter fullscreen mode Exit fullscreen mode

Top comments (0)