Newman と Bail オプション
この記事は Postman Adventcalender の13日目の記事です。
過去Postman CLIの使い方を簡単にまとめました。
今日はNewmanというツールに使い方を纏めていきます。
Newman とは
Postman CLI と異なりNewmanはPostmanによって主導されているオープンソースツールです。対してPostman CLIはPostmanによって開発されています。Node16以降の環境で動作します。
NewmanはPublicに公開されているPostmanのコレクションをCLI経由で実行させることが可能です。PostmanCLIはそれに加えて、認証機能を持ち特定ワークスペースに存在しているコレクションの実行が可能です。
双方ともCI/CDにおけるテストに組み込まれるのが一般的なユースケースです。ただしPostmanCLIと異なり、Newmanはコレクションが連動する環境変数を読み込む機能があるため、例えば商用環境、ステージング環境、開発環境等で挙動を変更させる、といった使い方が可能であるため現時点ではCI/CD環境における柔軟性はNewmanの方が高そうです。
一方Postman CLIはコレクションの実行に加えて、ワークスペースや環境管理、ドキュメント作成、API 監視などの機能を有していますが、統合開発ツールとしてはPostman CLIの方が協力、といった違いがあります。
さっそくやってみる
コレクションの作成と公開
いつも通りhttps://requestcatcher.com/を用いて簡単なAPIコールをコレクションとして作成し保存しておきます。
手順が不明の場合こちらに纏まっています。
疎通がとれたら(ステータスコード200が戻ってきたら）、保存をクリックします。
Newmanは認証機能がなくPublic公開されているコレクションのみを実行可能ですので、一度このコレクションを公開します。
コレクションの右の・・・を選んで移動を選択します。
Publicを選択してCollectionを移動を選択します。
ワークスペースを切り替えると先ほどのコレクションが移動されています。
次に画面右側の情報ボタンを押してコレクションのIDをコピーしておきます。
Newmanのインストールとテスト
NewmanはNode16以降で動作します。このためインストールはnpmを用いるのが一番簡単です。
npm install -g newman
インストールが完了したらさっそく実行します。
npm install -g newman
newman run https://www.postman.com/collections/<collectionID>
<collectionID>は先ほどコピーしたものに置き換えます。
newman
New Collection
→ https://newman.requestcatcher.com/
GET https://newman.requestcatcher.com/ [200 OK, 1.74kB, 461ms]
┌─────────────────────────┬────────────────────┬───────────────────┐
│ │ executed │ failed │
├─────────────────────────┼────────────────────┼───────────────────┤
│ iterations │ 1 │ 0 │
├─────────────────────────┼────────────────────┼───────────────────┤
│ requests │ 1 │ 0 │
├─────────────────────────┼────────────────────┼───────────────────┤
│ test-scripts │ 0 │ 0 │
├─────────────────────────┼────────────────────┼───────────────────┤
│ prerequest-scripts │ 0 │ 0 │
├─────────────────────────┼────────────────────┼───────────────────┤
│ assertions │ 0 │ 0 │
├─────────────────────────┴────────────────────┴───────────────────┤
│ total run duration: 529ms │
├──────────────────────────────────────────────────────────────────┤
│ total data received: 1.55kB (approx) │
├──────────────────────────────────────────────────────────────────┤
│ average response time: 461ms [min: 461ms, max: 461ms, s.d.: 0µs] │
└──────────────────────────────────────────────────────────────────┘
実行にかかった時間、やり取りした回数、などが表示されます。
jsonからの実行
先ほどは直接URIとしてコレクションIDをしてしましたが、もう一つjsonから実行させる方法も試します。
コレクションからエクスポートを選択します。
エクスポートをクリックします。
以下のようなjsonが出力されます。
{
"info": {
"_postman_id": "e8c757f2-e046-4ed8-8e1d-ee17aacc7c4b",
"name": "New Collection",
"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",
"_exporter_id": "36690477",
"_collection_link": "https://www.postman.com/kameman-6657/public/collection/36690477-e8c757f2-e046-4ed8-8e1d-ee17aacc7c4b?action=share&source=collection_link&creator=36690477"
},
"item": [
{
"name": "https://newman.requestcatcher.com/",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "https://newman.requestcatcher.com/",
"protocol": "https",
"host": [
"newman",
"requestcatcher",
"com"
],
"path": [
""
]
}
},
"response": []
}
]
}
test.jsonとして保存した後、以下を実行します。
newman run test.json
先ほどと同じ結果が表示されれば成功です。
bail オプション
コレクションというのは複数のAPIコールを束ねたものです。newmanから実行された場合、コレクションに複数のAPIコールが存在しているケースでは上から順に実行されます。
デフォルトでは複数のAPIコールはお互いの結果（戻りのステータスコード）を意識せずに実行されます。
しかしCI/CD環境でNewmanを使う場合は、途中のAPIコールが失敗した時には処理をそこで停止させたいケースがあります。それがbailオプションです。
意図的に存在しないドメインのAPIを呼び出すものを作成しそれを一番目に設定します。
再度newman runを実行すると以下の通りエラーが出力されます。
（jsonを指定した実行の場合、再度エクスポートが必要です。コレクションIDは変らないためテストが楽です。）
newman
New Collection
→ Fail Call
GET https://newman.kamedatest.com/ [errored]
getaddrinfo ENOTFOUND newman.kamedatest.com
→ https://newman.requestcatcher.com/
GET https://newman.requestcatcher.com/ [200 OK, 1.74kB, 349ms]
┌─────────────────────────┬─────────────────────┬────────────────────┐
│ │ executed │ failed │
├─────────────────────────┼─────────────────────┼────────────────────┤
│ iterations │ 1 │ 0 │
├─────────────────────────┼─────────────────────┼────────────────────┤
│ requests │ 2 │ 1 │
├─────────────────────────┼─────────────────────┼────────────────────┤
│ test-scripts │ 0 │ 0 │
├─────────────────────────┼─────────────────────┼────────────────────┤
│ prerequest-scripts │ 0 │ 0 │
├─────────────────────────┼─────────────────────┼────────────────────┤
│ assertions │ 0 │ 0 │
├─────────────────────────┴─────────────────────┴────────────────────┤
│ total run duration: 657ms │
├────────────────────────────────────────────────────────────────────┤
│ total data received: 1.55kB (approx) │
├────────────────────────────────────────────────────────────────────┤
│ average response time: 174ms [min: 349ms, max: 349ms, s.d.: 174ms] │
└────────────────────────────────────────────────────────────────────┘
# failure detail
1. Error getaddrinfo ENOTFOUND newman.kamedatest.com
at request
inside ""
ポイントはこちらです。requests回数が2となっており、２つともテストされたことがわかります。
次に--bailオプションを付けて実行すると以下となります。
┌─────────────────────────┬──────────┬──────────┐
│ │ executed │ failed │
├─────────────────────────┼──────────┼──────────┤
│ iterations │ 1 │ 0 │
├─────────────────────────┼──────────┼──────────┤
│ requests │ 1 │ 1 │
├─────────────────────────┼──────────┼──────────┤
最初のAPIコールで実行が停止されていることがわかります。
Newmanでは全てのテストが成功した時点で0が戻りますが、失敗した場合1が戻ります。bailオプションを付与した場合、失敗時に即時1が戻るようになるため、異常を早めに検知できます。
Discussion