Postman + GitHub Actions で QAエンジニアが一からAPI テストを完全自動化した話

ヤプリでQAエンジニアをしています、ぐっさんです。

突然ですが、API テストの運用どうしていますか？

弊社ではAPIのテストをPostmanを使い手動実行しているのですが、観点は都度違えど手順が不変であり自動化移行しやすい状態でした。そこで今回、Postmanから手動で叩くだけの運用から脱却し、GitHub Actions + Newman を使って「何もしなくても月曜朝にテスト結果が Slack に届く」環境を構築しました。

今後、API テストの自動化を検討している方に向けて、技術選定、実装のハマりどころや技術的な工夫を紹介させていただきます。

技術スタックと選定理由
実装のポイント
GitHub Actionsからの定期実行へ
導入後の所感と次のステップ
まとめ

技術スタックと選定理由

そもそもなぜCIツールとしてGitHub Actionsを採用したのかですが、単純にいえば視覚的に理解しやすく、導入や学習にほとんどコストが掛からなかったのが一番の要因として大きいです。別プロジェクトではテスト自動化のCIツールとしてJenkinsを採用しているのですが、Jenkins はプラグインの柔軟性が高い一方で、サーバーの運用保守コストがかかります。他のQAメンバーも慣れたツールではあったものの、寧ろ新しいCIツールに触れて次に技術選定する際の選択肢として幅を広げるにもいい機会だったので、テスト自動化のCIツールとして初めてGitHub Actionsを選定しました。

また、ワークフローを YAML ファイルとして「コードで管理（Configuration as Code）」でき、リポジトリと密結合しているため、「テストスクリプトの変更と CI 設定の変更」を一気に行えるのが最大の強みを持っていることも、今回の技術選定で調べていくうちに学ぶことができました。

実装のポイント

技術選定が完了したところで、早速実装です。今回APIテストの自動化のために使用したのは以下のツールです。

Postman：テストスクリプト（JSON）の作成
Newman：Postmanのテストをコマンドラインで動かすエンジン
GitHub Actions：定期実行を行うCIツール
act (Docker)：自分のPCでActionsを試すための擬似実行ツール
Slack：テスト結果の通知先

今回実装してみてハマりどころやポイントがいくつかあったので、そちらも併せて紹介します。

ディレクトリ構成とパスの解決

まず、テストケースや実際GitHub Actionsで実行するためのYAMLを整理します。ディレクトリ構造に関しては、今後メンテナンスがしやすいように、以下のような構造を採用しました。

.
├── .github/workflows/postman_test.yml　# YAMLファイル（自動化の指示書）
├──   ./environment/　　　　　　　　　　　　# 環境ごとの変数定義
└──  ./test_case/　　　　　　　　　　　　　# テストのシナリオ本体

これをすることで、YAML、env、テストシナリオごとで管理できるため、テストケースの随時追加などメンテナンスがしやすくなります。また、GitHub Actions の Runner はリポジトリのルートを基準に動作します。 Newman 実行コマンドを書く際は、この構造に合わせてパスを指定します。

▼YAMLの例

# 1. ワークフローの名前（GitHubのActionsタブに表示される名前）
name: API Automation Test

# 2. いつこのテストを実行するか（トリガー）の設定
on:
  # 定期実行の設定
  schedule:
    # cron形式: 分 時 日 月 曜日 (UTC時間)
    # 日本時間(JST)の「月曜 朝9:00」は、世界標準時(UTC)では「月曜 0:00」となります
    - cron: '0 0 * * 1'
  
  # GitHubの画面から手動で「実行ボタン」を押せるようにする設定
  workflow_dispatch:

# 3. 具体的に実行する処理の内容
jobs:
  # ジョブの名前（任意。ここでは「api-testing」としています）
  api-testing:
    # 実行環境のOS（最新のUbuntu Linuxを使用）
    runs-on: ubuntu-latest

    # 実行する手順（ステップ）を順番に書く
    steps:
      # 【ステップ1】リポジトリのコードを仮想マシンにコピーする
      # これをしないと、フォルダ内のJSONファイルが読み込めない
      - name: Checkout repository
        uses: actions/checkout@v4

      # 【ステップ2】Node.js 実行環境をセットアップする
      # Newmanを動かすために必要
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20' # バージョン20を使用

      # 【ステップ3】Newman（Postman実行ツール）をインストールする
      - name: Install Newman
        run: npm install -g newman

      # 【ステップ4】実際にテストを実行する
      # -e で環境変数ファイルを指定し、その後にコレクションファイルを指定します
      - name: Run Postman Tests
        run: |
          newman run ./test_case/openapi_testcase.postman_collection.json \
          -e ./environment/openapi_test.postman_environment.json \
          --reporters cli

# (既存の Newman 実行ステップのあとに追加)
      
      - name: Slack Notification
        uses: rtCamp/action-slack-notify@v2
        if: always() # テストが失敗しても必ず実行する
        env:
          SLACK_WEBHOOK: ${{ secrets.SLACK_WEBHOOK_URL }} #セキュリティのため、Webhook URLなどの機密情報は GitHub Secrets に登録する
          SLACK_TITLE: APIテスト結果
          SLACK_COLOR: ${{ job.status }} # 成功なら緑、失敗なら赤に自動で変わる
          SLACK_MESSAGE: 'NewmanによるAPIテストが完了しました。ステータス: ${{ job.status }}'
          SLACK_USERNAME: GitHubポッド

今回はあえてシンプルな --reporters cli を採用しました。これにより、GitHub Actions の実行ログ（Console）上に直接、Postman でおなじみのテスト結果テーブルが表示されます。特別なツールを介さずとも、ログを見れば「どのテストが通ったか」が一目瞭然です。

世界標準時（UTC）と日本時間（JST）の罠

schedule イベントの cron は UTC（世界標準時）で動作します。

on:
  schedule:
    # 日本時間 月曜 AM 9:00 = UTC 月曜 AM 0:00
    - cron: '0 0 * * 1'

「月曜朝にやりたいのに、設定をミスして月曜夜に走ってしまった」というミスを防ぐため、コメントに JST の時間を併記しておくのがチーム運用のコツです。

actとDockerを利用したローカルでの試験実行

実装した内容をGitHub Actionsで実際に動かしてみる。

もちろんそれでもOKですが、「YAMLを書き換えては Push して失敗を確認する」というのは非効率です。そこで、これを解決するために、ローカル環境で GitHub Actions を擬似実行できるツール actとDockerを使い事前検証を実施しました。

導入することで、自分の PC 上に Docker コンテナ（GitHub Runner の模倣）を立ち上げ、YAML を実行することができます。

Slack 通知の高度化

定期実行の結果をActionのログ画面を見にいく必要はなく、Slackで通知できるようにも構成しました。また、単純な通知だけでなく、if: always() を使って「失敗した時こそ確実に通知を飛ばす」ように設計しました。

- name: Slack Notification
  uses: rtCamp/action-slack-notify@v2
  if: always() # 成功・失敗に関わらず実行
  env:
    SLACK_WEBHOOK: ${{ secrets.SLACK_WEBHOOK_URL }}
    SLACK_COLOR: ${{ job.status }} # success=緑, failure=赤に自動着色

成功時の結果だけでなく、失敗時も通知することで不具合についてもすぐさま検知できるような仕組みを構成しました。

GitHub Actionsからの定期実行へ

ローカルでの試験実行を経て、いよいよGitHub Actionsからの実行を試みました。

導入後の所感と次のステップ

今回の場合はあくまでも手動で実施していたAPIテストを自動化したにすぎず、まだ実装されているケース数が少なく試験運転段階なので、工数削減の実績を出せているわけではありません。ですが、毎週月曜日の朝にSlackに自動でテスト結果が流れてくるだけでもAPIの不具合を定期で検知できる心理的安全性を保証できるなと感じました。

環境構築が完了したので、次のステップとしてはクライアントに提供しているOpenAPIをすべて自動テストへ移行し、リグレッションテストとして検証環境で毎週定期実行を実施することを目標に実装を進めていきたいと考えてます。

まとめ

私もQAエンジニアとしての歴が長く、実際にソースコードを書いたり修正する技術を習得するのに時間を要してしまい、「自動化は面倒」というイメージに直結することが過去にもありました。

しかし、現在ではAIの力も借りてコードの実装はもはや事前知識が不要な段階まで進んでいます。（もちろん、出力されてきたものを理解をしなくてはいけませんが）

また、今回選定したGitHub Actions なら YAMLを設定するだけでよく、コード実装経験の少ない私でも簡単に導入できた手応えを確かに実感できました。同じくAPIテストの自動化について悩まれている方は、まずは手元の Postman コレクションを act で動かすところから始めてみてはいかがでしょうか？

Yappli Tech Blog

株式会社ヤプリの開発メンバーによるブログです。最新の技術情報からチーム・働き方に関するテーマまで、日々の熱い想いを持って発信していきます。