APIテストを作成しました。それらはあなたのマシン上ではパスします。しかし、それらはそこにとどまることになります。なぜなら、それらを実行することは誰かが覚えておくべきことだからです。チームメイトが金曜日の午後に変更をデプロイし、認証エンドポイントがいつの間にか特定のコードパスで500エラーを返し始め、それに最初に気づくのは月曜日のユーザーです。カバレッジは常に存在していました。しかし、リグレッションを捕捉できたはずの瞬間に誰も実行しませんでした。
この問題を解決するには、テストをエディターからパイプラインに移行し、人間の介入なしにプッシュごとに実行されるようにすることです。そのためには、APIテストをヘッドレスで実行し、明確なパスまたは失敗を返し、既存のあらゆるCIシステムに組み込めるコマンドが必要です。Apidog CLIがそれを実現します。Apidogでテストシナリオを視覚的に構築し、Node.jsがインストールされた任意のCIランナーが実行できる単一のターミナルコマンドからそれらを実行します。GUIは不要、テストをコードとして書き直す必要もなし、ホストする追加サービスも不要です。
これはコピペガイドです。以下に、GitHub Actions、GitLab CI、Jenkins、CircleCI、およびAzure Pipelines向けのすぐに使えるパイプラインファイルと、健全なビルドを維持するための一握りのパターンを見つけることができます。あなたのプラットフォーム用のブロックをコピーし、IDとシークレットを入れ替えれば、その日の終わりにはすべてのマージをAPIテストでゲートできるようになります。もし詳細なフラグのリファレンスが必要な場合は、より広範なテーマであるCI/CDでのAPIテスト自動化の方法が戦略をカバーしています。このページは、動作するパイプラインを貼り付けることについてです。
接続するもの
Apidog CLIはapidog-cliというnpmパッケージです。これはApidogアプリで作成したテストシナリオを実行します。具体的には、連鎖したリクエスト、アサーション、あるレスポンスから次のレスポンスへ引き継がれる値、データ駆動型の反復などです。CLIは独自のテストフォーマットを考案しません。プロジェクトにアクセスし、IDでシナリオを見つけ、アプリと同じ方法で実行し、終了コードで結果を報告します。
その終了コードが最も重要な点です。すべてのアサーションがパスすると、実行は0で終了します。いずれかが失敗すると、ゼロ以外のコードで終了します。CIシステムはその終了コードを読み取り、ステップを失敗とマークし、マージやデプロイをブロックします。ゲートを設定するわけではありません。ゲートは終了コードそのものです。apidog runステップがパイプラインに存在するかぎり、アサーションが壊れていればラインは停止します。
実行を機能させる3つの要素があり、以下の各ブロックでそれらを確認できます。
- アクセス可能なシナリオの実行を証明するアクセストークン。パスワードのように扱ってください。コミットされたファイルには絶対に保存せず、CIシークレットとして保存します。
- 何をテストするかを示すシナリオID（またはフォルダーID、またはテストスイートID）。
- どこでテストを実行するか（開発、ステージング、または本番）を示す環境ID。
これらのIDを手動で入力する必要はありません。Apidogでテストシナリオを開き、そのCI/CDタブに切り替え、コマンドラインオプションを選択し、アクセストークンを生成します。ApidogはシナリオIDと環境IDがすでに記入された完全なapidog runコマンドを提供します。一度コピーしたら、トークンをシークレットに移動します。まだシナリオを構築していない場合は、Apidogでテストシナリオを作成する方法から始め、パスするシナリオができたら戻ってきてください。
すべての基盤となるコマンド
これが標準的な実行方法です。すべてのパイプラインファイルは、この行をラップしています。
apidog run \
--access-token $APIDOG_ACCESS_TOKEN \
-t 605067 \
-e 1629989 \
-n 1 \
-r html,junit \
--out-dir ./apidog-reports
各要素の機能は以下のとおりです。
--access-tokenは実行を認証します。これは$APIDOG_ACCESS_TOKEN環境変数から読み取られ、この変数はシークレットから設定します。-t 605067はそのIDを持つテストシナリオを実行します。フォルダー全体を実行するには-tを-f <folderId>に、厳選されたスイートを実行するには--test-suite <id>に置き換えます。-e 1629989は環境をターゲットにします。これにより、同じシナリオがPRチェックでステージングをヒットし、デプロイ後のスモークテストで本番をヒットするようになります。-n 1はシナリオを1回実行します。ループさせるにはこの値を増やし、CSVまたはJSONデータファイルから反復を駆動するには-d <file>と組み合わせて使用します。-r html,junitはレポート形式を選択します。junitはCIダッシュボードがパス/失敗ツリーとして解析するXMLを出力します。htmlはビルド成果物として保存する閲覧可能なレポートです。ログにも読みやすい出力を求める場合はcliを追加します。--out-dir ./apidog-reportsはレポートが保存されるディレクトリです。
レポーターは「ビルドが失敗した」と「これが失敗したアサーションとそれを壊したレスポンスです」の違いをもたらします。JUnit XMLはほとんどすべてのプラットフォームがネイティブに理解する形式なので、以下の5つのブロックすべてに登場します。
GitHub Actions
これを.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 \
-n 1 \
-r html,junit \
--out-dir ./apidog-reports
env:
APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}
- name: Upload report
if: always()
uses: actions/upload-artifact@v4
with:
name: apidog-report
path: ./apidog-reports
重要な点が2つあります。トークンは「Settings → Secrets and variables → Actions」にAPIDOG_ACCESS_TOKENとして保存され、env:を通じてステップに渡されます。そして、アップロードステップのif: always()は、テストが失敗した場合でもレポートを入手できることを意味します。これはまさにレポートを読み取る必要がある時です。シナリオが破損した場合、apidog runステップはゼロ以外のコードで終了し、ジョブは失敗し、PRには失敗したチェックが表示されます。このプラットフォームのより詳細な手順については、GitHub ActionsでのAPIテスト自動化の方法を参照してください。
GitLab CI
.gitlab-ci.ymlでも同じ考え方です。node:20イメージにはすでにランタイムが含まれているため、設定はインストールのみです。
stages:
- test
api-tests:
stage: test
image: node:20
script:
- npm install -g apidog-cli
- >
apidog run
--access-token "$APIDOG_ACCESS_TOKEN"
-t 605067
-e 1629989
-r junit,cli
--out-dir ./apidog-reports
artifacts:
when: always
paths:
- apidog-reports/
reports:
junit: apidog-reports/*.xml
APIDOG_ACCESS_TOKENは、「Settings → CI/CD → Variables」にマスキングされた保護変数として保存し、ログに表示されないようにします。reports: junit:ブロックはGitLabユーザーが見落としがちな部分です。これはGitLabにXMLを解析し、マージリクエストウィジェットに結果を直接表示するよう指示します。レビュー担当者は何もダウンロードすることなく、どのアサーションが失敗したかを確認できます。
Jenkins
Declarative Pipelineの場合、トークンをJenkinsクレデンシャルとして保存し、環境にプルして、ステージでCLIを呼び出します。postブロックはJUnit XMLをJenkinsのテストトレンドグラフに供給し、HTMLレポートをビルドに残します。
pipeline {
agent any
environment {
APIDOG_ACCESS_TOKEN = credentials('apidog-access-token')
}
stages {
stage('API tests') {
steps {
sh 'npm install -g apidog-cli'
sh '''
apidog run \
--access-token $APIDOG_ACCESS_TOKEN \
-t 605067 \
-e 1629989 \
-n 1 \
-r html,junit \
--out-dir apidog-reports
'''
}
}
}
post {
always {
junit 'apidog-reports/*.xml'
archiveArtifacts artifacts: 'apidog-reports/**', allowEmptyArchive: true
}
}
}
ビルドエージェントにCLIがすでにキャッシュされている場合は、npm install行を削除してapidog runを直接呼び出してください。シェルステップではなくプラグイン経由で統合したい場合は、ApidogはJenkins専用の統合ガイドも提供しています。CI/CD向けにApidog自動テストをJenkinsと統合する。
CircleCI
.circleci/config.ymlでは、Nodeコンビニエンスイメージを使用し、トークンを「Project Settings → Environment Variables」の下にプロジェクト環境変数として保存します。
version: 2.1
jobs:
api-tests:
docker:
- image: cimg/node:20.11
steps:
- checkout
- run:
name: Install Apidog CLI
command: npm install -g apidog-cli
- run:
name: Run API test scenario
command: |
apidog run \
--access-token "$APIDOG_ACCESS_TOKEN" \
-t 605067 \
-e 1629989 \
-r junit,cli \
--out-dir ./apidog-reports
- store_test_results:
path: ./apidog-reports
- store_artifacts:
path: ./apidog-reports
destination: apidog-reports
workflows:
test:
jobs:
- api-tests
store_test_resultsはGitLabのJUnitブロックに相当するCircleCIの機能です。レポートディレクトリを指し示すことで、CircleCIはテストタブに失敗したアサーションを表示します。store_artifactsはHTMLレポートを添付したままにして、ビルドページから開けるようにします。
Azure Pipelines
azure-pipelines.ymlでは、タスクでNodeをインストールし、CLIを実行し、JUnit結果を公開します。APIDOG_ACCESS_TOKENをパイプラインのシークレット変数として追加（またはAzure Key Vault変数グループから取得）し、それをスクリプトステップのenvにマッピングします。
trigger:
- main
pool:
vmImage: ubuntu-latest
steps:
- task: NodeTool@0
inputs:
versionSpec: '20.x'
displayName: 'Install Node.js'
- script: npm install -g apidog-cli
displayName: 'Install Apidog CLI'
- script: |
apidog run \
--access-token "$APIDOG_ACCESS_TOKEN" \
-t 605067 \
-e 1629989 \
-r junit,html \
--out-dir ./apidog-reports
displayName: 'Run API test scenario'
env:
APIDOG_ACCESS_TOKEN: $(APIDOG_ACCESS_TOKEN)
- task: PublishTestResults@2
condition: always()
inputs:
testResultsFormat: 'JUnit'
testResultsFiles: 'apidog-reports/*.xml'
testRunTitle: 'Apidog API tests'
$(APIDOG_ACCESS_TOKEN)マクロは、シークレットパイプライン変数を読み取ります。それをenvを通じてマッピングすることで、可視コマンドラインから隠蔽します。condition: always()付きのPublishTestResults@2は、実行が成功したか失敗したかにかかわらず、テストタブに結果が表示されるようにします。このプラットフォームのより詳しい説明については、ApidogがAzure DevOpsパイプラインのAPIテストに関する専用のウォークスルーを提供しています。
ゲートを信頼できるものにするパターン
テストを実行するパイプラインは基本です。これらのレシピは、日々の運用でそれを役立つものにします。
デプロイ直後のスモークテスト。リリースが本番環境にデプロイされた瞬間に、本番環境をターゲットにした高速なシナリオを1つ実行し、最初の失敗で停止します。
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e <prodEnvId> -r cli --on-error end
夜間の完全なリグレッションテスト。スケジュールに従ってシナリオのフォルダー全体を実行し、最初の失敗で停止するのではなく、すべての失敗を1つのレポートにまとめます。
apidog run --access-token $APIDOG_ACCESS_TOKEN -f <folderId> -r html,junit --on-error continue --out-dir ./nightly-reports
ここでのポイントは--on-errorです。endはデプロイゲートに必要な高速失敗を実現します。continueはすべてのステップを実行するため、ナイトリーレポートで一度にすべての破損箇所を表示できます。どちらの場合でも、何かが失敗すれば実行はゼロ以外のコードで終了するため、ゲートは機能します。
多数の入力に対して1つのシナリオを実行します。データファイルから反復を駆動し、各行を個別のパスとして扱います。
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -d ./test-data.csv -r junit
mainではなくフィーチャーブランチをテストします。ブランチ上に存在するシナリオをそのまま実行します。
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 --branch feature-payments -e 1629989 -r cli
CIのみで発生する失敗のデバッグ。シナリオがローカルではパスするがパイプラインで失敗する場合、--verboseを追加します。これにより、ランナーが送信した正確なリクエストと受信した正確なレスポンスが出力されます。これは、ギャップを引き起こしている環境の違いを見つけるほぼ常に有効な方法です。
ビルドが偽りの結果を出すとき
いくつかの失敗モードはよく発生し、それぞれが密かにゲートを無効にするため、特に注意が必要です。
テストが失敗すべきときにビルドがグリーンになる。これは危険なケースです。ほとんどの場合、終了コードが無視されています。コマンドをシェルパイプラインでラップしたり、「ビルドを壊さないように」|| trueを追加したりすると、何も捕捉できなくなります。ゼロ以外の終了コードをマスクするものはすべて削除してください。apidog runステップは、CIステップが読み取るものでなければなりません。
認証エラー。トークンが間違っているか、期限切れであるか、コマンドに到達していません。CIシークレットが実際に設定されていることを確認し（値ではなく、その長さがマスクされてエコーされるように）、必要であればシナリオのCI/CDタブから再生成してください。
「シナリオが見つかりません」。シナリオID、プロジェクトID、またはブランチが一致していません。CI/CDタブからコマンドを再度コピーしてIDが最新であることを確認し、--branchが意図した場所を指していることを再確認してください。
ローカルではパスするがCIで失敗する。これはほとんどの場合、環境の違いが原因です。ランナーが異なる-e環境をターゲットにしている、ホストに到達できないファイアウォールの背後にある、またはシナリオが必要とする変数が不足している可能性があります。--verboseで実行し、ランナーが生成したリクエストとローカルで送信したリクエストを比較してください。
内部ホストに対するTLSエラー。エンドポイントが内部CAを使用している場合、検証を無効にするのではなく、追加のCA証明書を渡してください。-k（SSL検証をスキップ）は、自己署名証明書を持つ信頼できる内部ホストでの最終手段としてのみ使用し、公開されたものに対しては決して使用しないでください。
なぜ視覚的に構築し、ヘッドレスで実行するのか
これらすべてには真の設計選択があり、それを説明する価値があります。スクリプトを主体とするランナーでは、テストとその実行が同じファイル内にあるため、脆いスクリプトはテストであると同時にボトルネックにもなります。Apidogでは、プロジェクト内のシナリオがテストであり、CLIは人間が介入できない場所でそれを実行するだけです。誰も同じチェックの2つの表現を維持することはありません。ビジュアルビルダーで素早く作成し、パイプラインで自動的に実行され、両者は同じアーティファクトであるため同期が保たれます。これは、CIが導入された際にチームがApidogをAPIテストのためのPostmanの代替として扱う大きな理由であり、また、APIアサーションの質が、それを包むランナーよりも重要である理由でもあります。
一度実行されれば、ループはシンプルです。アプリでリクエストを設計およびデバッグします。それらをアサーションとともにシナリオに連結します。コードをプッシュすると、CLIは変更ごとにCIでそのシナリオを実行します。何かが壊れた場合、レポートはアサーションを特定し、終了コードがデプロイを停止します。修正し、再度プッシュすると、同じゲートが修正を確認します。
もしテストがまだ誰かのエディター内にあるなら、それが今週埋めるべきギャップです。Apidogをダウンロードし、1つのシナリオをパスさせ、そのCI/CDタブからapidog runコマンドをコピーし、あなたのプラットフォーム用の上記のブロックを貼り付けてください。そうすれば、その日の午後には、すべてのマージをAPIテストでゲートできるようになります。
よくある質問
Apidog CLIはCIで無料で使えますか？CLIは無料のnpmパッケージです: npm install -g apidog-cli。これはあなたのApidogプロジェクトのシナリオを実行するため、実行できる内容はApidogのプランに依存しますが、コマンドラインランナー自体は別途有料の製品ではありません。
テストをコードとして書き直す必要がありますか？いいえ。Apidogでシナリオを視覚的に構築し、CLIがIDでそれらを実行します。シナリオがテストであり、CLIは単なる実行者です。これがスクリプト主体のランナーとの主な違いです。
失敗したテストはどのようにビルドを実際に失敗させるのですか？終了コードを通じてです。いずれかのアサーションが失敗すると、apidog runはゼロ以外のコードで終了します。あなたのCIシステムはそれを読み取り、ステップを失敗とマークし、マージやデプロイをブロックします。ゲートを機能させるために追加の設定をする必要はありません。
どのレポート形式を使用すべきですか？CIダッシュボードがパス/失敗の結果として解析する機械可読なXMLにはjunitを使用し、ビルド成果物として閲覧可能なレポートを保存したい場合はhtmlを追加してください。一般的な組み合わせは-r junit,htmlです。ビルドログにも読みやすい出力が必要な場合はcliもオンにしてください。
CIサーバーにApidogをインストールする必要がありますか？いいえ。CIランナーにはNode.js（v16以降）とapidog-cliパッケージのみが必要です。デスクトップアプリもGUIも、ボックス上のライセンスファイルも不要です。パッケージとアクセストークンがあれば十分です。
グローバルインストールなしで実行できますか？はい。永続的なグローバルインストールなしで実行するにはnpx apidog-cli run ...を使用します。これは、各ジョブの後に破棄されるエフェメラルランナーではよりクリーンです。
これはNewmanとどう違いますか？NewmanはコマンドラインからPostmanコレクションを実行します。Apidog CLIはApidogテストシナリオを実行します。役割は並行していますが、Apidogランナーはアプリで作成したシナリオを実行し、単一のapidog-cliパッケージとして提供されます。その比較のPostman側については、Postman CLI vs Newmanを参照してください。
アクセストークンとIDはどこで入手できますか？すべてApidogのテストシナリオのCI/CDタブから入手します。コマンドラインオプションを選択し、アクセストークンを生成し、シナリオと環境IDがすでに記入されたApidogが生成する完全なapidog runコマンドをコピーします。その後、トークンをCIシークレットに移動し、$APIDOG_ACCESS_TOKENとして参照します。