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

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

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での変数宣言

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

2.1.3 Requestでの変数呼出

ステップ1:Requestファイルを開く
ステップ2: {{variable_name}}形式で変数を呼び出す
ステップ3:Saveボタンを押下

2.2 Consoleウィンドウ

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

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

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

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

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

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

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

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

例4: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 上記のスクリプトの仕組み

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

2.3.2 作業手順

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

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


ステップ3:ステップ2で抽出したレスポンスパラメータ名を上記のスクリプトの1行目の[]にコピー・ペーストする
例:
コピー・ペースト前
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"]

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

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

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

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

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

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

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

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

パターン3: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."
→ この場合においては、担当開発者に過剰なレスポンスパラメータを削除するように依頼してください。

パターン4: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."
→ この場合においては、担当開発者に不足なパラメータを補足するように依頼してください。

パターン5: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/