Postman Code モックサーバー入門シリーズ
- Postman Code モックサーバー入門 - 概要編 (本記事)
- Postman Code モックサーバー入門 - 実装編 (近日中に投稿予定)
- Postman Code モックサーバー入門 - 障害注入編 (近日中に投稿予定)
2026年7月21日のPostman v12.20.1で、Postman Codeモックサーバー（以下、Codeモックサーバー）とPostman Simulator（以下、Simulator）がクラウドで使えるようになりました。
どちらもこれまではGitリポジトリに接続されたワークスペースでのローカル開発向けの機能でしたが、クラウドサービスとして利用できるようになったことで、チームや外部利用者との共有や、モックAPIとしての利用の幅が大きく広がりました。
そこで本シリーズでは、3回に分けてCodeモックサーバーを紹介します。概要編である本記事では、Codeモックサーバーが何であり、何ができるのか、そして開発の流れを整理します。
Codeモックサーバーとは
Postmanには2種類のモックサーバーがあります。
- コレクションベースのモックサーバー：従来から提供されているモックサーバーです。コレクションをベースに作成され、コレクションに保存済みのサンプル（example）をそのまま返します
- Codeモックサーバー：JavaScriptでリクエストの処理とレスポンスのロジックを書き、応答を制御するモックサーバー
この2つは作成方法が違うだけで、クラウドにデプロイされたあとはどちらも単に「モックサーバー」です。
コレクションベースのモックサーバーは作成した時点からクラウド上で動くモックサーバーであり、Codeモックサーバーはローカルで実行してからクラウドへデプロイできます。
本記事では両者の違いを明確にするため、それぞれを「コレクションベースのモックサーバー」「Codeモックサーバー」と呼び分けます。
コレクションベースのモックサーバーは設定が簡単なので、APIの設計確認や固定レスポンスの共有、シンプルなプロトタイピングに向いています。
一方Codeモックサーバーは、コードで応答を組み立てられる分、表現力が高くなります。
コレクションベースのモックサーバーではできないことのうち、代表的なものは次の3つです。
- 条件分岐やロジックの実行：認証の前後で応答内容を変える、など
- 状態を持つAPIの再現：リクエストをまたいで状態を保持するCRUD処理、カウンター、セッションごとの別状態、など
- データ駆動の応答：データセット（Datasets）を参照し、リクエスト条件に合う行を返す
固定レスポンスだけで足りるなら、コレクションベースのモックサーバーで始めるのが手軽です。
ログイン状態、CRUDの蓄積、段階的に変わる処理状態、一定間隔で失敗する挙動などを再現したいなら、Codeモックサーバーを選びます。
図: Codeモックサーバーの全体イメージ
書いたCodeモックサーバーはローカルで実行できますし、クラウドにデプロイして公開URLとして払い出すこともできます。
Codeモックサーバーの利用について
- Codeモックのローカル実行は、Postmanアプリ(デスクトップ)またはPostman CLIでのみ可能です
- Codeモックのクラウドへのデプロイは、有料プランでのみ利用できます
- デプロイ済みCodeモックサーバーの設定について
- デフォルトは非公開設定で、アクセスにはワークスペース権限またはPostman APIキーが必要です
- 公開設定にすることで、URLを知っているユーザーがアクセスできます
- ローカルでの変更を自動的に反映する自動デプロイも設定可能です
Codeモックサーバーの開発の流れ
Codeモックサーバーは、ローカルでコードを書いて検証し、それをクラウドへ同期してデプロイする、という流れで開発します。
ローカル実行とクラウド実行では同じハンドラーコードを使い、実行場所だけを切り替えられます。
全体の流れは次の6ステップです。
| # | ステップ | 実行場所 | やること |
|---|---|---|---|
| 1 | モックを作成する | ローカル | JavaScriptのハンドラーを書く（＊1） |
| 2 | ローカルで実行する | ローカル | Postmanアプリ（デスクトップ）またはPostman CLIでローカル起動する |
| 3 | コレクションで検証する | ローカル | コレクションをモックに向けて実行し、レスポンスを確認する |
| 4 | クラウドへPushする (＊2 ネイティブGit連携で、GitをSSoTとする場合のみ) |
クラウド | Git管理のモックコードの定義をクラウドのワークスペースへ同期する |
| 5 | モックサーバーとしてデプロイする | クラウド | 常時稼働するURLを払い出す |
| 6 | 運用して改善する | 両方 | ログを確認し、フィードバックをハンドラーへ反映する |
図: Codeモックサーバーの開発の流れ
＊1 - ハンドラーの実装は、Postman AI（Agent Mode）を活用することで大幅に効率化・自動化できます
＊2 - ネイティブGit連携で、GitをSSoT（Single Source of Truth、信頼できる唯一の情報源）とする場合とは？: ネイティブGit連携で、モックサーバーのコードのバージョンをGitベースのレポジトリで管理している場合のこと。ネイティブGit連携については、こちらの記事が参考になります。
ステップバイステップでの開発方法については、「Postman Code モックサーバー入門 - 実装編」にて紹介予定です
ローカルでの開発（ステップ1〜3）
ハンドラーではリクエストを読み取り、ステータスコード、ヘッダー、レスポンス本文を決定します。
書いたらPostmanアプリ（デスクトップ）またはPostman CLIでローカル起動し、localhostのエンドポイントにリクエストを送って動作を確認します。
たとえばGET /healthだけを持つ、最小のCodeモックサーバーは次のように書けます。
const http = require("http");
// 実行環境が指定するポートを優先（ローカルとクラウドで同じコードが動く）
const PORT = process.env.PORT || 4500;
// Node.js標準のhttpモジュールでハンドラーを定義する
const server = http.createServer((req, res) => {
const { method, url } = req;
// @endpointコメントでエンドポイントを宣言する（Postman固有の作法）
// @endpoint GET /health
// メソッドとパスで分岐し、自分でレスポンスを組み立てる
if (method === "GET" && url === "/health") {
res.writeHead(200, { "Content-Type": "application/json" });
return res.end(JSON.stringify({ status: "ok" }));
}
// どのエンドポイントにも一致しない場合のフォールバック
res.writeHead(404, { "Content-Type": "application/json" });
res.end(JSON.stringify({ error: "Endpoint not defined" }));
});
server.listen(PORT, () => {
console.log(`Mock server running on port ${PORT}`);
});
動作を確認したら、対象のコレクションをローカルのモックに向けて実行し、ステータスコードやレスポンス形式が期待どおりかを検証します。
CIでは同じファイルを使って、コミットごとに再現可能なテストを回せます。
クラウドへの公開（ステップ4〜5）
PushとDeployについての補足です。
Pushは、検証済みのコードの定義をPostmanクラウド上のワークスペースへ同期する操作です。先述の通り、ネイティブGit連携で、GitをSSoTとする場合にのみ行います。
Pushした段階ではコードがクラウドに保存されるだけで、常時稼働するURLはまだありません。
Deployは、クラウド上のモックのコードをモックサーバーとして稼働させる操作です。
デプロイすると安定したクラウドURLが払い出され、利用者がアクセスできるようになります。デフォルトでPrivate、つまり利用者はアクセスにPostman APIキーが必要なURLが払い出されます。
デプロイ後は、リクエストログや状態、レスポンスを確認しながらハンドラーを改善していきます。
変更したらローカルで再検証し、あらためてクラウドへ同期して再デプロイします。
Codeモックサーバーで利用可能な主要JavaScript API
Codeモックサーバーのハンドラーで利用できる主要なJavaScript APIを紹介します。イメージが湧くように、スニペットも合わせて示します。
4つ紹介しますが、まずはpm.mockとpm.stateの2つを押さえると、Codeモックサーバーの利点が見えやすくなります。
pm.mock - リクエストマッチ、サンプル指定
pm.mock.matchRequestでリクエストをマッチさせ、pm.mock.sendExampleで保存済みのサンプル（example）を参照してレスポンスを返します。
すべてを手書きするのではなく、既存コレクションのサンプルを流用できます。
ベースは既存のサンプルに任せ、一部だけ条件分岐を加えたいときに効きます。
const server = http.createServer((req, res) => {
const { method, url } = req;
const requestPath = "<collection-and-folder-path>/GetUserById.request.yaml";
const examplePath = "<collection-and-folder-path>/.resources/GetUserById.resources/examples/200 OK.example.yaml";
// @endpoint GET /users/:id`
if (pm.mock.matchRequest(requestPath, req)) {
return pm.mock.sendExample(examplePath, res);
}
//...snip...
});
pm.mockのリファレンス: Postman Docs: pm.mock
pm.state (BETA) - 状態管理
pm.stateは状態を管理するAPIです。リクエストをまたいで状態を保持したいときに使います。
これによってCodeモックサーバーは、固定レスポンスを返すだけのものから、前の操作を覚えているAPIのように振る舞うものになります。
主な操作はpm.stateのget、set、delete、keys、clear、incrementメソッドです。なお、いずれも非同期なのでawaitを使う必要があります。
const sessionId = req.headers['x-mock-session'] || 'shared';
const stateKey = `cart:${sessionId}`;
const items = (await pm.state.get(stateKey)) || [];
const newItem = "New Value";
items.push(newItem);
await pm.state.set(stateKey, items);
// ...snip...
}
pm.stateのリファレンス: Postman Docs: pm.mock
pm.datasets (BETA) - データセット操作
データセットを読み込み、SQLクエリやviewを使って応答データを組み立てます。
固定JSONを大量に抱えることなく、問い合わせ条件に応じて現実的なデータを返せます。
const dataset = pm.datasets('<dataset-unique-ID>');
const userId = "user-ID";
const result = await dataset.executeQuery(
'SELECT userId, email, name FROM source_users WHERE userId = ?',
[userId]
);
const rows = [];
for await (const row of result.rows) {
rows.push(row);
}
pm.datasetsのリファレンス: Postman Docs: pm.datasets
pm.require - パッケージの読み込み
pm.requireはパッケージを読み込むAPIです。読み込み元は次の2つです。
- Package Library：チーム内で共有する自作のパッケージ
- 外部パッケージレジストリ：npmなどの外部レジストリのパッケージ
共通のロジックを毎回書き写す必要がなくなるので、複数のモックで同じ処理を使い回したいときに活用します。
ここで、主要なJavaScript APIを紹介しましたが、まずはpm.mockとpm.stateの2つを押さえると、Codeモックサーバーの利点が見えやすくなります。
代表的なユースケース
| ユースケース | できること | 使う機能 |
|---|---|---|
| 認証フロー | ログイン前後でアクセス可否を変える |
pm.stateによる状態管理と条件分岐 |
| CRUD API | POSTで保存し、GETで取得し、DELETEで削除する |
pm.stateによる状態管理と条件分岐 |
| セッション分離 | ユーザーごとに互いに影響しないシナリオを検証する | セッション用ヘッダー（例：x-mock-session）で識別し、pm.stateでセッションごとの状態を管理 |
| データ参照API | データセットから該当するユーザーを返す |
pm.datasetsによるデータセットに格納せれているレコードの活用 |
| 障害注入 | 一定割合や一定回数で5xxを返す | Postman Simulatorの活用 |
Simulatorによるモックへの障害注入
Simulatorは、1つまたは複数のモックに障害シナリオを適用するシミュレーションを作る機能です。
デプロイ済みのCodeモックサーバーに対して障害を注入できるので、利用者は同じモックサーバーのまま、本番に近い異常系を再現できます。
注入できる障害は次のとおりです。
- 遅延
- エラー（4xx、5xx）
- レート制限
- Chaosモード（指定した割合で5xxを返す）
図: Postman Simulatorによるモックへの障害の注入のイメージ
設定はPostmanアプリのUIから行えます。また、ローカル開発の場合はYAMLで記述することもできます。
下図は、2種類のモック、inventory_mockとpayment_mockに対してそれぞれ、Chaos（80%の確率で5xxエラー）とレートリミット（10 req/min）を発生させる設定の例です。左がPostmanアプリのUIでの設定、右がYAML設定ファイルになります。
図: Simulationの設定例 (Postman App UIとYAMLでの設定)
Simulatorによるモックサーバーへの障害注入の流れ
デプロイ済みのモックに対して次の流れで障害を注入します。
- Simulatorのシナリオを作成します（シナリオごとにURLが発行されます）
- 作成したシミュレーションを開始します
- 利用者はSimulatorが適用されたモックURLに切り替えて利用します（これで、障害レスポンスが返ります）
ステップバイステップでの障害注入の方法については、「Postman Code モックサーバー入門 - 障害注入編」にて紹介予定です
さいごに
本記事では、Codeモックサーバーの概要として、コレクションベースのモックサーバーとの違い、ハンドラーで使える主要なJavaScript API、開発の流れ、そしてSimulatorによる障害注入までを見てきました。
Codeモックサーバーの要点は、モックを「保存済みのレスポンスを返すもの」から「コードで振る舞いを組み立てるもの」へ広げられることです。
pm.stateでリクエストをまたいだ状態を持たせ、pm.datasetsでデータに基づいた応答を返し、Simulatorで異常系を注入する。
これらを組み合わせれば、認証フローやCRUD、遅延やエラーといった、本番に近い条件をモックの段階で再現できます。
次回の実装編では、本記事で紹介したJavaScript APIを使って、実際に動くモックサーバーをステップバイステップで組み立てていきます。