Claude CodeでAPIテストを実行する方法は?Apidogコマンド1つで、終了コード0の場合のみ合格

著者注:Apidog のシナリオ実行コマンドを CLAUDE.md に書き込み、Claude Code が既存のシナリオで API 自動テストを実行し、終了コードで結果を判定できるようにします。Seedance の動画インターフェースを例に、課金と審査に関するアサーションを設計します。

Claude Code で API コードを書いているなら、おそらくこんな経験があるでしょう。フィールドをひとつ変更しただけなのに、Apidog に切り替えて手動でシナリオを実行し、また戻って Claude Code に結果を伝えなければならない、と。本記事で紹介する方法は、Apidog CLI のシナリオ実行コマンドを CLAUDE.md に書き込み、Claude Code 自身にテストを実行させ、終了コードを自分で読ませるというものです。これにより、Claude Code による API 自動テストを閉ループにできます。

これは、ありふれた Claude Code 入門の解説記事ではありません。本文中の Apidog の操作手順は Apidog 公式が公開しているベンダーチュートリアルに基づき、Seedance の課金・審査ルールは APIYI ドキュメントの原文に基づいています。どちらも本文中で出典を明記するので、ご自身で照合できます。

本記事の核心:読み終えれば、CLAUDE.md に実行コマンドを固定する方法、合否をモデルの口頭結論ではなく終了コードで判定すべき理由、トークンをどこに置くべきか、そして非同期動画 API に対して本当に意味のあるアサーションを何本書くべきかが分かります。

claude-code-api-automated-testing-apidog-ja-image-0


Claude Code API自動テスト Apidog の要点

作業を始める前に、まずソリューション全体をいくつかの重要な判断ポイントに分解しておきましょう。以下の表は、ベンダーのチュートリアルと APIYI のドキュメントの中から、この方法に関係する核心的な制約をまとめたものです。いずれも、テストを安定して再現できるかどうかに直接影響します。

要点 説明 メリット
実行コマンドを CLAUDE.md に書く Claude Code はリポジトリのルートにある CLAUDE.md を読み取ります。コマンドの形式は apidog run -t シナリオID -e 環境ID -r cli です 毎回のセッションで同じコマンドを実行でき、記憶に頼りません
終了コードで結果を判定 終了コード 0 はアサーションがすべて成功したことを示し、非 0 は失敗が存在することを示します モデルが「通った」と言ったのに実際には通っていない、という事態を避けます
ID は CI/CD ページからコピー シナリオ ID と環境 ID は、Apidog の該当シナリオの CI/CD ページで取得します モデルがその場で ID をでっち上げてシナリオが見つからなくなるのを防ぎます
トークンはファイルに書かない ローカルでは apidog login でログインし、CLAUDE.md に --access-token を書きません トークンがリポジトリと一緒にコミットされて漏洩するのを防ぎます
2 種類のエンドポイントを分ける Claude Code を動かすテキストモデルと、テスト対象の動画インターフェースは同じエンドポイントではありません 設定が明確になり、課金も追跡できます

Claude Code が CLAUDE.md を読み取る仕組み

Apidog のベンダーチュートリアルによると、ツール本体は npm パッケージの apidog-cli で、Claude Code の起動時にリポジトリのルートにある CLAUDE.md をプロジェクト説明として読み取ります。つまり、このファイルに書いた実行コマンド、判定ルール、禁止事項が、Claude Code の各セッションのコンテキストになります。今回のセッションで実際にどの説明ファイルが読み込まれたかわからない場合は、Claude Code で /memory を実行して確認できます。

この点が、この方法の安定性を左右します。毎回の会話で「Apidog のシナリオを実行してください」と繰り返すよりも、コマンドを一度だけ固定してしまいましょう。Claude Code はコードを修正した後、CLAUDE.md の説明に従って apidog run を呼び出し、ターミナルの出力を見て修復を続けるかタスクを終えるかを決めます。

Apidog CLI の終了コードとレポート形式の詳細

ベンダーのチュートリアルでは、-r cli というレポート形式を必ず残すよう強調しています。Claude Code はターミナルの出力を頼りに次のアクションを判断するからです。ブラウザで開けるレポートも欲しい場合は、-r パラメータに html を追加できます。生成されたファイルは ./apidog-reports ディレクトリに置かれます。ここで注意したいのは「置き換え」ではなく「追加」だという点です。cli レポートを外すと、Claude Code は結果を読み取る手がかりを失ってしまいます。

終了コードは、この方法全体の審判役です。チュートリアルが示す確認順序は、そのまま取り入れる価値があります。まず、ターミナルに本当に apidog run というコマンドが表示されたかを確認します。次に終了コードを見て、終了コードとモデルの口頭での結論が食い違う場合は、終了コードを優先します。シナリオが見つからないと表示されたら、CLAUDE.md に戻って ID が正しいかを確認します。

claude-code-api-automated-testing-apidog-ja-image-1


Claude Code API 自動テスト クイックスタート

このセクションでは、「環境を準備 → CLAUDE.md を書く → 権限を設定 → 初回実行」の順で解説します。オンラインチュートリアル形式のため、すべてのコマンドはインラインコードで示しています。1つずつコピーしてターミナルで実行できます。

ステップ1:Claude Code のモデル接続先を設定する

Claude Code 自体の実行にもトークンを消費し、その後テスト対象の動画APIを呼び出す際にもさらに消費します。そのため、まず2種類の接続先を明確に区別しましょう。APIYI経由で接続する場合、Claude Code は Anthropic のネイティブプロトコルを使用します。接続先は https://api.apiyi.com で、末尾に /v1 を追加しないでください。追加すると /v1/v1/messages に組み合わされ、リクエストが失敗します。OpenAI 互換プロトコルのクライアントの場合に限り、接続先は https://api.apiyi.com/v1 です。

具体的には、Claude Code を起動するシェルで環境変数を設定します。ANTHROPIC_BASE_URL には Anthropic ネイティブの接続先を、ANTHROPIC_AUTH_TOKEN にはプラットフォームで作成したトークンを設定してください。Claude シリーズモデルのトークンは ClaudeCode グループに置き、後で動画APIに使用するトークンとは分けて管理することをおすすめします。

🚀 クイックスタート:公式に推奨されている方法は、APIYI apiyi.com のコンソールで Claude Code 用とテスト対象API用のトークンをそれぞれ作成することです。新規ユーザーには無料テスト枠があり、最初のシナリオを動作確認できるため、その後で長期的にどのモデルを使うかを決められます。

ステップ2: CLAUDE.md にテスト手順を書き込む

ベンダーのチュートリアルによると、CLAUDE.md のテスト関連の内容には次の項目を含めるのが推奨されています。それぞれ1文で明確に書けば十分です。

  1. 実行コマンド: 回帰テストでは apidog run -t <シナリオID> -e <環境ID> -r cli を使用します。2つのIDには、Apidog の CI/CD ページからコピーした実際の値をそのまま入力します。
  2. 判定ルール: コマンドの終了コードで結果を判定します。0 はすべて合格、0 以外は失敗があることを示します。自然言語の要約を結論にしないでください。
  3. 禁止事項: シナリオIDや環境IDを勝手に捏造・変更しないでください。コマンドに --access-token を追加しないでください。
  4. レポート要件: -r cli を保持してください。ブラウザレポートが必要な場合は html を追加できます。生成物は ./apidog-reports に置かれます。
  5. リージョンの説明: プロジェクトが Apidog の欧州リージョンにデプロイされている場合、コマンドに --api-base-url api.eu.apidog.com を追加する必要があります。これは Apidog 自身のリージョンアドレスであり、モデルの接続先アドレスとは関係ありません。

ステップ3: ログインと権限の設定

トークン管理は最も問題が起きやすい部分です。ベンダーのチュートリアルでは、ローカルで一度 apidog login を実行してログインを完了することを推奨しており、トークンを CLAUDE.md に書き込まないこと、またこのファイルに --access-token を登場させないことを明確にしています。CLAUDE.md は通常、リポジトリと一緒にコミットされるため、一度トークンを書き込むと公開したのと同じことになります。

Claude Code はデフォルトで、Bash コマンドを実行する前に確認を求めます。テストを自動実行させたい場合は、.claude/settings.json の権限 allow リストに Bash(apidog run *) を追加し、この種類のコマンドだけを許可します。チュートリアルでは同時に、--dangerously-skip-permissions は CI のような一時的な環境にのみ適しており、毎日常時有効にしているローカルマシンには適さないと注意しています。

設定項目 推奨される方法 推奨されない方法 出典
Apidog ログイン ローカルで apidog login CLAUDE.md に --access-token を書く ベンダーのチュートリアル
コマンドの許可 Bash(apidog run *) を allow リストに追加 ローカルで --dangerously-skip-permissions を常時有効にする ベンダーのチュートリアル
シナリオID CI/CD ページからコピー モデルに推測・生成させる ベンダーのチュートリアル
Claude Code のアドレス ANTHROPIC_BASE_URL に /v1 を付けない /v1 を付けるとパスが重複する APIYI のドキュメント
トークングループ Claude は ClaudeCode、動画は SeeDance2 1つのトークンで全グループを混用する APIYI のドキュメント

ステップ4:初回実行を成功させ、内容を確認する

設定が完了したら、Claude Code に回帰テストを1回実行させます。ベンダーのチュートリアルにある確認順序に従い、次の3点を自分の目で確かめてください。ターミナルに完全な apidog run コマンドが表示されていること。コマンドが明確な終了コードを返していること。失敗があれば、ターミナル出力でどのアサーションが不合格だったかを具体的に確認できること。この3点がすべて満たされて初めて、この閉ループは本当に確立されたといえます。

💡 技術的なヒント:初回実行を成功させるときは、いずれかのアサーションの期待値をわざと間違えてみるとよいでしょう。終了コードが非0になり、Claude Code がそれを手がかりに調査を続けることを確認できます。この手順により、「終了コードを基準にする」というルールが確実に有効になっていることを検証できます。


Claude Code API自動化テスト 実践:Seedance 動画インターフェースのアサーション設計

テキストインターフェースのテストは比較的わかりやすいですが、非同期の動画インターフェースこそアサーション設計の真価が問われます。本節では、APIYI で提供中の Seedance シリーズを例に、Apidog のシナリオで何をアサーションすべきか、何をアサーションすべきでないかを説明します。

Seedance のモデル、グループ、価格

APIYI のドキュメントによると、Seedance で利用できるモデル ID は doubao-seedance-2-5-260628、doubao-seedance-2-0-260128、doubao-seedance-2-0-fast-260128、doubao-seedance-2-0-mini-260615 です。これらのモデルを呼び出すトークンは SeeDance2 グループに属している必要があり、そうでない場合は「该模型无可用渠道」が返されます。テスト対象の動画 API と Claude Code を動かすテキストモデルは別々のエンドポイントであり、model フィールドを書き換えるだけで両者を共通利用できるわけではありません。Apidog のシナリオでは、Seedance のドキュメントに従って送信リクエストと照会リクエストを個別に設定する必要があります。

次の表は、価格一覧表(2026-11-16 更新)に記載された従量課金の表示価格で、単位は米ドル / 100万 tokens です。モデルと価格はプラットフォームのモデル一覧を基準とします。

モデル 入力 出力 キャッシュ読み取り 利用可能プラットフォーム
doubao-seedance-2-5-260628 70 70 なし APIYI apiyi.com
doubao-seedance-2-0-260128 46 46 なし APIYI
doubao-seedance-2-0-fast-260128 37 37 なし APIYI
doubao-seedance-2-0-mini-260615 23 23 なし APIYI

ドキュメントには、720p・5 秒の動画についての換算例も記載されています。2.5 は約 1.3721 ドル、2.0 標準版は約 0.9074 ドルです。ここで強調しておきたいのは、これは 100万 token あたりの単価を 1 本の動画に換算した例にすぎず、一覧表とは別の価格体系ではないという点です。

推奨される5つのアサーション

以下に挙げる5つのアサーションは、いずれもドキュメントの原文に基づいており、そのままApidogのシナリオに組み込むことができます。

  • タスクにはIDがある:リクエストの送信が成功したら、レスポンスには必ずタスクIDが含まれている必要があります。後続のポーリングはこのIDに依存するため、IDが無ければ失敗と判定します。
  • 長さは明示的に渡す:ドキュメント原文には、2.5のdurationのデフォルト値が-1であると書かれています。テストリクエストでは長さを明示的に渡さなければ、各回の費用を比較できません。
  • パラメータエラーは課金されない:ドキュメント原文に、HTTP 400のパラメータエラーは課金されないと書かれています。必須フィールドを欠いたリクエストを作り、ステータスコードが400であることをアサートし、ログで請求が発生していないことを確認できます。
  • モデレーションによるブロックは課金されない:ドキュメント原文には、PUBLIC_ をプレフィックスとするエラーは上流のコンテンツモデレーションによるブロックであり、同じく課金されないと書かれています。アサーションの役割はこうしたエラーコードを識別し、パラメータエラーとは区別して2種類の失敗として扱うことだけです。
  • 2つのログを足したものが合計金額:ドキュメント原文には、1本の動画についてログに2件の課金記録があると書かれています。送信時に仮請求され、完了後に実際の量に応じて返金または追加請求され、合計費用は2件の合計になります。

仮請求の金額について、ドキュメント原文には2.0系で約0.09ドル/秒、2.5で約0.135ドル/秒と記載されており、完了後に実際のtoken数に基づいて精算されます。したがって、コストのアサーションは最初のログだけを見てはいけません。それはあくまで仮請求額にすぎません。

claude-code-api-automated-testing-apidog-ja-image-2

テストとして書くべきでないもの

審査によるブロックはコンプライアンス上の境界であり、「突破」を狙うテストケースではありません。ドキュメントでも、審査に失敗した後は同じプロンプトで繰り返し再試行しないよう明確に推奨されているため、シナリオ内にもループ再試行や審査ルールを探る手順を設計すべきではありません。同様に、実在の人物の顔を含む参照画像はアップストリームで拒否されるため、先にアセットとして登録し、asset:// で参照する必要があります。これはコンプライアンス上の前提条件であり、テストケースの1つとしてではなく、テストデータ準備の説明に記載すべきものです。

📊 データについて:上記の Seedance の課金および審査ルールは、すべて APIYI ドキュメントの原文からの抜粋です。apiyi.com ドキュメントセンターの Seedance ページで最新の記述を確認したうえで、アサーションに固定してください。


Claude Code で使用するモデルの選択とコスト

Claude Code でテストを実行すること自体もトークンを消費するため、どのモデルを選ぶかが日常コストに直接影響します。次の表は価格一覧における3つの Claude モデルの価格で、単位は同じく米ドル / 100万トークンです。いずれも chat と messages のエンドポイントに対応しています。

モデル 入力 出力 キャッシュ読み取り グループ
claude-opus-5-5 4 20 0.2 ClaudeCode、Claude_Reverse、Claude_Enterprise、Default、SVIP
claude-sonnet-5-5 2 10 0.1 同上
claude-haiku-5-5 0〜10万トークンは 0.1、超過分は 0.5 0.5 0.01 ClaudeCode、Claude_Enterprise、Default、SVIP

Haiku の行には Claude_Reverse グループがない点に注意してください。トークンがそのグループのみに属している場合、Haiku に切り替えると利用可能なチャネルがなくなります。よくある考え方は、日常的に Claude Code で回帰テストの実行や終了コードの読み取りといった構造化されたタスクを回すときは軽量なモデルを使い、複雑な失敗で深く調査する必要があるときに、より強力なモデルへ切り替えるというものです。

💰 コスト最適化:駆動モデルと被テスト側のインターフェースの両方で課金が発生するため、APIYI コンソールでトークン単位に使用量ログを確認し、Claude Code の消費と Seedance の消費を別々に集計して、テストコストが主にどちら側に費やされているかを判断することをお勧めします。


よくある質問(FAQ)

Q1:Claude Code の API 自動テストにおける Apidog ソリューションとは何ですか?

Apidog CLI のシナリオ実行コマンドをリポジトリのルートディレクトリにある CLAUDE.md に書き込んでおく方法です。これにより Claude Code がコード修正後に自ら `apidog run` を実行し、終了コードに基づいてテストの合否を判断するため、手動で実行ボタンを押す手間がなくなります。

Q2:なぜ Claude Code の結論ではなく、終了コードを基準にするのですか?

モデルが生成する自然言語の要約には誤差が生じる可能性がありますが、終了コードはテストツールが返す確定した結果です。ベンダーのチュートリアルには、両者が一致しない場合は終了コードを優先すると明記されています。0 は全件成功、0 以外は失敗ありを意味します。

Q3:Claude Code の接続先に /v1 を付ける必要はありますか?

いいえ、不要です。Claude Code は Anthropic ネイティブのプロトコルを使用しており、接続先は `https://api.apiyi.com` です。`/v1` を付けると `/v1/v1/messages` になってしまいます。`/v1` 付きの接続先を使うのは OpenAI 互換クライアントだけです。

Q4:Apidog のトークンはどこに置くべきですか?

ローカル環境では `apidog login` でログインするだけで問題ありません。ベンダーのチュートリアルでは、CLAUDE.md に `–access-token` を書かないこと、またトークンをこのファイルに書き込まないことが明確に求められています。コードリポジトリと一緒に漏洩するのを防ぐためです。

Q5:Seedance を使った動画インターフェースのテストはどう始めればよいですか?

APIYI(apiyi.com)で登録した後、`SeeDance2` グループに属するトークンを作成し、Seedance のドキュメントに従って送信リクエストと問い合わせリクエストを設定します。さらに Apidog のシナリオに、タスク ID、明示的な長さ、エラーコードの分類、2 件の課金ログといったアサーションを追加してください。新規ユーザー向けの無料テスト枠を使って、最初のシナリオを最後まで通せます。

Q6:Claude Code がシナリオを見つけられないと表示する場合は?

まずターミナルで実際に実行されているコマンドを確認し、その後 CLAUDE.md に戻ってシナリオ ID と環境 ID をチェックしてください。必ず Apidog の該当シナリオの CI/CD ページから再コピーし、モデルに推測させてはいけません。欧州リージョンのプロジェクトでは、`–api-base-url api.eu.apidog.com` を追加しているかどうかも確認が必要です。

Q7:このソリューションにはどのような制限がありますか?

第一に二重課金です。Claude Code とテスト対象のインターフェースがそれぞれ token を消費します。第二に権限の許可は控えめにすべきで、ローカルでは `Bash(apidog run *)` のみを許可してください。第三に、審査によるブロックや実在人物の顔の参照画像はコンプライアンス上の境界にあたるため、識別と事前処理にとどめ、回避を目的としたテストケースとして設計してはいけません。


Claude Code API自動化テスト 主なポイント(Key Takeaways)

  • コマンドの固定化:apidog run -t -e -r cli を CLAUDE.md に書き込み、セッションごとに同じコマンドで実行します。
  • 終了コードによる判定:0 は合格、非0 は失敗です。口頭の結論と矛盾する場合は、終了コードを優先します。
  • トークンの分離:ローカル環境では apidog login でログインします。トークンも --access-token も CLAUDE.md には記載しません。
  • 権限の最小化:許可するのは Bash(apidog run *) のみです。権限確認をスキップするパラメータは CI 専用です。
  • アドレスの区別:Claude Code は /v1 を付けないネイティブアドレスを使用し、OpenAI 互換の場合にのみ /v1 を付けます。
  • 動画のアサーション:タスクID、明示的な再生時間、400 ステータスと PUBLIC_ 分類、2件の課金ログの合計金額を検証します。
  • 始め方:APIYI で ClaudeCode と SeeDance2 のグループトークンをそれぞれ作成し、無料枠で最初のシナリオを実行します。

まとめ

Claude Code API自動化テストと Apidog を組み合わせる際のポイントは、次の3つです。

  1. コマンドとルールをファイルに残す:CLAUDE.md に実行コマンド、判定ルール、禁止事項を記載し、トークンは apidog login に任せます。
  2. 終了コードに判断を委ねる:-r cli の出力を保持し、ベンダーのチュートリアルの順序に沿ってコマンド、終了コード、ID を確認します。
  3. アサーションを実際の課金に合わせる:非同期動画APIでは、タスク状態を検証し、パラメータエラーと審査によるブロックを区別し、2件の課金ログを合計し、再生時間を明示的に渡します。

まずは最もシンプルなテキストAPIシナリオで一連の流れを実行し、その後、Seedance のような非同期APIのアサーションを段階的に追加することをおすすめします。APIYI(apiyi.com)で同じアカウントを使って Claude Code とテスト対象モデルのトークンおよび使用量を管理すると、両側のコストがひと目でわかり、テスト費用の継続的な最適化が容易になります。


📚 参考資料

  1. Apidog 公式チュートリアル:Claude Code で Apidog CLI を使う:著者名 INEZA Felin-Michel、バージョン日付はサイト上の表示に準ずる
  2. リンク:apidog.com/blog/apidog-cli-in-claude-code
  3. 内容:CLAUDE.md の書き方、終了コードのルール、権限設定と確認手順の出典

  4. Apidog CLI 公式紹介:Agent と CI 向けの位置づけ、およびリージョン指定パラメータ

  5. リンク:docs.apidog.com/en/introduction-to-apidog-cli-605134m0
  6. 内容:欧州リージョンの --api-base-url の説明を含む

  7. APIYI Seedance 2 ドキュメント:モデル ID、グループ、課金、審査ルール

  8. リンク:docs.apiyi.com/api-capabilities/seedance2/overview
  9. 内容:本記事における動画アサーション設計の根拠

  10. APIYI モデル価格一覧表:各モデルの従量課金価格とグループ

  11. リンク:docs.apiyi.com/models
  12. 内容:モデル名と価格はこのページの最新内容に準ずる

  13. APIYI プロトコル仕様:Anthropic ネイティブと OpenAI 互換エンドポイントの違い

  14. リンク:docs.apiyi.com/llms.txt
  15. 内容:Claude Code のアドレスに /v1 を付けられない理由の解説

著者:APIYI 技術チーム
技術交流:APIYI サイトのトップページからお気軽にお問い合わせください。その他の資料は docs.apiyi.com のドキュメントセンターでご覧いただけます。

コメントする