GitHub ActionsでApidog CLI APIテストを実行する完全ガイド

お使いの環境ではAPIテストがパスします。しかし、チームメイトが変更をマージするとログインエンドポイントが壊れ、顧客がチケットを提出するまで誰も気づきません。テストは存在していました。ただ、重要な局面、つまりマージ前のプルリクエストでは一度も実行されなかったのです。

そのギャップを埋めるのが継続的インテグレーション（CI）です。テストをローカルのターミナルから、プッシュごと、変更ごとに自動的に実行されるパイプラインに移行します。特にAPIテストの場合、これを行う最もクリーンな方法は、既に構築した正確なシナリオを実行し、合否の終了コードを返し、CIがビルドをグリーン（成功）にするかレッド（失敗）にするかを決定できるコマンドラインランナーを使うことです。

ボタン

TL;DR

Apidog CLIはnpmパッケージapidog-cliです。npm install -g apidog-cliでワークフローステップにインストールし、apidog runでシナリオを実行します。
Apidogアプリで設計したテストシナリオをIDで実行します。テストをコードに移植する必要はありません。CLIは認証用のアクセストークンを使用して同じシナリオを実行します。
最小限のGitHub Actionsジョブは、チェックアウト、Nodeのセットアップ、CLIのインストール、apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t <scenarioId> -e <environmentId> -r junit,cliの4ステップです。
アサーションが1つでも失敗すると、CLIはゼロ以外の終了コードで終了します。GitHubはその終了コードを読み取り、チェックを失敗させ、マージをブロックします。それが品質ゲートの全てであり、追加の設定は不要です。
アクセストークンはGitHub Actionsシークレットとして保存し、env:経由で渡します。決してコミットしないでください。
結果をダッシュボードにフィードするには-r junitを、ブラウザで閲覧可能なアーティファクトには-r htmlを使用し、テストが失敗した場合でもレポートが得られるようにアップロードステップでif: always()を使用します。

なぜCIでAPIテストを実行するのか

実行することを覚えていなければ実行されないテストは、信頼できないテストです。シナリオを作成している間はローカルでの実行で問題ありません。しかし、チームが関与した途端に破綻します。なぜなら、各開発者のマシンは微妙に異なり、誰もがプッシュの前にすべてのスイートを完全には実行しないからです。

CIは、実行を自動化し、均一にすることで信頼性の問題を解決します。すべてのプルリクエストは、同じクリーンなランナー上で、同じ環境に対して、同じジョブをトリガーします。エンドポイントが500を返し始めたり、レスポンススキーマがずれたりすると、その原因となったPRでチェックが失敗し、プッシュした人の名前が添付されます。フィードバックは、変更がまだ新しい数日後ではなく、数分後に届きます。

APIテストは、高速で決定論的であるため、これに非常に適しています。シナリオは実際のエンドポイントにアクセスし、ステータスコードとレスポンスボディをアサートし、パスまたはフェイルします。不安定なブラウザはなく、レンダリングを待つ必要もありません。そのため、マージゲートとして理想的です。すべてのPRで実行するのに十分な速さで、悪いPRをブロックするのに十分な決定力があります。CI/CDとは何か、そしてその構成要素がどのように連携するかについての広範な背景を知りたい場合は、CI/CDとは何か、どのように機能するかの入門記事が基本をカバーしています。

Apidog CLIが実際にやること

最も時間を節約できる部分はこちらです。CLIのためにテストコードを書く必要はありません。

リクエスト、アサーション、環境変数、必要なデータをすべて使って、Apidogアプリで視覚的にテストシナリオを構築します。CLIはランナーです。シナリオIDとアクセストークンが与えられると、Apidogプロジェクトからそのシナリオを取得し、アプリが実行するのとまったく同じように、リクエストごとに実行し、すべてのアサーションを評価します。結果はレポートと終了コードです。

この設計はCIにとって重要です。ほとんどのテストランナーは、テストの個別のコード表現を維持するように求めます。その結果、パイプラインで実行するものが、設計したものからずれてしまうことがあります。Apidogでは、パイプラインはチームがアプリで既に維持しているのと同じシナリオを実行します。ビジュアルエディタでアサーションを更新すると、次のCI実行でそれが反映されます。同期を維持するための別のコピーは不要です。

バイナリはapidogで、npmパッケージapidog-cliとして配布されています。すべてのコマンドはapidog runで始まります。ランナーがより完全な自動化ワークフローに組み込まれている様子を見たい場合は、Claude SkillsとApidog CLIを統合したAPIテスト自動化ガイドのウォークスルーがその側面をカバーしています。この記事では、GitHub Actionsパイプラインに必要なフラグに焦点を当てています。

始める前に：必要な3つのもの

ワークフローを実行する前に、3つの情報が必要です。2つはApidogプロジェクトからのID、1つはトークンです。

テストシナリオ。まだ構築していない場合は、Apidogアプリで構築してください。これがCLIが実行するものです。ログインしてプロファイルをフェッチする単一のシナリオで十分です。後で拡張できます。
シナリオIDと環境ID。シナリオIDはCLIに何を実行するかを伝え、環境IDはどこで実行するか（開発、ステージング、本番）を伝えます。どちらもアプリで確認できます。
アクセストークン。これはCLIがApidogアカウントに認証され、シナリオを取得して実行できるようにするためのものです。

これらすべてを一度に取得する最もクリーンな方法は、シナリオのCI/CDタブです。自動化したいテストシナリオを開き、CI/CDタブに切り替え、コマンドラインオプションを選択します。クリックしてアクセストークンを追加し、生成します。Apidogは、アクセストークン、シナリオID（-t）、環境ID（-e）が既に入力された完全なapidog runコマンドを組み立ててくれます。そのコマンドをコピーしてください。それがCIステップの基礎となります。

最初に述べておくべき重要なルールが1つあります。アクセストークンはパスワードのように扱ってください。コミットされたワークフローファイルに貼り付けないでください。GitHub Actionsシークレットとして保存し、環境変数として参照してください。以下のすべての例で$APIDOG_ACCESS_TOKENを使用しているのはそのためです。

ステップ1：アクセストークンをGitHubシークレットとして保存する

GitHubでリポジトリを開きます。Settings（設定）に移動し、Secrets and variables（シークレットと変数）、Actions（アクション）をクリックし、New repository secret（新しいリポジトリシークレット）をクリックします。

Name: APIDOG_ACCESS_TOKEN
Secret: Apidogが生成したトークンを貼り付けます

保存します。これでトークンは保存時に暗号化され、ワークフローの実行時にのみ公開され、ログに表示されることはありません。ワークフローでは、${{ secrets.APIDOG_ACCESS_TOKEN }}として参照し、env:ブロックを通じてCLIに渡します。シナリオIDと環境IDはシークレットではありません。無害なIDなので、ワークフローファイルに直接記述できます。保護が必要なのはトークンだけです。

チームが同じApidogプロジェクトを対象とする複数のリポジトリで作業している場合は、組織レベルでシークレットを一度だけ定義し、関連するリポジトリにアクセス権を付与してください。同じ名前で、更新する場所は1つになります。

ステップ2：最小限のワークフロー

リポジトリに.github/workflows/api-tests.ymlを作成します。これは、mainをターゲットとするすべてのプルリクエストでシナリオを実行する、最小限の有用なワークフローです。

name: API tests

on:
  pull_request:
    branches: [main]

jobs:
  api-tests:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install Apidog CLI
        run: npm install -g apidog-cli

      - name: Run API test scenario
        run: |
          apidog run \
            --access-token "$APIDOG_ACCESS_TOKEN" \
            -t 605067 \
            -e 1629989 \
            -r cli
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}

605067をあなたのシナリオIDに、1629989をあなたの環境IDに置き換えてください。このファイルをコミットし、プルリクエストを開き、Checksタブを確認してください。ジョブはUbuntuランナーを起動し、Node 20をインストールし、CLIをインストールし、シナリオを実行します。すべてのアサーションがパスすれば、チェックはグリーンになります。1つでも失敗すれば、apidog runはゼロ以外の終了コードで終了し、GitHubはチェックを失敗させ、PRには赤いXが表示されます。

この赤いXが重要なポイントです。何かが壊れたことを知るためにログを読む必要はありません。失敗したチェックはプルリクエストに直接表示されます。

インストールステップに関する注意点：グローバルなnpm install -g apidog-cliはシンプルで動作します。ランナーのグローバルパッケージを変更したくない場合は、インストールステップをスキップし、代わりにnpx経由でCLIを呼び出すことができます。

      - name: Run API test scenario
        run: npx apidog-cli run --access-token "$APIDOG_ACCESS_TOKEN" -t 605067 -e 1629989 -r cli
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}

どちらのアプローチも同じシナリオを実行します。npxは一時的なランナーではよりすっきりしますが、グローバルインストールは、実行間でnode_modulesをキャッシュする場合にわずかに高速です。あなたのコーディングスタイルに合う方を選択してください。

ステップ3：実際に読めるレポートを公開する

緑または赤のチェックは結果を伝えます。テストが失敗した場合、その理由を知りたいでしょう。そのためにはレポートが必要です。

-r（または--reporters）フラグはレポート形式を制御します。cli、html、json、junitをカンマ区切りで受け入れます。CIの場合、2つの形式が役立ちます。

junitは標準のJUnit形式でXMLを出力します。ほとんどすべてのCIダッシュボードとテストレポートツールは、これを解析して合否ツリーに変換する方法を知っています。
htmlは自己完結型のレポートを生成し、ビルドアーティファクトとして保存してブラウザで開くことができ、各ステップの完全なリクエストとレスポンスが含まれます。

ビルドログ自体で読みやすい出力を求める場合は、cliも有効にしておきましょう。以下は、両方のレポート形式を生成し、それらをディレクトリに書き込むようにアップグレードされた実行ステップと、実行後もレポートが残るようにするアップロードステップです。

      - name: Run API test scenario
        run: |
          apidog run \
            --access-token "$APIDOG_ACCESS_TOKEN" \
            -t 605067 \
            -e 1629989 \
            -n 1 \
            -r html,junit,cli \
            --out-dir ./apidog-reports
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}

      - name: Upload test report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: apidog-report
          path: ./apidog-reports

これを意図通りに機能させる2つの詳細があります。--out-dirフラグはCLIにレポートの書き込み先を指示します。ここでは./apidog-reportsであり、アップロードステップがそれを取得します。そして、アップロードステップのif: always()が重要な点です。デフォルトでは、GitHubはステップが失敗すると後続のステップをスキップしますが、テストが失敗した場合に最もレポートが必要になります。if: always()は、テストの結果に関係なくアップロードが実行されるように強制します。ジョブが終了した後、レポートは実行概要ページのArtifacts（アーティファクト）の下に表示され、ダウンロード可能になります。

-n 1フラグはイテレーション回数を1回に設定します。シナリオを連続して複数回実行したい場合は、これを増やしてください。

GitHubにJUnitの結果をダウンロード可能なファイルではなく、注釈付きチェックとしてインラインで表示させたい場合は、実行ステップの後にpublished-test-resultsアクションを追加し、./apidog-reports/*.xmlを指すようにします。これにより、XMLが実行に添付された合否の概要に変換され、ログのスクロールが現実的でない大規模なスイートに便利です。

ステップ4：適切なタイミングで適切な環境をテストする

プルリクエストはステージングに対してテストを行うべきです。本番へのデプロイは本番環境に対して検証されるべきです。同じシナリオで両方を行うことができます。-eで環境IDを変更するだけです。

一般的な、持続可能なセットアップでは、1つのワークフローファイルで2つのトリガーを使用します。プルリクエストは、マージゲートとしてステージング環境に対してシナリオを実行します。mainへのプッシュ（マージによって生成されるもの）は、デプロイ後のスモークテストとして本番環境に対して同じシナリオを実行します。

name: API tests

on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

jobs:
  pr-check:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install -g apidog-cli
      - name: Test staging
        run: |
          apidog run \
            --access-token "$APIDOG_ACCESS_TOKEN" \
            -t 605067 \
            -e 1629989 \
            -r junit,cli \
            --out-dir ./apidog-reports
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: staging-report
          path: ./apidog-reports

  prod-smoke:
    if: github.event_name == 'push'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install -g apidog-cli
      - name: Smoke test production
        run: |
          apidog run \
            --access-token "$APIDOG_ACCESS_TOKEN" \
            -t 605067 \
            -e 1730055 \
            -r cli \
            --on-error end
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}

2つの環境ID（ステージング用1629989、本番用1730055）が唯一の大きな違いです。PRジョブはJUnitレポートをビルドしてアーカイブし、レビュアーが失敗を調査できるようにします。本番のスモークテストは、--on-error endを使って無駄を省き、最初の失敗で停止するため、デプロイがうまくいかなかったことを素早く知ることができます。

--on-errorは知っておく価値があります。これは、シナリオ途中でステップが失敗した場合の動作を制御します。endは最初の失敗で実行を停止します（高速フィードバック、スモークテストに最適）。continueは残りのすべてのステップを実行し、1つのレポートですべての失敗を確認できます（徹底的なPRチェックに最適）。ignoreは、既知の不安定なステップをスキップし、実行を中断させません。いずれを選択しても、何かが失敗した場合は実行はゼロ以外の終了コードで終了するため、ゲートはどちらの場合も保持されます。

さらに進む：マトリックス実行、フォルダ、データ駆動型テスト

基本的なゲートが設定されたら、いくつかのフラグを追加するだけで、YAMLをそれほど追加することなく機能を拡張できます。

単一のシナリオではなく、フィーチャーエリア全体を実行します。-t <scenarioId>を-f <folderId>に置き換えてフォルダ内のすべてのシナリオを実行するか、--test-suite <testSuiteId>を使用して厳選されたスイートを実行します。スイートは、特定の順序付けられたシナリオセットを1つの論理ジョブとして実行したい場合に適切なツールです。テストスイートによる自動化APIテストのスケーリングに関するガイドで、いつそれらを使用すべきかがカバーされています。

複数の環境を並行してテストします。マトリックスは、複数の環境IDにわたって同じジョブを一度に実行します。

jobs:
  api-tests:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        env-id: [1629989, 1730055]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install -g apidog-cli
      - name: Run scenario against ${{ matrix.env-id }}
        run: |
          apidog run \
            --access-token "$APIDOG_ACCESS_TOKEN" \
            -t 605067 \
            -e ${{ matrix.env-id }} \
            -r cli
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}

GitHubはマトリックス値ごとに1つのランナーを起動するため、ステージングと本番は同時にテストされ、それぞれが独自の合否を報告します。

データファイルからイテレーションを駆動します。-dフラグは、CSVまたはJSONファイルの行にわたって1つのシナリオを実行し、各行を個別のパスとして扱います。例: apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 605067 -d ./test-data.csv -r junit。これにより、50個のシナリオを構築することなく、同じエンドポイントを50個の入力に対して検証できます。

ブランチに対して実行します。チームがApidogのブランチ機能を使用している場合、--branch <branchName>は実行をmainではなく特定のブランチにポイントし、フィーチャーブランチのPRがそのブランチのシナリオ定義に対してテストできるようにします。

一般的なCI失敗のトラブルシューティング

ジョブはグリーンなのに、テストが失敗するはずだった。apidog runステップの終了コードが実際にGitHubに到達しているかを確認してください。コマンドをシェルパイプラインでラップしたり、|| trueを追記したりすると、ゼロ以外の終了コードが飲み込まれ、ゲートがサイレントに機能しなくなります。終了コードを隠すものはすべて削除してください。コマンドはそれ自体で1行で実行するか、run:ブロックの最後のコマンドとして実行し、その終了ステータスがステップの終了ステータスになるようにしてください。

認証が失敗する。最も一般的な原因は、シークレット名が一致しないことです。env:キー、値の参照${{ secrets.APIDOG_ACCESS_TOKEN }}、および設定で作成したシークレットはすべて同じ名前を使用する必要があります。また、トークンを保存してからApidogで再生成されていないかを確認してください。再生成すると古いトークンは無効になります。

ローカルではパスするが、CIでは失敗する。一時的に実行コマンドに--verboseを追加してください。これにより、ランナーが送信した完全なリクエストと受け取った完全なレスポンスが出力され、通常は違いが明らかになります。多くの場合、マシン上では設定されているがCI環境では設定されていない環境変数、またはローカルのものとは異なる動作をするステージングサービスが原因です。

レポートがアーティファクトとして表示されない。実行ステップの--out-dirとアップロードステップのpath:が同じディレクトリを指していること、およびアップロードステップにif: always()があることを確認してください。if: always()がないと、テストが失敗した場合にアップロードがスキップされ、まさにレポートが必要なときに失われてしまいます。

ランナーがAPIに到達できない。ステージング環境や本番環境がファイアウォールやVPNの背後にある場合、公開されているGitHubホスト型ランナーはそれに到達できません。ネットワーク内にセルフホステッドランナーを設置するか、GitHubのIP範囲を許可リストに追加する必要があります。

代替手段との比較

フレームワークを使ってAPIテストをコードとして書き、テストランナーに組み込み、それをActionsから呼び出すことも可能です。それは機能しますが、APIとチームがAPIツールで設計したものと同期を保つ必要があるコードスイートを維持することになります。Apidogのアプローチはその重複をスキップします。チームがアプリで既に維持しているシナリオが、CIで実行されるテストとなります。

ワークフローステップで生のcurlコマンドをスクリプト化することもできます。単一のヘルスチェックには問題ありませんが、それ以上は面倒です。なぜなら、CLIが無料で提供するアサーション、環境切り替え、レポート機能を自力で実装することになるからです。

GitHub Actionsだけがこの方法の場所ではありません。まったく同じapidog runコマンドは、GitLab CI、Jenkins、CircleCI、またはシェルコマンドを実行して終了コードを読み取ることができる任意のランナーに適用できます。GitHub Actionsがあなたのプラットフォームでない場合でも、ここでのパターンは直接適用可能です。CI/CDでのAPIテスト自動化ガイドでクロスプラットフォームの視点を見るか、Jenkinsを使用している場合はApidog自動テストとJenkinsの統合に関するウォークスルーを参照してください。

実行するシナリオを構築するには、Apidogをダウンロードし、アプリでテストを設計し、シナリオのCI/CDタブからCLIコマンドを取得します。ランナーは無料のnpmパッケージです。実行できる内容はApidogプロジェクトによって異なりますが、コマンドラインランナー自体は別の有料製品ではありません。

まとめ

設定は見た目よりもシンプルです。Apidogでシナリオを構築し、アクセストークンをGitHubシークレットとして保存し、ワークフローファイルにいくつかのステップを追加するだけです。それだけで、すべてのプルリクエストでAPIテストが自動的に実行され、失敗したエンドポイントはマージ前にチェックを赤に変え、何が壊れたか確認する必要がある場合はいつでもレポートがArtifactsタブで待機しています。

これがシンプルに保たれる理由は、役割分担にあります。Apidogアプリがテストを所有し、CLIがテストを実行し、GitHubが終了コードを読み取ります。何も重複させたり、同期を保ったりする必要はありません。アプリでアサーションを更新すると、次のCI実行でそれが使用されます。これが、最初の本番障害後に後付けするのではなく、プロジェクト初日からこれを行う価値がある理由です。

ボタン