ApidogセルフホストランナーでAPIテストを定期実行する設定方法

APIテストスイートは、信頼できるスケジュールで実行されてこそ役に立ちます。手動でトリガーするコレクションは、クリックすることを覚えていればバグをキャッチします。あなたが管理するマシンで夜間実行すれば、ユーザーが気づく前に午前2時にバグをキャッチできます。それがApidogランナーの仕事です。Apidogランナーは、Dockerを使ってあなたのサーバーにインストールされる自己デプロイ型サービスで、Apidogで構築したスケジュールされたテストシナリオを実行し、レポートをあなたのプロジェクトにプッシュします。

Apidogでテストをスケジュールする3つの方法については、自動APIテストのスケジューリングガイドで説明しました。その投稿では、クラウド実行、ランナー、CLIを大まかに比較しています。本記事ではランナーのパスについて詳しく掘り下げます。いつランナーが必要になるのか、どのようにデプロイするのか、スケジュールされたタスクをどのようにランナーに向けるのか、そして代替手段との比較についてです。

セルフホスト型テストランナーが必要な場合

クラウド実行は便利ですが、次の3つの状況ではチームはセルフホスト型テストランナーを選択せざるを得なくなります。

APIがプライベートネットワーク上にある場合。 https://orders.staging.internal:8443 のステージング環境は、パブリックインターネットからは解決できません。どのクラウドサービスもそこに到達することはできません。あなたのVPCまたはオフィスネットワーク内にデプロイされたランナーは、その場所からリクエストを送信するため、到達可能です。イントラネット上でセルフホスト型モックサーバーを実行するのと同じ理由です。ワークロードはネットワークアクセスがある場所に存在する必要があります。

コンプライアンスによりトラフィックが社内に留まる場合。 セキュリティチームが、現実的な顧客データを含むテストペイロードがインフラストラクチャから出ることを禁止している場合、クラウド実行は選択肢になりません。ランナーを使用すると、リクエストはあなたのサーバーから発信され、APIに直接アクセスします。テストレポートのみがApidogに戻されます。

どのラップトップにも依存しない安定したスケジュールが必要な場合。 デスクトップアプリ内でスケジュールされたテストは、アプリが閉じると停止します。CIに組み込まれたテストは、誰かがコードをプッシュしたときに実行されます。どちらも「6時間ごとに、永遠に、何があっても」という保証は提供しません。常時稼働するサーバー上のランナーは、まさにこれを実現します。

これらのいずれにも該当しない場合、おそらくランナーは必要ありません。アプリでの手動実行やCIでのCLIで十分でしょう。

Apidogランナーとは

セルフホスト型ランナーは、独立したサーバーにデプロイする自動化サービスです。チームに接続されると、以下のことが可能になります。

• Apidogテストシナリオから構築されたスケジュールされた自動テストタスクの実行
• 定期的なスケジュールでのAPIドキュメントのインポート
• セルフホスト型モック応答の提供

ランナーには2つのスコープがあります。チームレベルの汎用ランナーは1つのチームに属します。組織レベルのランナーは、組織内の全チームの全プロジェクトで共有できます。デプロイメントはどちらの場合も同じ方法で行われます。

重要な考え方として、ランナーはワーカーであり、プロジェクトのコピーではありません。テストシナリオ、環境、アサーションはApidogに残ります。ランナーはタスクを受け取り、アクセス可能な任意のネットワークに対して実行し、結果をアップロードします。チームメンバーは、何が起こったかを確認するためにランナーにSSH接続することはありません。アプリで実行履歴を開いて確認します。

前提条件

デプロイする前にこれらを確認してください。ランナーのデプロイ環境に関するドキュメントから直接引用しています。

ハードウェア。 最低2CPUコア、4GB RAMが必要です。同時タスクを実行する場合やチームの規模が大きい場合は、4コア以上、8GB RAMが推奨されます。ログとテスト成果物用に少なくとも30GBのディスク容量を確保し、快適な運用には50GBが目安です。

Docker。 ホストにはDockerバージョン20.10.0以降が必要で、20.10.13が推奨されています。サーバーが新しく構築されたばかりの場合は、まずお使いのディストリビューションの公式Docker Engineインストールガイドに従ってください。

ネットワーク。 ランナーはポート443でHTTPS経由でApidogサーバーと通信し、リアルタイムタスクディスパッチのためにWebSocket (WSS) 接続を開いたままにします。また、レポートアップロードに使用されるAWSドメインへのアウトバウンドアクセス、そしてもちろん、テスト対象となるすべてのAPIへのネットワークアクセスも必要です。ここで方向性に注意してください。ランナーは外部にダイヤルアウトします。Apidogがランナーに到達するためにインバウンドポートを開く必要がないため、運用チームとのファイアウォールに関するやり取りは短く済みます。

権限とプラン。 ランナーのデプロイはチームのリソースアクションであるため、適切なチームロールが必要です。実行できるスケジュールタスクの数はサブスクリプションティアによって異なります。現在のプランごとの制限については、Apidogの価格ページを確認してください。

ステップ1：Apidogからデプロイコマンドを取得する

Apidogは、認証トークンが組み込まれたDockerデプロイコマンドを生成します。このブログ記事を含め、ブログ記事からコピーしないでください。トークンはコンテナをチームにバインドするものです。

1. Apidogを開き、Apidogホームぺージに移動します。まだアカウントをお持ちでない場合は、Apidogを無料でダウンロードして手順を進めてください。
2. ランナーが属するチームを選択します。
3. 右側のリソースをクリックします。
4. 汎用ランナーをデプロイをクリックします。

ポップアップに完全なデプロイコマンドが表示されます。すぐにコピーしてください。これは機密性の高いトークンを含み、一度しか表示されません。チームのWikiのスニペットではなく、CIシークレットとして扱ってください。

コピーする前に、ダイアログでコマンドを調整できます。

• サーバーOS: Linux、macOS、またはWindows。
• イメージバリアント: GeneralにはNode.js 18、Java 21、Python 3、PHP 8が付属しており、これらの言語での前処理/後処理スクリプトは追加設定なしで動作します。SlimにはNode.js 18のみが含まれ、より高速にプルできます。Customは、テストが内部CA証明書や珍しいライブラリに依存する場合に、独自のDockerfileを提供できます。
• 公開ポート: ランナーをセルフホスト型モックにも使用する場合、-pでマッピングします（例: -p 80:4524）。
• マウントされたデータディレクトリ: データ駆動型実行用のCSVデータセットなど、テストシナリオがローカルデータファイルを読み込む場合、-vボリュームマウントを追加します。

汎用ランナーのドキュメントで、各オプションが詳細に説明されています。

ステップ2：コンテナを実行し、接続を確認する

対象サーバーにSSH接続し、コマンドを貼り付けて、Dockerがイメージをプルしてコンテナを起動させます。運用上、初日に設定しておくべき2つの注意点があります。

• 環境変数としてTZを渡します（例: TZ=Asia/Singapore）。これにより、「毎日02:00」がコンテナのデフォルトではなく、あなたのタイムゾーンの02:00を意味するようになります。
• ランナーバージョン2.2.5以降、イメージには非rootユーザーrunner（UID/GID 10001）が含まれています。プラットフォームがrunAsNonRootを強制する場合、エントリポイントは非rootモードでディレクトリの所有者を変更できないため、セキュリティコンテキストを適切に設定し、ボリューム権限を事前設定してください。

Apidogに戻ると、WebSocketハンドシェイクが完了すると、ランナーがチームのリソースの下に表示され、チームメンバーはタスク作成時にそれを選択できるようになります。1分以内に表示されない場合は、docker logsでコンテナログを確認し、ホストがポート443でApidogサーバーに到達できることを確認してください。厳重にロックダウンされた企業ネットワークでは、ブロックされたWSS接続が一般的な原因です。

1つのチーム内に複数のランナーをデプロイできます。チームは、ステージングVPC内に1つ、本番環境への読み取りアクセス権を持つ別のランナーを配置し、タスクごとに選択することがよくあります。

ステップ3：ランナーをターゲットにしたスケジュールタスクを作成する

ランナーがオンラインになると、スケジューリングはスクリプトではなくフォームになります。

1. プロジェクトで、テストモジュールを開き、スケジュールタスクをクリックします。タスクはフォルダ構造になっているため、リストが増えるにつれてサービスまたは環境ごとにグループ化してください。
2. タスクを作成し、6か月後でもチームメイトが理解できるような名前を付けます。「注文サービスのスモークテスト、ステージング、6時間ごと」は「test1」よりも優れています。
3. 1つ以上のテストシナリオを選択します。シナリオごとに、環境、テストデータ、繰り返し回数、リクエスト間の遅延、およびリクエスト/レスポンスボディを保存するかどうかを設定できます。
4. 環境と変数スコープを設定します。タスク内のすべてのシナリオに変数を適用するのが推奨される中間策です。フォルダ全体のスコープは強力ですが、誤って使用しやすいです。
5. 実行サイクルを設定します。毎週日曜日の午後11時、6時間ごと、何か問題が発生したことをどれくらいの速さで知る必要があるかに合わせて設定します。
6. 実行元の下で、名前でセルフホスト型ランナーを選択します。
7. 通知を設定します。すべての実行後に通知するか、失敗時のみに通知するかを選択できます。失敗時のみが健全なデフォルトです。緑色のチェックマークでいっぱいのチャネルは、誰もがそれを無視するように訓練してしまいます。

保存します。この時点から、誰かがApidogアプリを開いているかどうかにかかわらず、スケジュールはあなたのサーバーで実行されます。

ステップ4：Apidogで実行レポートを読む

各実行後、ランナーは自動的にApidogサーバーに結果をアップロードします。アプリでスケジュールタスク → 実行履歴を開くと、すべての実行（合格/不合格ステータス、シナリオごとの結果、アサーションの失敗、タイミング）を確認できます。

これは、手作りのcronとスクリプトのセットアップに対するランナーの目立たない利点です。実行はあなたのインフラストラクチャで行われますが、レポートはテストが定義されているのと同じ共有ワークスペースに届きます。火曜日の午前2時の実行が失敗した場合、調査を行うQAエンジニアは、ログファイルをサーバーで検索することなく、どのステップでどのアサーションが失敗したかをコンテキストで確認できます。

失敗通知と実行履歴を組み合わせると、監視ループが完成します。アラートが発火したら、レポートを開き、同じ環境に対してアプリで失敗したステップを手動で再現し、修正し、次の正常な実行を待ちます。

ランナー vs CLI vs クラウド：実行パスの選択

Apidogでは、アプリでの手動クリック以外にテストを実行する3つの方法があり、それぞれ異なる問題を解決します。Apidog CLI GitHub Actionsガイドでは、CIパスの完全なウォークスルーを記述しており、以下の比較表でそれぞれの位置付けを示します。

これらのパスは競合するのではなく、補完し合います。一般的なセットアップとしては、CLIがパイプライン内のすべてのデプロイをゲートし、ランナーがステージングに対して1時間ごとのスモークテストスイートと夜間の完全回帰テストを実行し、コード変更ではなくインフラストラクチャのずれや期限切れの認証情報によって引き起こされた障害を捕捉します。

タイミングに関する注意点です。スケジュールタスクのドキュメントによると、スケジュールタスクはセルフホスト型ランナーで実行するように設計されており、Apidog Cloudは利用可能になったときに選択できるようになります。もし今日中にスケジュール実行が必要で、プランのクラウド利用可能性を待てない場合は、ランナーが信頼できる選択肢となります。

FAQ

CIでApidog CLIをすでに使用している場合でも、ランナーは必要ですか？

それぞれ異なる質問に答えます。CIはプッシュ時に「この変更でAPIが壊れたか？」を教えてくれます。ランナーは「今、APIは正常か？」を一定のサイクルで教えてくれ、期限切れのトークン、機能停止した依存関係、インフラのずれによって引き起こされた、コミットが関連付けられていない障害を捕捉します。多くのチームが両方を実行しています。このパターンのCIでスケジュールされる部分については、夜間APIテストセットアップガイドを参照してください。

ランナーはイントラネットAPIに到達できますか？

はい、これがランナーが存在する主な理由です。ランナーはデプロイされているマシンからリクエストを送信します。VPCまたはオフィスネットワーク内に配置すれば、どのクラウドサービスも解決できない*.internalホストをテストできます。タスクを受信しレポートをアップロードするために、ApidogサーバーへのアウトバウンドHTTPSおよびWebSocketアクセスのみが必要です。

最小サーバー仕様は何ですか？

2CPUコア、4GB RAM、30GBディスク、およびDocker 20.10.0以降が必要です。同時スケジュールタスクを実行するチームの場合は、4コア以上、8GBに移行してください。小規模なVMやオフィスのラックにある予備のマシンでも動作します。制約は稼働時間であり、処理能力ではありません。

セルフホスト型ランナーでのスケジュールタスクにはどのプランが必要ですか？

スケジュールタスクの実行クォータはサブスクリプションティアによって異なるため、高頻度のスケジュールを計画する前に、Apidog価格ページで現在の制限を確認してください。複数のツール間で実行オプションを評価している場合は、Apidog CLI vs Postman CLI比較で各プラットフォームのテストランナー側が何を含んでいるかを確認してください。