API テストは、使えるツールが cURL しかなかった頃と比べて大幅に進歩しています。 現在では、Postman の使いやすいインターフェイスで簡単にリクエストを作成し、E2E (エンドツーエンド) テストを快適に行えるようになりました。 Postman はあらゆる機能が備わったコラボレーション プラットフォームであり、API の開発とテストにお勧めです。
このチュートリアルでは、Postman の概要や Postman のコマンドライン ユーティリティである Newman を使用して API テストを実行する方法と、このテストを自動化する方法について説明します。
Postman とは？
Postman とは、APIを開発・テストするためのコラボレーションプラットフォームです。Postmanでは、Tokenなどを設定し、APIのエンドポイントにリクエストを投げ込めば Response（レスポンス）を確認することができます。現在 Postmanには、HTTP や REST、SOAP、GraphQLなどのリクエストテストや、API design、API documentation、API detection、Mock Server、Monitors、Workspaces などの機能が存在します。Postmanを利用することによってAPI開発が簡略化され作業効率の向上を実現することができます。
前提条件
このチュートリアルを進めるには、いくつかの準備が必要です。
- JavaScript の基礎を理解する
- デスクトップ版 Postman をシステムにインストールする (ダウンロードはこちら)
- CircleCI アカウントを用意する
- GitHub アカウントを用意する
今回は、こちらの記事で開発およびデプロイ済みの API をテストします。 これは、ユーザー アカウントの作成用エンドポイントとフェッチ用エンドポイントで構成されたシンプルな Node.js API です。 前述の記事では、この API を https://my-adonis-api-app.herokuapp.com というアドレスにデプロイしました。 こちらにあるソース コードを、記事 (段落冒頭のリンク) の手順に従ってデプロイしてください。
すべてのインストールとセットアップが済んだら、チュートリアルを始めましょう。
Postman の環境をセットアップする
API テスト用の自動テスト パイプラインをセットアップするには、Postman で環境を作成する必要があります。 環境のスコープを設定しておくと、ポストマン全体や環境間での変数の衝突を防止できるので、おすすめです。
デスクトップ版 Postman を開きます。 インターフェイス右上隅にある [Manage Environments (環境の管理)] 歯車アイコンをクリックします。 [Manage Environments (環境の管理)] ダイアログで [Add (追加)] をクリックします。
注: Postman の UI は、チュートリアルのスクリーンショットとは若干異なる場合がありますが、必要なツールは説明のとおりの場所にあります。
[Add Environment (環境の追加)] ダイアログで、環境の名前を入力します。
以下のように、環境変数 api_url を入力します。 API のベース URL として https://cci-gwp-adonis-api.herokuapp.com と入力します (末尾のスラッシュなし)。 [CURRENT VALUE (現在の値)] には、[INITIAL VALUE (初期値)] の値がコピーされます。 このチュートリアルでは、これらの値は同一のままにしてください。
[Add (追加)] をクリックして、新しい環境を作成します。 インターフェイス右上のドロップダウンで、作成した新しい環境を選択します。
API テスト用に Postman コレクションを作成する
次のステップは、テストする API のユーザー エンドポイント用に Postman のコレクションを作成することです。 Postman のコレクションとは、API リクエストのコンテナのようなものです。 一般には、特定のエンティティに関連するリクエストをグループ分けするために使用します。
新しいコレクションを作成するため、インターフェイスの左サイド バーにある [Collections (コレクション)] タブをクリックします。 次に、[New Collection (新規のコレクション)] をクリックします。
[New Collection (新規のコレクション)] ダイアログで、作成するコレクションの名前を入力します (今回は Users)。 コレクションには、用途を把握しやすいように説明をつけることもできます。
[Create (作成)] をクリックしてコレクションの設定を完了します。 新しいコレクションが、[Collections (コレクション)] タブの下の左サイド バーに表示されます。
コレクションにリクエストを追加する
これで、コレクションにリクエストを追加できるようになりました。 今回のテスト対象の API は、2 つのエンドポイントで構成されています。
{{api_url}}/user/get(GET): ユーザー プロファイルのリストをフェッチします。{{api_url}}/user/create(POST): 新しいユーザー プロファイルを作成します。
新しいリクエストを追加するために、下図のとおりコレクションの横に表示されるフライアウト メニューをクリックします。
[Add requests (リクエストの追加)] をクリックします。 {{api_url}}/user/get エンドポイントへのリクエストを下図のとおり作成し、[Save to Users (Users に保存)] をクリックします。 Users には、先ほど作成したコレクションの名前が入ります。
新しいリクエストのタブが一覧に加わりました。 現在の環境用に作成した api_url 変数を使用して、アドレス バーにリクエストのエンドポイントを入力します ({{api_url}}/user/get)。 リクエストのメソッドとして [GET] を選択します。 下図のようにリクエストを実行します。
Postman からユーザーの配列が返されます。 [Save (保存)] をクリックします。
今度は、{{api_url}}/user/create エンドポイントへのリクエストを下図のとおり作成します。 これは POST リクエストであり、username、email、password が必須です。
リクエストの保存をお忘れなく。
API リクエストのテストを作成する
準備が完了したので、テストをいくつか追加しましょう。
左サイド バーで {{api_url}}/user/get リクエストが選択されていることを確認してください。 選択されていない場合は、このリクエストをクリックして選択してください。 [Tests (テスト)] タブをクリックして、以下のとおり入力します。
pm.test("リクエストはステータス コードが 200 で成功", function () {
pm.response.to.have.status(200);
});
pm.test("配列が返されるかテスト", function () {
var jsonData = pm.response.json();
pm.expect(jsonData).to.be.an("array");
});
今追加した Postman のテストは、Chai アサーションです。
上記コードの最初のテストでは、リクエストがステータス コード 200 で無事に完了するかどうかを確認しています。 2 つ目のテストでは、リクエストから返されたデータが配列であるかどうかを確認しています。このチュートリアルでは、ユーザー プロファイルの配列が返されるはずです。
またリクエストを保存して実行しましょう。 合格したテストの情報が [Test Results (テスト結果)] タブに表示されます。
次に、{{api_url}}/user/create エンドポイントへの POST リクエストについてのテストを追加します。 このエンドポイントのテストは、先ほどのテストよりも複雑です。 この API では、リクエストの username と email パラメーターについて重複確認を実施するためです。 パラメーターをハードコーディングしてしまうと、2 回目以降のリクエストが必ず失敗することになってしまいます。
こうした場合でも、Postman の Pre-request Script (プレリクエスト スクリプト) を使用すれば問題ありません。 プレリクエスト スクリプトは、リクエストの送信前に実行されます。 このスクリプトを使って、リクエスト用にランダムなユーザー名とメール アドレスを動的に生成しましょう。
リクエストをクリックして読み込み、[Pre-request Script (プレリクエスト スクリプト)] タブをクリックします。 以下のスクリプトを追加します。
let random = +new Date();
pm.globals.set("username", `${random}-user`);
pm.globals.set("email", `${random}-user@test.com`);
上記のスクリプトでは、リクエストの送信の度に、現在のタイムスタンプを使用してランダムなユーザー名とメール アドレスを作成します。 ランダムな username と email は、リクエスト インスタンスのグローバル変数として設定しています。 リクエスト本文の username と email を、下図のように動的な値に置き変えてください。
これで、リクエストごとに、username と email で動的パラメーターが使用されるようになりました。 このリクエストの [Tests (テスト)] ウィンドウに、以下のコードを追加します。
pm.test("ユーザー作成が成功", function () {
pm.expect(pm.response.code).to.be.oneOf([200, 201, 202]);
});
pm.test("応答メッセージを確認", function () {
var jsonData = pm.response.json();
pm.expect(jsonData.message).to.eql("User Successfully created");
});
上記コードの最初のテストでは、ステータス コードが 200、201、202 であれば応答が成功したとみなします。 つまり、POST リクエストの成否を判断します。 2 つ目のテストでは、返された json 応答のメッセージが、想定される成功メッセージと一致するかどうかを確認します。
リクエストを実行すると、下図のようにテストが成功するはずです。
テスト自動化プロジェクトをセットアップする
ここまでは、Postman の便利な GUI を使用してリクエストを作成してきましたが、このチュートリアルのゴールは、テストの実行とテスト結果の生成を自動化することです。 ここからは、テスト自動化プロジェクトをセットアップしましょう。
まずは、ローカル マシンの任意の場所にプロジェクト用フォルダーを作成します。
mkdir postman-api-testing
リクエストを保存してから、 コレクションのコンテキスト メニューの [Export (エクスポート)] をクリックします。
Users.postman_collection.json という名前のファイルがダウンロードされます。
このチュートリアルで作成した Postman の環境もエクスポートしましょう。 [Manage Environments (環境の管理)] アイコンをクリックし、ポップアップ ダイアログから環境をダウンロードします。 My-Remote-API-Testing.postman_environment.json という名前のファイルがダウンロードされます。
注: ファイル名を変える場合は、一貫性を保つように注意するか、チュートリアル内のサンプル ファイルの名前を変更して使用してください。
これら 2 つのファイルをプロジェクト フォルダーのルートに配置します。
プロジェクトと CircleCI を連携させる
初めに、プロジェクトを GitHub にプッシュします。
次に、CircleCI ダッシュボードの [Projects (プロジェクト)] ページに移動して、プロジェクトを追加します。
[Set Up Project (プロジェクトをセットアップ)] をクリックします。
セットアップ ページで、表示されたサンプルを無視して設定ファイルを手動でセットアップするため、[Use Existing Config (既存の設定ファイルを使用する)] をクリックします。 パイプラインの設定ファイルをダウンロードするのか、ビルドを開始するのかを確認するメッセージが表示されます。
[Start Building (ビルドの開始)] をクリックします。 設定ファイルのセットアップがまだのため、このビルドは失敗します。 これについては、次のステップで実行します。
Newman Orb を使用してテスト プロセスを自動化する
このチュートリアルの最後のステップは、テスト自動化スクリプトを作成することです。 このスクリプトでは、Postman の CLI 版である Newman を使用して、エクスポートした環境でコレクションを実行します。 幸い、CircleCI には Newman 用 Orb があります。 Orb とは、さまざまな定型コードを抽象化したパッケージです。 Orb を使用することで、API で共通のコマンドを呼び出したり、Newman、Heroku といったツールや環境を使用したりしやすくなります。
newman はサードパーティ製 Orb なので、使用するには CircleCI アカウントの設定で許可する必要があります。 このために、お使いの CircleCI アカウントの [Organization Settings (組織設定)] に移動します。 左サイド バーの [Security (セキュリティ)] をクリックします。 ビルドでのサードパーティ製 Orb の使用を許可するため、[Orb Security Settings (Orb のセキュリティ設定)] ページで [Yes (はい)] を選択します。
設定ファイルを作成する
プロジェクトのルートに .circleci という名前のフォルダーを作成し、その中に config.yml という名前の設定ファイルを追加します。 このファイルに、以下のコードを貼り付けます。
version: 2.1
orbs:
newman: postman/newman@0.0.2
jobs:
build:
executor: newman/postman-newman-docker
steps:
- checkout
- newman/newman-run:
collection: ./Users.postman_collection.json
environment: ./My-Remote-API-Testing.postman_environment.json
上記のスクリプトでは、newman/newman-run コマンドを呼び出して、Postman の Newman Orb を読み込み、指定した environment で collection を実行しています。 シンプルですね。
変更をコミットしてからリモート リポジトリにプッシュし、パイプラインのビルドをトリガーしましょう。
テスト結果を確認するために、ビルドをクリックして、[Test (テスト)] タブを展開します。
想定どおり、Newman がコレクションを実行し、その後テストの実行の詳細に関するレポートが生成されています。
うまく行きましたね！
まとめ
テスト プロセスを手動で処理していると、すぐに複雑化し、ミスが起こりやすくなってしまいます。 Postman の GUI は、API 開発者ならば必須のツールキットとなっています。 このチュートリアルでご紹介したとおり、CircleCI の自動パイプラインと newman Orb を活用すれば、API テストのプロセスをさらに発展させることができます。
Happy coding！
