Apidog CLI APIテストをDrone CIで実行するには、Nodeイメージを使用し、`apidog-cli`をインストールし、環境に対して`apidog run`を実行するDockerパイプラインステップを追加します。ApidogアクセストークンはDroneのシークレットとして保存され、`from_secret`を通じて注入されます。このガイドでは、コピペで使える`.drone.yml`、シークレットの扱い方、ブランチによる実行制御、そしてDroneに組み込みのアーティファクトストアがない場合にテストレポートを公開する方法について説明します。
Drone CIとは何か、どのように機能するか
Droneは、オープンソースのコンテナネイティブCI/CDプラットフォームで、現在はHarnessの一部です。CI/CDは継続的インテグレーションと継続的デリバリーの略で、変更があるたびにコードを自動的にビルドしテストするプラクティスを指します。この概念自体について復習したい場合は、「CI/CDとは何か」をご覧ください。
Droneの最大の特徴はシンプルさです。各パイプラインステップは独自のDockerコンテナ内で実行されます。多数のプリインストールツールが乱雑に存在する共有ビルドエージェントはありません。各ステップにイメージを選択し、Droneはその中でコマンドを実行します。これにより、ビルドは再現可能になり、理解しやすくなります。
パイプラインは、リポジトリのルートにある`.drone.yml`ファイルで定義します。Dockerパイプラインには、`kind`、`type`、`name`の3つのトップレベルキーがあります。実際の作業は`steps`の下で行われ、各ステップは`name`、`image`、および`commands`のリストを宣言します。
kind: pipeline
type: docker
name: api-tests
steps:
- name: greeting
image: alpine
commands:
- echo hello
- echo world
Droneは`commands`を`set -e`と`set -x`付きのシェルスクリプトとして実行するため、最初の非ゼロ終了コードでビルドはすぐに失敗し、各コマンドは実行前にエコーされます。コマンドはコンテナのエントリーポイントを上書きし、作業ディレクトリはリポジトリのルートです。
なぜコンテナステップでAPIテストを実行するのか
APIテストはコントラクトの逸脱を防ぎます。レスポンスの形式やステータスコードを密かに変更するバックエンドの変更は、下流のすべてのクライアントを壊す可能性があります。プッシュごとにこれらのテストを実行することで、リリース前にリグレッションを捕捉できます。
Apidogはこのモデルによく適合します。Apidogアプリでテストを視覚的に構築・保守し、Apidog CLIを使用してコマンドラインから全く同じテストシナリオを実行します。スクリプトの書き換えや、別途テストハーネスを用意する必要はありません。APIテストをパイプラインに組み込むためのより広範なガイダンスについては、「APIテストにおけるCI/CDのベストプラクティス」をお読みください。
Apidogは、デザイン、デバッグ、テスト、モック、ドキュメント作成のためのオールインワンAPIプラットフォームです。CLIは、保存されたテストシナリオを単一の繰り返し可能なコマンドに変換する部分であり、これはまさにDroneステップが必要とするものです。
実行するApidog CLIコマンド
npmでCLIをインストールし、テストシナリオを実行します。CIでは、フラグを使って保存済みのシナリオを実行するため、ローカルのコレクションファイルを管理する必要はありません。
npm install -g apidog-cli
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -r cli
各フラグの機能は以下のとおりです。
- `--access-token` はApidogアクセストークンを渡します。短い形式はありません。
- `-t` は実行したいテストシナリオIDです。
- `-e` は環境IDであり、必須です。これにより、実行が使用するベースURLと変数が選択されます。
- `-r` はレポーターをリストします。有効な値は`cli`、`html`、`json`、`junit`です。
必要に応じて、さらにフラグを追加できます。
- `-n` または `--iteration-count` は、指定された回数だけ実行を繰り返します。
- `-d` または `--iteration-data` は、データ駆動型実行のために、CSVまたはJSONファイルパス、あるいは数値の保存済みデータセットIDを受け取ります。
- `--out-dir` はレポートの出力ディレクトリを設定します。
- `--upload-report` はレポートの概要をApidogクラウドにプッシュし、アプリで確認できます。これは単独のフラグとして使用できます。
- `--on-error` は、`continue`、`end`、または `ignore` でエラー時の動作を制御します。
- `--project` と `--branch` は、特定のプロジェクトブランチをターゲットにします。
コマンドとそのオプションの完全な説明については、「Apidog CLI完全ガイド」および「コマンドラインからのREST APIテスト」のチュートリアルをご覧ください。
Apidogテストのための完全な.drone.yml
以下は動作するパイプラインです。Nodeイメージを使用し、CLIをインストールし、シナリオを実行します。トークンはハードコードされたものではなく、Droneのシークレットから取得されます。
kind: pipeline
type: docker
name: apidog-api-tests
steps:
- name: run-api-tests
image: node:20-alpine
environment:
APIDOG_ACCESS_TOKEN:
from_secret: apidog_access_token
commands:
- npm install -g apidog-cli
- apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -r cli
trigger:
branch:
- main
event:
- push
- pull_request
`1234567`をテストシナリオIDに、`89012`を環境IDに置き換えてください。どちらもApidogアプリで確認できます。このステップは`cli`レポーターを使用しているため、詳細な合否結果はDroneのビルドログに直接出力され、ビルドを確認する誰もがそれを読むことができます。
Drone CIでのシークレットの保存
APIトークンをリポジトリにコミットしないでください。DroneはシークレットをYAMLから分離し、実行時に注入します。
ステップの`environment`ブロック（またはプラグインの`settings`ブロック）内でシークレットを参照するには、`from_secret`を使用します。記述する値はシークレットの名前であり、トークン自体ではありません。
environment:
APIDOG_ACCESS_TOKEN:
from_secret: apidog_access_token
シークレットを作成する一般的な方法は2つあります。1つ目はDrone UIを使用する方法です。リポジトリを開き、「Settings（設定）」から「Secrets（シークレット）」に進み、`apidog_access_token`という名前であなたのトークンを値として持つシークレットを追加します。2つ目はDroneコマンドラインツールを使用する方法です。
drone secret add \
--repository your-org/your-repo \
--name apidog_access_token \
--data your-apidog-token
CLIフラグはリリース間で変更される可能性があるため、お使いのバージョンのDrone CLIドキュメントで正確なフラグ名を確認してください。Droneはまた、`drone encrypt`が生成した暗号化されたブロブを別の`kind: secret` YAMLドキュメントとして埋め込む、リポジトリ内暗号化シークレットのバリアントもサポートしています。ほとんどのチームにとって、UIまたは`drone secret add`を通じて追加されるリポジトリシークレットはよりシンプルであり、推奨される出発点です。
トークンをシークレットに保存することは、他の場所で適用するのと同じ規律です。CLIが認証情報をどのように処理するかについての詳細は、「Apidog CLI認証」のガイドをご覧ください。
ブランチとイベントによる実行の制御
Droneは、作業を実行するタイミングを制御するための2つの手段を提供します。パイプラインレベルでの`trigger`と、ステップレベルでの`when`です。
`trigger`ブロックは、パイプライン全体を実行するかどうかを決定します。すべての条件が真と評価される必要があるため、以下の例は`main`をターゲットとするプッシュとプルリクエストの場合のみ実行されます。
trigger:
branch:
- main
event:
- push
- pull_request
`when`ブロックは単一のステップ内に配置され、そのステップのみの実行を制御します。これは、パイプラインの大部分をどこでも実行させつつ、より重いテストパスを特定のブランチに限定したい場合に便利です。
steps:
- name: run-api-tests
image: node:20-alpine
commands:
- npm install -g apidog-cli
- apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -r cli
when:
branch:
- main
event:
- push
どちらのブロックもグロブパターンと`include`/`exclude`サブキーをサポートしています。サポートされているイベントタイプには、`push`、`pull_request`、`tag`、`promote`、`rollback`、`cron`、`custom`があります。
アーティファクトストアなしでテストレポートを公開する
Droneにはネイティブのアーティファクトホスティング機能がありません。そのため、レポートの扱い方が変わりますが、2つの明確な選択肢があります。
最初の選択肢は最もシンプルです。`cli`レポーターを使用して、結果がビルドログに直接出力されるようにします。ほとんどのチームにとって、ログにはすでにどのアサーションが成功し、どのアサーションが失敗したかが表示されるため、これで十分です。
2番目の選択肢は、HTMLレポートを生成し、永続的な場所にアップロードすることです。Droneは、S3またはS3互換のストアにファイルをアップロードする公式S3プラグイン`plugins/s3`を公開しています。`html`レポーターと`--out-dir`を使ってレポートを生成し、アップロードステップを追加します。
steps:
- name: run-api-tests
image: node:20-alpine
environment:
APIDOG_ACCESS_TOKEN:
from_secret: apidog_access_token
commands:
- npm install -g apidog-cli
- apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -r cli,html --out-dir reports
- name: upload-report
image: plugins/s3
settings:
bucket: my-bucket
region: us-east-1
source: reports/**/*
target: /apidog-reports
access_key:
from_secret: aws_access_key
secret_key:
from_secret: aws_secret_key
このプラグインは、Apidogトークンに使用したのと同じメカニズムである`from_secret`を通じて、シークレットからAWS認証情報を読み取ります。`source`キーはアップロードするファイルのグロブであり、`target`はバケット内の宛先プレフィックスです。
レポートの内容と読み方について詳しく知りたい場合は、「Apidog CLIテストレポート」の内訳をご覧ください。
データ駆動型実行の追加
時には、1つのシナリオを多数の入力行（10個のユーザーID、数十のペイロード、一連のエッジケースなど）に対して実行する必要がある場合があります。CLIは、CSVまたはJSONファイルパス、あるいは保存されたデータセットIDを受け入れる`-d`でこれを処理します。
commands:
- npm install -g apidog-cli
- apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -d ./data.csv -r cli
`data.csv`の各行は1つのイテレーションとなり、列の値はシナリオ変数にバインドされます。完全なパターンについては、「Apidog CLIデータ駆動型テスト」で説明されています。
他のCIツールとの比較
クリーンなコンテナにCLIをインストールして1つのコマンドを実行するというDroneのパターンは、ほぼすべてのCIシステムに引き継がれます。ラッパーの構文は異なりますが、Apidogのステップは同じです。
他の場所でもパイプラインを実行している場合、ApidogにはGitHub ActionsおよびAzure Pipelines向けのチュートリアルがあります。共通の考え方は、テストはApidog内に存在し、CIツールがそれらを単にトリガーするというものです。
スコープに関する正直な注意点として：Apidog CLIは機能テストと契約テストを実行するものであり、大規模な負荷テストは行いません。エンドポイントに負荷をかけるために数千の同時仮想ユーザーが必要な場合は、専用の負荷テストツールを使用してください。APIがコミットごとに正しく動作することを確認するには、Droneステップ内のCLIで十分です。
テストを視覚的に構築し、1つのコマンドで実行する
この快適なワークフローは、作成と実行の分離にあります。Apidogでエンドポイントを設計し、リクエストを連結し、ステータスコードやレスポンスフィールドをアサートし、環境変数を再利用して、テストシナリオを視覚的に組み立てます。スイートを構築するのにコードは必要ありません。
そして、CIはコンテナステップ内で1つのCLIコマンドを使って同じスイートを実行します。チームメイトがApidogアプリでテストを更新すると、次のDroneビルドがそれを自動的に検出します。同期を保つためのテストのコピーが二重にある必要はありません。
最初のテストシナリオを構築するには、Apidogを無料でダウンロードし、上記の`.drone.yml`をリポジトリに配置して、プッシュごとに実行してください。
よくある質問
Drone CIとは？
DroneはオープンソースのコンテナネイティブCI/CDプラットフォームで、現在はHarnessの一部です。すべてのパイプラインステップを独自のDockerコンテナ内で実行し、パイプラインは`.drone.yml`ファイルで定義されます。これにより、ビルドは再現可能になり、従来のビルドエージェントに見られるプリインストールされたツールの乱雑さを回避できます。
Drone CIは無料ですか？
Droneのコアプロジェクトはオープンソースであり、セルフホストは無料です。Harnessによる買収後、DroneはHarness CI Community Editionとなり、有料のエンタープライズティアも利用可能になりました。ほとんどのチームにとって、セルフホストされたオープンソースバージョンで、このガイドのようなAPIテストを実行するのに十分です。
Drone CIはオープンソースですか？
はい。DroneはオリジナルのコンテナネイティブCIツールの1つであり、現在もオープンソースです。2020年にHarnessが買収した際、同社はプロジェクトをオープンソースとして維持することを約束し、今でもセルフホストすることができます。
Drone CIはどのように使用されますか？
チームはDroneを使用して、プッシュやプルリクエストごとにコードを自動的にビルド、テスト、デリバリーします。リポジトリに`.drone.yml`をコミットすると、Droneがそれを読み取り、各ステップをコンテナで実行します。一般的なステップには、コードのコンパイル、ユニットテストの実行、APIテストの実行、アーティファクトの外部ストレージへのアップロードなどがあります。
Drone CIでシークレットを保存するにはどうすればよいですか？
シークレットは、Drone UIのリポジトリの「Settings（設定）」から「Secrets（シークレット）」画面を通じて、またはCLIから`drone secret add`コマンドで追加します。その後、各シークレットは、ステップの`environment`ブロックまたはプラグインの`settings`ブロック内で`from_secret`を使用して参照します。ここで値はシークレットの名前です。トークン自体がYAMLに現れることはありません。
スクリプトを書かずにApidogテストをCIで実行できますか？
はい、できます。Apidogアプリでテストシナリオを視覚的に構築し、CIでは単一の`apidog run`コマンドで実行します。Droneステップに必要なのは、Nodeイメージ、`npm install -g apidog-cli`の行、そしてシナリオおよび環境IDを指す実行コマンドだけです。