Postman Collection¶

Mayhem は Postman Collection で指定された API のテストをサポートしています。Postman を最大限に活用するため、サポートされる Postman の機能に関する用語を確認しておきましょう。

1. Postman API (API キー)¶

Postman Workspace の Postman Collection にアクセスするには、API キーが必要です。

Postman API キーを作成するには、https://learning.postman.com/docs/developer/postman-api/authentication/ に移動します。

API キーを使用するには、POSTMAN_API_KEY 環境変数を設定するか (推奨される方法)

POSTMAN_API_KEY=PMAK-1234... mapi run

mapi run への引数として値を渡します。

mapi run ... --postman-api-key PMAK-1234

2. Postman Collection¶

Postman Collection は、API と連携する方法を定義する仕様です。

Mayhem は Postman Collection ID を直接使用して API を解析できます (推奨される方法)。Collection の ID を検索する方法については https://support.postman.com/hc/en-us/articles/5063785095319-How-to-find-the-ID-of-an-element-in-Postman を参照してください。

たとえば、次のコマンドを実行すると、ID 20703797-d40355dc-b188-4f35-9b3a-3c882be4ba7d を持つコレクションを使用して http://localhost:8080 で実行されている API がスキャンされます。

mapi run my-api auto 20703797-d40355dc-b188-4f35-9b3a-3c882be4ba7d \
  --url http://localhost:8080

別の方法として、エクスポートされた Postman Collection JSON ファイルを使用することもできます。

mapi run my-api auto /home/mayhem/api/postman_collection.json \
  --url http://localhost:8080

3. Postman 環境¶

Postman 環境は、リクエストでの再利用やチームとの共有が可能な変数のセットです。それらの変数は、リクエスト認証、クエリー、パスパラメーター、リクエストボディ、スクリプト内で参照できます。変数は効率的に作業したり、チームメイトとコラボレートしたり、動的ワークフローをセットアップしたりするのに役立ちます。

パス変数、ヘッダー、クエリーパラメーター、またはリクエストボディ内で Postman 動的変数の多くを使用するリクエストは、ファジング時に Mayhem によって処理され、適切な型にマップされます。

Mayhem と共に Postman 環境を使用する際、環境 ID (またはエクスポートされた環境 JSON ファイル) を指定すると、Postman Collection の変数が自動的に環境の変数に置き換えられます。

環境の ID を取得する方法については https://support.postman.com/hc/en-us/articles/5063785095319-How-to-find-the-ID-of-an-element-in-Postman を参照してください。

たとえば、次のコマンドを実行すると、ID 12345 を持つ環境を使用してコレクション 20703797-d40355dc-b188-4f35-9b3a-3c882be4ba7 の変数に値が挿入されます。

mapi run my-api auto 20703797-d40355dc-b188-4f35-9b3a-3c882be4ba7d \
  --postman-environment 12345 \
  --url http://localhost:8080

別の方法として、エクスポートされた Postman Environment JSON ファイルを使用することもできます。

mapi run my-api auto 20703797-d40355dc-b188-4f35-9b3a-3c882be4ba7d \
  --postman-environment /home/mayhem/api/envs/exported_postman_environment.json \
  --url http://localhost:8080

4. Postman Workspace Global Variable¶

グローバル変数を使用すると、コレクション、リクエスト、テストスクリプト、環境を越えてデータにアクセスできます。グローバル変数はワークスペース全体で利用可能です。

Mayhem と共に Workspace Global Variableを使用する際、ワークスペース ID (またはエクスポートされたグローバル変数 JSON ファイル) を指定すると、Postman Collection の変数が自動的にグローバル変数に置き換えられます。

ワークスペースの ID を取得する方法については https://support.postman.com/hc/en-us/articles/5063785095319-How-to-find-the-ID-of-an-element-in-Postman を参照してください。

たとえば、次のコマンドを実行すると、ID abcdef を持つワークスペースを使用してコレクション 20703797-d40355dc-b188-4f35-9b3a-3c882be4ba7 の変数に値が挿入されます。

mapi run my-api auto 20703797-d40355dc-b188-4f35-9b3a-3c882be4ba7d \
  --postman-global-variables abcdef \
  --url http://localhost:8080

別の方法として、エクスポートされた Postman Global Variables JSON ファイルを使用することもできます。

mapi run my-api auto 20703797-d40355dc-b188-4f35-9b3a-3c882be4ba7d \
  --postman-global-variables /home/mayhem/api/envs/exported_global_variables.json \
  --url http://localhost:8080

グローバル変数と環境の両方を使用した場合、変数キーが重複しているとき、常にグローバル変数よりも環境が優先されます。

すべてを組み合わせる¶

次のコマンドを実行すると、上記のすべてのオプションを使用し、Postman Collection、環境、ワークスペースグローバル変数を使用して API を解析できます。

export POSTMAN_API_KEY=PMAK-1234...

mapi run my-postman-api auto <postman collection id> \
  --url <url> \
  --postman-environment <postman environment id or exported environment> \
  --postman-global-variables <postman workspace id or exported global variables>

Postman 変数とスクリプト¶

Postman には Mayhem がサポートしていないスクリプトエンジンがあります。

通常、それらのスクリプトは、別の API レスポンスから返された値をリクエストに設定するのに使用されます。Mayhem はファジング実行時に自動的に API レスポンスを使用します。

スクリプトを使用する Postman コレクションをフォークし、可能であればスクリプトを変数に置き換え、フォークされたコレクションを Mayhem のターゲットにすると有効です。