POSTMANおよびその有益な各機能

Posted: 2023年04月14日/Under: News, IT technique/By: Briswell Vietnam Co Ltd

POSTMANは、2012年に初めてリリースされ、約10年間にわたって2,500万人以上のユーザーを獲得し、API（アプリケーション・プログラミング・インターフェイスというApplication Programming Interfaceの略）のテストに使われる最も人気のあるツールとなっています。

POSTMANは、HTTPのPOST・PUT・GET・DELETEメソッドによるリクエスト送信、JSON・XML形式での返却データ確認、Collection機能によるリクエスト管理、インポート・エクスポート機能によるデータ共有といった多種多様な機能を提供してくれるので、プログラミングの知識を持たない者でも簡易に使えます。

長い間、POSTMANの基本的な機能を使った皆さんは、より高度な機能についても習得したいかもしれません。では、本記事で弊社の共有する有益な情報を見逃さないようお願いいたします。

1.POSTMANインストール

POSTMANは、オープンソースツールであり、以下のリンクからは簡易にダウンロードしてインストールできます。

ホームページ：https://www.postman.com/downloads/

2.POSTMANの有益な各機能

POSTMANは、本記事の冒頭で述べた基本的な機能に加え、次のような有益な各機能を提供してくれます。

2.1 変数設定

2.1.1 なぜ変数を利用するのか？

同一プロジェクトの各リクエストについて、URLのドメイン名やAuthorizationの値など、共用したり、宣言を繰り返したりする値が多くあります。

ドメイン名やAuthorizationの値が新しい値に更新された場合、リクエストごとにその新しい値を反映する必要があるので、手間がかかり、過失が発生しやすくなります。例：一次でサイトのURLは「https://api-example1.com/」と命名されましたが、二次でサイトのURLが「https://api-example2.com/」に変更されます。その際、すべてのリクエストの新しいドメイン名を反映する必要があるので、手間がかなりかかりそうです。

POSTMANは、この問題を解決するために、Global変数、Collection変数、Environment変数、Data変数、Local変数の5変数が用意されています。変数を使用することによって、URLのドメイン名やAuthorizationの値などの情報を変更した場合、変数を宣言した個所にアクセスし、その変数を新しい値に変更さえすれば、その変数を呼び出しているすべてのリクエストに、最新の値が自動的に反映されます。

本記事では、Collectionの範囲内で変数を宣言する方法について説明いたします。（他の変数の宣言方法が同じなので飛ばさせていただきます。）この変数は、宣言されたCollection、および、そのCollection内のリクエスト内でのみ有効になります。

2.1.2 POSTMANのCollectionでの変数宣言

ステップ１：Collection名の右にある「・・・」アイコンを押下し、Editを選択
ステップ２：Edit CollectionドロップダウンメニューでVariablesタブを選択
ステップ３：VARIABLE欄に変数名を入力
ステップ４：CURRENT VALUE欄に変数に値を入力
ステップ５：Saveボタン押下

2.1.3 Requestでの変数呼出

ステップ１：Requestファイルを開く
ステップ２： {{variable_name}}形式で変数を呼び出す
ステップ３：Saveボタンを押下

2.2 Consoleウィンドウ

通常、Bodyタブで返却される値を確認します。しかし、返却されるパラメータの数量が多い場合は、Bodyタブで結果を確認することがややこしくなり、下部の情報を確認するために何度もマウスのスクロールをする必要があります。この問題を解決するには、console.log(pm.response.json())コマンドを使用することで返却される値をConsoleウィンドウに出力し、そこで返却情報を確認します。

2.2.1 console.log(pm.response.json())コマンドによる返却情報の出力

ステップ１：画面の左下部にあるConsoleアイコンを押下し、Consoleウィンドウを開く
ステップ２：Testsタブを選択
ステップ３：console.log(pm.response.json())コマンドを作成
ステップ４：Sendボタンを押下
ステップ５：Consoleウィンドウで出力された返却情報を確認
ステップ６：Consoleウィンドウの右側にあるClearボタンを押下することで出力された情報を削除

2.2.2 console.log(pm.response.json())コマンド

console.log(pm.response.json())コマンドは次の二つの要素から構成されます。
・console.log()：呼び出された対象の値を出力するための関数
・pm.response.json()：Bodyで返却された情報を抽出するためにPOSTMANで定義された構文

例１： Bodyのレスポンスがオブジェクトであり、Bodyの情報をすべて出力する場合
→ console.log(pm.response.json())コマンドを利用します。

例２：Bodyのレスポンスが配列であり、Bodyの情報をすべて出力する場合
→ console.log(pm.response.json())コマンドを利用します。

例３：Bodyのレスポンスが配列であり、配列の最初のオブジェクトの情報のみを出力する場合
レスポンスパラメータの数量や性質上、配列の各オブジェクトが同等なので、一つの代表的なオブジェクトを確認して良いです。
→ console.log(pm.response.json()[0])コマンドを利用します。

例４：Bodyのレスポンスがオブジェクトであり、指定したレスポンスパラメーターの値を出力する場合
→ console.log(pm.response.json().{response parameter name})コマンドを利用します。

2.3 レスポンスパラメータのテストに使われるスクリプト

検索系APIについて返却されるレスポンスパラメータにAPI設計書に記載されたレスポンスパラメータとを比べて、過不足がある場合もあります。この場合においては、下記のスクリプトを使うことで、APIから返却されるレスポンスパラメータと、設計書に記載されるスポンスパラメータとがオブジェクト単位で同じであることを確認できます。

let expectedKeys = []
let returnKeys = Object.keys(pm.response.json())
function checkReturnKeys(expectedKeys,returnKeys){
    let duplicatedExpectedKeysAray = expectedKeys.filter((item,index) => {
        return expectedKeys.indexOf(item) !== index})
    if (duplicatedExpectedKeysAray.length === 0) {
        let missExpectedKeys = expectedKeys.filter((item) => !returnKeys.includes(item))
        let redundantExpectedKeys = returnKeys.filter((item) => !expectedKeys.includes(item))
        if(!_.isEqual(expectedKeys,returnKeys)){
            if(missExpectedKeys.length !== 0 && redundantExpectedKeys.length !== 0){
                console.log('Some parameters that are described in the specification are not being returned in the API response result, such as: '+missExpectedKeys+'. Please check again.')
                console.log('Some parameters are being returned in the API response result that are not described in the specification, such as: '+redundantExpectedKeys+'. Please check again.')
            }else if(missExpectedKeys.length !== 0){
                console.log('Some parameters that are described in the specification are not being returned in the API response result, such as: '+missExpectedKeys+'. Please check again.')
            }else{
                console.log('Some parameters are being returned in the API response result that are not described in the specification, such as: '+redundantExpectedKeys+'. Please check again.')
            }
            return false;
        }else{
            console.log('The parameters returned from the API match those described in the specification.')
            return true;
        }
    }else{
        console.log('The expectedKeys array contains elements with duplicate names, such as: '+ duplicatedExpectedKeysAray+'. Please check again.')
    }
}
pm.test("Check return keys", () => {
    pm.expect(checkReturnKeys(expectedKeys.sort(),returnKeys.sort())).eql(true);
});

2.3.1 上記のスクリプトの仕組み

・１行目：let expectedKeys = []
→ expectedKeysは、期待結果であり、API設計書から抽出されたレスポンスパラメータ名の要素を含む配列です。
・２行目：let returnKeys = Object.keys(pm.response.json())
→ returnKeysは、実際結果であり、APIから返却されたレスポンスパラメータ名の要素を含む配列です。
・このスクリプトの目的としては、expectedKeys配列（期待結果）とreturnKeys配列（実際結果）との要素を比較して同じであるか確認するためです。
→ 全く同じである場合は、Test Resultsタブで結果がPASSと返却され、Consoleタブに通知メッセージが表示されます。
→ 全然同じでない場合は、Test Resultsタブで結果がFAILと返却され、Consoleタブに通知メッセージが表示されます。
そのため、上記のスクリプトを実行する前に、次の二つの作業を行う必要があります。
・１行目で、設計書からレスポンスパラメータ名の要素の全てを[]にコピー・ペーストする
・２行目で、テスト対象のオブジェクトのレスポンスパラメータ名を正確に取得でるいように、pm.response.json()を変更する

2.3.2 作業手順

ステップ１： POSTMANのTestsタブに上記のスクリプトをコピー・ペーストする

ステップ２：API設計書を開き、レスポンス部分に記載されるテスト対象のオブジェクトを確定してから、そのオブジェクトのレスポンスパラメータ名を抽出する
例：autoDisplaySearchId APIは、autoDisplayの親オブジェクトが一つあり、material、laminateなどの子オブジェクトがあります。
下記の画像は、autoDisplayの親オブジェクトのレスポンスパラメータを抽出する仕方を示します。

ステップ３：ステップ２で抽出したレスポンスパラメータ名を上記のスクリプトの１行目の[]にコピー・ペーストする
例：
コピー・ペースト前
let expectedKeys = []
コピー・ペースト後
let expectedKeys = ["id","type","code","name","width1","width2","paste","unit","laminateType",
"sort","supplier","maker","settingDate","beforeUnit","comment","disableFlag","createdAt","createdBy",
"createdUserName","updatedAt","updatedBy","updatedUserName"]

ステップ４：上記のスクリプトの２行目にあるreturnKeys = Object.keys(pm.response.json())をテスト対象のオブジェクトに合わせるように変更する

例１：オブジェクトを返却するautoDisplaySearchId APIのテスト対象がautoDisplayオブジェクトの場合、以下のようにする
returnKeys = Object.keys(pm.response.json())

例２：オブジェクトを返却するautoDisplaySearchId APIのテスト対象がmaterialオブジェクトの場合、以下のようにする
returnKeys = Object.keys(pm.response.json().material)

例３：配列を返却するautoDisplaySearch APIのテスト対象がautoDisplayオブジェクトの場合、以下のようにする
returnKeys = Object.keys(pm.response.json()[0])

例４：配列を返却するautoDisplaySearch APIのテスト対象がmaterialオブジェクトの場合、以下のようにする
returnKeys = Object.keys(pm.response.json()[0].material)

Sendボタンを押下してリクエストを送信してから、Test ResultsタブでPASSかFAILと返却される結果、Consoleタブで表示される通知メッセージを確認します。

パターン１：expectedKeys配列とreturnKeys配列との要素が全然同じ、すなわち、APIから返却されたパラメータと設計書に記載されるパラメータに過不足がない場合、以下の通りとなります。
・Test Resultsタブ：PASSと表示
・Consoleタブ：下記のメッセージ表示
"The parameters returned from the API match those described in the specification."

パターン２： expectedKeys配列に同じ名前の要素が含まれている場合、以下の通りとなります。
・Test Resultsタブ：FAILと表示
・Consoleタブ：下記のメッセージ表示
"The expectedKeys array contains elements with duplicate names, such as: {the same name element}. Please check again."
→ この場合においては、 expectedKeys配列から重複した要素を削除してからAPIを再実行します。

パターン３：APIからは設計書と比べて、過剰なレスポンスパラメータを返却する場合、以下の通りとなります。
・Test Resultsタブ：FAILと表示
・Consoleタブ：下記のメッセージ表示
"Some parameters are being returned in the API response result that are not described in the specification, such as: {parameter name}. Please check again."
→ この場合においては、担当開発者に過剰なレスポンスパラメータを削除するように依頼してください。

パターン４：APIからは設計書と比べて、不足なレスポンスパラメータを返却する場合、以下の通りとなります。
・Test Resultsタブ：FAILと表示
・Consoleタブ：下記のメッセージ表示
"Some parameters that are described in the specification are not being returned in the API response result, such as: {parameter name}. Please check again."
→ この場合においては、担当開発者に不足なパラメータを補足するように依頼してください。

パターン５：APIからは設計書と比べて、過不足なレスポンスパラメータを返却する場合、以下の通りとなります。
・Test Resultsタブ：FAILと表示
・Consoleタブ：下記のメッセージ表示
"Some parameters are being returned in the API response result that are not described in the specification, such as: {parameter name}. Please check again."
"Some parameters that are described in the specification are not being returned in the API response result, such as: {parameter name}. Please check again."
→ この場合においては、担当開発者に過不足なレスポンスパラメータを削除・補足するように依頼してください。

3.参考元

https://learning.postman.com/docs/sending-requests/variables/

https://giangtester.com/category/api-testing/postman/

POSTMANおよびその有益な各機能