DEV Community

Cover image for TraeでApidog CLIを使う方法
Akira
Akira

Posted on • Originally published at apidog.com

TraeでApidog CLIを使う方法

TraeのBuilderエージェントは、リポジトリの読み取り、ファイル編集、ターミナルコマンドの実行、出力に基づく次のアクションの判断を繰り返します。このループにApidogのAPIテストを組み込めば、API変更後にエージェント自身がシナリオを実行し、終了コードを確認して、失敗時には修正と再実行を行えるようになります。

今すぐApidogを試す

実装のポイントは、Apidog CLIをインストールし、Traeのプロジェクトルールに実行コマンドと判定ルールを記述することです。apidog-cliは、Apidogで作成したテストシナリオをターミナルから実行できます。Builderはユニットテストと同様にapidog runを実行し、終了コードが非ゼロならテスト失敗として扱えます。

まだCLIをセットアップしていない場合は、先にAIコーディングエージェントを使用したApidog CLIのインストール方法を実行してください。この記事では、以下を満たしている前提で進めます。

apidog --version
Enter fullscreen mode Exit fullscreen mode
  • バージョン番号が表示される
  • apidog loginによる認証が完了している

どのTraeについての話か

TraeはByteDanceのAI IDEで、VS Codeをベースにしています。Builderモードでは、エージェントがファイルを編集し、ターミナルコマンドを提案・実行できます。詳細はTrae公式サイトを参照してください。

この記事の対象はデスクトップIDE版のTraeです。GitHub上のスタンドアロンなtrae-agent研究プロジェクトではありません。Traeを開いたときにエディター横のチャットパネルからBuilderを選択できる場合、この手順を適用できます。

TraeのBuilderエージェント画面

Traeでは、プロジェクトルールファイルにエージェントの作業ルールを定義できます。ここにApidog CLIのコマンドを記述することで、一度だけのチャット指示ではなく、以後のBuilder実行で再利用できる検証手順になります。

CLI単体の使い方を確認したい場合は、Apidog CLI完全ガイドも参照してください。

ステップ1：プロジェクトルールファイルを追加する

TraeのBuilderは作業開始時にルールファイルを読み込みます。Traeのルールに関するドキュメントに従い、リポジトリルートに次のファイルを作成します。

.trae/rules/project_rules.md
Enter fullscreen mode Exit fullscreen mode

APIに影響する変更ではApidogシナリオを実行するよう、ルールを追加します。

## Apidog CLIによるAPIテスト

APIエンドポイントに触れるコードを変更した際は、ユニットテストだけでなく、
Apidogテストシナリオを実行して検証してください。

コマンド:
  apidog run -t <scenario_id> -e <env_id> -r cli

ルール:
- `apidog run`はすべてのアサーションがパスした場合に0を返し、
  いずれかの失敗で非ゼロを返します。
  サマリーが問題なさそうに見えても、非ゼロの終了コードはテスト失敗として扱ってください。
- このマシンは`apidog login`経由で既に認証されています。
  `--access-token`フラグを追加したり、このファイルにトークンを記述したりしないでください。
- 不明なフラグがある場合は、`apidog run --help`を実行し、
  ヘルプに表示された正確なフラグを使用してください。
Enter fullscreen mode Exit fullscreen mode

チャットでシナリオIDを伝えるだけでは、セッション終了時にその情報が失われます。一方、.trae/rules/project_rules.mdに記述すれば、チームメイトを含む今後のBuilder実行で同じルールを共有できます。

モノレポでは、サービス単位でサブディレクトリの.trae/rules/にルールを配置することもできます。

ステップ2：Apidogから実行コマンドを取得する

シナリオIDや環境IDを手入力で推測しないでください。Apidogで対象のテストシナリオを開き、CI/CDタブへ移動して、生成されたapidog runコマンドをコピーします。

生成されたコマンドには、次の値がすでに設定されています。

  • -t：テストシナリオID
  • -e：実行環境ID

コピーしたコマンドをproject_rules.mdへ貼り付け、プレースホルダーを実際の値に置き換えます。

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

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

ステップ3：Builderにテストを実行させる

ルールファイルを配置したら、TraeでエージェントをBuilderに切り替え、対象リポジトリを開きます。Builderは初期化時にproject_rules.mdを読むため、Apidog CLIの実行ルールを認識できます。

まずは明示的に実行を依頼して動作を確認します。

Apidogテストシナリオを実行して、終了コードを教えてください。
Enter fullscreen mode Exit fullscreen mode

Builderはルールファイルにあるapidog runコマンドを提案します。Traeでは、エージェントがシェルコマンドを実行する前に承認操作が必要です。表示されたコマンドを確認し、実行をクリックしてください。

実行後、Builderはターミナル出力を読み取り、結果を分析します。確認すべき点は次の2つです。

  1. apidog runコマンドが実際に実行されている
  2. サマリーだけでなく終了コードも報告されている

-r cliレポーターを指定すると、各リクエスト、アサーション、サマリーがターミナルに出力されます。

ステップ4：Trae内でレポートを読み取る

テストが失敗した場合、-r cliの出力から原因を確認できます。Builderはターミナル内で次の情報を読み取れます。

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

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

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

htmlレポーターは自己完結型のレポートファイルを./apidog-reportsへ出力します。Builderが次の修正を判断できるよう、インライン出力用のcliは残してください。

JSONやJUnitを含むレポーターの詳細は、Apidog CLIテストレポートのガイドを参照してください。

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

この設定の目的は、毎回「テストを実行して」と指示しなくても、BuilderがAPI変更後に検証を実行できるようにすることです。

たとえば、BuilderがチェックアウトAPIのレスポンスを変更する場合、理想的な流れは次のようになります。

  1. ハンドラーやレスポンス定義を編集する
  2. ユニットテストを実行する
  3. ステージング環境に対してApidogシナリオを実行する
  4. 終了コードを確認する
  5. 成功なら次のタスクへ進む
  6. 失敗なら、失敗したアサーションを読み取る
  7. ステータスコード、フィールド不足、値の不一致を修正する
  8. Apidogシナリオを再実行する

つまり、APIテストがBuilderの既存の編集・テスト・修正ループに入ります。

この運用では、Apidogで人間が視覚的にシナリオを管理し、BuilderはCLIで実行結果を検証します。より広い運用パターンは、AIエージェントをAPIテストに利用する方法とApidog AIテストハーネスを参照してください。

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

エージェントの要約だけでテスト成功を判断しないでください。次の順序で確認します。

1. 実行コマンドを確認する

Traeのターミナルに、実際のapidog runコマンドとその出力が表示されていることを確認します。

Builderが「テストを実行した」と報告しても、ターミナルにコマンドがなければ実行されていません。その場合は、生出力を表示するように再度依頼します。

Apidogテストを再実行し、ターミナルの生出力と終了コードを表示してください。
Enter fullscreen mode Exit fullscreen mode

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

次に、終了コードを確認します。

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

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

終了コード 意味
0 すべてのアサーションが成功
非ゼロ 1件以上のアサーションが失敗

Builderの要約が「成功」となっていても、終了コードが非ゼロならテストは失敗です。終了コードを正としてください。

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

scenario not foundが表示された場合、Builderが誤ったIDを使用している可能性があります。

次の値を照合してください。

  • project_rules.mdの-tと-e
  • ApidogのCI/CDタブからコピーしたコマンド
  • ターミナルで実際に実行されたコマンド

ルールファイルには、Apidogが生成した正しいコマンドをそのまま保存するのが安全です。

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

project_rules.mdからapidog runを実行するだけでも、APIテストの自動検証は実現できます。

さらにMCPサーバーを接続すると、TraeのBuilderはAPI仕様を参照しながらコードを作成できます。TraeエージェントはMCPクライアントとして動作し、MCPサーバーが提供するツールを呼び出せます。

設定手順は次のとおりです。

  1. Traeの設定を開く
  2. MCPタブへ移動する
  3. マーケットプレイスからサーバーを選ぶ、または手動で追加を選択する
  4. サーバーのcommand、args、envを含むJSON設定を追加する

詳細はTraeのMCPサーバー追加ガイドを参照してください。

Apidog MCPサーバーは、MCP経由でAPI仕様を公開します。役割は明確に分けられます。

  • Apidog CLI：テストシナリオを実行する
  • Apidog MCPサーバー：エージェントへAPI仕様を提供する

よくある問題と対処法

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

Builderが汎用コマンドを実行したり、何も実行しなかったりする場合は、ルールファイルの配置を確認してください。

<repository-root>/
└── .trae/
    └── rules/
        └── project_rules.md
Enter fullscreen mode Exit fullscreen mode

確認ポイントは次のとおりです。

  • ファイルがリポジトリルート配下にある
  • ディレクトリ名がruleではなくrulesである
  • ファイル名がproject_rules.mdである
  • Traeのセッションを再起動してルールを再読み込みした

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

ローカルマシンでapidog login済みなら、ルールファイルやチャットにアクセストークンを記載しないでください。

- このマシンは`apidog login`経由で既に認証されています。
  `--access-token`を追加しないでください。
Enter fullscreen mode Exit fullscreen mode

対話利用とCIにおける認証情報の扱いは、Apidog CLI認証を参照してください。

Builderが存在しないフラグを使う

「不明なオプション」エラーは、インストール済みCLIに存在しないフラグを指定していることを示します。

まずローカルのヘルプを確認します。

apidog run --help
Enter fullscreen mode Exit fullscreen mode

その出力にあるフラグだけをproject_rules.mdへ反映してください。ローカルで実行したヘルプが、現在のCLIバージョンに対する正しい情報です。

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

サマリーの文面よりも終了コードを優先してください。

終了コードが非ゼロなら、テスト失敗として扱ってください。
Enter fullscreen mode Exit fullscreen mode

このルールをproject_rules.mdに書いておくことで、Builderがテスト結果を曖昧に解釈するリスクを減らせます。

日常のエージェント作業を、テスト済みのループへ変える

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

  1. インストールガイドに従ってapidog-cliをインストールする
  2. apidog loginで認証する
  3. ApidogのCI/CDタブからapidog runコマンドをコピーする
  4. .trae/rules/project_rules.mdへコマンドと終了コードのルールを追加する
  5. BuilderでAPIに影響する変更を行い、実行結果を確認する

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

テストシナリオは引き続きApidogで視覚的に構築し、BuilderにはそのシナリオをCLIで実行させます。Apidogをダウンロードして1つのシナリオを作成し、生成されたapidog runコマンドを.trae/rules/project_rules.mdに追加してみてください。

エージェントを使わないCI環境でも同じシナリオを実行したい場合は、GitHub ActionsでのApidog CLIで、シークレット、レポーター、終了コードによるゲート処理を確認できます。

Top comments (0)