DEV Community

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

Posted on • Originally published at apidog.com

Apidog CLIをClineで使う方法

Clineは、計画、ファイル編集、コマンド実行、出力確認、次のアクション決定を繰り返すループ型のコーディングエージェントです。APIテストがApidogのGUI内だけにあり、人がクリックしないと実行されない状態では、このループに組み込めません。apidog-cliを使えば、Apidogで作成したテストシナリオをターミナルから実行でき、Clineはユニットテストと同じように終了コードと出力に基づいて修正・再実行できます。

今すぐApidogを試す

Apidog CLIは、Apidogで作成したテストシナリオをターミナルから実行するnpmパッケージ apidog-cli です。CLIをインストールし、Clineのプロジェクトルールに実行方法を追加すると、エージェントはapidog runを実行し、終了コードが非ゼロなら失敗として扱い、原因を確認して修正を試みられます。

まだCLIをインストールしていない場合は、先にセットアップしてください。AIコーディングエージェントでApidog CLIをインストールする方法では、npmでのインストール、認証、初回実行を解説しています。以降の手順では、次の状態を前提とします。

apidog --version
Enter fullscreen mode Exit fullscreen mode

上記のコマンドでバージョン番号が表示され、Apidogアカウントへの認証が完了していることを確認してください。

この記事で説明するClineについて

Clineは、VS Code拡張機能として利用できるオープンソースの自律型コーディングエージェントです。JetBrains向けビルドやCLI版もあります。

Clineはリポジトリを読み込み、プランモードで作業を計画し、アクティブモードでファイル編集やシェルコマンド実行を行います。承認が必要な操作は、設定に応じて確認を求めます。ホスト型チャットボットではなく、ローカルのコードベースを対象に動作する点が特徴です。

VS CodeでClineパネルを開き、変更差分とターミナル出力を確認できる状態なら準備できています。基本的な導入やモデル選択は、Clineの使い方を参照してください。

ClineにAPIテストを継続して実行させるには、チャットで毎回指示するのではなく、プロジェクトルールとして保存します。そのために使用するのが.clinerules/ディレクトリです。

ステップ1：.clinerules/にApidog CLIのルールを追加する

Clineはタスク開始時に、ワークスペースルートの.clinerules/ディレクトリからプロジェクトルールを読み込みます。ディレクトリ内の.mdおよび.txtファイルは、セッション中に適用される指示として統合されます。

単一の.clinerulesファイルを使うこともできますが、ルールが増える場合はディレクトリで管理する方が拡張しやすくなります。詳細はClineルールリファレンスを参照してください。

リポジトリのルートで、次のファイルを作成します。

.clinerules/apidog.md
Enter fullscreen mode Exit fullscreen mode

内容は次のようにします。

# ApidogによるAPIテスト

- APIをテストするには、curlやアドホックスクリプトではなく、Apidog CLIを実行してください。
- コマンド: apidog run -t <scenario_id> -e <env_id> -r cli
- シナリオIDと環境IDはApidogのCI/CDタブから取得します。それらの正確な値を使用してください。
- 終了コード0はすべてのアサーションが成功したことを意味します。0以外は失敗を意味します。終了コードが真実であり、あなたの要約ではありません。
- マシンは`apidog login`ですでに認証されています。`--access-token`を追加したり、このファイルにトークンを置いたりしないでください。
- 不明なフラグがある場合は、`apidog run --help`を実行し、そこにある正確なフラグを使用してください。
Enter fullscreen mode Exit fullscreen mode

チャットに入力したシナリオIDは、そのタスクが終われば失われます。一方、.clinerules/apidog.mdに保存したルールは、以後のClineタスクと、そのリポジトリをチェックアウトするチームメンバーに共有されます。

このファイルはコードと同様にバージョン管理してください。

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

Clineに渡すのは、推測したコマンドではなく、Apidogが生成した実際のapidog runコマンドです。

  1. Apidogで対象のテストシナリオを開きます。
  2. CI/CDタブに移動します。
  3. 生成されたコマンドをコピーします。

たとえば、次のようなコマンドです。

apidog run -t 8291 -e 42 -r cli
Enter fullscreen mode Exit fullscreen mode
  • -t: テストシナリオID
  • -e: 環境ID
  • -r cli: CLI形式で実行結果を出力するレポーター

コピーした正確なIDを、.clinerules/apidog.mdのルールへ反映してください。

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

これにより、Clineが存在しないシナリオIDや誤った環境IDを推測するリスクを減らせます。利用可能なフラグは、apidog runコマンドリファレンスで確認してください。

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

ルールを追加したら、新しいClineタスクを開始します。Clineはタスク開始時に.clinerules/を読み込むため、Apidog CLIの実行ルールを認識した状態で作業できます。

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

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

Clineは計画を立て、アクティブモードでルールに定義したapidog runコマンドを実行します。

実行時に承認を求めるかどうかは、Clineの自動承認設定に依存します。ステージング環境に対する読み取り専用のテストシナリオは、安全なコマンドとして扱えるケースがあります。安全なコマンドの実行を自動承認している場合、apidog runは確認なしで実行されます。

毎回の確認を減らす場合は、execute-safe-commandsの自動承認設定を確認してください。ただし、実行対象の環境とシナリオ内容は事前に確認し、意図しない更新操作を含まないようにします。

-r cliを指定すると、各リクエスト、アサーション、実行結果の要約がターミナルに出力されます。Clineはこの出力と終了コードを次の判断に利用できます。

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

テストが失敗した場合は、-r cliの出力を確認します。ターミナルには通常、次の情報が表示されます。

  • 実行されたリクエスト
  • 実行されたアサーション
  • 失敗したリクエスト
  • 期待値と実際値
  • ステータスコードや不足フィールドなどの失敗理由

この情報を使うと、Clineは失敗したフィールド、レスポンス形式、ステータスコードなどを基に修正候補を特定できます。

ブラウザで確認したい場合や、チームメンバーにレポートを共有したい場合は、HTMLレポーターを追加します。

apidog run -t 8291 -e 42 -r cli,html
Enter fullscreen mode Exit fullscreen mode

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

Clineが次の修正方針を判断するにはインライン出力も必要になるため、レポーター一覧にはcliを残してください。

JUnit形式など、CIダッシュボード向けのレポーターやフラグについては、Apidog CLI完全ガイドおよびApidog CLIテストレポートガイドを参照してください。

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

この設定の目的は、Clineがコード変更後にAPIテストを実行し、結果に応じて次の行動を決められるようにすることです。

たとえば、Clineがチェックアウトレスポンスを構築するハンドラを変更しているとします。期待する流れは次のとおりです。

  1. Clineがコードを編集する。
  2. apidog runでステージング環境のシナリオを実行する。
  3. 終了コードとCLI出力を確認する。
  4. 終了コードが0なら、次の作業へ進む。
  5. 終了コードが非ゼロなら、失敗したアサーションを確認する。
  6. ステータスコード、不足フィールド、値の不一致などを修正する。
  7. 同じシナリオを再実行する。

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

これは、エージェント活用における「委任して検証する」モデルです。Apidogでテストシナリオを視覚的に作成・管理し、ClineにはCLIを通じて実行と結果確認を担当させます。エージェントの要約だけに依存せず、終了コードと実際の出力を定期的に確認してください。

より広いパターンについては、APIテストにAIエージェントを使用する方法およびApidog AIテストハーネスを参照してください。

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

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

1. 実行コマンドと生出力を確認する

Clineはタスクビューに、実行したコマンドと出力を表示します。次のような行が実際に表示されているか確認してください。

apidog run -t 8291 -e 42 -r cli
Enter fullscreen mode Exit fullscreen mode

その直後にテスト結果の出力があることも確認します。

Clineが「テストを実行した」と述べていても、実行コマンドや出力が表示されない場合は、実際には実行されていない可能性があります。次のように依頼してください。

Apidogテストを再実行し、コマンドと生出力をそのまま表示してください。
Enter fullscreen mode Exit fullscreen mode

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

終了コードはテスト結果の最終的な判定です。Clineには次のように質問できます。

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

apidog runは、すべてのアサーションが成功した場合に0で終了し、失敗がある場合は非ゼロで終了します。

Clineの文章による要約と終了コードが一致しない場合は、終了コードを優先してください。

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

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

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

  • ApidogのCI/CDタブで生成されたコマンド
  • .clinerules/apidog.md内の-tの値
  • .clinerules/apidog.md内の-eの値

ルールファイルには、Apidogが生成した実際のIDを保存してください。

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

.clinerules/からapidog runを実行するだけでも、多くのAPIテストワークフローに対応できます。さらに、仕様情報をClineへ提供したい場合はMCPを利用できます。

ClineはModel Context Protocol（MCP）をサポートしています。VS Code拡張機能では、次の手順でMCP設定を開けます。

  1. ClineパネルのMCPサーバーアイコンをクリックする。
  2. Configureを開く。
  3. Configure MCP Serversをクリックする。
  4. cline_mcp_settings.jsonを開く。
  5. mcpServersオブジェクトにサーバーを追加する。

また、Cline MCPドキュメントのとおり、MCPマーケットプレイスからサーバーを参照・インストールすることもできます。

Apidog MCPサーバーを利用すると、MCP経由でAPI仕様をClineに公開できます。

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

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

Clineがコードを書く前にスキーマを参照し、変更後にCLIでテストを実行するフローを構築できます。

なお、Clineは対話型の拡張機能であり、ヘッドレスランナーのような非対話型テストモードを組み込んでいるわけではありません。Clineが存在しないCIパイプラインでapidog runを実行する場合は、GitHub ActionsでのApidog CLIとApidog CLI CI/CDパイプラインガイドを参照してください。

Clineが期待どおりに動かない場合

セットアップ時に発生しやすい問題と確認方法をまとめます。

ルールファイルを読み込まない

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

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

  • ディレクトリ名が正確に.clinerulesである
  • .clinerulesがワークスペースのルートにある
  • ルールファイルの拡張子が.mdまたは.txtである
  • 新しいClineタスクを開始している

新しいタスクを開始すると、Clineはルールを再読み込みします。

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

Clineが--access-tokenを追加しようとする場合、公開されている例をもとに推測している可能性があります。

ローカル環境がapidog loginで認証済みなら、トークンをコマンドや.clinerules/に書き込む必要はありません。ルール内で明示的に禁止してください。

- マシンは`apidog login`ですでに認証されています。`--access-token`を追加したり、このファイルにトークンを置いたりしないでください。
Enter fullscreen mode Exit fullscreen mode

認証方法の詳細は、Apidog CLI認証ガイドを参照してください。

存在しないフラグを使う

unknown optionや不明なオプションのエラーは、Clineが現在のCLIバージョンに存在しないフラグを推測したことを示します。

次のコマンドで、インストール済みバージョンがサポートする正確なフラグを確認してください。

apidog run --help
Enter fullscreen mode Exit fullscreen mode

ルールにも、推測ではなくヘルプの出力を優先する指示を残します。

- 不明なフラグがある場合は、`apidog run --help`を実行し、そこにある正確なフラグを使用してください。
Enter fullscreen mode Exit fullscreen mode

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

最も重要なのは、要約ではなく終了コードを信頼することです。

  • 終了コード0: すべてのアサーションが成功
  • 非ゼロの終了コード: 何らかの失敗が発生

Clineの要約が「成功」となっていても、終了コードが非ゼロならテストは失敗です。このルールは.clinerules/apidog.mdに明示し、レビュー時にも確認してください。

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

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

  1. インストールガイドに従ってapidog-cliをインストールする。
  2. Apidogでテストシナリオを作成する。
  3. CI/CDタブからapidog runコマンドをコピーする。
  4. リポジトリの.clinerules/apidog.mdに実行ルールとして保存する。
  5. ClineにAPI変更後のテスト実行を依頼する。
  6. コマンド、出力、終了コードを確認する。

GUI内のテストは、人がクリックしたときに実行されます。一方、CLIコマンドとして定義したテストは、Clineがコード変更を検証するタイミングで実行できます。

Apidogでシナリオを視覚的に管理し、Clineには実行・出力確認・修正ループを任せてください。Apidogをダウンロードして1つのシナリオを作成し、そのapidog runコマンドを.clinerules/apidog.mdへ追加するところから始められます。

Top comments (0)