GitHub ActionsでPostman + NewmanのAPIテストを実行してみた

はじめに

こんにちは、CX事業本部の木村です。

APIのインテグレーションテストをする機会がありましたので、Postman + NewmanでCLIベースのAPIテストを、GitHub ActionsのCI/CDパイプラインで実行する方法について検証してみました。

今回はお試しなので、テスト対象のAPIのダミーとして、JSONPlaceholderを利用させていただきます。

Postman + Newmanを試してみる

そもそもPostmanとは

API開発のためのコラボレーションプラットフォームです。 Postmanドキュメント

• APIへのリクエストやレスポンスの検証がGUIから容易に行えます
• 認証、テスト、リクエスト前処理などが行えます
• ブラウザやデスクトップアプリケーションから使用できます

過去記事にも大変詳しいものがあります。 [ツール] Postmanを利用したAPIの試験 [機能の紹介] [ツール] PostmanでAPI疎通試験 [試験を実行]

Newmanとは

PostmanにおけるCollection（APIリクエストのグループ）を実行するためのCLIツールです。

ローカルにない場合は、以下のコマンドでインストールできます。

$ npm install -g newman

Newmanドキュメント

Postman + Newmanを試す

それぞれのAPIリクエストをまとめたCollectionという単位があります。まずはそのCollectionを作成します。

次にリクエストを作成します。

今回は単純なGetリクエストを一つ作ります。

「Tests」タブにテストを定義することができます。右側のペインに雛形があるので、それらを選択し編集していくだけで楽にテストを記載できます。

「Send」を押すとリクエストが発行されて、結果が下部に表示されます。基本的なレスポンスを確認できるのに加え、「Test Results」タブには「Tests」で定義したテストの結果が表示されます。

テストがパスしたら、Collectionのタブへ進み、「Export」を選択します。

NewmanでAPIテストを実行します。

$ newman run {exportしたjsonファイルへのpath}

結果は以下の通りとなりました。

newman

GitHubActionsPostman

→ getTask
  GET https://jsonplaceholder.typicode.com/todos/1 [200 OK, 1.22KB, 430ms]
  ✓  Status code is 200
  ✓  Your test name

┌─────────────────────────┬────────────────────┬───────────────────┐
│                         │           executed │            failed │
├─────────────────────────┼────────────────────┼───────────────────┤
│              iterations │                  1 │                 0 │
├─────────────────────────┼────────────────────┼───────────────────┤
│                requests │                  1 │                 0 │
├─────────────────────────┼────────────────────┼───────────────────┤
│            test-scripts │                  1 │                 0 │
├─────────────────────────┼────────────────────┼───────────────────┤
│      prerequest-scripts │                  0 │                 0 │
├─────────────────────────┼────────────────────┼───────────────────┤
│              assertions │                  2 │                 0 │
├─────────────────────────┴────────────────────┴───────────────────┤
│ total run duration: 480ms                                        │
├──────────────────────────────────────────────────────────────────┤
│ total data received: 83B (approx)                                │
├──────────────────────────────────────────────────────────────────┤
│ average response time: 430ms [min: 430ms, max: 430ms, s.d.: 0µs] │
└──────────────────────────────────────────────────────────────────┘

非常に簡単に設定ができました。

PostmanからCollectionを取得する

Collectionの定義をファイルとして保存して取り回してもいいのですが、チーム開発の場合を考えると更新のタイミング等で齟齬が発生しそうです。なので、CLIから常に最新版を取得できるようにします。

まずはPostman Api Keyを取得します。

次にCollectionのidを取得します。これはCLIから実行します。

curl https://api.getpostman.com/collections?apikey={ api key } | jq '.collections[] | select(.name == "{ Collection名 }") | {"name": .name, "id": .id}'

Collectionのidを用いてCollection定義を取得

curl https://api.getpostman.com/collections/{ 上で取得したcollectionのid }?apikey={ api key }

これで最新版のCollection定義をCLI経由で取得できるようになりました。

GitHub Actionsで動かす

上記で準備は整ったので、GitHub Actionsを設定していきます。

テンプレート定義

repositoryのルートに.github/workflows/{任意のファイル名}.yamlを作成します。

name: aws-deploy


on:
  push:
    branches:
        - master
jobs:
  aws_cdk:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v1

      - name: Setup Node
        uses: actions/setup-node@v1
        with:
          node-version: '14.x'

      - name: newman install
        if: contains(github.event_name, 'push')
        run: sudo npm install -g newman

      - name: setup
        if: contains(github.event_name, 'push')
        run: curl https://api.getpostman.com/collections/$POSTMAN_COLLECTION_ID?apikey=$POSTMAN_API_KEY > api.json
        env:
          POSTMAN_API_KEY: ${{ secrets.POSTMAN_API_KEY }}
          POSTMAN_COLLECTION_ID: ${{ secrets.POSTMAN_COLLECTION_ID }}

      - name: E2E Tests
        if: contains(github.event_name, 'push')
        run: newman run ./api.json

      - name: Cleanup
        if: always()
        run: rm -f ./api.json

GitHubにSecrets登録

GitHub Actionsを設定するリポジトリの「Settings」から「Secrets」を選択して、「New repository secret」を押下してSecretsを登録します。

「PostmanからCollectionを取得する」のところで取得した2つの値を以下の名称で登録します。

• POSTMAN_API_KEY
• POSTMAN_COLLECTION_ID

GitHubのSecretsについて、詳しくは公式ドキュメントをご参照ください。

確認

ここまで設定できたら、あとはmasterブランチにpushすればworkflowが開始されます。

まとめ

Postmanで作成したAPIテストをGitHub ActionsのCI/CDパイプラインで実行する方法を書いてみました。

今回は非常に簡単なシナリオだったため触れていませんが、認証についてもBasic認証, AWS Signature V4, API Keyなど多くのオプションが用意されています。また、Collectionの中には複数のAPIリクエストを含めることができます。これらにより複雑なAPIテストのシナリオを組むことができます。

また、Workspaceなどの機能を使用して、チームで開発することも簡単そうです。

結構手軽に設定が可能なのに、十分に応用も効きそうなので折を見てプロジェクトで導入してみたいと思いました。