Postmanの使い方｜環境変数・テストスクリプト・コマンドでの実行

Postman は、API にリクエストを送って結果を確かめるツールです。 リクエストを「コレクション」にまとめ、URL やトークンは「変数」にし、応答のチェックを「テストスクリプト」に書いておくと、同じテストをコマンド（newman・Postman CLI）や CI で何度でも流せます。

# コレクションと環境を書き出して（Export）、コマンドで実行する
npx newman run users.postman_collection.json -e local.postman_environment.json
npx postman collection run users.postman_collection.json -e local.postman_environment.json

この記事のために、ログイン・ユーザーの作成・取得・削除ができる小さな API を作り、6リクエスト・16アサーションのコレクションを newman で流した結果です。

→ ログイン
  POST http://localhost:3088/login [200 OK, 204B, 40ms]
  ✓  ステータスが 200
  ✓  応答が 1000ms 未満
  ✓  token が文字列で返る

❏ users
↳ ユーザー作成
  POST http://localhost:3088/users [201 Created, 251B, 5ms]
  ✓  201 Created
  ✓  Location ヘッダーがある
  ✓  JSON の形が正しい
  ✓  送った name が返る
  ……
┌─────────────────────────┬──────────────────┬──────────────────┐
│                         │         executed │           failed │
├─────────────────────────┼──────────────────┼──────────────────┤
│                requests │                6 │                0 │
├─────────────────────────┼──────────────────┼──────────────────┤
│              assertions │               16 │                0 │
└─────────────────────────┴──────────────────┴──────────────────┘

確認環境：newman 6.2.3・Postman CLI 1.73.0（どちらも npm で入れたもの）・Node.js 22.22.2・Ubuntu 24.04 で、自作の API に対してコレクションを実行しました。変数の優先順位・pm.* のスクリプト・終了コード・レポーターは newman で動かした結果です。Postman アプリの画面操作（Collection Runner など）と Postman CLI のクラウド連携は、Postman の公式ドキュメント（v12）で確かめています。GitHub Actions のワークフローは actionlint 1.7.12 で文法を確かめ、同じコマンドを手元で流しました（確認日 2026年10月13日）。

全体の流れ

API のテストで何を確かめるか（正常系・異常系・認可・境界値）は、関連記事「APIテストの観点チェックリスト｜正常系・異常系・認可・境界値」で扱っています。

変数の種類と優先順位

変数は {{名前}} で URL・ヘッダー・本文のどこにでも書けます。 Postman の変数には5つの範囲（スコープ）があり、同じ名前があると範囲の狭いほうが勝ちます（Postman のドキュメントより）。

優先順位を確かめた結果

同じ名前の変数 who を、5つの範囲すべてに別の値で置き、/echo?who={{who}} に送って、どの値が使われたかを見ました。

global < collection < environment < data < local の順で、右ほど強いことが確かめられました。どこにも定義されていない変数は、エラーにならずに {{who}} という文字のまま送られます。「URL に {{ が入っている」ときは、環境を選び忘れているか、変数名の打ち間違いです。

newman の --env-var は環境変数を上書きします。 環境ファイルに who=environment があっても、--env-var who=cli を付けると cli が使われました。--global-var は global なので、コレクション変数に同じ名前があると負けます（--global-var who=cli でも collection が使われました）。

値の種類：共有する値と手元の値

Postman v12 のドキュメントでは、変数の値は2つに分かれます。

パスワードやトークンは、手元の値か Postman Vault（秘密情報の保管場所）に置きます。 共有する値に入れると、ワークスペースの人に見えます。環境を JSON に書き出すと値が入ることがあるので、リポジトリに入れる環境ファイルには秘密情報を書かず、CI では --env-var で渡します。秘密情報の扱いは、関連記事「.envの使い方と注意点｜APIキーを安全に管理する方法」で扱っています。

変数は文字列で保存される

ドキュメントに「Postman stores variables as strings」とあるとおり、オブジェクトや配列は JSON.stringify() で文字列にして入れ、JSON.parse() で戻します。数値も文字列になるので、比べるときは Number() で数値にします。

pm.environment.set("user", JSON.stringify({ id: 1, role: "admin" }));
const user = JSON.parse(pm.environment.get("user"));

pm.collectionVariables.set("userId", 2);                  // 文字列 "2" として入る
pm.expect(u.id).to.eql(Number(pm.collectionVariables.get("userId")));

テストスクリプト（pm.*）の例文集

テストは、リクエストの「Scripts」タブの Post-response に書きます。 pm.test("名前", 関数) の中で pm.expect や pm.response.to を使い、失敗すると関数の中でエラーが投げられて、そのテストが失敗になります。以下はすべて newman 6.2.3 で通ることを確かめたものです。

ステータスコード

pm.test("ステータスが 200", () => {
  pm.response.to.have.status(200);
});
pm.test("2xx", () => pm.response.to.be.success);
pm.test("200 か 201", () => pm.expect(pm.response.code).to.be.oneOf([200, 201]));
pm.test("404 は notFound", () => pm.response.to.be.notFound);
pm.test("4xx", () => pm.response.to.be.clientError);

ステータスコードの意味は、関連記事「HTTPステータスコード 一覧｜全コードの原因と対処・curl実例つき」で扱っています。

JSON の本文

const u = pm.response.json();
pm.test("本文に name がある", () => pm.response.to.have.jsonBody("name"));
pm.test("値の一致", () => pm.response.to.have.jsonBody("name", "Sato"));
pm.test("型", () => pm.expect(u.id).to.be.a("number"));
pm.test("メールの形", () => pm.expect(u.email).to.match(/^[^@\s]+@[^@\s]+$/));
pm.test("キーがそろっている", () => pm.expect(u).to.have.all.keys("id", "name", "email"));
pm.test("error の文言", () => {
  pm.expect(pm.response.json()).to.deep.equal({ error: "not found" });
});

JSON スキーマで形をまとめて確かめる

const schema = {
  type: "object",
  required: ["id", "name", "email"],
  properties: {
    id: { type: "integer" },
    name: { type: "string" },
    email: { type: "string" }
  }
};
pm.test("JSON の形が正しい", () => {
  pm.response.to.have.jsonSchema(schema);
});

失敗すると、足りないキーが分かります。手元で 401 が返ったときのメッセージです。

expected data to satisfy schema but found following errors:
data should have required property 'id', data should have required property 'name', data should have required property 'email'

ヘッダー・時間・サイズ

pm.test("Location ヘッダーがある", () => pm.response.to.have.header("Location"));
pm.test("WWW-Authenticate: Bearer", () => {
  pm.response.to.have.header("WWW-Authenticate", "Bearer");
});
pm.test("Content-Type が JSON", () => {
  pm.expect(pm.response.headers.get("Content-Type")).to.include("application/json");
});
pm.test("応答が 1000ms 未満", () => pm.expect(pm.response.responseTime).to.be.below(1000));
pm.test("サイズ", () => pm.expect(pm.response.responseSize).to.be.below(1024));
pm.test("本文が空", () => pm.expect(pm.response.text()).to.equal(""));

値を次のリクエストに渡す

// ログインの Post-response
const body = pm.response.json();
pm.environment.set("token", body.token);          // 以降 {{token}} で使える

// ユーザー作成の Post-response
pm.collectionVariables.set("userId", pm.response.json().id);   // /users/{{userId}} で使う

前処理：トークンを取ってくる（pm.sendRequest）

pm.sendRequest({
  url: pm.environment.get("baseUrl") + "/login",
  method: "POST",
  header: { "Content-Type": "application/json" },
  body: { mode: "raw", raw: JSON.stringify({ user: "admin", password: "secret" }) }
}, (err, res) => {
  pm.environment.set("token", res.json().token);
});

newman では、この前処理のあと POST /login → GET /users/1 の順に送られ、取ったトークンで 200 が返りました。

前処理：署名・ID・ランダムな値

const cryptoJs = require("crypto-js");
const ts = "1760000000";
pm.variables.set("sig", cryptoJs.HmacSHA256("GET\n/echo\n" + ts, "key").toString());
pm.variables.set("rid", require("uuid").v4());

// 組み込みのランダムな値（dynamic variables）
pm.variables.set("name", pm.variables.replaceIn("{{$randomFirstName}}"));

const CryptoJS = require("crypto-js") と書くと、newman では Identifier 'CryptoJS' has already been declared の SyntaxError になりました。 サンドボックスに CryptoJS という名前が既にあるためで、別の名前で受け取ると動きました。同じように、lodash を _ で使うと「Using "_" is deprecated. Use "require('lodash')" instead.」と表示されました。

流れを変える・止める

// ログインに失敗したら、残りを実行しない
if (pm.response.code !== 200) {
  pm.execution.setNextRequest(null);
}

// 前処理で、このリクエストを飛ばす
if (pm.environment.get("skipSlow") === "yes") {
  pm.execution.skipRequest();
}

// あとで書くテスト（skipped と表示される）
pm.test.skip("あとで書くテスト", () => {});

ログインに失敗すると、後ろのリクエストは全部 401 になり、失敗が雪だるま式に増えます。 パスワードを間違えて流すと 16 件中 12 件が失敗しましたが、pm.execution.setNextRequest(null) を入れると、ログインの1リクエストで止まりました（失敗は2件）。

よく使う pm.* 一覧

pm.variables.set は local に書きます。 Postman のドキュメントでは、その値は「今のリクエストかコレクションの実行の間だけ残る」とされています。次のリクエストに渡したい値は、pm.environment.set か pm.collectionVariables.set で書きます。

Collection Runner：まとめて流す

Collection Runner は、Postman アプリでコレクションのリクエストを上から順に流す画面です。 ドキュメントでは、サイドバーでコレクション（またはフォルダー）を選び、Overview タブの Run から開きます。

ドキュメントには、アプリでの手動の実行は「プランごとに月に使える回数が決まっている」とあり、繰り返しが何回あっても1回の実行として数えられます。回数を気にせず CI で流すには、次の newman か Postman CLI を使います。

データファイルで繰り返す

name,email
Tanaka,tanaka@example.com
Suzuki,suzuki@example.com

npx newman run users.postman_collection.json -e local.postman_environment.json -d users.csv

CSV の1行目が変数名になり、2行分の繰り返しで12リクエスト・32アサーションが流れました。本文の {"name":"{{name}}"} には、1回目は Tanaka、2回目は Suzuki が入ります。

newman：コマンドで実行する

newman は、Postman のコレクションを実行するコマンドで、npm で入ります。 Postman アプリで「Export」したコレクション（Collection v2.1）と環境の JSON を渡します。

npm install -D newman            # プロジェクトに入れる（npx newman で動かす）
npx newman run users.postman_collection.json \
  -e local.postman_environment.json \
  -d users.csv \
  -r cli,junit \
  --reporter-junit-export results/newman.xml

よく使うオプション

終了コード

CI は終了コードで成功・失敗を判断します。 newman はテストが1件でも失敗すると 1 で終わるので、そのまま CI のステップが失敗になります。-x は「レポートだけ取りたい」ときに使い、付けたままにすると失敗に気づけなくなります。

失敗したときの表示です。どのリクエストのどのテストが、何を期待して何だったかが出ます。

 01.  AssertionError  ステータスが 200
                      expected response to have status code 200 but got 401
                      at assertion:0 in test-script
                      inside "ログイン"

レポーター

npx newman run users.postman_collection.json -e local.postman_environment.json \
  -r cli,junit,json,htmlextra \
  --reporter-junit-export out/junit.xml \
  --reporter-json-export out/result.json \
  --reporter-htmlextra-export out/report.html

JUnit の XML は、フォルダー・リクエストごとに testsuite、テストごとに testcase になりました。

<testsuites name="Users API" tests="6" time="0.043">
  <testsuite name="ログイン" tests="3" failures="0" errors="0" time="0.029">
    <testcase name="ステータスが 200" time="0.029" classname="UsersApi"/>
    <testcase name="応答が 1000ms 未満" time="0.029" classname="UsersApi"/>
    <testcase name="token が文字列で返る" time="0.029" classname="UsersApi"/>
  </testsuite>
  ...

Node.js から呼ぶ

// run-tests.js
const newman = require('newman');

newman.run({
  collection: require('./users.postman_collection.json'),
  environment: require('./local.postman_environment.json'),
  reporters: ['cli'],
  envVar: [{ key: 'password', value: process.env.API_PASSWORD }],
}, (err, summary) => {
  if (err) throw err;
  const failures = summary.run.failures.length;
  console.log(`assertions: ${summary.run.stats.assertions.total}, failures: ${failures}`);
  process.exitCode = failures > 0 ? 1 : 0;
});

API_PASSWORD=secret node run-tests.js で assertions: 16, failures: 0（終了コード 0）、間違ったパスワードで assertions: 16, failures: 12 になりました。

Postman CLI：Postman 公式のコマンド

Postman CLI は、Postman が出している公式のコマンドです。 npm の postman-cli で入り、コマンド名は postman です。ローカルのコレクションファイルはログインなしで実行でき、オプションの多くは newman と同じ名前です。

npm install -g postman-cli
postman collection run users.postman_collection.json -e local.postman_environment.json -r cli,junit

手元で実行すると、newman と同じ 6リクエスト・16アサーションがすべて通り、JUnit のレポートは postman-cli-reports/Users-API-2026-10-13-02-48-02.xml に保存されました。実行の最後に「Postman credentials are required for publishing run details to Postman cloud.」と表示され、結果をクラウドに送るにはログインが必要でした。

# CI でログインする（API キーは Postman の設定で作り、CI のシークレットに入れる）
postman login --with-api-key "$POSTMAN_API_KEY"

GitHub Actions に組み込む

API を起動して、newman を流し、JUnit の結果を保存するワークフローです。actionlint で文法を確かめ、テストを流す部分は手元で同じコマンドを実行して終了コード 0 と results/newman.xml ができることを確かめました。

# .github/workflows/api-test.yml
name: API test

on:
  push:
    branches: [main]
  pull_request:

jobs:
  newman:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7

      - uses: actions/setup-node@v7
        with:
          node-version: 22

      - name: API サーバーを起動
        run: |
          node server.js &
          for _ in $(seq 1 30); do
            curl -s -o /dev/null http://localhost:3088/echo && break
            sleep 1
          done

      - name: newman でテスト
        run: |
          npx --yes newman@6.2.3 run postman/users.postman_collection.json \
            -e postman/local.postman_environment.json \
            --env-var "password=${{ secrets.API_PASSWORD }}" \
            -r cli,junit \
            --reporter-junit-export results/newman.xml

      - name: 結果を保存
        if: always()
        uses: actions/upload-artifact@v7
        with:
          name: newman-results
          path: results/

Postman CLI で流す場合は、テストのステップをこう書きます。

      - name: Postman CLI でテスト
        env:
          POSTMAN_API_KEY: ${{ secrets.POSTMAN_API_KEY }}
        run: |
          npm install -g postman-cli
          postman login --with-api-key "$POSTMAN_API_KEY"
          postman collection run postman/users.postman_collection.json \
            -e postman/local.postman_environment.json \
            -r cli,junit

GitHub Actions の基本は関連記事「CI/CDとは｜GitHub Actionsで最初のパイプラインを作るまで」、キャッシュと matrix は「GitHub Actionsのキャッシュとmatrix｜コピペ用YAMLとキー設計」で扱っています。

よくある質問

Q. URL に {{baseUrl}} がそのまま入って送られます。 A. 変数がどこにも定義されていません。環境を選び忘れていないか（アプリ右上の環境の選択、newman なら -e）、変数名の大文字・小文字が合っているかを見ます。手元でも、定義していない変数は {{who}} のまま送られました。

Q. 環境変数を書き換えたのに、別の値が使われます。 A. 同じ名前が data か local（pm.variables.set）にあると、そちらが勝ちます。pm.variables.get("名前") は「今使われる値」を返すので、console.log で確かめます。

Q. newman と Postman CLI のどちらを使えばよいですか？ A. ローカルのファイルを CI で流すだけなら、どちらでも同じ結果になりました。結果を Postman のクラウドで見たい、クラウドのコレクションを ID で流したい場合は Postman CLI、レポーターを npm で足したい・Node.js のスクリプトから呼びたい場合は newman が向いています。

Q. curl で同じことを確かめるには？ A. Postman のリクエストは、Code（</>）から curl のコマンドに変換できます。curl の使い方は、関連記事「curlコマンドの使い方｜よく使うオプションとAPIの確認方法」で扱っています。

Q. API の URL やエラーの形はどう決めればよいですか？ A. 関連記事「REST APIの設計｜URL・ステータスコード・エラー形式の決め方」で扱っています。

まとめ

• 変数は global < collection < environment < data < local。狭いほうが勝つことを newman で確かめた。定義が無いと {{名前}} のまま送られる
• 値は文字列で保存される。オブジェクトは JSON.stringify、数値は Number() で戻す
• テストは pm.test + pm.expect / pm.response.to。形は jsonSchema でまとめて確かめる
• ログイン失敗で後ろが全部落ちるときは pm.execution.setNextRequest(null)
• newman は失敗があると 終了コード 1。-x は 0 にする。--bail は最初の失敗で止める
• CI では JUnit のレポーターと、秘密情報の --env-var
• Postman CLI はローカルのファイルをログインなしで実行できた。クラウド連携・--output はログインが要る

参考・出典

確認日はいずれも 2026年10月13日です。

• Postman Docs「Store and reuse values using variables」（v12）：https://learning.postman.com/docs/use/send-requests/variables/variables/
• Postman Docs「Reference variables in Postman scripts」：https://learning.postman.com/docs/tests-and-scripts/write-scripts/postman-sandbox-reference/pm-variables
• Postman Docs「Run collections using the Collection Runner」：https://learning.postman.com/docs/collections/running-collections/intro-to-collection-runs/
• Postman Docs「Postman CLI options」：https://learning.postman.com/docs/postman-cli/postman-cli-options/
• Postman Docs「Postman CLI collection commands」：https://learning.postman.com/docs/postman-cli/postman-cli-collections/
• newman（GitHub）：https://github.com/postmanlabs/newman
• npm「newman」：https://www.npmjs.com/package/newman
• npm「postman-cli」：https://www.npmjs.com/package/postman-cli
• npm「newman-reporter-htmlextra」：https://www.npmjs.com/package/newman-reporter-htmlextra

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。