DEV Community

Cover image for ウィンドサーフでのApidog CLIの使い方
Akira
Akira

Posted on • Originally published at apidog.com

ウィンドサーフでのApidog CLIの使い方

WindsurfのCascadeエージェントは、ファイル編集、ターミナルコマンドの実行、出力の読み取り、次の作業の判断をループで行います。このループにAPIテストも組み込めば、API変更後にテストを実行し、失敗した場合は結果を基に修正する流れを自動化できます。Apidogで作成したテストシナリオは、apidog-cliを使うことでターミナルから直接実行できます。

今すぐApidogを試す

Apidog CLIをCascadeに認識させるには、プロジェクトルールに実行コマンドと判定条件を記述します。Cascadeはユニットテストと同様にapidog runを実行し、終了コードが0以外なら失敗として扱えます。

前提条件

最初にApidog CLIをインストールし、認証を完了してください。

  • apidog --versionでバージョン番号が表示される
  • apidog loginによる認証が完了している
  • Apidog上に実行対象のテストシナリオがある

インストール、認証、初回実行については、AIコーディングエージェントを使用してApidog CLIをインストールする方法を参照してください。

WindsurfとCascadeの役割

WindsurfはCodeiumのエージェント型IDEで、組み込みエージェントはCascadeです。Cascadeはローカル環境で次の操作を実行できます。

  • リポジトリ内のファイルを読む
  • ファイルを編集する
  • 統合ターミナルでコマンドを実行する
  • コマンド出力と終了コードを読む
  • 自動実行設定に応じて承認を求める

Windsurfをまだセットアップしていない場合は、Windsurfのダウンロードとインストール方法から始めてください。

ステップ1: .windsurf/rulesにApidogルールを追加する

Cascadeは作業開始時にプロジェクトルールを読み取ります。Apidog CLIの実行方法を永続化するため、リポジトリルートに次のファイルを作成します。

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

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

# Apidog APIテスト

このプロジェクトにはApidogテストシナリオがあります。Apidog CLIで実行してください:

    apidog run -t <scenario_id> -e <env_id> -r cli

ルール:
- 上記の正確なコマンドを使用し、フラグを勝手に作成しないでください。不明な場合は `apidog run --help` を実行してください。
- `apidog run` は、すべてのアサーションがパスした場合は0を、いずれかが失敗した場合は0以外の値を返します。
  終了コード0をパス、0以外を失敗として扱います。実際の終了コードを報告してください。
- マシンはすでに `apidog login` 経由で認証されています。コマンドにアクセストークンを追加したり、
  このファイルにコミットしたりしないでください。
- APIに触れるコードを変更したら、シナリオを実行し、結果に基づいて行動してください。
Enter fullscreen mode Exit fullscreen mode

.windsurf/rules/にルールを置くと、チャット内の一時的な指示ではなく、Gitで管理できるプロジェクト設定になります。チームメンバーと今後のCascadeセッションも同じコマンドを利用できます。

Windsurfは従来の.windsurfrulesも読み取りますが、プロジェクト固有のルールには.windsurf/rules/を使用するのが適しています。詳細はWindsurfのルールと記憶のリファレンスを確認してください。

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

<scenario_id>と<env_id>を推測で入力しないでください。Apidogが対象シナリオに対応するコマンドを生成します。

  1. Apidogでテストシナリオを開く
  2. CI/CDタブへ移動する
  3. 表示されたapidog runコマンドをコピーする
  4. .windsurf/rules/apidog.mdのテンプレート行をコピーしたコマンドに置き換える

最終的には、次のように実際のIDを含むコマンドをルールへ保存します。

    apidog run -t actual_scenario_id -e actual_env_id -r cli
Enter fullscreen mode Exit fullscreen mode

Apidogが生成したコマンドには、対象シナリオ、環境、レポーターフラグが含まれます。利用できるフラグの詳細は、apidog runコマンドリファレンスを参照してください。

ステップ3: CascadeからApidogテストを実行する

ルールを保存したら、対象リポジトリでCascadeを開きます。APIに影響するコードを変更した後、または明示的な確認として、次のように依頼します。

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

Cascadeはルールに書かれたapidog runコマンドを実行し、ターミナル出力と終了コードを確認します。

apidog runを自動実行できるようにする

Cascadeが確認なしでコマンドを実行できるかどうかは、Windsurfの自動実行設定に依存します。主なレベルは次の4つです。

  • 無効: すべてのコマンドで承認が必要
  • 許可リストのみ: 許可リストに一致するコマンドだけ自動実行
  • 自動: プレミアムモデルの判断で実行
  • ターボ: 拒否リストに一致しないコマンドを自動実行

すべてのコマンドを緩和せず、Apidog CLIだけを許可する場合は、設定のwindsurf.cascadeCommandsAllowListにapidogを追加します。

{
  "windsurf.cascadeCommandsAllowList": [
    "apidog"
  ]
}
Enter fullscreen mode Exit fullscreen mode

拒否リストはwindsurf.cascadeCommandsDenyListです。両方に一致する場合、拒否リストが優先されます。設定の詳細はWindsurfのターミナルドキュメントを参照してください。

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

-r cliを指定すると、各リクエスト、アサーション、失敗内容がCascadeのターミナルに出力されます。失敗時は、次の情報を確認します。

  • ステータスコードの不一致
  • 必須フィールドの欠落
  • 期待値と実際の値の差異
  • 失敗したアサーション名
  • 終了コード

ブラウザで共有可能なレポートも出力したい場合は、HTMLレポーターを追加します。

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

htmlレポーターは./apidog-reportsに自己完結型のレポートファイルを書き出します。cliを残しておけば、Cascadeはターミナルのインライン出力を読み取り、次の修正判断に利用できます。

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

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

設定後のCascadeは、APIに関わるコードを変更した際に次のループを実行できます。

  1. ハンドラやサービスを編集する
  2. apidog runでステージング環境のシナリオを実行する
  3. 終了コードを確認する
  4. 成功なら次の作業へ進む
  5. 失敗ならアサーション結果を読み、修正して再実行する

たとえば、チェックアウトレスポンスを返すハンドラを変更した場合、Cascadeはステータスコード、レスポンスフィールド、値の不一致をCLI出力から確認できます。APIテストをユニットテストと同じ編集・検証ループに含めることで、変更中に問題を検出できます。

これは、エージェントに作業を委任しつつ結果を検証するための実装パターンです。Apidogでは引き続き視覚的にシナリオを作成し、CascadeにはCLIの終了コードと出力を判断材料として渡します。

関連する実践例は、AIエージェントをAPIテストに利用する方法およびApidog AIテストハーネスを参照してください。

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

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

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

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

apidog run ...
Enter fullscreen mode Exit fullscreen mode

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

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

次のように直接確認します。

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

apidog runは、すべてのアサーションが成功した場合に0、いずれかが失敗した場合に0以外を返します。Cascadeの要約が「成功」となっていても、終了コードが0以外なら失敗として扱います。

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

「シナリオが見つかりません」と表示された場合、誤ったIDが使われている可能性があります。次を比較してください。

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

IDはApidogが生成したコマンドを正とし、ルールファイルを更新します。

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

CLIによるapidog runだけで、テスト実行の大半はカバーできます。API仕様をコーディング中にも参照させたい場合は、MCPサーバーを追加できます。

CascadeはModel Context Protocolをサポートしており、Windsurfは次のファイルからMCPサーバー設定を読み取ります。

~/.codeium/windsurf/mcp_config.json
Enter fullscreen mode Exit fullscreen mode

設定はファイルを直接編集するか、Cascade MCPパネルから管理できます。WindsurfのMCPリファレンスと、WindsurfでMCPサーバーを設定する方法を参照してください。

Apidog MCPサーバーを使うと、CascadeはMCP経由でAPI仕様を参照できます。役割は分けて考えると分かりやすくなります。

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

よくある問題と対処

ルールを無視する

Cascadeが一般的なコマンドを実行する、または何も実行しない場合は、ルールの配置を確認します。

<repository-root>/
└── .windsurf/
    └── rules/
        └── apidog.md
Enter fullscreen mode Exit fullscreen mode

確認項目:

  • ファイルがリポジトリルート配下の.windsurf/rules/にある
  • 拡張子が.mdである
  • ルールファイルが12,000文字以内である
  • Cascadeを再起動してルールを再読み込みした

アクセストークンをコマンドに追加しようとする

認証済み環境では、コマンドにアクセストークンを追加しないでください。

apidog login
Enter fullscreen mode Exit fullscreen mode

を一度実行して認証を済ませ、トークンをGit管理下のルールファイルへ保存しない運用にします。認証の詳細はApidog CLI認証ガイドを参照してください。

存在しないフラグを使う

unknown optionエラーが出た場合、Cascadeが未対応のフラグを推測している可能性があります。インストール済みバージョンのヘルプを確認します。

apidog run --help
Enter fullscreen mode Exit fullscreen mode

表示されたフラグだけをルールファイルやコマンドに使用してください。

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

要約より終了コードを優先します。

終了コード 0     → 成功
終了コード 0以外 → 失敗
Enter fullscreen mode Exit fullscreen mode

この条件を.windsurf/rules/apidog.mdへ明示しておくことで、Cascadeが失敗結果を成功として扱うリスクを下げられます。

まとめ

apidog-cliを一度インストールし、.windsurf/rules/apidog.mdにプロジェクトで使う正確なapidog runコマンドを保存すれば、CascadeはAPI変更後にテストを実行し、終了コードとレポートを基に次の作業を判断できます。

Apidogでは引き続き視覚的にシナリオを作成し、WindsurfではCLIコマンドを使ってエージェントの編集・テスト・修正ループへ組み込みます。ローカルで動作するコマンドをCI/CDでも実行したい場合は、GitHub ActionsにおけるApidog CLIを参照してください。

Apidogをダウンロードし、まず1つのシナリオを作成して、そのapidog runコマンドをWindsurfルールへ追加してみてください。

Top comments (0)