お使いのAPIテストはラップトップでは合格します。より難しい問題は、人間が何もクリックしなくても、すべてのプルリクエスト、すべてのマージ、すべての夜間ビルドでそれらが実行されるかどうかです。その役割はコマンドラインランナーにあります。それはあなたがすでに書いたテストを受け取り、パイプライン内でヘッドレスで実行し、CIが読み取れるステータスコードで終了し、ダッシュボードが解析できるレポートを作成します。GUIなし、手動ステップなし、実行をスキップする言い訳もありません。
長年、このニーズに対するデフォルトの答えは、PostmanのオープンソースコマンドラインコレクションランナーであるNewmanでした。これは堅実でよく理解されているツールであり、多くのチームが今でもまずこれを採用しています。しかし、PostmanではなくApidogでテストを作成する場合、2つ目の選択肢があります。それはApidog CLIです。これは、アプリで視覚的に作成した同じテストシナリオを、CIでヘッドレスで実行します。この記事では、この2つを正直かつコマンドレベルで比較します。Newmanの優れた点、Apidog CLIが適する場所、そしてそれぞれが実際のパイプラインに組み込まれたときにどのように感じられるかについて説明します。
要約 (TL;DR)
- Newman（
newman、npm install -g newmanでインストール）は、エクスポートされたPostmanコレクションのJSONファイルを実行します。オープンソースで無料で、ディスクまたはURLからコレクションと環境ファイルを読み込みます。環境、データファイル、反復回数、JUnit/JSON/HTMLレポーターをサポートし、テストが失敗した場合はゼロ以外のステータスコードで終了します。 - Apidog CLI（
apidog-cli、バイナリはapidog）は、アクセストークンを使用してIDでフェッチされた、Apidogアプリで設計したテストシナリオを実行します。何もエクスポートしたり、手動でJSONファイルを維持したりする必要はありません。視覚的なシナリオがテストであり、CLIはアプリとまったく同じようにそれを実行します。 - どちらもGitHub Actions、GitLab CI、Jenkins、およびNode.jsが動作するあらゆる環境に接続できます。どちらもテストが失敗するとビルドを失敗させます。JUnit XMLは、どちらの側でもCIダッシュボードに接続するものです。
- テストがすでにPostmanコレクションとして存在し、新しいアカウントなしで無料のレポジトリフレンドリーなランナーを望む場合はNewmanを選択してください。
- 視覚的なオーサリング、リクエストの連鎖、環境管理、およびチームが毎日デバッグするのと同じシナリオと同期を保つデータ駆動型実行を望む場合はApidog CLIを選択してください。
本当の問題：存在するのに一度も実行されないテスト
手動で実行するテストは、陳腐化するテストです。誰かがそれを作成し、一度合格しましたが、APIがその下で変化する間、手つかずのまま放置されます。テストの数を増やしても、それは解決しません。変更があるたびに自動的に実行されるテストは解決します。なぜなら、それらはパイプラインが対応できる合否のシグナルを生成するからです。
CLIランナーはそのギャップを埋めます。CIで役立つためには、次の3つのことを行う必要があります。GUIなしで実行すること、何かが失敗したときにビルドが赤くなるようにゼロ以外のステータスコードで終了すること、そしてレビュー担当者が何が壊れたかを確認できるように機械可読なレポートを作成することです。NewmanとApidog CLIはどちらもこの基準をきれいにクリアしています。それらが異なるのは、実行コマンドの上流、つまりテストがどのように書かれ、どこに存在するかです。CIをゼロからセットアップしている場合、CI/CDでAPIテストを自動化する方法の広範なパターンは、この比較とよく合います。ここでは、2つのランナーに焦点を当てます。
Newmanの優れた点
Newmanはその地位を確立しています。Postmanの公式オープンソースコンパニオンであり、テストがすでにPostmanコレクションとして存在するチームにとって、「私のマシン上のテスト」から「CI内のテスト」への最も直接的なパスです。比較の前に、その強みを明確に述べておく価値があります。
それは無料でオープンソースです。npmからインストールし、Node.jsが動作する場所ならどこでも実行できます。ランナー自体に別途ライセンスは必要ありません。コレクションは移植可能なJSONファイルであり、レポジトリにコミットしたり、ビルド成果物として保存したり、URLからフェッチしたりできます。その移植性は本物であり、Newmanがほぼすべてのパイプラインに摩擦なく組み込めることを意味します。
それは、あなたがすでに構築したものを再利用します。チームがPostmanでリクエスト、プリリクエストスクリプト、テストアサーションを記述する場合、Newmanはそれらの同じコレクションを未変更で実行します。書き換えは必要ありません。Postmanエディタで書いたスクリプトは、ヘッドレス実行でも同じように実行されるため、Postmanを使用しているチームの学習曲線は緩やかです。
インストールは1つのコマンドです。
npm install -g newman
バイナリはnewmanです。エクスポートされたコレクションは、通常、環境ファイルとともにJSONファイルを指定して実行します。
newman run api-tests.postman_collection.json -e staging.postman_environment.json
これがコアループです。Postmanからコレクションをエクスポートし、JSONをコミットして実行します。Newmanはファイルからリクエストとアサーションを読み込み、順序通りに実行します。完全なセットアップパスについては、Apidog自身のNewmanのインストール方法とPostmanコレクションの実行方法のウォークスルーで、エクスポートと実行のフローがステップバイステップで説明されています。
Newmanは、期待されるCIの必須機能もサポートしています。データ駆動型実行はCSVまたはJSONファイルから行われます。
newman run api-tests.postman_collection.json \
-e staging.postman_environment.json \
-d users.csv \
-n 5
ここで-dはデータファイルを供給し、-nは反復回数を設定します。これにより、コレクションは行ごとに1回または指定された回数だけ実行されます。これらはどの本格的なランナーにも必要な基本的な機能であり、Newmanは何年も前からこれらを備えています。
Newmanがコストをかけ始める場所
上記の長所は正直ですが、トレードオフも同様に正直であり、単一のコマンドではなく、日々のメンテナンスで現れます。
最大のものはエクスポートステップです。CIにおけるPostmanコレクションはスナップショットです。Postmanアプリで作成とデバッグを行い、その後ヘッドレス実行のためにJSONファイルをエクスポートします。誰かがアプリでリクエストを編集し、再エクスポートを忘れた瞬間、コミットされたコレクションは真のソースから乖離します。実際のAPIが先に進んでいる間も、CIの実行は古い定義に対して合格し続けます。ツールには、これら2つを同期させるための強制力はありません。それはエクスポートを覚えている人に委ねられます。
もう一つはスクリプティングです。Postmanのテストロジックは、各リクエストにアタッチされたJavaScriptスニペット内に存在し、これらのスクリプトで連鎖、変数抽出、アサーションが行われます。これは柔軟ですが、テストスイートが手動で記述、デバッグ、維持する必要がある小さなスクリプトの山であることを意味します。シナリオが成長するにつれて、所有するスクリプトの表面積も増大します。これは、コレクションがスケーリングするにつれてチームが直面する広範なパターンの一部であり、Postman Collection Runnerの制限と回避策で詳しく説明しています。
これらすべてがNewmanを悪いツールにするわけではありません。Postmanのオーサリングモデル、つまりスクリプトとエクスポートステップにエルゴノミクスが結びついたランナーであるということです。そのモデルがチームに合うなら、Newmanで問題ありません。エクスポートと同期のダンスが問題を引き起こし続ける部分であるなら、まさにそこで別のランナーが役立ちます。
Apidog CLIの異なる点
Apidogは、同じパイプラインに対して異なるアプローチを取ります。Apidogアプリで視覚的にテストを構築します。リクエストをテストシナリオに連鎖させ、ノーコードエディタでアサーションを追加し、あるレスポンスから次のリクエストに値を抽出し、データファイル全体をループさせます。CLIは、これらのシナリオのヘッドレスエグゼキュータです。独自のファイル形式はなく、エクスポートするものもありません。ApidogプロジェクトからIDで指定したシナリオをフェッチし、アプリとまったく同じように実行します。
これにより、ドリフトの問題が解消されます。プロジェクト内のシナリオがテストです。CLIはコピーではなくライブシナリオを実行するため、同期がずれるエクスポートされたスナップショットはありません。リクエストの連鎖とアサーションを処理するビジュアルビルダーで一度作成すると、同じシナリオがCIで実行されます。高速な作成ループと自動化ループは、単一の真のソースを共有します。
インストールはnpmコマンド一つです。
npm install -g apidog-cli
バイナリはapidogです。典型的な実行では、IDでシナリオを指定し、環境を選択し、アクセストークンで認証します。
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -n 1 -r html,junit
これらのIDを手動で入力する必要はありません。Apidogでテストシナリオを開き、CI/CDタブに切り替え、アクセストークンを生成すると、ApidogがシナリオIDと環境IDがすでに記入された完全なコマンドを自動で作成します。一度コピーし、その後トークンをCIのシークレットに移動し、$APIDOG_ACCESS_TOKENとして参照します。インストールされているバージョンがどのフラグをサポートしているか不明な場合は、apidog run --helpを実行すると、利用可能な正確なオプションが表示されます。
トークンベースのIDによるフェッチモデルは、Newmanとの最も明確な違いです。Newmanはディスクからコレクションファイルを読み込みますが、Apidog CLIはネットワーク経由でプロジェクトにアクセスし、認証された上でそこに保存されているシナリオを実行します。どちらも間違いではありません。これらは異なるチーム構成に適しており、テストをエクスポートされたファイルとして維持したいのか、共有ワークスペース内のライブシナリオとして維持したいのかによって、選択は大きく異なります。
サイドバイサイド
| 項目 | Newman（newman） |
Apidog CLI（apidog） |
|---|---|---|
| パッケージ | newman |
apidog-cli |
| 実行コマンド | newman run <collection.json> |
apidog run |
| テストソース | エクスポートされたPostmanコレクションJSON（ファイルまたはURL） | Apidogプロジェクト内のテストシナリオ（IDでフェッチ） |
| オーサリング | Postmanアプリ、JavaScriptテストスクリプト | ビジュアルシナリオビルダー、ノーコードアサーション |
| 同期モデル | JSONスナップショットをエクスポート。変更時に再エクスポート | 実行時にフェッチされるライブシナリオ。エクスポートなし |
| CIでの認証 | ファイルの場合はなし。クラウドからフェッチする場合はPostman APIキー | アクセストークン（--access-token） |
| 環境 | -e <environment.json> |
-e <environmentId> |
| データ駆動型 | -d <file.csv or .json> |
-d <path> (CSV または JSON) |
| 反復 | -n <count> |
-n <count> |
| レポーター | cli, json, junit, html |
cli, html, json, junit |
| フェイルファスト | --bail |
--on-error end (デフォルトは最初のエラーで失敗) |
| オープンソース | はい | いいえ（無料のnpm CLI。プランに基づいてシナリオを実行） |
| アカウント | クラウドコレクション用のPostmanアカウント | プロジェクト用のApidogアカウント |
2つの点が際立っています。第一に、どちらのランナーも同じCIの必須機能をカバーしています。環境選択、データ駆動型反復、重要なレポート形式、そして失敗時のゼロ以外の終了です。フラグ名も（-e, -d, -n, -r）指の記憶が引き継がれるほど似ています。第二に、真の区別は生の能力ではありません。それはテストがどこに存在し、どのように書かれたかです。Newmanはスクリプトで作成されたエクスポートされたコレクションを実行します。Apidogは参照によってライブの視覚的シナリオを実行します。この比較のより深いバージョンで、2つのPostman系ランナーに焦点を当てたものは、Postman CLI vs Newmanにあります。
レポーターと終了コード：CIが実際に読み取る部分
ランナーは、そのレポートと返す終了コードという2つの振る舞いによって、パイプラインでの位置を確立します。これらを正しく設定すれば、残りは配線だけです。
Newmanは、-rフラグとカンマ区切りのリストでレポーターを選択します。JUnitとJSONは標準で含まれています。HTMLレポーターは最も一般的なアドオンです。
newman run api-tests.postman_collection.json \
-e staging.postman_environment.json \
-r cli,junit \
--reporter-junit-export ./results/junit.xml
JUnit XMLは、CIダッシュボードが合否ツリーに解析するものです。Newmanの--bailフラグは、最初の失敗後に実行を停止するため、スモークテストでのフィードバックを迅速に保ちます。これがない場合、実行は完了し、すべての失敗を一度に報告します。
Apidog CLIは同じカンマ区切りの-rフラグを使用し、すべての出力を1つの出力ディレクトリに書き込みます。
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 \
-r html,junit --out-dir ./apidog-reports
その--on-errorフラグは、シナリオ途中での動作を決定します。endは最初の失敗で停止し、これがデフォルトです。continueはすべてのステップを実行して、1つのレポートですべての失敗を収集します。ignoreは既知の不安定なステップをスキップします。いずれにしても、何かが失敗した場合、実行はゼロ以外のコードで終了します。
終了コードの契約は両者で同じであり、これが重要な部分です。アサーションが失敗すると、ランナーはゼロ以外のコードで終了します。CIはそのコードを読み取り、ステップを失敗とマークし、ジョブを失敗させ、マージまたはデプロイをブロックします。追加の設定は何も必要ありません。両者にとって共通の唯一の落とし穴は、終了コードを飲み込んでしまうことです。シェルパイプラインで実行をラップしたり、|| trueを付加したりすると、ゼロ以外の終了が無視され、ゲートが機能しなくなります。これは避けてください。レポート形式に関するより広いコンテキストについては、CSVまたはJSONを使用したデータ駆動型APIテストで、レポートが反復データにどのように結びついているかを示しています。
GitHub ActionsでのNewman
コレクションはリポジトリ内のエクスポートされたファイルなので、ワークフローはシンプルです。コードをチェックアウトし、Newmanをインストールし、コレクションを実行し、失敗時でもレポートをアップロードします。
name: API tests
on:
pull_request:
branches: [main]
jobs:
api-tests:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Set up Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
- name: Install Newman
run: npm install -g newman
- name: Run API tests
run: |
newman run ./tests/api-tests.postman_collection.json \
-e ./tests/staging.postman_environment.json \
-r cli,junit \
--reporter-junit-export ./results/junit.xml
- name: Upload report
if: always()
uses: actions/upload-artifact@v4
with:
name: newman-report
path: ./results
コレクションと環境ファイルがリポジトリにコミットされていれば、シークレットは不要です。if: always()の行は、テストが失敗した場合でもレポートのアップロードを実行し続けます。これはまさにレポートを読みたい時です。あなたが負うコストは、そもそもこれらのJSONファイルを作成したエクスポートステップと、APIが変更されたときにそれらを更新することを忘れないようにすることです。
GitHub ActionsでのApidog CLI
Apidogのワークフローも同様の形式ですが、1つ変更点があります。アクセストークンはリポジトリのシークレットから取得され、ファイルパスを指定する代わりにIDでシナリオを選択します。
name: API tests
on:
pull_request:
branches: [main]
jobs:
api-tests:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Set up Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
- name: Install Apidog CLI
run: npm install -g apidog-cli
- name: Run API test scenario
run: |
apidog run \
--access-token "$APIDOG_ACCESS_TOKEN" \
-t 605067 \
-e 1629989 \
-r html,junit \
--out-dir ./apidog-reports
env:
APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}
- name: Upload report
if: always()
uses: actions/upload-artifact@v4
with:
name: apidog-report
path: ./apidog-reports
対称性に注目してください。同じチェックアウト、同じNodeセットアップ、同じインストールしてから実行という形式、常にアップロードする点も同じです。唯一の違いは、シークレットとして配線されたトークンと、ファイルパスではなくIDでシナリオが選択される点です。シナリオはライブでフェッチされるため、最新の状態を保つべきJSONファイルはありません。他のシステムでの同じパターンについては、GitHub ActionsでのAPIテストの自動化方法でGitLab CIやJenkinsにおける構造が説明されています。
選択方法
どちらのランナーが客観的に優れているかという問題に帰着することはめったにありません。それは、あなたのテストがすでにどこに存在し、チームがそれをどのように維持したいかにかかっています。
テストがすでにPostmanコレクションである場合はNewmanを選択してください。 もしあなたのスイートがPostmanに存在し、チームがエディタでテストスクリプトを記述し、新しいアカウントなしでどんなパイプラインにも組み込める無料のオープンソースランナーを求めているなら、Newmanはまさにフィットします。これは、コレクションのエクスポートとJSONのコミットに慣れており、テストスクリプトを手動で所有することに抵抗がないPostmanを使っているチームにとって自然な選択です。NewmanとPostmanの違いについて、Postmanエコシステム内の違いをさらに詳しく読むことができます。
Postman内に留まることよりも、作成速度と単一の真実の源が重要である場合は、Apidog CLIを選択してください。 もし視覚的にテストシナリオを構築し、リクエストを連鎖させ、変数を抽出し、テストコードを記述して再エクスポートすることなく、その同じシナリオを複数の環境で実行したいのであれば、Apidogはその摩擦を取り除きます。デザイン、デバッグ、モック、テストが1つのワークスペースでライブで行われ、CLIはあなたが構築した正確なシナリオを実行します。Postmanから移行するチームにとって、ApidogはAPIテストのためのPostmanの代替として、その移行をカバーしており、インポートはワンクリックで完了します。
両方のツールを使用するという選択肢もあります。一部のチームは、レガシーコレクションを実行するために既存のNewmanステップを残しつつ、新しくより複雑な連鎖シナリオをApidogに移行しています。2つのCLIは1つのパイプライン内で問題なく共存できます。それぞれが独立したステップであり、個別の終了コードを持つため、Newmanステップは自身のタイミングで廃止できます。
最初の自動化されたシナリオを設定し、同じ日の午後にターミナルから実行するには、Apidogをダウンロードし、テストシナリオを構築し、そのCI/CDタブから生成されたコマンドをコピーしてください。