Akira

Posted on Jul 15 • Originally published at apidog.com

Apidogでの自動APIテスト定期実行設定 (Cloud, Runner, CLI活用)

テストスイートがパスし続ける場合にのみ、テストは役に立ちます。今日のチェックアウトフローは正常でも、依存関係が午前2時に破壊的変更をリリースしたり、週末に証明書が期限切れになったり、設定ドリフトで日曜日に決済エンドポイントが停止したりする可能性があります。テスト実行ではなく、怒った顧客から初めて障害を知る状態は避けるべきです。APIテストをスケジュールに従って自動実行し、失敗した瞬間に通知を受け取れるようにしましょう。

今すぐApidogを試す

Apidog には、この用途のための組み込み「スケジュール済みタスク」機能があります。作成済みのテストシナリオ、実行頻度、実行マシン、通知先を指定して無人実行できます。

初めてライブエンドポイントの無人チェックを設定する場合は、API監視の入門記事も参照してください。UIの正式な仕様はApidogスケジュール済みタスクのドキュメントで確認できます。

「スケジュール済みタスク」機能は現在ベータ版です。また、実行可能なスケジュール済み実行数はプランによって異なります。

スケジュール済みタスクとは何か

Apidogのスケジュール済みタスクは、1つ以上の保存済みテストシナリオを指定した間隔で繰り返し実行する機能です。

代表的な用途は次のとおりです。

コアAPI全体に対する夜間回帰テスト
ステージング環境への数時間ごとのスモークテスト
週末に実行する本番環境の健全性チェック

タスクには、以下の設定が保存されます。

実行するテストシナリオ
対象環境
実行頻度
テストを実行するRunner
失敗時の通知先

スケジュール済みスクレーパーとの違い

ここでいうスケジュール済みタスクは、Webページを定期クロールするスクレーパーではありません。

Apidogのテストモジュールで作成したAPIテストシナリオを実行します。アサーション、連鎖リクエスト、抽出済み変数などを含むシナリオを起動し、結果としてスクレイピングデータではなくAPI契約の合否レポートを得ます。

つまり、設定するのはセレクターやクロールルールではなく、次の4点です。

どのテストシナリオを実行するか
どの環境に対して実行するか
いつ実行するか
どのRunnerで実行するか

始める前に：セルフホスト型Runnerを構成する

スケジュール済みタスクを実行するには、先にセルフホスト型Runnerを構成する必要があります。

Runnerはテストスイートを実行するマシンです。スケジュール済みタスクが起動すると、Apidogはデスクトップクライアントではなく、選択したRunnerにジョブを渡します。スイート内のすべてのHTTPリクエストは、そのRunnerから送信されます。

Runnerには、次のようなマシンを利用できます。

CIサーバー
常時稼働する小型サーバー
専用VM

選択するRunnerは、設定したスケジュールの時間帯に稼働しており、対象APIへ接続できる必要があります。

Runnerのネットワーク条件を確認する

リクエストはRunnerのネットワークから送信されるため、ローカル実行と異なる結果になる場合があります。

たとえば、Runnerが以下の環境にある場合です。

企業VPNの内側
別リージョン
ファイアウォールで保護されたサブネット
APIと同じVPC

この違いは障害ではなく、実運用に近い条件で監視できる利点になることがあります。一方で、ローカルでは成功するのにスケジュール実行だけ失敗する場合は、RunnerからのDNS、VPN、IP許可リスト、ファイアウォール設定を確認してください。

Runnerターゲットには「Apidog Cloud」も表示されますが、「近日公開」とされています。現時点ではセルフホスト型Runnerを選択してください。

ステップバイステップ：スケジュール済みタスクを作成する

ここでは、ユーザー登録、商品一覧、カート、Stripe 決済を含むEコマースAPIの夜間回帰スイートを例に設定します。

1. テストモジュールでスケジュール済みタスクを開く

Apidogクライアントでテストモジュールを開きます。

テストフォルダツリーからスケジュール済みタスクをクリックすると、プロジェクト内のタスクを一覧表示・管理できます。プロジェクト全体で何がいつ実行されるかを確認する場所として使えます。

2. タスクを作成する

+新規をクリックして、スケジュール済みタスクを作成します。

必要に応じてフォルダを作成し、関連するタスクをグループ化してください。たとえば、次のように分けると管理しやすくなります。

スケジュール済みタスク
├── production
│   ├── nightly-regression
│   └── hourly-health-check
└── staging
    ├── pre-release-smoke
    └── integration-regression

タスク名と説明には、対象・目的・頻度が分かる情報を含めます。

タスク名: nightly-regression-production
説明: 本番環境のサインアップ、カート、Stripeチェックアウトを毎晩実行

各タスクには有効・無効のトグルがあります。計画停止や移行中は削除せず、無効化しておくと再開しやすくなります。

3. 実行するテストシナリオを選択する

テストシナリオで、実行対象のシナリオを1つ以上選択します。

EコマースAPIなら、たとえば次のシナリオを1つのタスクに含めます。

サインアップとログイン
商品閲覧とカート追加
Stripeテストカードでのチェックアウト

各シナリオには、個別の実行設定を持たせることができます。

環境
テストデータ
イテレーション
実行間の遅延
リクエストとレスポンスを保存するかどうか

すべてのシナリオに同一設定を使う場合は、同じ実行設定を使用を有効にします。大きなスイートで環境や実行条件を統一したい場合に便利です。

環境はタスク単位で明確に分ける

環境の混在は調査を難しくするため、原則として1タスクは1環境にします。

目的	推奨環境	例
夜間監視	本番環境	決済・認証・主要検索
リリース前確認	ステージング	スモークテスト
結合テスト	開発・検証環境	外部依存を含む検証

シナリオごとに異なる環境を指定することもできますが、障害発生時に「どの環境で失敗したか」を即座に把握できる構成にしておくことをおすすめします。

4. 実行サイクルを設定する

実行スケジュールで実行頻度を設定します。

画面によっては、以下のように表示される場合があります。

実行サイクル
実行モード
実行スケジュール

いずれもスケジュール設定を指します。

設定例は次のとおりです。

毎週日曜日の23:00
6時間ごと
8時間ごと

用途ごとの目安は以下です。

テスト種別	推奨頻度	目的
本番の夜間回帰	毎晩	業務時間前に異常を検知
ステージングのスモークテスト	6時間ごと	環境の継続的な健全性確認
軽量なヘルスチェック	より短い間隔	主要エンドポイントの生存確認

まずは夜間実行から開始し、安定性・実行時間・プラン上の実行枠を確認して頻度を上げると安全です。

5. 実行するRunnerを選択する

runnerフィールドでセルフホスト型Runnerを設定します。

UI上では以下の表記揺れがある場合があります。

Runs on
Run On
Runs On

いずれもテストを実行するマシンの選択です。

複数のRunnerがある場合は、APIへの実際のアクセス経路に近いRunnerを選択してください。たとえば、APIと同じVPC内のRunnerや、ユーザーに近いリージョンのRunnerを使用します。

テストスイート内のすべてのリクエストは、ここで選択したRunnerから送信されます。

6. 通知を設定する

通知を有効にして、タスク失敗時にアラートを受け取れるようにします。無人実行では、失敗を検知して通知することが最も重要です。

Apidogでは、次の通知チャンネルが利用できます。

Slack
Teams
Webhook
Jenkins
Email

Emailでは、プロジェクトメンバーのアドレスが自動補完されます。オンコール担当者や共有メールボックス向けに、非メンバーのアドレスを手動入力することもできます。

Webhookを利用すれば、PagerDutyや社内の通知基盤など、任意のエンドポイントへ結果を送信できます。

通知条件を選ぶ

通知タイミングは、次のどちらかを選択できます。

すべての実行後
失敗時のみ

通常の夜間回帰テストでは、失敗時のみがおすすめです。正常時の通知を減らし、問題が起きたときだけチームに知らせます。

一方で、不安定なロールアウト中は、すべての実行後に通知することで、ジョブ自体が継続して動いていることを確認できます。

7. 保存して有効にする

設定を保存し、タスクのトグルを有効にします。

有効化後、設定した頻度で実行が始まります。メンテナンスや移行時には、削除ではなく無効化を使うと設定を維持できます。

8. 実行履歴を確認する

各実行後、結果はRunnerからサーバーへ自動アップロードされます。

クライアントのスケジュール済みタスク - 実行履歴を開くと、次の情報を確認できます。

実行日時
成功・失敗
失敗したシナリオ
失敗したアサーション
実行結果の詳細

Slackなどでアラートを受け取った場合は、実行履歴を開いて、どのリクエスト・アサーションで問題が起きたかを確認してください。

詳細設定とバリエーション

基本的なタスクを作成したら、変数スコープと永続化を調整して、より堅牢なテストにします。

変数のスコープを最小化する

Apidogでは、変数を共有する範囲を選択できます。

現在のテストシナリオ内でのみ共有
現在のスケジュール済みタスク内の全テストシナリオで共有
現在のスケジュール済みタスクフォルダ内の全タスクで共有

データが必要な範囲だけ共有してください。

たとえば、ログインシナリオで取得した認証トークンを、同じタスク内のチェックアウトシナリオへ渡す場合は、タスク内共有が適しています。一方で、関係のないタスクまでトークンを共有する必要はありません。

実行間で変数を保持する

前回の実行で取得した値を次回に引き継ぐ必要がある場合は、テストシナリオデザイン画面の変数の値を保持を有効にします。

この設定が必要になる例は次のとおりです。

前日の実行で作成した注文IDを使う
更新済みトークンを次回実行でも利用する
前回処理したカーソルやページネーション位置を保持する

有効にしない場合、スケジュール実行は毎回クリーンな状態で開始されます。実行間の状態に依存するテストでは、この設定漏れが失敗原因になりやすいため注意してください。

フォルダでタスクを整理する

スイートが増えたら、スケジュール済みタスク配下にフォルダを作成して分類します。

たとえば、以下のように用途別・環境別に分けます。

production/
  nightly-regression
  payment-health-check

staging/
  smoke-test
  release-candidate-regression

フォルダ単位の変数スコープを使うと、関連するタスクだけで設定を共有できます。

プランの実行制限を確認する

利用可能なスケジュール済み実行数はサブスクリプションによって異なります。

毎時実行のような高頻度設定を行う前に、プラン上の上限を確認してください。詳細は以下の記事も参照できます。

Apidog CLIでワークフローを自動化する

スケジュール済みタスクのUIに加えて、Apidog CLIを使う方法もあります。

CLIでは、保存済みシナリオをヘッドレスで実行し、cronやCIプロバイダー側でスケジューリングします。

Apidog CLIにはネイティブのスケジュールコマンドはありません。実行頻度の制御はcronやCIのスケジュール機能で行います。

インストールと認証後、シナリオIDと環境IDを指定して実行します。Apidog CLIインストールガイドではトークン設定を確認できます。

npm install -g apidog-cli
apidog login --with-token <YOUR_TOKEN>
apidog run --access-token $APIDOG_ACCESS_TOKEN -t <SCENARIO_ID> -e <ENV_ID> -r cli,junit

主なオプションは以下です。

オプション	用途
`-t`	テストシナリオID
`-e`	環境ID
`-r`	レポーター。`cli`、`html`、`junit`を指定可能。複数指定はカンマ区切り

cronで毎晩実行する

Linuxサーバーなどでcronを利用する場合、次のように設定できます。

0 2 * * * cd /srv/api-tests && apidog run --access-token $APIDOG_ACCESS_TOKEN -t 4471 -e 88 -r junit >> run.log 2>&1

この例では、毎日2:00にテストを実行し、標準出力とエラー出力をrun.logへ追記します。

GitHub Actionsでスケジュール実行する

GitHub ActionsのスケジュールトリガーからCLIを実行することもできます。JUnitレポートを既存のパイプラインダッシュボードで扱いたい場合に有効です。

cronやGitHub Actionsのスケジュールトリガーを含む設定例は、CI/CDパイプラインでのApidog CLIを参照してください。

FAQ

現在、Apidog Cloudでスケジュール済みテストを実行できますか？

まだできません。RunnerターゲットではApidog Cloudが「近日公開」と表示されているため、現時点で利用できる実行マシンはセルフホスト型Runnerです。先にRunnerを登録してから、タスクで選択してください。

スケジュール済みタスクはどのくらいの頻度で実行できますか？

プランで許可された範囲で実行できます。ドキュメントには6時間ごと、毎週日曜日23:00などの例がありますが、スケジュール済み実行数はサブスクリプションによって制限されます。正確な上限は料金ページで確認してください。

テストが失敗した場合のみ通知を受け取るにはどうすればよいですか？

タスクの通知設定で、すべての実行ではなく失敗時のみを選択してください。その後、Slack、Teams、Webhook、Jenkins、またはEmailの通知チャンネルを追加します。

軽量なAPI健全性チェックも並行して実行すると、詳細な回帰スイートとは別に、迅速な生存確認を行えます。

スケジュール済み結果がローカル実行と異なるのはなぜですか？

リクエストはラップトップではなくRunnerのマシンから送信されるためです。Runnerのネットワーク、リージョン、VPN、ファイアウォール設定が応答に影響します。

多くの場合、これはユーザーや本番インフラに近い条件を再現できている状態です。

実行ごとに変数がリセットされます。何を確認すればよいですか？

テストシナリオデザイン画面の変数の値を保持を確認してください。有効にすると、取得した値を次回実行へ引き継げます。

無効の場合、各スケジュール済み実行は新しい状態で始まるため、実行間の値に依存するテストは失敗します。

まとめ

スケジュール済みテストを導入すると、「APIはたぶん動いている」状態から、「APIが動いていることを継続的に確認できており、失敗すればすぐ通知される」状態へ移行できます。

実装手順はシンプルです。

テストシナリオを作成する
セルフホスト型Runnerを登録する
実行環境と実行サイクルを設定する
失敗時のSlack・メール・Webhook通知を設定する
実行履歴を確認できる状態にする

CIパイプラインにも同じチェックを組み込みたい場合は、CLIとcronを組み合わせて実行できます。

Apidogをダウンロードして、最初のスケジュール済み回帰スイートを設定してみてください。

DEV Community