Cursorのエージェントは、すでにファイルを編集し、ターミナルを実行し、出力を読み取り、壊れた部分を修正します。次のステップは、そのループにAPIテストを組み込むことです。つまり、Cursorに実際のApidogシナリオを実行させ、合否を読み取り、継続させます。これを可能にするのが、Cursorが呼び出すことができるコマンドラインランナーです。
そのランナーはApidog CLIというnpmパッケージで、apidog-cliという名前です。これは、Apidogで視覚的に構築したテストシナリオをターミナルから実行し、Cursorがそれに基づいて動作できるステータスコードで終了します。このガイドでは、Cursorに特化した部分、つまりCursorにワークフローを教えるルールファイル、テストを実行するプロンプト、実行が編集・テスト・修正ループにどのように組み込まれるか、そしてコード作成中にAPI仕様をCursorに渡すオプションのMCPサーバーについて説明します。
まだCLIがインストールされていない場合は、AIコーディングエージェントでApidog CLIをインストールする方法から始めてください。これは、Cursorにインストールと認証の手順を説明します。apidog --versionがバージョン番号を表示するようになったら、ここに戻ってきてください。また、少なくとも1つの保存されたテストシナリオを持つApidogアカウントも必要です。お持ちでない場合は、Apidogをダウンロードしてください。
CursorでCLIを使用するとはどういう意味か
Cursor用のApidogプラグインはありませんし、必要ありません。Cursorのエージェントはすでにプロジェクトのターミナルでシェルコマンドを実行します。したがって、CursorでApidog CLIを使用するということは、次の3つのことを意味します。
- プロジェクトルールでCursorにワークフローを一度教えることで、コマンド、フラグ、そして終了コードが真実の源であることを認識させます。
- エージェントに
apidog runを実行させる。これはユニットテストを実行するのと同様に、ループ内の通常のステップとして行われます。 - 必要に応じてApidog MCPサーバーを接続する。これにより、Cursorはテストがチェックするコードを作成する際にAPI仕様を読み取ることができます。
このルールがあるからこそ、これは一般的な「ターミナルを開いて入力する」ガイドではなく、Cursorに特化したものになるのです。
ステップ1：プロジェクトルールを追加する
Cursorは、リポジトリのルートにある.cursor/rulesディレクトリからプロジェクトルールを読み取ります。各ルールは、小さなフロントマターブロックを持つ.mdcファイルで、コードと一緒にバージョン管理されるため、チーム全体が同じ動作を得ることができます。
ルールを作成するには2つの方法があります。チャットで/create-ruleと入力して希望する内容を記述するか、Cursor Settings > Rules, Commandsを開き、+ Add Ruleをクリックします。どちらの方法でも.cursor/rulesの下にファイルが作成されます。
これを.cursor/rules/apidog-cli.mdcとして保存します。
---
description: How to run Apidog API tests from the terminal
alwaysApply: false
---
# Running Apidog API tests
This project has API test scenarios in Apidog. Run them with the
apidog-cli, which is installed globally and already authenticated.
- The command is `apidog run`. The binary is `apidog`.
- Run a single scenario by ID: `apidog run -t <scenarioId> -e <environmentId> -n 1 -r cli`
- `-t` is the test scenario ID, `-e` is the environment ID.
- `-n 1` runs it once. `-r cli` prints a readable report to the terminal.
- Do not pass `--access-token`. Auth is handled by a prior `apidog login`.
- The exit code is the source of truth: `0` means every assertion passed,
non-zero means a failure. Report the exit code, not just a summary.
- If a flag is unknown, run `apidog run --help` and use the exact flag from there.
Never guess at flag names.
- After changing code that touches an endpoint, run the relevant scenario
and read the result before claiming the change works.
フロントマターは重要です。descriptionとalwaysApply: falseを組み合わせることで、これは賢く適用されるルールになります。つまり、Cursorはチャットがテスト実行に関する場合にのみこのルールを読み込み、すべての会話でコンテキストを消費するのを防ぎます。常にスコープ内に含めるには、alwaysApply: trueを設定します。ファイルタイプにスコープを設定するには、descriptionを削除してglobs行を追加すると、一致するファイルが開かれたときにCursorが自動的にアタッチします。
コンテンツが実際の作業を行います。コマンドの形式を固定し、認証元を示し、エージェントを正直に保つ一文を述べます。「終了コードは文章に勝る」と。エージェントは失敗したレポートを読んで「問題ない」と判断することがありますが、このルールを一度書き記しておけば、手作業でそれを修正する必要がなくなります。
ステップ2：Apidogからコマンドを取得する
エージェントに何かを実行させる前に、正しいことが分かっているコマンドを取得してください。CursorにIDを推測させないでください。
Apidogでテストシナリオを開き、CI/CDタブに切り替えて、コマンドラインオプションを選択します。Apidogは、シナリオID、環境ID、およびアクセストークンがすでに記入された完全なapidog runコマンドを生成します。
apidog run --access-token YOUR_ACCESS_TOKEN -t 605067 -e 1629989 -n 1 -r cli
605067はテストシナリオID、1629989は環境IDです。あなたのものとは異なるでしょう。CLIをインストール時に認証済みなので、--access-tokenの部分は削除し、IDはそのまま残してください。それがルールがCursorに使うように指示したコマンドです。
ステップ3：エージェントにテストを実行させる
Cursorのエージェント（インライン編集ではなく、ターミナルコマンドを実行するチャットモード）を開きます。ルールが設定されていれば、プロンプトは短くなります。
私のApidogテストシナリオを実行して、完全な出力を表示し、終了コードを教えてください。
Cursorはコマンドを提案し、あなたが承認した後、統合ターミナルでそれを実行します。
apidog run -t 605067 -e 1629989 -n 1 -r cli
デフォルトでは、Cursorはターミナルコマンドを実行する前に尋ねるので、何が実行されようとしているのかを正確に確認できます。それを承認すると、エージェントはシナリオを実行し、その実行結果と要約を読み上げます。
あなたの確認事項：要約ではなく、終了コードを見てください。apidog runは、すべてのアサーションが成功した場合は0で終了し、1つでも失敗した場合は非ゼロで終了します。この動作こそが、CIとエージェントにとってこれがゲートとして機能する理由です。もしCursorが「テストが成功しました」と言っても、終了コードが非ゼロであれば、それは誤りです。コードを信頼してください。これは、ステップ1のルールが防ぐまさにその失敗です。
異なるレポート形式やより多くのイテレーションが必要な場合は、エージェントにapidog run --helpを実行させて、インストールされているバージョンに対応する実際のフラグリストを読み取らせてください。Apidog CLI完全ガイドでは、html、json、junitレポート出力機能やデータ駆動型イテレーションを含む、すべてのフラグが文書化されています。
ステップ4：Cursor内でレポートを読み取る
-r cliレポーターは、Cursorがすでに読み取っているターミナルに結果を出力するため、エージェントの作業に適しています。エージェントはあなたと同じ行を見ます。どのシナリオが実行されたか、各リクエスト、各アサーション、そして最終的な合否カウントです。
実行が失敗した場合、レポートは失敗したアサーション、期待値、およびエンドポイントが返したものを表示します。そのテキストはエージェントのコンテキストにあるため、同じチャットでフォローアップできます。
シナリオが失敗しました。レポート内の失敗したアサーションを読み取り、そのフィールドを生成するハンドラーを見つけて修正案を提案してください。その後、シナリオを再度実行し、新しい終了コードを表示してください。
これでテストはループの一部になりました。Cursorはハンドラーを編集し、apidog runを再実行し、新しい終了コードを読み取り、次に進むか再試行します。あなたのAPIチェックは、Cursorが単体テストに使用するのと同じ編集・テスト・修正サイクルに組み込まれますが、これらは実際のエンドポイントに対して実行されます。より広範なパターンについては、APIテストにAIエージェントを使用する方法が、それが適している場所と適していない場所をカバーしています。
オプション：Apidog MCPサーバーを接続する
CLIはCursorにテストを実行させます。Apidog MCPサーバーは、Cursorがコードを記述している間にAPI仕様を読み取ることを可能にします。この2つは連携します。MCPサーバーはCursorにスキーマを提供し、契約に一致するコードを生成させ、CLIはそのコードを実際のシナリオに対して検証します。
CursorはJSON設定を通じてMCPサーバーをサポートします。プロジェクトスコープのサーバーはリポジトリのルートにある.cursor/mcp.jsonに、グローバルなサーバーは~/.cursor/mcp.jsonに配置します。形式は名前をキーとするmcpServersオブジェクトで、それぞれcommand、args配列、およびオプションのenv値を含みます。
{
"mcpServers": {
"apidog": {
"command": "npx",
"args": ["-y", "apidog-mcp-server@latest", "--project=YOUR_PROJECT_ID"],
"env": {
"APIDOG_ACCESS_TOKEN": "YOUR_ACCESS_TOKEN"
}
}
}
}
2点注意してください。MCPは一部のインストールでトグルによって制限されている場合があるため、Cursor設定を開き、モデルコンテキストプロトコルセクションを見つけて、Apidogサーバーが有効になっていることを確認してください。また、.cursor/mcp.jsonをコミットする場合、トークンをハードコードせず、環境変数を参照してください。プロジェクトIDとトークンの取得方法を含む完全な設定については、Apidog MCPサーバーガイドを参照してください。手動で設定する代わりに、パッケージ化された再利用可能なワークフローについては、ClaudeスキルとApidog CLIガイドにスキルベースのバージョンが示されています。
ローカルループからCIへ
Cursorがローカルでシナリオを実行し、終了コードに基づいて動作した後、パイプラインが使用する正確なコマンドが検証されます。CIへの移行は簡単です。apidog runは同じですが、トークンは保存されたログイン情報の代わりにマスクされたシークレットとして渡されます。ルールからコマンドを知っているので、Cursorにステップを作成するよう依頼することもできます。
そのステップのメカニズム（シークレット、レポーター、終了コードゲート）については、GitHub ActionsでのApidog CLIに記載されています。同じコマンドが、あなたのターミナル、Cursorのエージェントループ、そしてCIの3つの場所で実行され、すべて同じ終了コードを信頼します。
よくある問題
ルールが適用されない。 descriptionとalwaysApply: falseを設定した場合、Cursorはチャットが関連性があると判断した場合にのみルールを読み込みます。テストセッションがルールを認識しない場合は、チャットで@apidog-cliと記述するか、alwaysApply: trueに切り替えてください。
エージェントがコマンドを実行できない。 コマンドを実行せずに提案するだけの場合、エージェントモードではなく編集モードになっているか、承認プロンプトを見逃した可能性があります。エージェントチャットにいることを確認し、Cursorが尋ねたときに承認してください。ターミナルの実行が完全に失敗する場合、通常はインストールガイドで説明されているapidog: command not foundというPATHの問題です。
apidog whoamiで認証されていないと表示される。 ログイン情報はCursorではなく、お使いのコンピューターに保存されます。Apidogから新しいトークンを使用して自分でapidog login --with-tokenを実行し、その後エージェントにapidog whoamiで確認を依頼してください。トークンはチャットに含めないでください。
誤ったフラグを生成する。 実行が「unknown option」エラーで失敗した場合、エージェントがあなたのバージョンに存在しないフラグを推測した可能性があります。エージェントにapidog run --helpを実行させ、正確なフラグをコピーしてください。
まとめ
Cursorの設定は1つのファイルと1つの習慣です。コマンド、認証元、終了コードルールを固定する.cursor/rules/apidog-cli.mdcルールと、エージェントにapidog runを実行させ、自分で終了コードを確認する習慣です。Apidog MCPサーバーを追加すれば、Cursorはコード作成中に仕様を読み取ることもできます。
あなたはApidogでシナリオを視覚的に作成し続け、Cursorはそれらを実行するだけです。ここから、GitHub ActionsでのApidog CLIを使用して同じコマンドをパイプラインに渡し、またはApidog CLI完全ガイドで完全なフラグ参照を読んでください。