青色が好きな高橋です。現在はAWSを使った自社プロダクトの運用管理システムの開発を行っています。
PostmanというGUIのツールを用いてAPIテストを作成し、それをCI/CDへ組み込み自動化する作業を行いました。Postmanを使うことで、APIを簡単に作成、検証、ドキュメント化できて非常に便利だったので、この記事でご紹介いたします。
本記事では、Postmanの概要とPostmanのコマンドラインユーティリティであるNewmanを使用してAPIテストを自動化する方法について説明します。チュートリアルも用意しているので実際に手を動かしながら理解を深めていただける記事になっています。
読了時間は20分、チュートリアルは60分程度で完了できる内容となっています。
目次
- 本記事の概要
- 本記事の対象者
- 本記事の概要
- Postmanについて
- Postmanの概要
- Postmanの基本的な使い方
- チュートリアル①：PostmanでAPIテストを試してみよう
- 簡単なテストを試してみよう
- データ駆動型テスト（DDT）を試してみよう
- チュートリアル②：CI/CDに組み込んでみよう
- まとめ
記事の概要
本記事ではPostmanとNewmanを利用してCI/CD（GitHub Actions）に組み込み、APIテストを自動実行するところまで行います。また、Postmanを全く知らない方でも実施できるように、Postmanの基本的な使い方も説明しています。
本記事のチュートリアルで紹介したコードはGitHub(https://github.com/takuto-takahashi/postman-tutorial)にアップしていますので必要に応じて参照ください。
本記事の対象者
- Postmanで何ができるか知りたい
- PostmanをAPIテストに活用したい
- APIテストの自動化を検討している
使用するツール群
- Postman
- Newman
- Github
Postmanについて
Postmanの概要
Postmanとは、Postman Inc. が開発している API 開発コラボレーションツールです。API クライアント機能やテスト機能があり、Open API Spec のインポートやPostmanコレクションなどを用いることによって、外部サービスとの API情報の受け渡しも効率的に行うことができます。
Postmanが提供している基本的な機能は下記の表を参照下さい。Postmanを利用するためのクライアントツールはここからダウンロードできます。なお、サインインしないとWorkspase機能等が利用できなくなるので注意してください。
| API Client | REST、SOAP、GraphQLのリクエストを直接実行できます |
| Automated Testing | 自動テスト機能を提供します |
| Design & Mock | Mock Server機能を提供し、エンドポイントとレスポンスをシミュレートし、API の予想される動作をします |
| Documentation | PostmanのAPI定義から自動的にAPI仕様書を生成します |
| Monitors | 定期的にパフォーマンスとレスポンスをチェックし、APIのアップデートや変更のモニタリング機能を提供します |
| Workspaces | チーム間でのAPIの共同開発機能を提供します |
Postmanの基本的な使い方
Postmanでは4階層構成を用意しており、上から順にワークスペース、コレクション、フォルダ（ランコレクション）、リクエストになっています。ワークスペースはチーム間で共有したい単位で分割することが可能です。また、フォルダはなくても構いませんが、フォルダ単位でAPIリクエストの同時実行が可能です。そのため、同時実行する単位でAPIリクエストをフォルダ分けしておくと良いです。
【ワークスペース作成】
新しいワークスペースを作成するには、ヘッダーで[Workspaces]を選択してから、[Create Workspace]を選択します。出てきたポップアップ画面にワークスペース名等の必要事項を記載して、[Create Workspace]を押下します。
【コレクション作成】
新しいコレクションを作成するには、左サイドバーから[Cllections]を選択してから、そのすぐ右にある[+]ボタンを押下します。
【リクエスト作成】
新しいリクエストを作成するには、対象のコレクション、又はフォルダを選択してからそのすぐ右にある[…]ボタンを押下します。そのあと、プルダウンメニューから[Add Request]を選択します。また、 [Add folder]で作成したCollectionの中にフォルダを作り、階層を作る事もできます。
【リクエスト詳細設定】
リクエストの詳細情報を設定するには、対象のリクエストを選択してから、API実行に必要な「メソッドの種類」、「リクエストURL」や「Parameters」を設定することが出来ます。最後に [Send] ボタンをクリックして、API リクエストを実行 します。
| Params | クエリーパラメータ、パスパラメータを指定できます |
| Authorization | Basic認証やOAuth2.0など、リクエストの認証方法を指定できます |
| Headers | Content-TypeやAuthorizationなどのリクエストヘッダーを指定できます |
| Body | リクエストボディーを指定できます |
| Pre-request Script | リクエスト前に実行するJSコードを記載できます |
| Tests | レスポンスの妥当性を検証するJSコードを記載できます |
【インポート/エクスポート機能】
Postmanには、インポート/エクスポート機能が備わっています。CollectionsやEnvironmentの設定ファイル（Postmanコレクション）をJSON形式で丸ごとエクスポートして、 他のPCからインポートすることで同じ環境が再現できます。なお、インポートできるのはPostmanコレクションファイルだけでなく、Swaggerファイルなども可能です。
【その他の機能】
上記で紹介しきれていない機能については、公式のPostman Learning Centerを参照ください。
公式サイト：https://learning.postman.com/docs/getting-started/introduction/
■チュートリアル①：PostmanでAPIテストを試してみよう
簡単なテストを試してみよう
ここからは、実際に手を動かしてPostmanでAPIテストを試してみます。今回はJSONPlaceholderを利用して、簡単なAPIのテストを行います。なお、作成するコレクション名は任意のもので大丈夫です。
【① 環境変数設定】
- コレクションを作成＆選択
- [Variables]タブを選択
- 以下の環境変数情報を入力
- 変数名： baseUrl , 値： https://jsonplaceholder.typicode.com
【② APIリクエスト情報の設定＆実行】
- リクエストを作成＆選択
- メソッドタイプとして「GET」を選択
- 以下のURLを入力
- URL： {{baseUrl}}/posts/:id*1
- [Params]タブを選択
- 以下のパスパラメータを入力*2
- パスパラメータ名： id , 値： 1
- [Send]ボタンを押下※3
- [Body]タブを選択
- レスポンスを確認
*1 変数を埋め込みたいときは{{変数名}}とすることで認識されます。
*2 パスに「: 変数名」と書くことでパスパラメータとして認識されます。
*3 [Send]ボタンを押下してエラーが出た場合は、①-⑤の設定項目が保存されていない
可能性があります。その際には、「Ctrl」+ 「S」で保存を行ってください。
【③ APIテストの設定＆実行】
- [Tests]タブを選択
- 対象のTest Scriptを選択： Status code: Code is 200*4
- [Send]ボタンを押下*3
- [Test Results]タブを選択
- テスト結果を確認
*4 Testsタブ右側のSNIPPETSには、何パターンか用意されているテストコードの雛形を活用でき ます。
データ駆動型テスト（TDD）を試してみよう
次に外部ファイルからテストデータや環境変数ファイルを読み込んで、APIの正常系と異常系をまとめてテストしてみましょう。まず、本セクションで使用するNewmanのインストールを行います。NewmanはPostmanで作成した処理をCLIから実行するためのツールです。npmでインストールできます。
$ npm install -g newman
【① 環境変数ファイルの作成： env.json】
[
{
"key": "baseUrl",
"value": "https://jsonplaceholder.typicode.com",
"type": "string"
}
]
【② テストデータファイルの作成： test_data.json】
[
{
"id": "1",
"status": 200,
"result": {
"userId": 1,
"id": 1,
"title": "sunt aut facere repellat provident occaecati excepturi optio reprehenderit",
"body": "quia et suscipit\nsuscipit recusandae consequuntur expedita et cum\nreprehenderit molestiae ut ut quas totam\nnostrum rerum est autem sunt rem eveniet architecto"
}
},
{
"id": "999",
"status": 404,
"result": {}
}
]
【③ アクセス先URLとテストコードを変更】
アクセス先URLを以下の通りに変更してください。
{{baseUrl}}/posts/{{id}}
テストコードを以下の通りに変更してください。
pm.test("Status code check", function () {
expectedStatus = pm.iterationData.get("status");
pm.response.to.have.status(expectedStatus);
});
pm.test("Response data check", function () {
expectedResult = pm.iterationData.get("result");
var jsonData = pm.response.json();
pm.expect(jsonData).to.eql(expectedResult);
});
【④ テストコードを実行】
newman runコマンドを実行して、APIテストを実行します。以下のようにコレクション、環境変数ファイル、テストデータファイルをコマンドに渡します。なお、PostmanコレクションファイルはPostmanの概要の【インポート/エクスポート機能】で紹介させていただいたエクスポート機能を使って出力したファイルになります。
$ newman run [Postmanコレクションファイル] -e [環境変数ファイル]
-d [テストデータファイル]
【⑤ テスト結果の確認】
全ての処理が完了すると、テスト結果のサマリに加えエラーがあった場合は詳細が出力されます。
■チュートリアル②：CI/CDに組み込んでみよう
本セクションではCI/CD（GitHub Actions）に組み込んで、APIテストを自動実行してみます。実際の使い方に則して、デプロイ処理の実行が完了してから、APIテストを実行する方法を紹介いたします。参考までにプロジェクトのディレクトリ構成は以下のようにしています。src配下に「3-2 データ駆動型テスト（TDD）を試してみよう」の成果物を入れています*5。今回作成するのは.github配下のworkflowになります。
*5 Tutorial_1.postman_collection.jsonはPostmanから設定ファイルをエクスポートした ものになります。
【APIテスト処理を呼び出す側のワークフロー： deploy_develop.yml】
デプロイ処理は簡略化した仮想上の処理を入れています。needsを設定することで「deploy」ジョブ完了後に「api-test」ジョブを実行させることが出来ます。また、usesを使って「api-test」ワークフローを呼び出すように設定しています。なお、Github Secretsから利用したいシークレット情報がある場合は以下のようにして呼び出し側から渡す必要があります。
name: Auto Deploy
on:
push:
branches:
- "develop"
jobs:
deploy:
name: Deploy
runs-on: ubuntu-latest
steps:
- name: CheckOut
uses: actions/checkout@v2
- name: Deploy
run: echo deploy
# APIテストのワークフローを呼び出し
api-test:
# デプロイ処理完了後にAPIテストを実行する
needs: deploy
uses: ./.github/workflows/api_test.yml
# GitHub Secretsから渡したいシークレット情報
# secrets:
# login_username: ${{ secrets.LOGIN_USERNAME }}
# login_password: ${{ secrets.LOGIN_PASSWORD }}
【APIテスト処理のワークフロー： api_test.yml】
APIテスト実行に必要なNodeとNewmanをインストールした後、APIテスト前処理、APIテスト実行、APIテスト後処理を実施しています。APIテスト前・後処理はDBなどのセットアップやティアダウン処理が行われることが多いと思います。なお、Github Secretsから利用したいシークレット情報がある場合は以下のようにして呼び出し側から渡された値を受け取る必要があります。
name: api-test
on:
workflow_call:
# 呼び出し側から渡されるシークレット情報
# secrets:
# login_username:
# description: ユーザ名
# required: true
# login_password:
# description: パスワード
# required: true
jobs:
api_test:
name: api-test
runs-on: ubuntu-18.04
steps:
- name: CheckOut
uses: actions/checkout@v2
- name: Setup Node
uses: actions/setup-node@v2
with:
node-version: '14.x'
- name: Newman install
run: sudo npm install -g newman
- name: SetUp
if: always()
run: echo Start API testing.
- name: Run API API testing
working-directory: "./src"
run: newman run Tutorial_1.postman_collection.json
-e env.json -d test_data.json
- name: CleanUp
if: always()
run: echo Finish API testing.
■まとめ
いかがでしたでしょうか？意外と簡単にAPIの自動テストが出来ましたね！Postmanには本記事で紹介しきれていない機能もございますので、興味がわいた方は是非公式サイトの方も覗いてみてください。
最後まで読んでいただきありがとうございます。本記事が読者の皆さんの一助となれば幸いです。
あなたもAMBLで働いてみませんか？
AMBLは事業拡大に伴い、一緒に働く仲間を通年で募集しています。
データサイエンティスト、Webアプリケーションエンジニア、AWSエンジニア、ITコンサルタント、サービス運用エンジニアなどさまざまな職種とポジションで、自分の色を出してくださる方をお待ちしています。ご興味のある方は、採用サイトもご覧ください。
●AMBL採用ページ
-メンバーインタビュー （1日の仕事の流れ／やりがい／仕事内容）
-プロジェクトストーリー （プロジェクトでの実績／苦労エピソード）
●募集ページ
プリセールス/ エンジニア/ クリエイター/ データサイエンティスト /営業・コンサルタント /コーポレート /サービス企画 /教育担当
