CircleCIでApidog CLIのAPIテストを実行するには、`cimg/node` Dockerエグゼキュータを使用し、npmで`apidog-cli`をインストールし、アクセストークン、テストシナリオID、環境IDを使用して`apidog run`を実行する`.circleci/config.yml`ファイルを追加します。トークンとIDはCircleCIの環境変数として保存し、`store_test_results`と`store_artifacts`でJUnitおよびHTMLレポートを公開します。このガイドでは、各部分を順に説明するため、コピー＆ペーストで簡単にデプロイできます。
この記事はCIプラットフォームの選択ではなく、テストの実行についてです。まだツールを検討中の場合は、CircleCIとJenkinsの比較が役立つでしょう。ここでは、読者がすでにCircleCIを選択しており、プッシュごとにAPIスイートを実行したいと考えていることを前提としています。
CircleCIとは何か、どのように機能するか
CircleCIは、クラウドベースの継続的インテグレーションおよびデリバリーサービスです。Gitリポジトリを監視し、コミットをプッシュすると、定義されたビルド、テスト、デプロイの各ステップを実行します。これらのステップは単一のYAMLファイルで記述されるため、パイプラインはコードとともにバージョン管理されます。
すべてはリポジトリのルートにある`.circleci/config.yml`から始まります。CircleCIはプッシュごとにこのファイルを読み込み、パイプラインに変換します。現在の設定形式はバージョン`2.1`で、基本となる2.0エンジンに加えて、orb、コマンド、パラメータなどの再利用可能な構成要素が追加されています。
CircleCIの設定には3つの主要な概念があります。
- ジョブ (Jobs) は作業の単位です。各ジョブは、コードのチェックアウト、依存関係のインストール、テストコマンドの実行など、一連のステップ (steps) を実行します。
- エグゼキュータ (Executors) は、ジョブがどこで実行されるかを定義します。Dockerエグゼキュータは、Node.jsプロジェクト用の`cimg/node`のように、選択したコンテナイメージ内でステップを実行します。
- ワークフロー (Workflows) はジョブを編成します。ワークフローは、どのジョブをどの順序で実行するか、並行して実行するか、順次実行するかを決定します。
この分離はAPIテストにとって重要です。Apidog CLIをインストールしてシナリオを実行するジョブを1つ定義し、その後、関心のあるブランチでそれをトリガーするワークフローを定義します。
なぜCircleCIでAPIテストを実行するのか
CIでAPIスイートを実行することで、本番環境に到達する前に契約違反を検出できます。スキーマの変更、フィールド名の変更、壊れた認証フローなどは、サポートチケットになる代わりに、ビルドエラーとして表示されます。
Apidog CLIはまさにこのために作られています。Apidogアプリでテストシナリオを設計およびデバッグし、その同じシナリオをCIでヘッドレスに1つのコマンドで実行できます。コードでアサーションを書き直す必要はなく、別途テストハーネスを保守する必要もありません。
自動化されたチェックがパイプラインにどのように組み込まれるかの全体像を知りたい場合は、APIテストのための12のCI/CDベストプラクティスガイドも併せて読むと良いでしょう。
前提条件
設定を記述する前に、Apidogアプリでこれらを準備してください。
- アクセストークン。Apidogアカウント設定で生成します。これはヘッドレス環境でCLIを認証するために使用されます。Apidog CLI認証ガイドでは、トークンの作成とCIのシークレット処理について詳しく説明しています。
- テストシナリオID。実行したいテストシナリオを開き、URLまたはシナリオ設定からIDをコピーします。
- 環境ID。これは、ステージング環境や本番環境など、CLIが使用するベースURLと変数を指定します。
また、Gitプロバイダーに接続されたCircleCIアカウントと、CircleCIダッシュボードで有効化されたプロジェクトが必要です。
シークレットを環境変数として保存する
アクセストークンを`config.yml`にハードコードしないでください。このファイルはGitにコミットされるため、そこにトークンがあると情報漏洩につながります。
CircleCIには、安全なオプションが2つあります。
- プロジェクト環境変数 (Project environment variables)。CircleCIのUIで、プロジェクト設定を開き、次に環境変数を開き、各値を追加します。これらは暗号化され、ジョブに`$VARS`として公開されます。
- コンテキスト (Contexts)。コンテキストは、複数のプロジェクトで共有される環境変数の名前付きグループです。組織設定で「Contexts」の下に作成し、ワークフローから参照します。コンテキストは、複数のリポジトリが同じApidogトークンを共有する場合に便利です。
このガイドでは、`APIDOG_ACCESS_TOKEN`、`APIDOG_TEST_SCENARIO_ID`、`APIDOG_ENVIRONMENT_ID`の3つの変数を追加します。CLIは実行時にこれらを読み取るため、機密情報がリポジトリ内に存在することはありません。
完全なconfig.yml
以下は、コピー＆ペーストで使える完全な設定です。`.circleci/config.yml`に配置し、3つの環境変数を設定してプッシュしてください。
version: 2.1
jobs:
api-tests:
docker:
- image: cimg/node:20.11
steps:
- checkout
- run:
name: Install Apidog CLI
command: npm install -g apidog-cli
- run:
name: Run Apidog API tests
command: |
apidog run \
--access-token $APIDOG_ACCESS_TOKEN \
-t $APIDOG_TEST_SCENARIO_ID \
-e $APIDOG_ENVIRONMENT_ID \
-r cli,junit,html \
--out-dir ./reports
- store_test_results:
path: ./reports
- store_artifacts:
path: ./reports
workflows:
test-api:
jobs:
- api-tests
各部分が何をするか、詳しく見ていきましょう。
エグゼキュータ
docker:
- image: cimg/node:20.11
`cimg/node`は、Node.js用のCircleCIのコンビニエンスイメージです。Node、npm、および一般的なビルドツールがプリインストールされているため、追加の設定なしで`npm install -g apidog-cli`が機能します。`:20.11`タグはNodeのバージョンを固定します。チームの標準に合わせて固定してください。
ステップ
`checkout`は、リポジトリをジョブの作業ディレクトリにプルします。最初の`run`ステップはCLIをグローバルにインストールします。2番目の`run`ステップはテストを実行します。
テストコマンドを詳しく見てみましょう。
apidog run \
--access-token $APIDOG_ACCESS_TOKEN \
-t $APIDOG_TEST_SCENARIO_ID \
-e $APIDOG_ENVIRONMENT_ID \
-r cli,junit,html \
--out-dir ./reports
各フラグは1つの役割を果たします。
- `--access-token`は実行を認証します。短縮形はありません。
- `-t`はIDでテストシナリオを選択します。
- `-e`は環境を選択します。このフラグは必須です。CLIは使用するベースURLと変数を把握する必要があります。
- `-r`はレポーターを設定します。ここでは3つを要求しています。`cli`はビルドログにライブ結果を出力し、`junit`は機械可読なXMLを書き出し、`html`はブラウザで表示可能なレポートを書き出します。
- `--out-dir`は、レポートファイルをどこに書き出すかをCLIに指示します。
レポートの公開
- store_test_results:
path: ./reports
- store_artifacts:
path: ./reports
`store_test_results`は、`./reports`内のJUnit XMLをCircleCIに指定します。CircleCIはそれを解析し、ビルド上に「Tests」タブを表示するため、失敗は名前とタイミングデータとともに一覧表示されます。これにより、ログの羅列が構造化された合否ビューに変わります。
`store_artifacts`は、HTMLレポートを含む同じディレクトリをダウンロード可能なファイルとしてアップロードします。ビルド後、アーティファクトタブを開いて、レンダリングされたレポートをブラウザで表示できます。Apidog CLIテストレポートガイドでは、CLI、HTML、JSON形式についてさらに詳しく説明しています。
ワークフロー
workflows:
test-api:
jobs:
- api-tests
このワークフローは、プッシュごとに`api-tests`ジョブを実行します。特定のブランチに制限するためのフィルターを追加したり、その前後に実行される他のジョブを追加したりできます。単一のテストジョブの場合、この最小限のブロックで十分です。
メインブランチでのみテストを実行する
すべての機能ブランチで完全なAPI実行を望まない場合があります。ワークフローにブランチフィルターを追加します。
workflows:
test-api:
jobs:
- api-tests:
filters:
branches:
only:
- main
- develop
これにより、ジョブは`main`と`develop`へのプッシュでのみ実行されます。他のブランチではスキップされるため、ビルド時間はデプロイ対象のブランチに集中できます。
プロジェクト変数ではなくコンテキストを使用する
複数のリポジトリで1つのApidogトークンを共有する場合、コンテキストを使用すると一元管理できます。組織設定でコンテキストを作成し、そこに変数を追加し、その後参照します。
workflows:
test-api:
jobs:
- api-tests:
context:
- apidog-secrets
これで、ジョブは`APIDOG_ACCESS_TOKEN`およびその他の情報を`apidog-secrets`コンテキストから読み取ります。トークンを一度ローテーションするだけで、すべてのプロジェクトが新しい値を取得します。
データ駆動型実行とその他のオプション
CLIには、このガイドで紹介されている以外のフラグも多数あります。CI向けには2つ知っておくべきものがあります。
`-d`と`-n`を使用して、テストデータの行ごとにシナリオを繰り返すことができます。
apidog run \
--access-token $APIDOG_ACCESS_TOKEN \
-t $APIDOG_TEST_SCENARIO_ID \
-e $APIDOG_ENVIRONMENT_ID \
-d ./data/users.csv \
-r cli,junit \
--out-dir ./reports
`-d`フラグは、CSVまたはJSONファイルのパス、あるいは数値の保存済みデータセットIDを受け取り、行ごとにシナリオを1回実行します。データ駆動型テストガイドでは、これらのファイルの構造について説明しています。
また、`--on-error`を使用して、実行が失敗をどのように処理するかを制御できます。これは`continue`、`end`、`ignore`を受け入れます。Apidogブランチを使用するプロジェクトの場合、`--project--branch`で特定のブランチをターゲットにできます。レポートの概要をApidogクラウドにプッシュするには、`--upload-report`をフラグとして追加します。
これがApidogワークフローにどのように適合するか
Apidog CLIのポイントは、テストコードを記述したり保守したりする必要がないことです。コマンドラインまたはビジュアルテストビルダーでテストシナリオを構築し、ステータスコードやレスポンスボディにアサーションを設定して保存します。CIはその後、その正確なシナリオを実行します。
シナリオがApidogプロジェクト内に存在するため、チームは1つの場所でテストを編集できます。CIの設定はめったに変更されず、`apidog run`を呼び出すだけです。誰かがアプリでアサーションを追加すると、次のCircleCIビルドはYAMLの編集なしでそれを受け取ります。
これにより、明確な分離が保たれます。Apidogは何をテストするかを所有し、CircleCIはいつどこで実行するかを所有します。この種の作業についてCircleCIを他のランナーと比較したい場合は、APIチーム向けの継続的インテグレーションツールのまとめでトレードオフが説明されています。
プッシュごとにAPIスイートを実行する準備はできましたか？Apidogをダウンロードし、テストシナリオを構築して、上記の設定をリポジトリに配置してください。
よくある質問
CircleCIとは何ですか？
CircleCIは、クラウドベースの継続的インテグレーションおよびデリバリープラットフォームです。Gitリポジトリに接続し、`.circleci/config.yml`ファイルを読み込み、コードをプッシュするたびにビルド、テスト、デプロイのステップを自動的に実行します。これにより、これらのステップを手動で自分のマシンで実行する必要がなくなります。
CircleCIは何のために使われますか？
チームはCircleCIを使用してテストとデプロイを自動化します。一般的なジョブには、コードのコンパイル、ユニットテストと統合テストの実行、APIコントラクトのチェック、Dockerイメージの構築、ステージングまたは本番環境へのリリースが含まれます。このガイドでは、ジョブはプッシュごとにApidog CLIのAPIテストを実行します。
CircleCIは無料ですか？
CircleCIには無料プランがあり、月間ビルドクレジットが含まれており、小規模プロジェクトや個人リポジトリには十分です。より多くの並行性、より長いビルド時間、またはより大きなマシンを必要とする大規模なチームは、有料のPerformanceおよびScaleプランに移行します。正確な制限については、CircleCIの現在の料金ページを確認してください。
CircleCIはオープンソースですか？
いいえ、CircleCIは商用でホスト型の製品であり、オープンソースではありません。YAMLファイルを通じて設定し、CircleCIのインフラストラクチャまたはセルフホスト型ランナーで実行します。完全にオープンソースのCIサーバーが必要な場合は、Jenkinsが一般的な代替手段であり、CircleCIとJenkinsの比較で議論されています。
CircleCIはどのように機能しますか？
コミットをプッシュすると、CircleCIは変更を検出し、`.circleci/config.yml`を読み込み、定義したエグゼキュータ（`cimg/node` Dockerコンテナなど）を起動します。ジョブの各ステップを順番に実行し、その後結果をGitプロバイダーに報告します。ワークフローを使用すると、ジョブを連結したり並列化したりできます。これがデリバリーパイプラインにどのように適合するかの全体像については、CI/CDとは何かガイドを参照してください。