WindsurfのCascadeエージェントはループを実行します。ファイルを編集し、ターミナルコマンドを実行し、出力を読み取り、次に何をすべきかを決定します。では、なぜあなたのAPIテストはそのループに含まれていないのでしょうか？APIテストはGUIの背後にあるApidogに置かれ、誰かがクリックするのを思い出したときに実行されます。Cascadeはそれらに触れることはありません。
解決策は1つの設定ブロックです。Apidog CLIはnpmパッケージ `apidog-cli` であり、Apidogで作成したテストシナリオをターミナルから直接実行します。CLIがインストールされ、Cascadeがその存在を認識すると、Windsurfはユニットテストを実行するのと同じ方法でApidogシナリオを実行します。コマンドを発行し、終了コードを読み取り、赤（失敗）が返された場合はコードを修正します。
まだCLIをインストールしていない場合は、まずそれを行ってください。AIコーディングエージェントを使用してApidog CLIをインストールする方法では、エージェントが入力する形でnpmのインストール、認証、および初回実行について説明しています。この記事は、`apidog --version` がバージョン番号を表示し、Apidogアカウントが認証されていることを前提としています。
この記事のWindsurfについて
WindsurfはCodeiumのエージェント型IDEであり、その組み込みエージェントはCascadeと呼ばれます。Cascadeはローカルで実行され、リポジトリを読み取り、ファイルを編集し、統合されたターミナルでシェルコマンドを実行し、自動実行設定に基づいて承認を求めます。これはエディターとそのエージェントであり、ブラウザ拡張機能やオートコンプリートプラグインではありません。
まだ設定していない場合は、まずWindsurfのダウンロードとインストール方法から始めてください。プロジェクトでCascadeを開くと、独自のルールメカニズムを通じてApidog CLIについて教えることができます。これにより、一度限りの「テストを実行する」という動作が、Cascadeが自律的に実行するものへと変わります。
ステップ1: .windsurf/rulesにApidogルールを追加する
Cascadeは作業を開始する前に、Markdownファイルからプロジェクトルールを読み取ります。それらをリポジトリのルートにある`.windsurf/rules/`ディレクトリに、1ファイルにつき1ルールとして配置してください。Windsurfは引き続きワークスペースルートにある従来の単一ファイル`.windsurfrules`と、すべてのプロジェクトに適用されるグローバルな`~/.codeium/windsurf/memories/global_rules.md`を読み取りますが、プロジェクトごとの指示には`.windsurf/rules/`ディレクトリが適切な場所です。これはWindsurfのルールと記憶のリファレンスに文書化されています。
`.windsurf/rules/apidog.md`を次のようなブロックで作成します。
# 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に触れるコードを変更したら、シナリオを実行し、結果に基づいて行動してください。
なぜチャットメッセージではなくルールファイルなのか？チャットに入力されたシナリオIDはセッションが終了すると消えてしまいます。一方、`.windsurf/rules/apidog.md`にあるものは、今後すべてのチームメイトとすべてのCascadeセッションで利用できます。それは永続的であり、Gitでバージョン管理され、Cascadeは起動時に自動的にコンテキストに読み込みます。
ステップ2: Apidogからコマンドを取得する
そのブロックの`<scenario_id>`と`<env_id>`は、あなたが推測するプレースホルダーではありません。Apidogが正確なコマンドを生成します。
Apidogでテストシナリオを開き、そのCI/CDタブに移動して、用意された`apidog run`コマンドをコピーしてください。そこには正しいシナリオID、環境ID、およびレポーターフラグがすでに入力されています。そのコマンドを例の行の代わりに`.windsurf/rules/apidog.md`に貼り付けてください。これで、ルールにはテンプレートではなく、実際にプロジェクトに対して機能するコマンドが保持されます。
そのコマンドの完全な構成と受け入れられるすべてのフラグについては、apidog runコマンドリファレンスを参照してください。
ステップ3: Cascadeにテストを実行させる
ルールが設定されたら、リポジトリでCascadeを開きます。起動時に`.windsurf/rules/apidog.md`を読み込むため、CLIの存在をすでに認識しています。APIに影響を与える変更を行うか、単にチェックを実行するように依頼してください。
Apidogシナリオを実行して、終了コードを教えてください。
Cascadeはルールから`apidog run`コマンドを発行します。プロンプトなしで実行されるかどうかは、自動実行設定によって異なります。Windsurfには4つのレベルがあります: 無効 (すべてのコマンドに承認が必要)、許可リストのみ (許可リストに一致するコマンドのみ自動実行)、自動 (プレミアムモデルの判断)、ターボ (拒否リストに登録されたコマンドを除いてすべて自動実行)。ターボモードでは、通常の`apidog run`が自動で実行されます。より厳格なモードでは、Cascadeは一時停止して最初に尋ねます。
すべてを緩めることなく`apidog run`を自動実行させたい場合は、許可リストに追加してください。設定は`windsurf.cascadeCommandsAllowList`で、コマンドパレットの「設定を開く」からアクセスできます。`apidog`を追加すると、Cascadeは尋ねることなくコマンドを実行します。対応する拒否リストの設定は`windsurf.cascadeCommandsDenyList`で、コマンドが両方に一致する場合は拒否リストが優先されます。どちらもWindsurfのターミナルドキュメントで説明されています。ステージングに対する読み取り専用シナリオは、許可リストエントリがまさに想定しているような安全なワークスペース内コマンドです。
ステップ4: Windsurf内でレポートを読み取る
実行が赤（失敗）になった場合、レポートに答えがあります。`-r cli`レポーターは、Cascadeのターミナルにステップバイステップの結果と要約を直接出力します。各リクエスト、各アサーション、そして期待値と実際の値のどちらが失敗したかを報告します。失敗したアサーションは正確なフィールド名またはステータスコードを特定し、これは通常、Cascadeが次のパスで修正を見つけるのに十分です。
ブラウザで開いたり、チームメイトに渡したりできるレポートについては、HTMLレポーターを追加してください。
apidog run -t <scenario_id> -e <env_id> -r cli,html
`html`レポーターは自己完結型のファイルを`./apidog-reports`に書き込みます。`cli`をリストに残しておくことで、Cascadeは次のステップを決定するために読み取るインライン出力を引き続き取得できます。JUnit形式のCIダッシュボードが解析するものを含むすべてのレポーターについては、Apidog CLI完全ガイドとApidog CLIテストレポートの読み方を参照してください。
Windsurf自身のループ内でのテスト
重要なのは、あなたが尋ねるのをやめ、ルールがそうするように指示したためにCascadeが自律的にシナリオを実行したときに何が起こるかです。
Cascadeがチェックアウト応答を構築するハンドラを編集している状況を想像してください。そのループは変化します。コードを編集した後、成功を宣言するのではなく、ステージングに対してApidogシナリオを実行し、終了コードを読み取り、それに基づいて行動します。緑（成功）なら次のステップに進みます。赤（失敗）ならレポートを開き、どのアサーションが失敗したか（ステータスコード、欠落しているフィールド、間違った値）を読み取り、修正を試み、再実行します。APIテストは、Cascadeがすでにユニットテストを実行しているのと同じ「編集-テスト-修正」ループの一部となります。あなたは1つのルールを記述しただけで、Cascadeはそのコマンドを既存の動作に組み込みました。
これは、あらゆるエージェントワークフローを安全にする「委任して検証する」モデルです。Cascadeはコマンドを実行し、結果を読み取ります。あなたはApidogで視覚的にシナリオを作成し続け、エージェントが終了コードを正確に読み取っていることを随時確認します。より広範なパターンについては、AIエージェントをAPIテストに利用する方法とApidog AIテストハーネスを参照してください。
Cascadeが実際にCLIを実行しているかを確認する
エージェントは実際には達成していない成功を報告することがあり、Cascadeも例外ではありません。問題を発見する頻度順に3つのチェックを行います。
まず、コマンドが実行されたことを確認します。Cascadeは実行したコマンドとその出力をターミナルにインラインで表示します。文字通りの`apidog run ...`の行とその下の結果を探してください。Cascadeがテストを実行したと言っているのにコマンドが表示されない場合、それは実行しなかったことを要約しただけです。再度実行させ、生の出力を表示するように依頼してください。
次に、重要な終了コードを確認します。直接尋ねてください。
そのapidog runコマンドの終了コードは何でしたか？
`apidog run`はすべてのアサーションがパスした場合は0を、いずれかが失敗した場合は0以外の値を返して終了します。この単一の動作により、Cascadeやパイプラインは実行をクリーンなゲートとして扱うことができます。Cascadeの記述が「テストがパスした」と言っているにもかかわらず終了コードが0以外の場合、終了コードが正しいです。
第三に、実際のシナリオを使用したことを確認します。「シナリオが見つかりません」というエラーで実行が失敗した場合、CascadeがIDを捏造したか、誤って記憶した可能性があります。ルールファイルとCI/CDタブでApidogが生成したコマンドに対して、`-t`と`-e`の値を再確認してください。`.windsurf/rules/apidog.md`にあるIDが真実です。
オプション: Apidog MCPサーバーを接続する
ルールから`apidog run`を実行するだけで、ほとんどの要件を満たします。さらに一歩進めるには、MCPサーバーを接続します。
Cascadeはモデルコンテキストプロトコルをサポートしています。Windsurfは`~/.codeium/windsurf/mcp_config.json`からサーバーリストを読み取ります。これは直接編集することも、Cascade MCPパネルを通じて管理することもできます。形式はWindsurfのMCPリファレンスに文書化されており、WindsurfでMCPサーバーを設定する方法でパネル操作が説明されています。Apidog MCPサーバーはMCPを介してAPI仕様を公開するため、Cascadeはコードを記述する「最中」にスキーマを読み取ることができ、後で確認するだけではありません。役割分担は明確です。CLIがテストを実行し、MCPがエージェントに仕様を提供します。
Windsurfが誤った場合
セットアップ中にいくつかの失敗が頻繁に発生します。
ルールを無視する。Cascadeが一般的なコマンドを実行するか、まったく何も実行しない場合、ルールが読み込まれていない可能性があります。ファイルがリポジトリルートの`.windsurf/rules/`内にあり、`.md`拡張子を持っていることを確認してください。各ルールファイルは12,000文字に制限されているため、Apidogブロックは短く保ってください。Cascadeを再起動すると、強制的に再読み込みが行われます。
いずれにしてもアクセストークンを渡す。Cascadeがコマンドにアクセストークンを追加しようとする場合、それは公開されている例から推測しているだけです。マシンが`apidog login`経由で認証されているため、あなたのルールはすでにそうしないように指示しています。その行を強調し、コミットされるルールファイルに実際のトークンを決して入れないでください。認証が実際にどのように機能するかについては、Apidog CLI認証ガイドを参照してください。
フラグを捏造する。「unknown option（不明なオプション）」エラーは、Cascadeがあなたのバージョンには存在しないフラグを推測したことを意味します。`apidog run --help`を実行させ、そこから正確なフラグをコピーするよう指示してください。これはインストールされているバージョンに対して常に正しいです。
失敗した実行をパスと報告する。これは最も代償が大きい間違いであり、終了コードに関するルールがルールファイルと検証ステップの両方にある理由です。要約と終了コードが一致しない場合、終了コードが優先されます。
日常のエージェントからテストされたループへ
これがセットアップです。インストールガイドに従って`apidog-cli`を一度インストールし、リポジトリの`.windsurf/rules/`ディレクトリに短いApidogルールを追加すると、Cascadeはコードを編集するためにすでに使用しているのと同じループ内で、APIテストを実行し結果を読み取る方法を認識します。壊れたエンドポイントは、変更がリリースされた後ではなく、Cascadeがまだ変更に取り組んでいる間に捕捉されます。
GUIの背後にあるテストは人間がクリックしたときに実行されますが、一行のコマンドはCascadeが決定するたびに実行されます。あなたはApidogで視覚的にシナリオを構築し続け、エージェントはあなたが監視していない場所でそれらを実行します。ローカルで動作するようになったコマンドをパイプラインで実行するには、GitHub ActionsにおけるApidog CLIがシークレット、レポーター、および終了コードのゲート処理について説明しています。Apidogをダウンロードし、1つのシナリオを作成し、その`apidog run`コマンドをWindsurfルールにドロップし、次の変更でCascadeがそれを取り上げるのを見てください。