[ツール] Postmanを利用したAPIの試験 [機能の紹介]

こんにちは。こむろ＠北の大地です。関東の方はそこそこ暑く梅雨にも突入したと聞きますので、しばし札幌の爽やかな写真をお楽しみください。

上から、北大、限定のサッポロクラシック、夜の赤れんが庁舎、おまけのリゾッテリア ガクの美味しいトマトリゾット（チーズ焼きをプラス）

はじめに

皆さんはAPIの試験をどのように行ってるでしょうか？

Webサービス？単体のアプリを使って？それともスクリプトを自前で書いて？

今回関わっている案件で Posmtan を利用して、APIの疎通確認や負荷テストを実行しました。なかなか良く出来たサービスだったたので、どのような機能を持っているか、どのように利用できるかを軽くご紹介します。

Postman

Postmanは、Web APIのテストクライアントサービスのひとつです。色々なクライアントの動きをテストできるようスクリプト拡張や、テストスイートシナリオの作成などの機能があります。これらの機能を使うことで、 ユーザーのOAuth認証 〜 アクセストークン取得 〜 ユーザーの新規登録 〜 ユーザー情報取得 〜 ユーザー情報の更新 〜 ログアウト 〜 ユーザー退会処理 というような一連のAPIの流れを、様々なケースを、状態を維持しながら一度に実行することができます。

クライアントにChrome AppとMacアプリが用意されています。

こちらはChrome App版

特にOAuthでのトークンのやりとりや、リダイレクトなどにも対応している点で、今回の案件にとてもマッチしており、簡単にリグレッションテストを含めて様々な試験を実施することができました。

様々な変数セットを保存して適宜切り替えて実行できるところも非常に優れており、ローカルサーバーへ対するテスト、ステージングサーバーへ対するテストもわざわざコードを書き直す必要はなく、変数セットを切り替えるだけで簡単にテスト対象を切り替えることができたのは、とても助かりました。

有料版

有料版は、シナリオや変数セットを自動的にSyncし、メンバー間で共有できる機能があります。そのため、ステージングサーバーの他に本番環境向けの変数セットが追加された場合なども、アプリケーションが自動的に同期を取ってくれるため、チームメンバーであれば誰でも、常に最新の環境でテストが実行できます。

機能

基本的な機能のみご紹介していきます。

テスト

APIの接続情報を定義します。

• HTTPメソッド: HTTPメソッドを選択。GET/PUT/POST/DELETE/HEAD/PATCHなど一通り揃ってる感じです。
• URL: APIのURLを記載する。後述する 変数 を指定することも出来るため、ホスト部分を変数化しておくと、変数セットでステージングサーバー向け、ローカル向けなど切り替えることが出来ます。
• Params: URLパラメータを設定するKey-Valueの形で設定すると自動的にURLを生成してくれます。
• Send: APIを実行
• Save: 設定したAPIの接続情報を名前と共に保存します。

HTTPメソッドの選択肢はこちら (ワーオ、多いな。そして知らないメソッドがたくさんある・・・)

Authorization

ここでは認証方式を選択することができます。Basic認証からOAuthなどまで様々対応しています。

選択すると、それぞれ必要な情報を入力する項目が現れます。試しにBasic認証を選択してみましょう。ユーザー名とパスワードを入力する欄が出現します。

Headers

ヘッダ情報を入力する箇所です。カスタムヘッダの値などを定義している場合はこちらに入力します。

keyにヘッダの項目名、valueに設定する値を入力します。

• Bulk Edit: Key-Valueの形での登録ではなくプレーンなテキストとしてヘッダ情報を入力することができます。
• Presets: ヘッダ情報のプリセットを利用する場合はこちらから選択します。プリセットを追加することで複数のヘッダ情報をまとめて管理しておけば、テストケースを作成する際に便利です。

Body

ボディ情報を入力します。こちらはGETやHEADなどはボディ情報を持たないので選択できません。POSTやPUTを選ぶとタブが有効になります。ポチッとね

• form-data: いわゆるKey-Valueの値をボディに持つための入力を行うことができます。こちらは後ろにフォーマットの選択肢が出てきますので、決められた任意の型のValueを送ることができます。
• x-www-form-urlencoded: UrlEncodeされたテキスト文字列をValueに持つ、Key-Valueの値をボディに持つことができます。この場合、Content-Typeは自動的にapplication/x-www-form-urlencodedが入力されてリクエストが作成されます。
• raw: プレーンなテキスト入力領域が現れます。こちらに任意の型（JSONやらTextやらXMLやら）で情報を入力し、適切な型を選択してやることで、Content-Typeが自動的に入力されリクエストが作成されます。今回のスクリーンショットはJSONで作成してみました。きちんとコードがハイライトされるのでとても分かりやすいです。
• binary: バイナリ情報を入力する際に利用します（一度も利用したことありません＞＜）

Pre-request Script

リクエスト実行前に実行されるスクリプトです。javascriptが実行できます。ここでは変数セットに定義されている変数へ値をセットすることができます。コードの書き方などは右の方にあるSnippetのリンクを押してみると、いくつかのサンプルコードが挿入されます。

例えば今回はユーザーの新規登録時に重複のないメールアドレスを生成する必要があったため、こちらでランダムな値のメールアドレスを作成するようにしてみました。

postman というオブジェクトを介して、変数へアクセスするようです。

• variable_keyに変数名を
• variable_valueに設定したい変数の値を

コードで入力します。

ランダムなメールアドレスで新規ユーザー登録したい

このような場合は、以下の様なコードを記述すると良いでしょう。

objDate = new Date();
postman.setEnvironmentVariable("email", "hogehoge+"+objDate.getTime()+"@gmail.com");

現在日時情報を利用したランダムなメールアドレスの作成コードになります。1ms以下の間隔で実行したり、同時に並列して走らせた場合重複する可能性がありますが、APIの疎通試験などを行う場合はこのようなもので充分かと思います。

ご存知かとは思いますが、Gmailの場合`+`以降の値を任意で付与することが可能です。`+`以降にランダムな値を与えても、このコードでは`hogehoge@gmail.com`宛にメールが届くはずです。そのため、ユーザー情報登録後にきちんとメールが届いたことを確認したい場合など、このように同じメールアドレスを利用しながらも、重複のないメールアドレスを作成することがあります。

Tests

レスポンスの検査を行うコードを記載する箇所になります。こちらも前述した Pre-request Script と同様にjavascriptが記述できます。

Pre-request ScriptよりSnippetのリンク数が多いですね。レスポンスをパースしたりできるようになっています。

レスポンスをパースしてJSONオブジェクトを取得する

以下のコードでレスポンスをJSONへ変換が可能です。レスポンスボディはresponseBodyという変数で参照できるようです。

var jsonData = JSON.parse(responseBody);

テストコードの記述について

右のSnippetの中から Status code: Code is 200 を選んでみましょう。以下の様なコードが追記されます。これはHTTPステータスコードが200であることを検証するテストコードです。

tests["Status code is 200"] = responseCode.code === 200;

文法は tests[テストの説明] = <テスト内容>; という形で記載ができるようです。他にもSnippetがあるので確認してみます。

tests["Status code name has string"] = responseCode.name.has("Created");

上記のコードは Status code: Code name has string をクリックした時に追記されたコードになります。こちらもレスポンスコードの検証ですね。Createdという文字列が存在するかを検証しています。

レスポンスで取得した情報を変数に格納する

Testsは、レスポンス後に実行されるセクションです。そのため、ここでレスポンスを解析し、変数へ入力することも可能です。変数の入力方法については、前述した Pre-reqeust Script で紹介したものと同じコードが利用できます。レスポンスのJSONを解析し、変数へ入力するコードを記述してみます。

var jsonData = JSON.parse(responseBody);
postman.setEnvironmentVariable("userId", jsonData.hash_id);

レスポンスボディには以下の様なJSONが返却される想定です。

{
 "hash_id" : "BOijewer029u3ga8dhfl2i3jrsA"
}

変数userIdに入力しています。テストと並行して記述すると以下の様な形でしょうか。

var jsonData = JSON.parse(responseBody);
postman.setEnvironmentVariable("userId", jsonData.hash_id);

tests["Status code is 200"] = responseCode.code === 200;

これで、この試験が通過した後は userIdに何らかの値が入った状態が保持されます。

変数セット(Environment)

先ほどから「変数セット、変数セット」連呼しているのですが、こちらの機能を紹介しないわけにはいきません。初めの方で説明したように変数を切り替えることで、様々な環境へ切り替えることができます。さらに環境によってCredentialの値なども異なるでしょうから、そういったものを Environment というグループで保存することができます。環境と呼ぶべきなのかもしれませんが、個人的に変数セットの方がなんとなくしっくりきてるので勝手にそう呼んでいます。

アプリケーションの上右部に Environment を選択する箇所が見えます。クリックしてみると定義してある変数セットがずらずらと表示されます。

ここで変数セットを切り替えてあげると、セットの中の変数にごっそり入れ替わります。

Manage Environments

変数セットを追加、作成、共有、削除を行うことができます。JSONの形でExportすることも可能です。

• Environments: 変数セット名称でリンクになっています。こちらをクリックすると、変数セットの編集画面になります。
• Share: 共有ボタンになります。有料版であればこちらの変数セットを共有することができますが、トライアル期間が過ぎた後のユーザーは実質利用できません。
• Duplicate: 四角っぽいアイコンが2つ並んでいるのが、複製ボタンです。同じ変数セットをコピーして複製します。変数がすごい数ある時にこちらは便利ですね。値だけを変更すれば良いのですから。
• Download: 矢印下向きのアイコンはダウンロードボタンになります。JSONでダウンロードすることができます。変数セットは基本的にURLでの共有などは許されていません。必ずダウンロードするか、Postmanの共有機能を利用しなければなりません。これは恐らくCredential情報などそれなりにクリティカルな情報を含んでいるからかと想像されます。
• Remove: ゴミ箱アイコンは、見ての通りですが変数セットの破棄です。

実際の使い方：ホスト名を環境によって切り替える

APIの場合、開発用のローカル環境、サーバー試験環境のステージング環境、さらに本番用のプロダクション環境など、様々な環境を利用するかと思います。ここではホスト名を切り替えることで、環境の切り分けを行っていることを想定して、ホスト名を変数セットの変数のひとつとして定義してみます。

まずはローカル環境を作ってみましょう。memberhost という名称でホスト名を設定しました。

このままでは変数が切り替わってもどこからも参照されていないので、APIのホスト名を変数の値を参照するように修正します。URLを以下のように修正します。

このように記述することで、変数セットを切り替えるだけでローカル、ステージング、プロダクションをスムーズに切り替えながら、同じテストを何度も実行することができます。

テストの実行

テストを実行してみましょう。 Send ボタンをぽちっと押します。

レスポンスが返却されテストが実行されると、結果が表示されます。

認証が必要なAPIに対してアクセストークンの取得を実行する前に、実行してみました。HTTPステータスコード４０１が返却されているため、HTTPステータスコード２００と比較するテストに失敗しているようです。何が失敗したのか、リクエストやレスポンスの詳細情報、はたまたCookie情報まで一通りこの画面で確認することができます。

まとめ

まずは機能を一通りざっと紹介しました。ここまでの機能でひとまずAPIへのリクエストは作成出来るかと思います。次回は、テストケースをまとめて順番に実行するためのCollectionや、CLIで実行できる newman を中心に紹介を行っていきたいと思います。

参照

• Postman - Introduction