Harness CI/CDでのApidog CLI APIテスト実行方法

Apidog CLI テストを Harness で実行するには、apidog-cli をインストールし、apidog run を実行して JUnit 結果を公開する単一の Run ステップを含む CI ステージを追加します。Apidog アクセストークンを Harness シークレットとして保存し、<+secrets.getValue("...")> 式で参照し、JUnit レポートブロックを CLI の XML 出力に向けます。このガイドでは、Harness Cloud とセルフホスト型デリゲートの両方に対応する、コピー＆ペースト可能なパイプライン YAML を提供します。

Harness CI/CDとは？

Harness CI は、Harness プラットフォームの継続的インテグレーションモジュールです。マネージドまたはセルフホスト型のビルドインフラストラクチャ上でコードをビルド、テスト、検証し、その後、デプロイのために成果物を Harness CD に引き渡します。

すべてを YAML として定義します。パイプラインには1つ以上のステージが含まれます。各ステージにはタイプがあり、CI ステージはビルドインフラストラクチャ上で実行されます。ステージ内では、実行ブロックにコマンドを実行するステップの順序付きリストが保持されます。

このモデルは API テストにきれいにマッピングされます。CI ステージを追加し、テストコマンドを実行するステップを挿入し、Harness に結果に基づいてビルドをゲートさせます。テストが失敗すると、ステップが失敗し、パイプラインが停止します。

Harness はテストレポートのために JUnit XML を読み取ります。Apidog CLI は JUnit を出力できるため、ビルドごとに合格数と不合格数を示すネイティブの「テスト」タブが表示されます。接着コードは不要です。

Harness CI の仕組み

YAML の階層は厳密なので、何かを書き始める前にネストを確認しておくと役立ちます。CI パイプラインは上から下へ、次のように構成されます。

pipeline にはメタデータと stages リストが含まれます。
各 stage には type: CI と spec があります。
ステージの spec はビルドインフラストラクチャと execution ブロックを宣言します。
execution には steps リストが保持されます。
各 step には type、name、identifier、および独自の spec があります。

シェルコマンドを実行する場合、ステップタイプは Run です。Run ステップの spec には shell フィールド（Bash、Sh、PowerShell、Pwsh、または Python）と、スクリプトを保持する command フィールドが含まれます。複数行のコマンドは YAML ブロックスカラー |- を使用して記述します。

その単一の Run ステップだけで、Apidog CLI をインストールして実行できます。このガイドのその他のすべては、その1つのステップに関する設定です。

1分でわかる Apidog CLI

Apidog CLI は、Apidog で視覚的に構築したテストシナリオを実行するコマンドラインランナーです。アプリ内でテストを設計し、どのパイプラインでもヘッドレスで実行できます。Newman が Postman コレクションを実行するのと同様です。比較については、Apidog CLI と Newman を参照してください。

npm からインストールし、単一のコマンドを実行します。

npm install -g apidog-cli
apidog run --access-token <ACCESS_TOKEN> -t <TEST_SCENARIO_ID> -e <ENVIRONMENT_ID> -r cli,junit --out-dir ./apidog-reports

CI にはいくつかのフラグが重要です。`--access-token` フラグはクラウド実行を認証し、短縮形はありません。`-e` フラグは環境を設定し、必須です。`-t` フラグは ID でテストシナリオを選択します。`-r` フラグはレポーターを選択し、`junit` はサポートされている値の1つです（`cli`、`html`、`json`、`junit`）。`--out-dir` フラグはレポートの出力先を制御し、デフォルトは `./apidog-reports` です。

この `-r cli,junit` の選択が Harness への橋渡しとなります。CLI は JUnit XML を出力ディレクトリに書き込み、Harness はそれを直接読み取ります。CLI が生成する内容の詳細については、Apidog CLI テストレポートのガイドを参照してください。

Apidog アクセストークンを Harness シークレットとして保存する

トークンを YAML に直接書き込まないでください。まず Harness シークレットマネージャーに追加し、次にそれを参照します。

Harness UI で、プロジェクト（または組織/アカウント）の設定に移動し、Secrets を開いて新しい Text シークレットを作成します。`apidog_token` という識別子を付けます。この識別子は YAML で参照するもので、表示名とは異なります。

次の式でシークレットを参照します。

<+secrets.getValue("apidog_token")>

引用符の中には識別子を使用し、表示名ではありません。組織スコープのシークレットの場合、`org.apidog_token` のように `org.` をプレフィックスとして付けます。アカウントスコープのシークレットの場合は、代わりに `account.` を使用します。

シェルコマンド内で式を一重引用符で囲みます。トークンに `$` 文字が含まれている可能性があり、一重引用符はシェルがそれを展開するのを防ぎます。トークンの設定については、Apidog CLI 認証の注意点でも詳しく読むことができます。

Harness Cloud パイプライン（推奨される開始点）

Harness Cloud は、Node.js と npm がプリインストールされた Harness マネージドのビルドマシンを提供します。維持するインフラストラクチャは不要で、Linux がすぐに実行できます。これは、動作するパイプラインを構築する最速の方法です。

Harness Cloud では、ステージの `spec` は `platform` ブロックと `type: Cloud` の `runtime` ブロックを使用します。マネージドマシンにはすでにツールが備わっているため、ここでは Run ステップで `image` を指定しません。

pipeline:
  name: Apidog API Tests
  identifier: apidog_api_tests
  projectIdentifier: YOUR_PROJECT
  orgIdentifier: YOUR_ORG
  stages:
    - stage:
        name: API Tests
        identifier: api_tests
        type: CI
        spec:
          cloneCodebase: false
          platform:
            os: Linux
            arch: Amd64
          runtime:
            type: Cloud
            spec: {}
          execution:
            steps:
              - step:
                  type: Run
                  name: Run Apidog CLI Tests
                  identifier: run_apidog_cli_tests
                  spec:
                    shell: Sh
                    command: |-
                      npm install -g apidog-cli
                      apidog run \
                        --access-token '<+secrets.getValue("apidog_token")>' \
                        -t 605067 \
                        -e 1629989 \
                        -n 1 \
                        -r cli,junit \
                        --out-dir ./apidog-reports
                    reports:
                      type: JUnit
                      spec:
                        paths:
                          - apidog-reports/*.xml

`605067` をテストシナリオ ID に、`1629989` を環境 ID に置き換えてください。`-n 1` フラグは1回イテレーションを実行します。テストは Apidog のクラウドに存在するため、パイプラインがリポジトリを必要としないため、`cloneCodebase: false` を設定します。

テスト結果の公開

Run ステップの `reports` ブロックは、Harness で結果を表示するためのものです。`type` に `JUnit` を、XML ファイルを指す `paths` リストを持つ `spec` を取ります。

reports:
  type: JUnit
  spec:
    paths:
      - apidog-reports/*.xml

Harness はネイティブレポートのために JUnit XML のみを解析します。ビルド後、「テスト」タブに各シナリオ、そのステータス、およびタイミングが表示されます。グロブ `apidog-reports/*.xml` は、CLI が `-r cli,junit` を使用してデフォルトの出力ディレクトリに書き込んだファイルと一致します。

Harness は Test Intelligence も提供しており、これは個別の `Test` ステップタイプを使用して、コード変更によって影響を受けるテストのみを実行します。この最適化は、ヘッドレス API シナリオではなく、言語レベルの単体テストを対象としています。Apidog CLI の出力を取り込むには、JUnit `reports` ブロックを持つ通常の Run ステップが正しい方法です。

レポーターを切り替える場合でも、`-r` リストには少なくとも `junit` を保持してください。これがないと、CLI は XML を書き込まず、ステップ自体が成功しても「テスト」タブは空のままになります。

セルフホスト型デリゲートの代替

プライベートネットワークアクセス、カスタムまたはレガシーランタイムが必要な場合、または Harness Cloud のビルドクレジットを避けたい場合は、デリゲートバックアップのビルドを使用します。Kubernetes デリゲートは、各ステージをポッドとして実行します。

構造は2つの点で変更されます。ステージの `spec` は `platform` および `runtime` の代わりに `infrastructure` ブロックを使用します。また、Kubernetes インフラストラクチャでは、各 Run ステップは `connectorRef` と `image` を宣言する必要があります。これは、ステップが指定したコンテナ内で実行されるためです。

        spec:
          cloneCodebase: false
          infrastructure:
            type: KubernetesDirect
            spec:
              connectorRef: YOUR_K8S_CONNECTOR
              namespace: harness-ci
          execution:
            steps:
              - step:
                  type: Run
                  name: Run Apidog CLI Tests
                  identifier: run_apidog_cli_tests
                  spec:
                    connectorRef: YOUR_DOCKER_CONNECTOR
                    image: node:20
                    shell: Sh
                    command: |-
                      npm install -g apidog-cli
                      apidog run \
                        --access-token '<+secrets.getValue("apidog_token")>' \
                        -t 605067 -e 1629989 -r cli,junit --out-dir ./apidog-reports
                    reports:
                      type: JUnit
                      spec:
                        paths:
                          - apidog-reports/*.xml

`image: node:20` の行は、ポッド内で Node.js と npm を提供します。`connectorRef` の値は、登録済みの Kubernetes および Docker コネクタを指します。1つのステージで2つのインフラストラクチャスタイルを混在させないでください。ステージは Harness Cloud（`platform` と `runtime`）またはデリゲートバックアップ（`infrastructure`）のいずれかであり、両方ではありません。

Harness Cloud とデリゲートの選択

API の場所とビルドマシンの所有者に基づいて選択してください。

要因	Harness Cloud	セルフホスト型デリゲート
セットアップ	インフラ不要、npmプリインストール済み	クラスターまたはVMを管理
ネットワーク到達性	パブリックエンドポイント	プライベートおよび内部エンドポイント
Run ステップにイメージが必要	不要	必要（Kubernetesインフラの場合）
コストモデル	ビルドクレジットを使用	自身のコンピューティングを使用
最適な用途	クラウドAPI、迅速な開始	内部API、カスタムランタイム

Apidog 環境がパブリックエンドポイントにアクセスする場合は、Harness Cloud から始めます。テスト環境が VPN の背後にある場合や、制御したいランタイムが必要な場合は、デリゲートに移行します。Run ステップと Apidog コマンドは、両者の間でほとんど同じままです。

データ駆動型実行

パラメータ化されたテストのために、CSV または JSON ファイルを実行に投入できます。`-d` フラグ（長い名前は `--iteration-data`）はデータファイルパスを受け取り、`-n` は反復回数を設定します。

apidog run --access-token <ACCESS_TOKEN> -t <TEST_SCENARIO_ID> -e <ENVIRONMENT_ID> -d ./data.csv -n 5 -r cli,junit --out-dir ./apidog-reports

これは、データ行ごとにシナリオを1回実行します。Harness の Run ステップでは、まずデータファイルを `git clone` するか、その他の方法でステージングし、次に `-d` でそのパスを指します。完全なパターンについては、Apidog CLI データ駆動型テストとより広範な自動化された API テストガイドを参照してください。

まず Apidog でテストを設計する理由

CLI は、Apidog プロジェクトにすでに存在するシナリオのみを実行します。それがポイントです。Apidog は、設計、デバッグ、テスト、モック、ドキュメント作成のためのオールインワン API プラットフォームなので、テストスイートを一度構築すればどこでも再利用できます。

スクリプトなしでビジュアルビルダーを使ってテストを設計します。リクエストを連結し、あるレスポンスから次のレスポンスに値を抽出し、UI を通じてアサーションを追加します。CLI はその正確なスイートを Harness でヘッドレスに実行するため、ローカルでデバッグしたものがパイプラインで実行されます。

Apidog はブランチサポートとチームワークスペースを備えた OpenAPI ネイティブであるため、QA エンジニアとバックエンド開発者は単一の信頼できる情報源を共有します。ブランチで承認されたシナリオは、`apidog run` コマンドが実行するのと同じシナリオになります。より広範なパイプラインパターンについては、CI/CD とは何かという入門書やGitHub Actions ワークフローガイドで同じ CLI を他のシステムでカバーしています。Apidog テストを Jenkins と統合する方法の Jenkins のチュートリアルでは、同じコマンド形式が使用されています。

Apidog を無料でダウンロードして最初のテストシナリオを構築し、上記の YAML を使用して Harness に組み込みましょう。

button

よくある質問

Harness CI/CDとは何ですか？

Harness CI/CD は、ソフトウェアのビルド、テスト、デプロイを行うためのパイプラインプラットフォームです。パイプラインはステージとステップで構成される YAML として定義します。CI ステージは、Harness が管理するクラウドマシンまたはセルフホスト型デリゲートのいずれかのビルドインフラストラクチャで実行され、CD ステージがデプロイを処理します。

Harness CI はどのように機能しますか？

パイプラインにはステージリストが保持されます。各 CI ステージには、ビルドインフラストラクチャを宣言する spec と実行ブロックがあります。実行ブロックは、順序付けられたステップのリストを実行します。Run ステップはシェルコマンドを実行する場所であり、Apidog CLI をインストールして実行します。

Harness でシークレットを保存して使用するにはどうすればよいですか？

Harness シークレットマネージャーでテキストシークレットを作成し、その識別子を控えます。YAML で <+secrets.getValue("identifier")> を使用して参照します。この際、表示名ではなく識別子を使用します。スコープに応じて org. または account. をプレフィックスとして付け、シェルコマンド内で式を一重引用符で囲みます。

Harness でテスト結果を公開するにはどうすればよいですか？

Run ステップに reports ブロックを追加し、type: JUnit と、XML ファイルを指す paths リストを設定します。Harness は JUnit XML を解析し、ビルドの「テスト」タブに結果を表示します。Apidog CLI は、-r junit または -r cli,junit を渡すとこの XML を出力します。

Harness CI は無料ですか？

Harness は CI 用の無料ティアを提供しており、Harness Cloud ビルドはプランに含まれるビルドクレジットを消費します。価格とクレジットの制限は時間の経過とともに変更されるため、ティアをコミットする前に現在の Harness の価格ページで正確な数値を確認してください。

リポジトリをクローンせずに Apidog CLI テストを実行できますか？

はい。テストが Apidog のクラウドに存在する場合、ステージで cloneCodebase: false を設定します。CLI はアクセストークンで認証し、ID でシナリオと環境をプルするため、テスト実行のためにパイプラインがソースコードを必要とすることはありません。