📚

API自動テストを一言で実行：Apidog × Claude実践ワークフロー

に公開
Apidog
リグレッションテスト
Skills
api自動テスト
claide
tech

正直に言うと、僕のチームにもAPI自動テストはある。でも、それが「あるけど使いにくい」状態だった。

テストシナリオはどこ？どれを実行すればいい？コマンドはどう書く？環境の切り替えは？実行後のレポートはどう見る？こういった細かいステップが積み重なって、リグレッションテストが「サクッとやれること」から「わざわざ時間を取らないとできないこと」に変わってしまう。

この記事では、僕が実際にローカル環境で運用しているワークフローを紹介する。Apidog の自動テスト資産（シナリオ/テストスイート）と Claude のターミナル機能を組み合わせて、「API自動テストの実行」を自然言語の一言で済ませる方法だ：

「dev環境でmock-e2e-order-payのリグレッションテストを実行。完了したら、通過率、失敗したテストケース、失敗原因の推測、修正手順の提案、この4点でまとめて。」

Claude Codeが自動的にClaude Skillsとマッチングし、対応するテストを特定して Apidog CLI を実行。最後に結果を読みやすい結論にまとめてくれる。この組み合わせは API自動テスト、リグレッションテスト、そしてテストを日常の開発フローに組み込むのに特に適している。

なぜAPI自動テストを「自然言語化」する必要があるのか

多くのチームでは、自動テストに「実行能力」は足りているが、「使いやすさ」が足りていない：

  • 新人はどんなテストが実行できるのか、どれを実行すべきかわからない
  • CLIコマンドが長すぎて、環境パラメータを間違えやすい
  • テスト失敗後にログを確認したりレポートを見たりするのに、コミュニケーションコストがかかる
  • リグレッションテストをコミット前やマージ前にサクッと実行するのが難しい

自然言語でトリガーできる価値は、「テスト実行」のハードルを一言話すのと同じレベルまで下げながら、専門ツール（Apidog）のテスト体系とレポート機能はそのまま活かせることにある。

全体像：Apidog × Claude 3つのコンポーネントの役割分担

このワークフローは3つのコンポーネントで構成されている：

  • Apidog CLI：Apidogのテストシナリオ/テストスイートを実行し、CLI/HTMLレポートを出力
  • Claude Code：ターミナル内のAIアシスタント。コマンド実行、ファイル操作、スクリプト実行が可能
  • Claude Skills（Agent Skills）：Claudeに「実行可能なフロー」を与え、テストの選択、環境切り替え、CLI実行、結果のまとめ方を教える

一言で言うと：

自然言語 → Claudeがスキルとマッチング → スクリプトを呼び出してApidog CLIを実行 → 出力を解析 → 結論をまとめる

準備作業

Apidog CLIとClaude Codeを動かすには、まずNode環境を用意してインストールを済ませておく必要がある。

1）環境要件：Node.js

Node 18+または20+を推奨。ターミナルで確認：

node -v
npm -v

2）Apidog CLIのインストール

npm install -g apidog-cli
apidog --version

バージョン番号が表示されればインストール成功。

3）Claude Codeのインストール

npm install -g @anthropic-ai/claude-code
claude --version
claude   # 初回実行時はプロンプトに従ってログイン

テスト資産の整理方法：リアルと安定の二本立て

「信頼性」と「安定した再現性」を両立させるため、テストを2種類に分けることをおすすめする：

  • local-real-smoke（リアルスモークテスト）
    実際のサービス（例：http://localhost:3001）で実行。通常は1〜2個の最も基本的なチェック（health/login）のみを含み、環境が利用可能かを確認する。
    apidog

  • mock-e2e-order-pay（Mockエンドツーエンドリグレッション）
    ローカルMockを使用して、全体のリグレッション結果を安定して出力。レポートがより安定し、スクリーンショットも楽で、読者の再現も容易。
    apidog

なぜこれが重要なのか？
デモで最も怖いのは「環境の違いで動かない」こと。リアルスモークテストで本物であることを証明し、Mockリグレッションでデモの安定性を保証する。これはチームの実運用でもよくあるパターン（スモークテストとリグレッションの階層化）だ。

Claude Skillsの実装：「テストの実行方法」をリポジトリに落とし込む

Claude Skillsの利点は、実行フローをバージョン管理可能でレビュー可能なプロジェクト資産に変えられること。口頭伝承で散らばらない。

最小限で使えるSkillディレクトリは大体こんな感じ：

  • .claude/skills/apidog-tests/

    • SKILL.md：トリガー条件 + 実行フロー（コア）

    • env/：異なる環境のtoken/envId（機密情報はGitにコミットしない）

    • tests/：各テストごとにMarkdownファイル（CLIコマンドを格納）

    • scripts/：CLIを組み立てて実行（コンテキストと手動コマンド組み立てのコストを削減）

      skill

この整理方法がもたらすメリット：

  • Apidogはテストシナリオ/スイートのメンテナンスを継続
  • Skillは「選択ロジック + 環境管理 + 実行規範 + 出力まとめ」を担当
  • チームメンバーはコマンドを覚える必要がなく、要件を言えるだけでいい

Apidog CLI：実行エンジン、Skillsは「ラッピングと自動化」のみ

Apidogのテストシナリオ/スイートページで、CLIコマンドを直接コピーできる（CI/CDまたはCLIエリア）。

典型的な形式はこんな感じ：

apidog run --access-token <TOKEN> -t <SCENARIO_ID> -e <ENV_ID> -n 1 -r html,cli

おすすめの方法は、コマンドをtests/*.mdに貼り付けて、機密パラメータは環境変数で管理すること（漏洩を避け、環境切り替えも便利）。

apidog

一言でAPI自動テストをトリガー：固定テンプレートですぐ使える

プロジェクトディレクトリに入ってClaude Codeを起動：

claude

一言でテスト回せる：

「dev環境でmock-e2e-order-payのリグレッションテストを実行。完了したら、通過率、失敗したテストケース、失敗原因の推測、修正手順の提案、この4点でまとめて。」

Claudeがやってくれること：

  1. 実行したいテストシナリオ/スイート（mock-e2e-order-pay）を識別
  2. 環境（dev）を確認して対応する環境変数をロード
  3. スクリプトを呼び出してApidog CLIを実行
  4. 出力を指定された4つの観点でまとめて、構造化された結論を提示

skill

出力がより「人間らしく」：自動まとめはログを見るより断然速い

従来のCLI出力は機械には優しいが、人間には優しくない。
Claude Skillsは出力を開発/テスト協業に適したまとめに整理してくれる。具体的には：

  • 通過率：全体の成功率を一目で把握
  • 失敗したテストケース：どのテストが落ちたのか明確に
  • 失敗原因の推測：認証エラー、環境変数の問題、アサーション失敗、Mockデータの不一致など
  • 修正手順の提案：環境を変えて比較、特定モジュールのみ実行、アサーション追加など

skill

このステップが「効率向上」の鍵だ。同僚が何度も「今どうなってる？どこが失敗した？」と聞く必要がない。
Claudeのまとめをチャットに貼るだけで次のステップに進める。

このワークフローの核心メリット

API自動テストを本当に日常の開発に組み込みたいなら、この組み合わせのメリットは明確だ：

  1. ハードルを下げる：新人はコマンドを覚えたり、シナリオIDを探したりする必要がなく、普通に話すだけ
  2. 標準化できる：テスト定義、環境変数、実行スクリプトをバージョン管理してリポジトリに蓄積
  3. 問題の特定が速い：失敗は「赤」だけじゃなく、原因の説明と修正提案も付いてくる
  4. フローに組み込みやすい：コミット前/マージ前の自動リグレッションに自然に拡張できる

よくある拡張方向

  • 複数環境の比較（dev vs test）：同じテストを異なる環境で実行して、差分を自動比較
  • Git変更に基づくテストフィルタリング：影響を受けるモジュール関連のテストのみ実行し、全体のリグレッション時間を削減
  • コミット前/マージ前の自動リグレッション：commit/PRステージで重要なテストを自動実行し、問題を事前にキャッチ

まとめ

Apidogは専門的なAPI自動テスト機能を提供し、Claude Skillsは自然言語駆動と実行オーケストレーション機能を提供する。両者を組み合わせた価値は、「テスト実行」を専門的な操作が必要なステップから、サクッとできる動作に変えることだ。

API自動テストの使用頻度を上げて、リグレッションを日常開発の一部にしたいなら、この Apidog × Claude のワークフローは試す価値がある。

僕自身、この組み合わせを使い始めてから、テストを実行する心理的ハードルがかなり下がった。「あとでまとめてやろう」が「今すぐ確認しよう」に変わる。これがAIツールの本当の価値だと思う。

この記事が役に立ったら、ぜひシェアしてください。あなたのチームでも似たような課題があれば、コメントで教えてください。一緒に解決策を考えましょう！

Discussion