Apidog CLIをインストールし、環境に対してapidog runを実行し、HTMLレポートをビルド成果物としてアップロードするコマンドステップを.buildkite/pipeline.ymlに定義することで、Buildkiteで自動化されたAPIテストを実行します。このガイドでは、BuildkiteがApidogアクセストークンがログに漏洩しないようにシークレットを処理する方法を含め、完全なパイプラインについて説明します。Apidogテストはすでに存在しているものとします。一度ビジュアルに構築すれば、CIで1つのコマンドから実行できます。
始める前に、簡単な説明をします。BuildkiteはCI/CDプラットフォームです。Docker内部のイメージビルドバックエンドであるDocker BuildKitとは異なります。名前は似ていますが、これらは無関係な製品です。この記事は、CI/CDプラットフォームとしてのBuildkiteについてのみ書かれています。
Buildkiteとは
Buildkiteは、ハイブリッドモデルを中心に構築されたCI/CDプラットフォームです。ホストされたコントロールプレーン（ブラウザで表示されるダッシュボードとビルドオーケストレーション）と、実際にジョブを実行するエージェントを備えています。
この分割は重要です。コントロールプレーンは作業をスケジュールしますが、作業はエージェント上で実行されます。エージェントは、独自のインフラストラクチャやクラウドでセルフホストすることも、Buildkiteが管理するコンピューティングであるBuildkiteホスト型エージェントを使用することもできます。
これがBuildkiteを完全にホストされたCIシステムと区別する主な点です。Buildkiteがビルドを調整する間、コードとシークレットは自身のマシン上に留まることができます。APIテストの場合、これはテストがサービスとネットワークアクセスがすでに存在する場所で実行されることを意味します。
Buildkiteエージェント自体はオープンソースです。Goで書かれており、MITライセンスの下でリリースされており、ソースはGitHubで公開されています。その周囲のプラットフォームとコントロールプレーンは商用のSaaS製品です。
Buildkiteの用途
チームはBuildkiteを使用して、コードの変更によってトリガーされるあらゆる種類の自動ジョブを実行します。具体的には、成果物のビルド、単体テストおよび結合テストの実行、サービスのデプロイ、エンドツーエンドチェックの実行などです。エージェントは独自のハードウェア上で実行できるため、コンピューティング、ネットワーク境界、またはGPUなどのハードウェアに対する制御が必要なチームでよく利用されます。
APIテストはこれによく合致します。テストをステージング環境またはテスト環境に対して実行し、実際のリスポンスを検証し、契約が破られた場合にはデプロイをブロックしたいと考えるでしょう。Buildkiteは、まさにそのフローをモデル化するためのステップタイプを提供しており、以下でそれを使用します。
他のオプションと比較してBuildkiteを検討している場合、APIチーム向けのベスト継続的インテグレーションツールに関する当社のまとめでは、このユースケースにおける複数のプラットフォームの比較について説明しています。
Buildkiteパイプラインの定義方法
Buildkiteパイプラインはステップのリストです。これらを定義するデフォルトの場所は、リポジトリ内の.buildkite/pipeline.ymlファイルです。ビルドが開始されると、Buildkiteは.buildkiteという名前のディレクトリ（pipeline.ymlファイルを含む）を探します。リポジトリのルートにある非表示ではないbuildkite/ディレクトリも機能します。
トップレベルのキーはsteps:で、リストを保持します。APIテストで最もよく使用するステップタイプは次のとおりです。
- コマンドステップは、エージェントでシェルコマンドを実行します。ここでテストが実行されます。
- 待機ステップは、前のすべてのステップが完了するまでパイプラインを一時停止します。これらは、単なる
- waitリスト項目として記述します。 - ブロックステップは、
- block: "Label"として記述される手動承認ゲートを作成します。これは、本番デプロイの前に人間がクリックして続行するのに役立ちます。
コマンドステップは、頻繁に使用する一連のキーをサポートしています。これには、名前付けと参照のためのlabelとkey、スクリプトのためのcommandまたはcommands、環境変数のためのenv、ターゲティングのためのagents、シークレット値の注入のためのsecrets、保持するファイルのためのartifact_paths、ファンアウトのためのparallelism、一連の値にわたって同じステップを実行するためのmatrixなどがあります。
agentsキーはタグペアのハッシュです。これを使用して、ステップを適切なエージェントにルーティングします。たとえば、queue: "tests"のように指定します。タグを使用すると、適切なネットワークアクセスまたはツールを備えたエージェントでテストジョブを保持できます。
APIテストを実行するコピー＆ペーストパイプライン
ここに、Apidog CLIをインストールし、環境に対してテストシナリオを実行し、HTMLレポートをアップロードする最小限の.buildkite/pipeline.ymlを示します。Apidog CLIは、コマンドラインからApidogテストシナリオを実行するNode.jsツールです。
steps:
- label: ":test_tube: API tests (Apidog)"
key: "api-tests"
command: |
npm install -g apidog-cli
apidog run \
--access-token "$APIDOG_ACCESS_TOKEN" \
-t 637132 \
-e 358171 \
-r html,cli
buildkite-agent artifact upload "apidog-reports/**/*"
agents:
queue: "default"
secrets:
- APIDOG_ACCESS_TOKEN
フラグに関するいくつかの注意点です。-tは実行したいテストシナリオまたはシナリオディレクトリのIDです。-eはランタイム環境IDであり、テストが使用するベースURLと変数を指定します。-r html,cliは、人間が読める端末要約とHTMLレポートファイルの両方を要求します。--access-tokenはApidogトークンを渡し、CLIがプロジェクトにアクセスできるようにします。
Buildkiteエージェントホストには、ジョブを実行するためにすでにbuildkite-agentバイナリが利用可能です。apidog-cliは自分でインストールするだけです。すべてのフラグの詳細については、Apidog CLI完全ガイドを参照してください。
最初にターミナルから単一のAPIを実行する手順を追ってみたい場合は、CIに組み込む前の準備としてApidog CLIコマンドラインテストチュートリアルが役立ちます。
BuildkiteシークレットでApidogアクセストークンを渡す
Apidogアクセストークンは認証情報です。pipeline.ymlに直接記述したり、ビルドログに出力したりしてはいけません。Buildkiteには、Buildkiteシークレットと呼ばれるネイティブ機能が用意されています。
Buildkiteシークレットは暗号化されたキーバリューストアです。値は保存時およびTLS経由での転送時に暗号化され、Buildkiteサーバーで復号化され、クラスターごとにスコープが設定され、各クラスターは独自の暗号化キーを持ちます。これはBuildkiteホスト型エージェントとセルフホスト型エージェントの両方で機能します。ログに表示されるシークレット値はすべて自動的に編集（マスク）されます。
保存されたシークレットを使用する方法は2つあります。1つ目は、コマンドステップのsecrets:キーです。最も簡単なリスト形式では、環境変数名がシークレットキーと一致します。
steps:
- command: |
apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 637132 -e 358171 -r html,cli
secrets:
- APIDOG_ACCESS_TOKEN
保存されたシークレットが、使用したい環境変数とは異なる名前を持つ場合、ハッシュ形式を使用します。キーは環境変数名、値はシークレットのキーです。
steps:
- command: |
apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 637132 -e 358171 -r html,cli
secrets:
APIDOG_ACCESS_TOKEN: apidog_token # env var name : Buildkite secret key
2つ目の方法は、エージェントCLIを使用してスクリプト内でシークレットを命令的に取得することです。これは、値がいつ読み取られるかを正確に制御したい場合に便利です。
APIDOG_ACCESS_TOKEN="$(buildkite-agent secret get apidog_token)"
apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 637132 -e 358171 -r html,cli
Buildkiteシークレットは唯一の選択肢ではありません。セルフホスト型エージェントでは、各ジョブの開始時に実行され、値を環境にエクスポートするenvironmentエージェントフックを使用できます。これを$BUILDKITE_PIPELINE_SLUGや$BUILDKITE_STEP_KEYのような変数でゲートして、シークレットが適切なジョブにのみロードされるようにすることができます。また、Buildkiteプラグインを介して、AWS Secrets Manager、HashiCorp Vault、GCPなどの外部ストアからプルすることも可能です。この場合、シークレットはBuildkiteに保存されたり送信されたりすることはありません。
単純なenv:の値は非機密設定には問題ありませんが、トークンをそこに入れないでください。シークレットストアからCLIへのトークンの流れの詳細については、Apidog CLI認証ガイドを参照してください。
HTMLレポートを成果物としてアップロードする
-r htmlレポーターは、エージェントのワークスペース内のローカルパスにHTMLレポートを書き込みます。そのファイルは、保存しない限り、ジョブが終了すると消えてしまいます。buildkite-agent artifact uploadコマンドはそれを保持します。
buildkite-agent artifact upload "apidog-reports/**/*"
グロブパターンを囲む引用符は重要です。これらは、エージェントがパターンを認識する前にシェルがパターンを展開するのを阻止し、エージェント自身がマッチングを実行するようにします。アップロードされた成果物は、デフォルトでBuildkite管理下のストレージに保存され、6か月の保持期間と成果物あたり5GBの制限があります。別の場所に送信したい場合は、2番目の引数として宛先を渡すことができます。
ビルドが実行された後、レポートはビルドの「Artifacts」タブに表示されます。ビルドを確認する誰もがダウンロードして、どのアサーションが成功または失敗したかを確認できます。まずレポート形式を理解したい場合は、Apidog CLIテストレポートガイドでCLI、HTML、JSON出力について説明しています。
複数の環境でテストを並行して実行する
同じスイートを複数の環境で同時に実行したい場合は、matrixを使用します。Buildkiteは1つのステップ定義をマトリックス値ごとに1つのジョブに展開し、それらは並行して実行されます。
steps:
- label: ":test_tube: API tests {{matrix.env}}"
command: |
npm install -g apidog-cli
apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 637132 -e "{{matrix.env}}" -r html,cli
buildkite-agent artifact upload "apidog-reports/**/*"
secrets:
- APIDOG_ACCESS_TOKEN
matrix:
setup:
env:
- "358171" # staging environment id
- "358172" # production environment id
ここでは、{{matrix.env}}がラベルと-eフラグの両方に置換されるため、各ジョブは異なるApidog環境をターゲットにします。単一のジョブの同一のコピーをファンアウトしたいだけであれば、マトリックスの代わりにステップにparallelism: 5を設定します。
データ駆動型実行の場合、1つのシナリオがCSVまたはJSONファイルの行を反復処理するときは、Buildkiteのmatrixではなく、Apidog CLIの独自の-dフラグで処理します。Apidog CLIデータ駆動型テストガイドでは、データファイルをシナリオに供給する方法が示されています。
テストに基づいてデプロイをゲートする
一般的なパターンは、テストを実行し、その完了を待ち、人間の承認を求め、それからデプロイするというものです。Buildkiteはこれをwaitおよびblockステップでモデル化します。
steps:
- label: ":test_tube: API tests"
command: "npm install -g apidog-cli && apidog run --access-token \"$APIDOG_ACCESS_TOKEN\" -t 637132 -e 358171 -r html,cli"
secrets:
- APIDOG_ACCESS_TOKEN
- wait
- block: ":rocket: Deploy?"
branches: "main"
- label: ":rocket: Deploy"
command: "scripts/deploy.sh"
waitステップは、テストが完了するまでパイプラインを保持します。blockステップは、手動クリックで一時停止し、branches:でmainブランチに制限されています。誰かが承認して初めて、デプロイステップが実行されます。これにより、失敗したテストスイートが本番環境に到達するのを防ぎます。この点に関するより広範なパターンについては、APIテストのためのCI/CDベストプラクティスを参照してください。
サマリー注釈を追加する
ビルドログは長くなりがちです。注釈は、ビルドページの上部に短くフォーマットされた要約を配置します。マークダウンをbuildkite-agent annotateにパイプすることで作成できます。
cat << 'EOF' | buildkite-agent annotate --style "success" --context "apidog"
### API test results
All Apidog scenarios passed. [Download the full HTML report](artifact://apidog-reports/index.html)
EOF
--styleフラグは色とアイコンを制御し、値としてinfo、warning、error、successを使用します。--contextフラグは注釈に一意のIDを与え、同じコンテキストを持つ後続のステップは新しい注釈を追加する代わりに同じ注釈を更新します。artifact://リンクは、レビューアをアップロードされたHTMLレポートに直接誘導します。
Apidogの位置づけ
上記のパイプラインは意図的に短くしています。テストの作成と保守という重労働は、YAMLではなくApidogで行われます。
Apidogは、APIの設計、デバッグ、テスト、モック、ドキュメント作成のためのオールインワンAPIプラットフォームです。ビジュアルエディタでテストシナリオを構築します。リクエストを連鎖させ、ステップ間でデータを渡し、スクリプトを書かずにアサーションを追加できます。シナリオはApidogプロジェクト内に存在するため、チームは一箇所で編集し、ブランチサポートでバージョン管理できます。
CLIはCIへの橋渡しです。シナリオを一度構築し、そのシナリオIDと環境IDを取得すれば、CI統合全体はたった1つのapidog runコマンドで済みます。Apidogでテストを更新すると、次のBuildkiteビルドはYAMLを編集することなく変更を反映します。この単一コマンドの特性が、ApidogがBuildkite、GitHub Actions、またはその他のシステムにクリーンに組み込める理由です。同じコマンドを他のプラットフォームで実行する方法については、Apidog CLI CI/CDパイプラインガイドおよびGitHub ActionsとApidog CLIのチュートリアルで説明しています。
CIに何も組み込む前に、まず自分のマシンで試したい場合は、次のコマンドをトークン付きでローカルで実行してください。
apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 637132 -e 358171 -r cli,html
Apidogを無料でダウンロードし、テストシナリオを構築して、その1行のapidog runコマンドをBuildkiteパイプラインにドロップしてください。
よくある質問
Buildkiteとは何ですか？
Buildkiteは、ハイブリッド設計のCI/CDプラットフォームです。ホストされたコントロールプレーンがダッシュボードを実行し、ビルドを調整する一方で、エージェントが実際のジョブを実行します。エージェントは、独自のインフラストラクチャやBuildkiteホスト型コンピューティング上で実行できます。これは、同様の名前を持つ別のイメージビルドツールであるDocker BuildKitとは無関係です。
Buildkiteは何に使われますか？
チームはBuildkiteを使用して、コード変更によってトリガーされるジョブ（成果物のビルド、テストの実行、デプロイなど）を自動化します。チームが独自のハードウェア上または独自のネットワーク内でビルドを実行したい場合に一般的に使用されます。APIチームにとっては、ステージング環境や本番環境に対して自動テストを実行し、テストが失敗した場合はデプロイをブロックすることができます。
Buildkiteはオープンソースですか？
Buildkiteエージェントはオープンソースです。Goで記述されており、MITライセンスの下でリリースされ、ソースコードはGitHubで公開されています。エージェントを取り巻くプラットフォームとコントロールプレーンは商用SaaS製品であるため、エージェント自体のみがオープンソースです。
Buildkiteは無料ですか？
はい、BuildkiteにはPersonalという無料プランがあります。クレジットカードなしで0ドルで、期限もありません。3つの同時ジョブ、1人のユーザー、90日間のデータ保持、月500分のLinuxホスト型エージェント利用、月50,000回のテスト実行が含まれます。また、有料機能を評価するための30日間のAll Accessトライアルもあります。
Buildkiteで成果物をアップロードするにはどうすればよいですか？
コマンドステップ内でbuildkite-agent artifact upload "<pattern>"を実行します。シェルではなくエージェントが一致させるようにグロブパターンを引用符で囲みます。ファイルはデフォルトでBuildkite管理下のストレージに送られ、6か月の保持期間と成果物あたり5GBの制限があります。APIテストの場合、レビューアがビルドのArtifactsタブから開けるようにHTMLレポートをアップロードします。
BuildkiteパイプラインでAPIテストを実行するにはどうすればよいですか？
.buildkite/pipeline.ymlにコマンドステップを追加し、npm install -g apidog-cliでApidog CLIをインストールします。次に、テストシナリオIDと-eを介した環境ID、およびレポート用の-r html,cliを指定してapidog runを実行します。Buildkiteシークレットを介してアクセストークンを渡し、ビルド後も結果が保持されるようにbuildkite-agent artifact uploadでHTMLレポートをアップロードします。