あなたのAPIテストは、すべてのプルリクエストでパスします。ビルドはグリーンです。あなたは出荷します。すると午前9時、別のタイムゾーンの誰かが、チェックアウトが500エラーを返していると報告しました。しかし、チェックアウトのコードは誰も変更していません。変更されたのは、サードパーティの決済サンドボックス、夜間に実行されたデータベースマイグレーション、あるいは静かに期限切れになったトークンでした。リポジトリ内で何も移動しなかったため、コミットごとのテストでは決してこれを検出できませんでした。
ナイトリービルドが埋めるのは、このギャップです。ナイトリービルドとは、コードの変更時だけでなく、実際のサービスや環境に対して、通常は深夜に1日1回実行されるスケジュールされたフルテスト実行です。これは、コミット間に潜む障害、例えばデータのずれ、不安定な連携、期限切れの認証情報、パフォーマンスの緩やかな低下、制御できないサービスによって引き起こされる契約違反などを検出します。APIの場合、ナイトリー回帰テストは、設定できる最も安価な早期警告システムです。
このガイドでは、Apidog を使用してそのシステムをエンドツーエンドで構築する方法を説明します。回帰テストスイートを設計し、Apidog CLIでコマンドライン実行を生成し、それをGitHub Actions、GitLab、JenkinsのスケジュールされたCIジョブに組み込み、スタンドアップの前にレポートが用意されている状態にします。もしあなたが、ナイトリー実行によって何時間も早く検出できたはずの障害をデバッグした経験があるなら、これはその時間を買い戻すワークフローです。
コミットごとのテストだけでは不十分な理由
継続的インテグレーションは、すべてのプッシュでテストを行うよう私たちを訓練しました。それは良いことであり、続けるべきです。しかし、コミットごとのテストは「この変更で何かが壊れたか？」という狭い問いに答えるものです。これらは高速で頻繁に実行され、開発者が作業を中断されないように範囲が限定されています。その範囲限定が、まさに問題の全カテゴリを見逃す理由なのです。
ナイトリービルドは、より広い問いに答えます。「誰も触れていなくても、システムは今も健全か？」この違いは重要です。なぜなら、本番環境にはあなたのコミットでは見ることのない動的な要素があるからです。
- 外部依存関係のずれ。決済プロバイダーがサンドボックスキーを更新したり、天気APIがフィールドを非推奨にしたりします。あなたのコードは同じですが、契約が密かに変更されているのです。
- コードなしのデータ変更。夜間のETLジョブ、スケジュールされた移行、コンテンツ更新などにより、高速テストでは検証されない状態にデータベースがなることがあります。
- トークンと証明書の期限切れ。OAuthのリフレッシュトークン、TLS証明書、APIキーには有効期限があります。いずれか一つが失効した日には、あなたのグリーンビルドは嘘になります。
- 高速スイートに隠れる緩やかな回帰。200ミリ秒から1.2秒に忍び寄るクエリは機能アサーションを失敗させませんが、応答時間しきい値を持つナイトリー実行はそれを検出します。
- すべてのプッシュに完全なスイートは遅すぎる。すべてのエンドポイント、すべてのエッジケース、すべての環境を網羅する400ケースの包括的な実行は、プルリクエストのゲートとして使用するには重すぎます。ナイトリー実行がふさわしい場所です。
したがって、パターンは二層構造であり、どちらか一方ではありません。高速なスモークテストが各コミットを保護します。より深い回帰テストスイートはスケジュールに基づいて実行されます。ナイトリー層は、遅すぎる、広すぎる、あるいは実世界の状況に依存しすぎるためインナーループには適さないすべてのものを置く場所です。
ナイトリーAPI回帰テストスイートに含めるべきもの
何かをスケジュールする前に、ナイトリー実行で実際に何をチェックするかを決定してください。ナイトリースイートは、コミットゲートのスモークテストよりも広範で、簡単なヘルスチェックよりも徹底的です。静かに壊れた場合にあなたが困るようなカバレッジを目指しましょう。
堅実なナイトリーAPIスイートは以下をカバーします。
- 重要なユーザー体験をエンドツーエンドで。単一のエンドポイントを個別にテストするのではなく、実際の連携を確認します。サインアップ、ログイン、リソースの作成、読み出し、更新、削除。各ステップでトークンやIDを次のステップに渡します。
- 認証と認可。有効なログイン、期限切れトークンの拒否、ロールベースのアクセス。認証は静かな殺し屋です。毎晩テストしましょう。
- 契約への準拠。すべてのレスポンスをOpenAPIスキーマに対して検証し、バックエンドが密かにフィールドを削除したりタイプを変更したりした場合に検出します。ドキュメントとレスポンスが乖離する傾向がある場合、これがそれを検出するチェックです。（仕組みについては、Swaggerのドキュメントとコレクションが乖離し続ける理由を参照してください。）
- 境界とエラーケース。不正な入力に対する400、リソースの欠落に対する404、レート制限下での429、認証情報なしでの401。ハッピーパスよりもアンハッピーパスの方が頻繁に壊れます。
- リクエスト間のデータ整合性。何かを作成した後、その後のリクエストでそれが確認できるかを確認します。結果整合性やキャッシュのバグを検出します。
- パフォーマンスしきい値。主要なエンドポイントが予算内で応答することを確認します。ナイトリーのトレンドラインは、インシデントになる前にパフォーマンスの低下を示します。
このような構造化されたケースをまだ書いたことがない場合は、APIテストケースのテンプレートと例が良い出発点となります。また、APIアサーションは、レスポンスボディ、ステータス、ヘッダー、タイミングを正確に検証する方法をカバーしています。
ステップ1: Apidogで回帰テストスイートを構築する
Apidogは、テストをAPIライフサイクルの一部として、後付けではなくファーストクラスで扱います。エンドポイントを設計し、それらを実際のワークフローを反映したテストシナリオに連結します。シナリオは、各ステップがアサーションを持つAPIリクエストであり、データがあるステップから次のステップへと流れる順序付けられたリストです。
以下は、チェックアウト回帰シナリオの概略です。
- POST /auth/login: 認証情報を送信し、
200をアサートし、レスポンスからaccessTokenを変数に抽出します。 - POST /carts: トークンを使用してカートを作成し、
201をアサートし、cartIdを抽出します。 - POST /carts/{cartId}/items: 商品を追加し、
200をアサートし、レスポンスボディのtotalが期待価格と等しいことをアサートします。 - POST /checkout: カートを送信し、
200をアサートし、order.statusが"confirmed"であることをアサートします。 - GET /orders/{orderId}: 注文を読み戻し、正しい品目が保持されていることをアサートします。
Apidogでは、これを視覚的に構築します。各ステップで、ボイラープレートコードを書くことなくアサーションを設定できます。例えば、「レスポンスステータスが200」や「JSONPath $.order.status が confirmed と等しい」といった視覚的なアサーションです。スキーマの準拠については、Apidogはエンドポイントの保存されたOpenAPI定義に対してレスポンスを自動的に検証できるため、すべてのフィールドに対して手動でチェックを記述する必要はありません。
ナイトリースイートを保守可能に保つためのいくつかの設計ルール：
- ハードコードされたURLではなく、環境を使用する。ベースURL、認証情報、変数を備えた
staging環境を定義します。同じシナリオが今夜はステージング環境で、来週はリリース候補に対して、一つのフラグを切り替えるだけで実行できます。 - 変数でパラメータ化する。テストユーザー名、ベースURL、および任意のIDを環境変数から取得することで、機密情報や環境固有のものがシナリオ自体に残らないようにします。
- シナリオをテストスイートにグループ化する。テストスイートは多くのシナリオをバンドルするため、一つのコマンドですべてを実行できます。それがスケジュールする単位となります。
他のツールから移行してきた方であれば、これはあなたが知っている概念にきれいにマッピングされます。シナリオを連携させるより広範な内容は、APIテストオーケストレーションガイドに記載されており、Apidogで構造化されたテストを実行したことがない場合は、ApidogでAPIをテストする方法がステップバイステップの出発点となります。Apidogをダウンロードし、この先を読み進める前に一つシナリオを作成してください。このガイドの残りの部分は、実行するスイートがあることを前提としています。
ステップ2: コマンドラインからスイートを実行する
ナイトリービルドは無人で実行されるため、ヘッドレスランナーが必要です。それがApidog CLIです。これは、GUIなしで任意のターミナルから保存されたテストシナリオを実行できるnpmパッケージです。CI/CDパイプライン内での自動実行のためにまさにこれが必要とされます。
グローバルにインストールします。CLIにはNode.js v16以降が必要です。
npm install -g apidog-cli
オンラインシナリオ（Apidogプロジェクトに存在するシナリオ）を実行するには、アクセス_トークンとシナリオまたはスイートIDの2つのものが必要です。ApidogのCI/CD設定にある「アクセストークンを追加」ボタンからトークンを生成します。そのトークンはパスワードのように扱ってください。それはシークレットに保存され、決してリポジトリには置かないでください。
単一のテストシナリオを実行するコマンドは次のようになります。
apidog run \
--access-token $APIDOG_ACCESS_TOKEN \
-t 123456 \
-e 789 \
-r cli,html \
--out-dir ./apidog-reports
実際のApidog CLIオプションを使用したフラグごとの説明：
--access-token <token>は実行を認証します。環境変数から渡します。-t, --test-scenario <id>は実行するシナリオを選択します。代わりにスイート全体を実行するには--test-suite <id>を使用し、シナリオのフォルダーを実行するには-f, --test-scenario-folder <id>を使用します。-e, --environment <id>は環境（ステージング、本番読み取り専用など）を選択します。-r, --reporters [reporters]は出力形式を設定します。cliはCIログのために結果をコンソールに出力します。htmlは共有可能なレポートファイルを生成します。--out-dir <dir>はHTMLレポートが保存される場所であり、CIがそれをアーティファクトとしてアーカイブできるようにします。
その他のフラグもナイトリー実行で役立ちます。-n, --iteration-count <n> は不安定さを浮上させるために実行を繰り返します。-d, --iteration-data <path> はCSVまたはJSONファイルを供給し、一つのシナリオが複数のデータ行で実行されるようにします。これは境界テストに最適です。--env-var "key=value" および --global-var "key=value" は実行時に値を挿入し、保存されたシナリオから認証情報を除外する方法です。
これを覚える必要はありません。Apidogは正確なコマンドを生成します。クライアントのCI/CDパネルを開き、シナリオまたはスイートを選択し、既製の apidog run 行をパイプライン設定に直接コピーします。スケジュールする前に、まず一度ローカルで実行し、グリーンであることを確認してください。
ステップ3: ナイトリービルドとしてスケジュールする
ナイトリービルドとは、このコマンドをタイマーで実行することです。すべてのCIプラットフォームは、cron構文を介してスケジュールされたジョブをサポートしています。そのパターンはすべてで同じです。つまり、日次トリガー、シークレットからのアクセストークン、CLI実行、そしてアーティファクトとしてアーカイブされるレポートです。
GitHub Actions
GitHub Actionsは、標準のcronによる schedule トリガーをサポートしています。このワークフローは毎日UTC 02:00に実行され、workflow_dispatch を介して手動ボタンも公開します。
name: Nightly API Regression
on:
schedule:
- cron: '0 2 * * *' # 02:00 UTC daily
workflow_dispatch: # allow manual runs
jobs:
regression:
runs-on: ubuntu-latest
steps:
- name: Set up Node
uses: actions/setup-node@v4
with:
node-version: '20'
- name: Install Apidog CLI
run: npm install -g apidog-cli
- name: Run nightly regression suite
run: |
apidog run \
--access-token $APIDOG_ACCESS_TOKEN \
--test-suite ${{ vars.APIDOG_SUITE_ID }} \
-e ${{ vars.APIDOG_ENV_ID }} \
-r cli,html \
--out-dir ./apidog-reports
env:
APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}
- name: Upload HTML report
if: always()
uses: actions/upload-artifact@v4
with:
name: apidog-nightly-report
path: ./apidog-reports
アップロードステップの if: always() は重要です。なぜなら、実行が失敗した場合でもレポートをアーカイブしたいからです。失敗した時こそ、レポートを読む必要があるからです。GitHubのスケジュールされたジョブはUTCで実行され、ピーク負荷時には遅延する可能性があるため、正確な秒単位で実行する必要があるものはスケジュールしないでください。
GitLab CI/CD
GitLabは、YAMLではなくUI（CI/CD > Schedules）を介してパイプラインをスケジュールします。その後、ジョブはルール条件に基づいて実行されるため、すべてのプッシュ時ではなく、スケジュールされたときのみ実行されます。
nightly-regression:
image: node:20
rules:
- if: '$CI_PIPELINE_SOURCE == "schedule"'
before_script:
- npm install -g apidog-cli
script:
- apidog run
--access-token "$APIDOG_ACCESS_TOKEN"
--test-suite "$APIDOG_SUITE_ID"
-e "$APIDOG_ENV_ID"
-r cli,html
--out-dir ./apidog-reports
artifacts:
when: always
paths:
- apidog-reports/
expire_in: 30 days
APIDOG_ACCESS_TOKEN をマスクされた保護されたCI/CD変数として設定し、0 2 * * * のようなcron式でパイプラインスケジュールを作成します。rules ブロックは、このジョブが通常のコミットで実行されないようにします。
Jenkins
Jenkinsでは、cron トリガーを持つ pipeline が同じジョブを実行します。トークンを認証情報として保存し、withCredentials を使用して取得します。
pipeline {
agent any
triggers {
cron('H 2 * * *') // around 02:00, H spreads load
}
stages {
stage('Install CLI') {
steps { sh 'npm install -g apidog-cli' }
}
stage('Nightly regression') {
steps {
withCredentials([string(credentialsId: 'apidog-token',
variable: 'APIDOG_ACCESS_TOKEN')]) {
sh '''
apidog run \
--access-token $APIDOG_ACCESS_TOKEN \
--test-suite $APIDOG_SUITE_ID \
-e $APIDOG_ENV_ID \
-r cli,html \
--out-dir ./apidog-reports
'''
}
}
}
}
post {
always {
archiveArtifacts artifacts: 'apidog-reports/**', allowEmptyArchive: true
}
}
}
H 2 * * * の H はJenkinsの気の利いた機能です。これは、時間内の安定した分を選択し、すべてのナイトリージョブが02:00ぴったりに殺到しないようにします。
そのcronフィールドは、3つのプラットフォームすべてで同じです。0 2 * * * は、毎日午前2時0分を意味します。問題をより早く発見するために一晩に2回実行したいですか？0 2,14 * * * を使用します。平日のみですか？0 2 * * 1-5 を使用します。ステージング環境が静かで、外部サンドボックスが起動している時間を選びましょう。
ステップ4: 失敗を見過ごせないようにする
誰も読まないログに失敗が記録されるだけのナイトリー実行は、ナイトリー実行がないよりも悪いものです。それは誤った自信を築きます。目的はアラートです。結果をチームがすでに確認している場所に連携させましょう。
CLIの終了コードがフックとなります。シナリオが失敗すると apidog run はゼロ以外のコードで終了するため、CIは自動的にジョブを赤く表示します。そこから：
- CIに自動で通知させる。GitHub Actions、GitLab、Jenkinsはすべて、スケジュールされた実行が失敗した場合に担当チームにメールまたはメッセージを送信します。これを有効にしましょう。
- チャットに投稿する。失敗時にSlackまたはWebhookメッセージを発信するステップを追加し、実行へのリンクとアーカイブされたHTMLレポートを含めます。レポートは、どのシナリオ、どのステップ、どのアサーションが壊れたかを示すため、オンコールエンジニアは再現するのではなくデバッグを開始できます。
- 合否だけでなく、傾向を追跡する。Apidogはレポートをアップロードできるため、履歴を保持できます。一度の赤はノイズですが、同じエンドポイントで3回連続の赤はシグナルです。
ナイトリービルドの信頼性を保つための規律が一つあります。失敗は、そうではないと証明されるまで本当のバグとして扱ってください。ナイトリースイートを台無しにする最も手っ取り早い方法は、不安定なテストが皆に赤信号を無視するように習慣づけてしまうことです。もしシナリオが断続的に失敗する場合、テストか環境を修正してください。軽視してはいけません。-n を使用してシナリオを繰り返したり、シナリオが依存するデータを安定させたりすることで、通常は真の不安定さが露呈します。
Apidogがナイトリーパターンに適している理由
ナイトリーAPIパイプラインは、複数のパーツから組み立てることもできます。設計用のツール、テスト作成用のツール、ヘッドレス実行用のツール、そしてスキーマバリデーターを後付けするといった方法です。多くのチームがそのように運用しており、各パーツが同期しなくなるまでは機能します。しかし、午前2時に実行されたテストが、実際に出荷したAPIと一致しなくなったときに問題が発生します。
Apidogはそれを一つのワークフローにまとめます。あなたが設計するエンドポイント、テストするシナリオ、検証するスキーマ、そしてスケジュールするコマンドはすべて、同じ信頼できる情報源を参照します。エンドポイントを変更すると、シナリオとスキーマチェックもそれに合わせて移動します。エクスポートのステップもなければ、静かに古くなるコレクションもなく、同期を保つための契約の二重コピーもありません。Postmanコレクションが信頼できる情報源ではないことの苦痛を感じたことがあるなら、この単一情報源設計がその違いです。
CLIはGUIと同じエンジンであるため、デスクで視覚的にデバッグしたシナリオは、CIで午前2時にまったく同じように実行されます。あなたは完全な可視性をもってテストを構築および修正し、その後一つのコマンドでヘッドレスに実行します。この対称性こそが、ナイトリービルドをあなたが手厚く世話するものではなく、信頼できるものにする理由です。
よくある質問
ナイトリービルドと継続的インテグレーションの違いは何ですか？
継続的インテグレーションは、新しいコミットの回帰を捕捉するために、コードの変更ごとにテストを実行します。ナイトリービルドは、何かが変更されたかどうかに関わらず、通常は夜間に固定されたスケジュールで実行されます。CIはチームが壊したものを見つけ、ナイトリー実行は外部環境が壊したもの、例えば期限切れのトークン、ずれた依存関係、データ変更、パフォーマンスの緩やかな低下などを検出します。成熟したパイプラインは両方を実行します。高速なスモークテストが各コミットを保護し、より広範な回帰テストスイートが毎晩実行されます。
ナイトリービルドはいつ実行すべきですか？
テスト環境がアイドル状態で、依存する外部サービスにアクセスできる時間帯を選びましょう。多くのチームにとって、それは現地時間の午前1時から午前4時です。APIがサードパーティのサンドボックスを呼び出す場合は、その時間にそれらが起動していることを確認してください。一部のプロバイダーは夜間にスロットリングしたり、一時停止したりすることがあります。何千ものジョブが一度にトリガーされる共有CIでは、ちょうど毎正時にスケジュールするのを避けてください。数分ずらすか（またはJenkinsの H 構文を使用する）ことで、負荷が分散されます。
ナイトリースイートを本番環境に対して実行できますか？
本番環境に対しては、読み取り専用のチェックを安全に実行してください。データを書き込むものについては、現実的なデータを持つ専用のステージング環境またはプリプロダクション環境にナイトリースイートを向けたり、冪等な操作とクリーンアップステップを使用したりしてください。一般的なパターンとしては、ステージング環境に対する完全な読み書き回帰実行と、ライブシステムが到達可能で正しく応答していることを確認するための本番環境に対する小規模な読み取り専用スモーク実行を組み合わせる方法です。
これは監視とどう違うのですか？
稼働時間監視は「APIは稼働していますか？」という問いに答えます。ナイトリー回帰テストスイートは「APIは正しいですか？」という問いに答えます。監視はエンドポイントにpingを打ち、200をチェックします。回帰実行は完全なワークフローを実行し、スキーマに対してレスポンスボディを検証し、認証境界をチェックし、ビジネスルールをアサートします。これらは補完的な関係にあります。監視は継続的で表面的であり、ナイトリーテストは定期的で深層的です。
APIテストをスケジュールするためにコードを書く必要がありますか？
いいえ。Apidogではスクリプトなしで視覚的にシナリオを構築し、CI/CDパネルから生成された apidog run コマンドをコピーするだけです。唯一の「コード」は、CIプラットフォームにいつ実行するかを指示する数行のYAMLまたはパイプライン設定であり、それらは上記のテンプレートです。コマンドラインランナー全般の比較をご覧になりたい場合は、Postman CLI vs Newman と NewmanなしでCIでコレクションを実行する が代替案をカバーしています。
最初のナイトリー実行を設定する
小さく始めてください。ログインフローやチェックアウトパスなど、1つの重要なワークフローを選択し、それを実際のアサーションを含む単一のApidogシナリオとして構築します。CLIでローカルで実行し、グリーンになるまで確認します。生成されたコマンドを上記のテンプレートのいずれかを使用してスケジュールされたジョブにドロップします。失敗をチームチャットに連携させます。これで、半日で動作するナイトリービルドが完成です。
そこからスイートを成長させます。次に重要なジャーニーのシナリオを追加し、全体的にスキーマ検証を有効にし、重要なエンドポイントにパフォーマンス予算を設定します。1週間以内に、コミットごとのテストでは決して検出できないように設計された障害を捕捉する回帰テスト網が構築され、午前9時の顧客からの報告ではなく、午前2時のチャットメッセージでそれらを知ることになるでしょう。