DEV Community

Cover image for ヘッドレスAPIテストツール：GUI不要でCI/CD環境でのAPIテスト自動化
Akira
Akira

Posted on • Originally published at apidog.com

ヘッドレスAPIテストツール：GUI不要でCI/CD環境でのAPIテスト自動化

ヘッドレスAPIテストツールは、GUIを開かずにコマンドラインからAPIテストを実行するためのランナーです。CIパイプラインに組み込めば、pushやpull requestごとに同じAPIチェックを自動実行できます。GUIで作成したテストをビルドサーバーで再利用したい場合、ヘッドレス実行がそのギャップを埋めます。この記事では、「ヘッドレス」の意味、Apidog CLIの使い方、NewmanやHurlなどの代替ツールの選び方を実装目線で整理します。

今すぐApidogを試す

APIテストにおける「ヘッドレス」とは

APIテストでいう「ヘッドレス」とは、GUIを使わずにテストを実行できることです。一般的なヘッドレスAPIテストツールには、次の特徴があります。

  • CLIコマンドとして実行できる
  • ディスプレイ、ログイン済みユーザー、手動クリックが不要
  • テスト定義をファイル、プロジェクトID、コレクションなどから読み込む
  • アサーション失敗時に非ゼロの終了コードを返す
  • JSON、JUnit XML、HTML、CLI出力などのレポートを生成する

重要なのは終了コードとレポートです。GUIは人間に結果を見せますが、ヘッドレスランナーはCI/CDに合否を伝えます。これにより、失敗したAPI変更のマージやデプロイを止められます。CI/CD全体での考え方は、APIテストのCI/CDベストプラクティスも参考になります。

GUIのテストをCLI実行に移す理由

GUIクライアントは、エンドポイントの探索、ヘッダー調整、レスポンス確認には便利です。しかし、リリース前に毎回40件のリクエストを手動実行する運用は現実的ではありません。

ヘッドレスランナーを使うと、同じテストを次の場所で再現できます。

  • ローカル開発環境
  • チームメンバーのマシン
  • CIサーバー
  • デプロイ前のステージング検証

さらに、CSVやJSONのデータを使えば、1つのシナリオを複数ケースで繰り返し実行できます。APIが外部ユーザーや他チームに依存されるものなら、この再現性は重要です。これは、APIを製品として扱うための基本でもあります。

Apidog CLIでヘッドレスAPIテストを実行する

Apidog CLIは、Apidogで作成したAPIテストをGUIなしで実行するためのCLIです。アプリ内でテストシナリオを作成・デバッグし、CIやターミナルでは apidog run で実行します。

実行対象には、次のようなものがあります。

  • テストシナリオ
  • フォルダー
  • テストスイート
  • ローカルにエクスポートしたファイル

実行後はレポートを生成し、CIが判定できる終了コードを返します。

1. Apidog CLIをインストールする 

npm install -g apidog-cli
Enter fullscreen mode Exit fullscreen mode

2. テストを実行する

最小構成は次のようになります。

apidog run https://api.apidog.com/...
Enter fullscreen mode Exit fullscreen mode

CIでは、環境、テストデータ、レポーターを指定して実行するのが一般的です。

apidog run https://api.apidog.com/... \
  -e <environment-id> \
  -d ./data/users.csv \
  -r cli,html,junit
Enter fullscreen mode Exit fullscreen mode

3. データ駆動型テストを実行する

CSVまたはJSONファイルを指定すると、Apidog CLIは行ごとにシナリオを繰り返し実行します。

apidog run https://api.apidog.com/... \
  -d ./data/users.csv
Enter fullscreen mode Exit fullscreen mode

使用する主なオプションは次の通りです。

-d, --iteration-data <path>
-n, --iteration-count <number>
Enter fullscreen mode Exit fullscreen mode

たとえば users.csv を使って、ユーザーごとの正常系・異常系を同じシナリオで検証できます。

username,email,expectedStatus
alice,alice@example.com,200
invalid-user,invalid@example.com,400
Enter fullscreen mode Exit fullscreen mode

詳しい流れは、Apidog CLIによるデータ駆動型APIテストで解説されています。

4. CI向けにレポートを出力する

-r, --reporters で出力形式を指定します。

apidog run https://api.apidog.com/... \
  -r cli,html,junit,json
Enter fullscreen mode Exit fullscreen mode

主な用途は次の通りです。

レポート形式 用途
cli ターミナルでの確認
html 人間が読む詳細レポート
json 独自の後処理や集計
junit CIのテストレポート画面への連携

HTMLとJUnitレポートは、デフォルトで apidog-reports/ に保存されます。CIではこのディレクトリをアーティファクトとして保存します。

5. 環境変数やシークレットを注入する

環境は -e で指定します。

apidog run https://api.apidog.com/... \
  -e <environment-id>
Enter fullscreen mode Exit fullscreen mode

CIのシークレットを使う場合は、--env-var や --global-var で実行時に値を渡します。

apidog run https://api.apidog.com/... \
  -e <environment-id> \
  --env-var token=$API_TOKEN \
  --global-var baseUrl=$BASE_URL
Enter fullscreen mode Exit fullscreen mode

これにより、トークンや環境固有の値をリポジトリにコミットせずに済みます。

Apidog CLIの導入から最初の実行までは、Apidog CLI完全ガイドで確認できます。具体的なREST APIを使った流れは、REST APIコマンドラインチュートリアルが参考になります。オプション単位の詳細は、apidog runコマンドリファレンスを参照してください。

AIエージェント向けのヘッドレス利用: Apidog MCP

Apidogには、CLI実行とは別にMCPサーバーを使ったヘッドレスな連携もあります。

Apidog MCPサーバーを使うと、AIエージェントやAI対応IDEがAPI仕様を直接参照できます。たとえばCursorやCline経由のVS Codeで、実際のAPI契約に基づいたコードやテストを生成できます。

これは、GUIを操作せずにAPI仕様をエージェントへ渡すワークフローです。詳細は、Apidog MCPクライアントによるビジュアルデバッグで紹介されています。

代表的なヘッドレスAPIテストランナー

Apidog CLI以外にも、ヘッドレス実行できるAPIテストツールがあります。選定では「既存のテストがどこにあるか」を最優先にすると失敗しにくいです。

Newman

Newmanは、PostmanコレクションをCLIで実行するためのランナーです。

Postmanコレクションがチームの信頼できる情報源になっている場合、Newmanは自然な選択肢です。

主な特徴は次の通りです。

  • PostmanコレクションをCIで実行できる
  • cli、json、junit、progress、emojitrain レポーターをサポート
  • HTMLレポートは追加npmパッケージで利用可能
  • -r でレポーターを指定できる 
newman run collection.json \
  -e environment.json \
  -d data.csv \
  -r cli,junit
Enter fullscreen mode Exit fullscreen mode

Hurl

Hurlは、プレーンテキストの .hurl ファイルにHTTPリクエストとアサーションを書くCLIツールです。

例:

GET https://example.com/api/users/1
HTTP 200
[Asserts]
jsonpath "$.id" == 1
jsonpath "$.email" exists
Enter fullscreen mode Exit fullscreen mode

HurlはRust製の小さなバイナリで、libcurlをベースにしています。次のようなチームに向いています。

  • テストをプレーンテキストで管理したい
  • Git diffでレビューしやすい形式にしたい
  • UIよりもコードに近いテスト定義を好む

Hoppscotch CLI

Hoppscotch CLI は、HoppscotchのコレクションとテストスクリプトをCIで実行するCLIです。

主な特徴は次の通りです。

  • エクスポート済みコレクションと環境JSONを実行できる
  • アクセストークンでコレクションIDや環境IDを参照できる
  • CSVイテレーションデータをサポート
  • --reporter-junit でJUnitレポートを出力できる
  • 失敗時に非ゼロ終了コードを返す

すでにHoppscotchを使っているチームには自然に適合します。比較検討する場合は、最適なHoppscotch CLIの代替も参考になります。

ヘッドレスランナーの比較

ツール テストソース データ駆動型入力 組み込みレポーター 向いているケース
Apidog CLI Apidogプロジェクト、スイート、エクスポートファイル CSV / JSON (-d) cli, html, json, junit 設計、モック、テスト、ドキュメントを1つの場所で管理したい場合
Newman Postmanコレクション CSV / JSON (-d) cli, json, junit, progress など。HTMLはアドオン経由 Postmanコレクションが信頼できる情報源である場合
Hurl プレーンテキスト .hurl ファイル ランナーオプション経由のCSV JUnit, TAP, JSON プレーンテキストでバージョン管理したい場合
Hoppscotch CLI Hoppscotchコレクション、ファイルまたはID CSV (--iteration-data) JUnit チームが既にHoppscotchを使っている場合

これらはすべてヘッドレスに実行できます。つまり、GUIを使わず、コマンドから起動し、終了コードで合否を返せます。

Apidog CLIの違いは、CIで実行できること自体ではありません。Newman、Hurl、Hoppscotch CLIもCIで実行できます。Apidogの強みは、CLIで実行するテストと、API契約、モック、ドキュメントを同じプロジェクトで管理できる点です。テスト定義とAPI定義が分離しにくくなります。

CIに組み込むときの実装例

GitHub Actionsの例 

name: API Tests

on:
  pull_request:
  push:
    branches:
      - main

jobs:
  api-test:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Install Apidog CLI
        run: npm install -g apidog-cli

      - name: Run API tests
        run: |
          apidog run https://api.apidog.com/... \
            -e ${{ secrets.APIDOG_ENV_ID }} \
            -d ./data/users.csv \
            -r cli,html,junit \
            --env-var token=${{ secrets.API_TOKEN }}

      - name: Upload Apidog reports
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: apidog-reports
          path: apidog-reports/
Enter fullscreen mode Exit fullscreen mode

ポイントは次の3つです。

  1. CLIをインストールする
  2. apidog run を実行する
  3. apidog-reports/ をアーティファクトとして保存する

テストが失敗すれば、CLIが非ゼロ終了コードを返し、GitHub Actionsのジョブも失敗します。

GitLab CIの例 

api_test:
  image: node:20
  script:
    - npm install -g apidog-cli
    - |
      apidog run https://api.apidog.com/... \
        -e $APIDOG_ENV_ID \
        -d ./data/users.csv \
        -r cli,html,junit \
        --env-var token=$API_TOKEN
  artifacts:
    when: always
    paths:
      - apidog-reports/
    reports:
      junit: apidog-reports/*.xml
Enter fullscreen mode Exit fullscreen mode

JUnitレポートをCIに読み込ませることで、失敗したケースをCI画面から確認できます。

どのツールを選ぶべきか

まず、既存のテスト資産を確認します。

  • Postmanコレクションが中心ならNewman
  • プレーンテキストでテストを管理したいならHurl
  • Hoppscotchを使っているならHoppscotch CLI
  • API設計、モック、テスト、ドキュメントを1つにまとめたいならApidog CLI

ツールを増やしたくない場合は、Apidogが向いています。GUIで作成したシナリオを同じAPI契約に基づいてCLI実行でき、モックサーバーを使えばバックエンド完成前の検証にも使えます。

よくある質問

ヘッドレスAPIテストツールとCLI APIテストツールは同じですか？

実務上はほぼ同じ意味で使われます。「ヘッドレス」はGUI不要という性質を指し、「CLI」はコマンドラインで操作するインターフェースを指します。

重要なのは、無人で実行でき、CIが読み取れる合否ステータスを返せることです。

テストスクリプトを書かずに実行できますか？

ツールによります。

Apidogでは、アプリ内でアサーションを視覚的に作成し、そのシナリオをCLIからヘッドレス実行できます。テストハーネスを手書きする必要はありません。

NewmanとHoppscotch CLIは、それぞれのアプリで作成されたテストスクリプトを含むコレクションを実行します。Hurlは .hurl ファイルを自分で記述します。

スクリプトを最小限にしたい場合は、Apidog CLI完全ガイドが参考になります。

実際のバックエンドがないとテストできませんか？

必ずしも必要ではありません。

ヘッドレスAPIテストは、次のいずれかに向けて実行できます。

  • 実行中のローカルサービス
  • ステージング環境
  • 本番前の検証環境
  • モックサーバー

モックサーバーをCIで使えば、バックエンド実装が完了する前にリクエストとレスポンスの形状を検証できます。Apidogのモックサーバーは、この用途にも使えます。

CI/CDに最適なヘッドレスランナーはどれですか？

単一の正解はありません。最適なのは、既存のテストを最小のセットアップでCI実行できるツールです。

ゼロから始める場合やツールを統合したい場合は、Apidog CLIが設計、モック、テスト、ドキュメントを1つのプロジェクトで扱えます。既存エコシステムがある場合は、それに合わせます。

  • Postman: Newman
  • Hoppscotch: Hoppscotch CLI
  • プレーンテキスト: Hurl
  • 統合管理: Apidog CLI

比較の詳細は、Apidog CLI vs NewmanとApidog CLI vs Postman CLIも参考になります。

まとめ

ヘッドレスAPIテストツールは、GUIなしでAPIテストを実行するためのコマンドラインランナーです。CIに組み込むことで、pushやpull requestごとに同じAPIテストを自動実行できます。

Newman、Hurl、Hoppscotch CLIはいずれも、それぞれのエコシステムで有効です。Apidog CLIも同じくヘッドレス実行に対応し、さらにテスト、モック、API契約、ドキュメントを1つのプロジェクトで管理できます。

Apidogをダウンロードして、シナリオを一度作成し、ローカルでもCIでも同じようにヘッドレス実行してみてください。

Top comments (0)