ReadyAPI Jenkins CI 設定ガイド - より簡単な代替案

要約

ReadyAPIテストをJenkinsで実行することは、testrunnerコマンドラインツールとSmartBear Jenkinsプラグインを通じて可能ですが、ビルドエージェントへのReadyAPIのインストールが必要であり、頻繁な構成上の問題が発生します。ApidogのCI/CD統合は、npmでインストールできるシンプルなCLIを通じて機能し、エージェントソフトウェアの要件も、実行ごとのライセンスも不要です。

💡

Apidogは、Jenkins、GitHub Actions、その他のパイプラインに、追加のライセンスなしで統合できる軽量なCLIランナーを備えた、無料のオールインワンAPI開発プラットフォームです。Apidogを無料でお試しください。クレジットカードは不要です。

ボタン

はじめに

APIテストをCI/CDパイプラインに統合することは、テストチームができる最も価値のあることの一つです。コードがステージングや本番環境に到達する前に、プルリクエストごとにリグレッションをキャッチすることは、セットアップの労力に見合う価値があります。

ReadyAPIは、コマンドラインのtestrunnerツールと公式のSmartBear Jenkinsプラグインという2つのメカニズムを通じてJenkins統合をサポートしています。どちらも機能しますが、それぞれに複雑さが伴います。このガイドでは、JenkinsでReadyAPIをセットアップする方法、発生する一般的な問題、そしてApidogがより少ないインフラオーバーヘッドで同じパイプライン統合を提供する方法について説明します。

JenkinsでReadyAPIをセットアップする：testrunnerアプローチ

testrunnerは、ReadyAPIのコマンドライン実行エンジンです。JenkinsがReadyAPIテストをヘッドレスで実行する必要がある場合、プロジェクトファイルを指す引数とともにtestrunnerを呼び出します。

前提条件：

ReadyAPIは、APIテストを実行するすべてのJenkinsエージェントにインストールされている必要があります。これが最大の運用要件です。5つのビルドエージェントがあり、ReadyAPIテストがそれらのいずれかで実行される場合、5つすべてにReadyAPIがインストールされている必要があります。これは以下の問題を引き起こします。

ReadyAPIの更新時のインストール保守の負担。
ライセンスの問題：各エージェントのインストールには独自のライセンスが必要か？SmartBearのCI/CDライセンスポリシーは契約によって異なります。アカウントチームに確認してください。
クラウドベースのエージェントのイメージサイズと起動時間の増加。

基本的なtestrunnerコマンド：

Linux/macOSの場合：

/path/to/ReadyAPI/testrunner.sh \
  -r \
  -f /path/to/results \
  -s "TestSuiteName" \
  -c "TestCaseName" \
  /path/to/project.xml

Windowsの場合：

C:\ReadyAPI\testrunner.bat ^
  -r ^
  -f C:\results ^
  -s "TestSuiteName" ^
  -c "TestCaseName" ^
  C:\projects\project.xml

testrunnerの主なフラグ：

-r: JUnit互換XMLレポートを生成
-f <directory>: 結果の出力ディレクトリ
-s <name>: 特定のテストスイートを実行（すべて実行する場合は省略）
-c <name>: 特定のテストケースを実行（すべて実行する場合は省略）
-e <environment>: 使用する環境を指定
-P <name>=<value>: プロジェクトプロパティを上書き

Jenkinsパイプラインステップ：

Jenkinsfile内：

stage('API Tests') {
  steps {
    sh '''
      /opt/readyapi/testrunner.sh \
        -r \
        -f ${WORKSPACE}/test-results \
        -e ${ENVIRONMENT} \
        ${WORKSPACE}/project.xml
    '''
    junit 'test-results/*.xml'
  }
}

junitステップは結果をJenkinsに公開し、ビルドレポートに失敗が表示されるようにします。

SmartBear Jenkinsプラグインの使用

SmartBearは、Jenkinsプラグインディレクトリから利用できるReadyAPI用のJenkinsプラグインを維持しています。このプラグインは、シェルコマンドを手動で記述する代わりに、Jenkins UIにビルドステップを提供します。

インストールするには：

Jenkins > Jenkinsの管理 > プラグインの管理に移動します。
「SmartBear ReadyAPI Functional Testing」を検索します。
インストールし、Jenkinsを再起動します。

インストール後、Jenkinsのグローバル設定でReadyAPIのインストールパスを設定し、ビルドステップドロップダウンから選択して、ビルドジョブにReadyAPIテストステップを追加します。

このプラグインは、引数構築を処理し、結果をJenkinsのテストレポートに統合します。GUI構成をGroovyパイプラインスクリプトよりも好むチームにとって、このプラグインはセットアップ時間を短縮します。

プラグインの制限： このプラグインは特定のJenkinsバージョンとReadyAPIバージョンに縛られています。プラグインの更新は、ReadyAPIのリリースとJenkinsのリリースの両方よりも遅れる傾向があります。最新のReadyAPIを実行しているチームは、プラグインの更新を待つ必要がある互換性の問題に遭遇する可能性があります。

Jenkins + ReadyAPIの一般的な問題

testrunnerが起動時にハングする。 ReadyAPIはJava/Swingアプリケーションです。CIでヘッドレスに起動すると、GUIコンポーネントを初期化しようとすることがあります。これに遭遇した場合は、DISPLAY環境変数を設定するか、-Djava.awt.headless=true JVM引数を使用してください。

ライセンス検証の失敗。 ReadyAPIは起動時にライセンスを検証します。CIエージェントがSmartBearのライセンスサーバーに到達できない場合（ロックダウンされた企業ネットワークでよくあること）、テストはテスト失敗ではなくライセンスエラーで失敗します。フローティングライセンスサーバー設定またはオフラインライセンスを設定する必要があります。

メモリ不足エラー。 testrunnerのデフォルトのJVMヒープ設定は控えめです。大規模なテストスイートや多くのデータファイルを含むプロジェクトでは、-Xmx設定の調整が必要になる場合があります。ヒープを増やすには、testrunner.shまたはtestrunner.batファイルを編集します。

-Xms128m -Xmx1024m

プロジェクトファイルのパスに関する問題。 ReadyAPIプロジェクトは、外部ファイル（データソース、スキーマ、スクリプト）をパスを使用して参照します。CIで実行する場合、作業ディレクトリが正しく設定されている場合にのみ相対パスが機能します。プロジェクトファイル内の絶対パスは、プロジェクトがマシン間を移動するときに問題を引き起こします。パスにはプロジェクトプロパティを使用し、実行時に-Pフラグを介して設定します。

テストはローカルでは合格するが、CIでは失敗する。 環境の違いによって引き起こされることがよくあります。外部ファイル内の異なるデータ、異なる環境変数値、またはハードコードされたパスなどです。testrunnerの-e引数で明示的な環境選択を行うReadyAPIの環境機能を使用してください。

Apidog Jenkins統合：よりシンプルなアプローチ

ApidogのCLIランナーはnpm経由でインストールされ、ビルドエージェントにデスクトップアプリケーションを必要としません。

Jenkinsエージェントへのインストール：

npm install -g apidog-cli

またはパイプラインステップで：

npm ci
# apidog-cli is in devDependencies

Jenkinsfileでテストを実行する：

stage('API Tests') {
  steps {
    sh '''
      apidog run \
        --collection ${WORKSPACE}/apidog-collection.json \
        --environment staging \
        --reporter junit \
        --reporter-junit-export ${WORKSPACE}/results/report.xml
    '''
    junit 'results/report.xml'
  }
}

ReadyAPIとの主な違い：

エージェントにデスクトップアプリケーションは不要です。Apidog CLIは軽量なNode.jsパッケージです。数分ではなく数秒でインストールできます。GUI初期化の問題も、ライセンスサーバー接続要件もありません。

実行ごとのライセンスに関する懸念はありません。ApidogはCI実行ごとに課金しません。パイプラインが必要とするだけ、1日に何回でもテストサイクルを実行できます。

環境変数またはフラグによる環境構成。Jenkins認証情報ストアから直接環境変数として資格情報とベースURLを渡します。

withCredentials([string(credentialsId: 'api-key', variable: 'API_KEY')]) {
  sh 'apidog run collection.json -e production --env-var "apiKey=${API_KEY}"'
}

GitHub Actionsとの比較：

GitHub Actionsも使用しているチームにとって、Apidogのアプローチは同様にクリーンです。

- name: Run API tests
  run: |
    npm install -g apidog-cli
    apidog run collection.json --environment staging
  env:
    API_BASE_URL: ${{ vars.STAGING_URL }}
    API_KEY: ${{ secrets.API_KEY }}

ReadyAPIの同等のものには、ReadyAPIがインストールされたセルフホストランナーか、複雑なDockerイメージのビルドが必要です。どちらもApidogほど簡単ではありません。

CI/CDをReadyAPIからApidogに移行する

テストスイートを移行し、CI/CD構成を同時に更新する必要がある場合：

ReadyAPIからAPI定義をエクスポートし、Apidogにインポートします。
JenkinsエージェントにApidog CLIをインストールします。
既存のReadyAPIステップと並行して、Apidogテストステップをパイプラインに追加します。
両方を並行して実行します。失敗率とテストカバレッジを比較します。
Apidogのカバレッジに自信を持ったら、ReadyAPIステップを削除します。
次回のエージェントイメージ更新時に、ビルドエージェントからReadyAPIを削除します。

よくある質問

ReadyAPIのtestrunnerには別途CIライセンスが必要ですか？SmartBearのCI/CD利用に関するライセンスポリシーは契約によって異なります。一部の契約では標準ライセンスにCI/CD実行権が含まれていますが、その他では別途契約が必要です。CI実行がカバーされていると仮定する前に、契約を確認するか、SmartBearのアカウントマネージャーにお問い合わせください。

ReadyAPIテストはDockerコンテナで実行できますか？はい、努力次第で可能です。ReadyAPIがインストールされたDockerイメージを構築し、それをJenkinsエージェントコンテナとして使用できます。イメージは大きく（ReadyAPIはデスクトップアプリケーション）、ヘッドレス構成が必要です。機能しますが、コンテナ化されたCI環境向けに構築されたツールと比較すると複雑さが増します。

ApidogはJenkinsでの並列テスト実行をサポートしていますか？はい。複数のApidog CLIインスタンスをJenkinsの異なるステージで並行して実行でき、それぞれが異なるコレクションや環境を実行できます。並列実行はApidog CLIではなく、Jenkinsfileを通じて制御されます。

ApidogはJenkins用にどのようなテストレポート形式を生成しますか？ApidogのCLIはJUnit XMLレポートを生成できます。これはJenkinsがネイティブで解析し、テスト結果セクションに表示します。この形式はReadyAPIのtestrunnerが生成するものと同じです。

ApidogのテストスクリプトはCLIランナーと同じプロセスで実行されますか？はい。JavaScriptテストスクリプトはApidog CLIのNode.jsプロセス内で実行されます。個別のスクリプト実行環境を設定する必要はありません。

公式のApidog Jenkinsプラグインはありますか？Apidog CLIはJenkinsのシェルステップとして実行されるため、専用のプラグインは必要ありません。このアプローチは、JenkinsやApidogが新しいバージョンをリリースしたときに更新が必要なプラグインベースの統合よりも、保守がシンプルです。

ReadyAPIのJenkins統合は機能しますが、かなりのインフラ管理が必要です。包括的なAPIテストカバレッジを維持しながらCI/CDセットアップを簡素化したいチームにとって、ApidogのCLIアプローチは、エージェントソフトウェアの要件、ライセンスサーバーの依存関係、複雑な環境構成といった最も一般的な問題点を解消します。