Travis CIでApidog CLIを用いたAPIテストの自動化方法

あなたのAPIはあなたのマシン上では動作する。単体テストはパスする。コードをマージしデプロイすると、1時間後に同僚からpingがあり、空のカートを持つユーザーに対して/checkoutエンドポイントが500エラーを返していると連絡が来る。そのバグはあなたが変更したコードにはなく、誰も再テストしなかった2つ先のサービスの契約にあった。これが、結合レベルのAPIテストが埋めるギャップであり、誰かの頭の中ではなく、コミットごとに自動的に実行したい種類のチェックだ。

Travis CIは、最も古いホスト型継続的インテグレーションサービスの一つであり、今でも優れた機能を持っている。それは、Gitリポジトリを監視し、プッシュやプルリクエストごとにクリーンな環境を立ち上げ、.travis.ymlファイルに記述したコマンドを実行することだ。ほとんどのチームは、コンパイルと単体テストのループにこれを使用している。しかし、稼働中のAPIに対して実際のHTTPテストを実行するチームははるかに少ない。高コストなバグが潜んでいるのは、まさにそこであるにもかかわらずだ。その理由は摩擦だ。APIテストランナーをCIボックスに組み込み、シークレットを安全に渡し、合否のシグナルを受け取るのは非常に面倒な作業であるため、人々はそれをスキップしてしまうのだ。

このガイドでは、Apidogコマンドラインランナーを使ってそのギャップを埋める方法を説明する。ApidogデスクトップアプリでAPIテストを設計・デバッグし、リクエストとアサーションを視覚的に確認した後、全く同じテストを単一のコマンドでTravis CI内でヘッドレスに実行できる。テストロジックをコードとして書き直す必要はなく、個別のテストハーネスを維持する必要もない。この記事では、最小限の.travis.yml、ランナーのインストール、アクセストークンの安全な受け渡し、実行する項目の選択、レポートの生成、エンドポイントが壊れたときにビルドを明確に失敗させる方法まで、全体的な手順を網羅している。続けて作業したい場合は、Apidogをダウンロードしてください。

ボタン

CIでAPIテストを実行する理由

単体テストは関数が正しい値を返すことを確認する。APIテストは、リクエストとレスポンスのサイクル全体が正しく動作することを確認する。つまり、ルートが存在するか、認証が強制されているか、ステータスコードが正しいか、JSONスキーマが一致しているか、ボディ内の値が健全か、といった点だ。これらは異なる障害モードであり、後者の種類は実際にユーザーが遭遇するものである。

ローカルで実行するのは問題ないが、そうでない場合もある。ローカルでの実行は、実行を忘れないこと、マシンが本番環境の設定と一致していること、回帰バグがすり抜けたときにコーヒーを飲んでいないこと、に依存する。継続的インテグレーションは、これら3つの言い訳をすべて排除する。すべてのプッシュは同じ環境で同じテストスイートをトリガーし、その結果はコミットとプルリクエストに添付され、誰もが確認できる。

特にAPIチームにとっては、さらに深いメリットがある。テストがAPI設計の隣にある場合、破壊的な変更は、サポートチケットとしてではなく、プッシュされた瞬間にアサーションの失敗として現れる。これがデリバリーパイプラインのどこに位置づけられるかの概念的な背景を知りたい場合は、CI/CDとは何かという解説記事が良い参考になるだろう。この記事では、Travis CIビルドの実践的な側面に焦点を当てている。

始める前に必要なもの

3つのものが必要だが、おそらくそのうちの2つは既に持っているだろう。

Travis CIに接続されたGitリポジトリ。travis-ci.comの無料枠は、利用制限内で公開リポジトリとプライベートリポジトリの両方で利用できる。

デスクトップアプリで既に構築し、正常に実行した少なくとも1つのテストシナリオを含むApidogプロジェクト。Apidogのテストシナリオは、アサーションを含むAPIリクエストの順序付きセットであり、「ログイン、注文作成、注文取得、削除」のような一連のエンドツーエンドのフローと考えるとよい。
Node.js。Apidog CLIはNode上で動作し、バージョン16以降が必要だ。Travisはnode_js言語環境でNodeを標準で提供しているため、これはほとんど1行の宣言で済む。

まだテストシナリオを構築していない場合は、まずアプリで構築すること。このワークフローの全体的なポイントは、一度視覚的にデバッグすれば、その後は永続的に自動化できることだ。CIログ内で手探りでテストを作成しようとするのは遠回りだ。優れたチェックの書き方の基本については、APIアサーション: 実践ガイドで、プッシュする前にステータスコード、レスポンスボディ、JSONスキーマを検証する方法が説明されている。

ステップ1: アクセストークンとシナリオIDを取得する

Apidog CLIはクラウドに保存されたテストをヘッドレスで実行するため、2つの認証情報が必要だ。

アクセストークン。ランナーがプロジェクトを読み取ることを許可されていることを証明するもの。Apidogアカウント設定のアクセストークンから生成する。パスワードのように扱い、プロジェクトデータへのAPIアクセスを許可する。
テストシナリオID。デスクトップアプリでシナリオを開き、そのIDをコピーするか、「CI/CDで実行」オプションを使用して、IDが事前に入力されたコマンドを生成する。

正しい最初のコマンドを取得する最も簡単な方法は、Apidogに記述させることだ。テストシナリオ内で、CI/CD実行オプションは次のようなものを生成する。

apidog run --access-token <your-access-token> -t 5564321 -e 4417023 -r cli

これがコマンドの全体像だ。認証し、シナリオ（-t）を指定し、環境（-e）を指定し、レポーター（-r）を選択する。これをコピーし、まず自分のラップトップで実行できることを確認してから、Travisに移行する。ローカルで検証することで、トークンのタイプミスをデバッグするために何十回もの失敗ビルドを費やす手間を省ける。

ステップ2: トークンを暗号化されたTravis変数として保存する

アクセストークンを.travis.ymlに決して貼り付けないでください。そのファイルはGitにコミットされるため、トークンが漏洩すると、誰でもあなたのAPIプロジェクトへの読み取りアクセス権を得てしまう。Travisには2つの安全な選択肢がある。

クリーンな方法は、TravisのWeb UIで設定するリポジトリ環境変数だ。Travisでリポジトリ設定に移動し、環境変数を見つけて以下を追加する。

APIDOG_ACCESS_TOKEN（あなたのトークン値）
APIDOG_ENV_ID（テストしたい環境ID）

ビルドログに値が表示されないように、「ビルドログに値を表示」のトグルはオフにしておく。Travisはこれらをすべてのビルドに実際の環境変数として注入し、設定はその名前で参照する。これにより、シークレットはリポジトリから完全に除外され、これが望ましい動作だ。貢献者がリポジトリをフォークしても、あなたのトークンは一緒に移動しない。

すべてをファイル内に収めたい場合は、TravisはCLI経由で暗号化された変数もサポートしている。

travis encrypt APIDOG_ACCESS_TOKEN="your-token-here" --add env.global

これにより、あなたのリポジトリのビルドのみが復号できる暗号化されたブロブが.travis.ymlに書き込まれる。どちらのアプローチも機能するが、UI経由の方がほとんどのチームにとってよりシンプルで、トークンの有効期限が切れた際のローテーションも容易だ。

ステップ3: .travis.ymlを記述する

Apidog CLIをインストールし、すべてのプッシュとプルリクエストで1つのシナリオを実行する、完全かつ最小限の設定を以下に示す。

language: node_js
node_js:
  - "18"

cache:
  npm: true

install:
  - npm install -g apidog-cli

script:
  - apidog run --access-token $APIDOG_ACCESS_TOKEN -t 5564321 -e $APIDOG_ENV_ID -r cli

3つのブロックが作業を行う。バージョン付きのlanguage: node_jsは、CLIに必要な十分な新しさのNodeランタイムを提供する。installステップはapidog-cliをグローバルにインストールし、apidogコマンドがパス上に存在するようになる。scriptステップはテストを実行する。-r cliレポーターは、可読性の高い合否サマリーをTravisログに直接出力する。これは、何かが壊れたときにあなたが見つめるものとなるだろう。

シナリオIDはハードコードされているが、シークレットは環境変数から来ることに注目してほしい。それが正しい分離だ。IDは機密情報ではないが、トークンは機密情報だ。このファイルをコミットしてプッシュすると、TravisはAPIテストを自動的に実行する。最初のグリーンビルドが、あなたのAPIに安全ネットが張られた瞬間だ。

複数のサービスを維持しており、ランナー間で共有されたメンタルモデルが必要な場合、CI/CDでのAPIテストの自動化ウォークスルーは、他のプラットフォームに適用された同じパターンを示しており、もし移行することがあればGitHub Actions版も精神的にはほとんど同じだ。

ステップ4: テストが失敗したときにビルドを失敗させる

これはチームが見落としがちな部分であり、ひっそりと全体の取り組みを台無しにしてしまう。CIジョブは、失敗したテストがビルドを赤（失敗）にした場合にのみ有用だ。ランナーが何があってもゼロで終了する場合、非常に高価なログプリンターを作ったことになる。

良いニュースがある。Apidog CLIは既に正しい動作をする。アサーションが失敗すると、apidog runプロセスはゼロ以外のステータスコードで終了し、Travisはscriptフェーズでのゼロ以外の終了をビルド失敗として扱う。したがって、上記の最小限の設定は、既にすぐに正しく失敗する。余分なつなぎ込みは必要ない。

調整できるのは、単一のリクエストがエラーになったときのシナリオ実行中の動作だ。--on-errorフラグがこれを制御する。

--on-error end は最初の失敗でシナリオを停止する。最速のフィードバックで、出力も少ない。
--on-error continue は残りのステップを実行するため、一度の実行ですべての失敗を確認できる。
--on-error ignore は実行を継続し、エラーによって実行を停止させない。

CIの場合、通常continueが最適だ。最初の赤いアサーションでジョブが中止されることなく、何が壊れたかの全体像を把握したい一方で、ビルドを失敗させるためにゼロ以外の終了ステータスで終了させる必要がある。妥当なスクリプト行は次のようになる。

script:
  - apidog run --access-token $APIDOG_ACCESS_TOKEN -t 5564321 -e $APIDOG_ENV_ID -r cli --on-error continue

コマンドに|| trueを追加して「ビルドをパスさせる」という誘惑には負けないでください。それは終了コードを飲み込み、取り除こうとしたまさにその盲点を再び持ち込むことになる。

ステップ5: HTMLレポートを生成し保持する

cliレポーターは素早い確認には適しているが、ビルドが失敗した際には、どのリクエストで、どのアサーションが失敗し、実際のレスポンスボディがどうだったか、といったより豊富な成果物が欲しくなることが多い。CLIはhtmlレポーターを使ってHTMLレポートを生成し、1回の実行で複数のレポーターをスタックできる。

script:
  - apidog run --access-token $APIDOG_ACCESS_TOKEN -t 5564321 -e $APIDOG_ENV_ID -r cli,html --out-dir ./apidog-reports

-r cli,htmlはログに出力し、スタンドアロンのHTMLファイルを書き込む。--out-dirはレポートの出力先を設定し、デフォルトは./apidog-reportsだ。ビルド終了後もそのレポートを保持するには、deployブロックで、S3バケットやGitHub Pagesなど、Travisが公開できる場所にデプロイする。よくあるパターンは次のとおりだ。

deploy:
  provider: pages
  skip_cleanup: true
  github_token: $GITHUB_TOKEN
  local_dir: apidog-reports
  on:
    branch: main

アーティファクトストレージを全く管理したくない場合は、CLIで--upload-reportを使ってレポートをApidogクラウドにプッシュできる。そこでは、追加のホスティングなしでチームがリンクからレポートを開くことができる。これは分散チームにとって最もメンテナンスの手間がかからないオプションだ。

ステップ6: 環境、データ、マトリックス実行を追加する

単一の環境に対して単一のシナリオを実行するのは良いスタートだ。実際のパイプラインは3つの方向に成長し、CLIフラグはそれぞれにきれいにマッピングされる。

複数の環境。-eフラグは、どの環境のベースURLと変数を使用するかを選択する。環境IDを入れ替えることで、すべてのプッシュ時にステージング環境に対して同じシナリオを実行し、毎晩のcronビルドで本番環境に対して実行できる。Travisのcronジョブは、設定UIでリポジトリごとに設定される。

データ駆動型実行。-dフラグ（ロングフォームは--iteration-data）は、CSVまたはJSONファイルをシナリオに供給し、行ごとに1回実行されるようにする。これにより、有効な入力、不足しているフィールド、過大なペイロード、特殊文字など、1つのシナリオ定義からすべてのエッジケースをカバーできる。ファイル駆動型のイテレーションではなく、固定回数の繰り返しが必要な場合は、-n（--iteration-count）と組み合わせて使用する。

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 5564321 -e $APIDOG_ENV_ID -d ./test-data.csv -r cli

並列シナリオ。Travisビルドマトリックスを使用すると、複数のシナリオを複数の並列ジョブで同時に実行できる。各エントリが異なるシナリオIDを持つ環境変数マトリックスを定義し、各マトリックスジョブは1つのシナリオを実行する。ビルドはすべてがパスした場合にのみグリーンになる。

env:
  - SCENARIO_ID=5564321   # checkout flow
  - SCENARIO_ID=5564322   # auth flow
  - SCENARIO_ID=5564323   # search flow

script:
  - apidog run --access-token $APIDOG_ACCESS_TOKEN -t $SCENARIO_ID -e $APIDOG_ENV_ID -r cli

スイートが成長するにつれて、シナリオを自動APIテスト用テストスイートに整理することで、マトリックスがIDの壁になるのを防ぎ、管理しやすくなる。

CIスクリプトでテストを手書きするよりも優れている理由

APIテストはcurlとjqを使ってTravisスクリプトに直接記述するか、エクスポートされたコレクションをNewmanで実行することもできる。どちらも動作するが、どちらも時間の経過とともに劣化する。

curlとシェルを組み合わせたアプローチは、すべてのアサーションを脆い文字列比較に変えてしまう。ネストされたJSONフィールドのチェックはjqのおまじないのようになり、スキーマのチェックは基本的に不可能で、APIにフィールドが追加された瞬間にgrepの半分を書き直す必要がある。結局、BashでAPI知識の2つ目の、より悪いコピーを維持することになる。

コレクションランナーのアプローチはより優れているが、CIをエクスポートと同期の儀式に結びつけてしまう。あるツールでテストを編集し、エクスポートし、JSONをコミットし、現実から乖離していないことを願うのだ。この乖離は現実のものであり、「テストはパスするがAPIは壊れている」という不満の元凶だ。我々は、この正確な失敗モードについてPostmanコレクションが唯一の信頼できる情報源ではない理由で記述しており、もし今日CIでコレクションを実行しているなら、NewmanなしでCIでPostmanコレクションを実行する方法が移行パスをカバーしている。

Apidogモデルはこのループを解消する。テスト、API設計、環境、モックサーバーがすべて一箇所に存在する。CLIはそれらのテストのライブで最新バージョンを実行するため、エクスポートするものも、乖離するものもない。アプリで不安定なアサーションを視覚的にデバッグし、保存すれば、次のCI実行がその変更を認識する。その唯一の信頼できる情報源こそが、シェルスクリプトの山ではなく、目的別に構築されたランナーを使用する最大の理由だ。現在のセットアップと比較検討している場合、APIテストに最適なPostman代替ツールのまとめ記事が、オプションを並べて提示している。

Travis CIに関する特別な注意点

Travisは何年もの間、オープンソースCIのデファクトスタンダードであり、多くの古いリポジトリが今でもこれを使用している。2026年に新たに始めるのであれば、この分野が変化していることを知っておく価値がある。現在ではGitHub Actions、GitLab CI、CircleCIがほとんどの新しいプロジェクトを担っており、我々のベストCI/CDツール比較がそれぞれのツールの位置づけを解説している。良いニュースは、Apidog CLIは設計上プラットフォームに依存しないことだ。あなたの.travis.ymlで機能する全く同じapidog runコマンドは、GitHub Actionsのステップ、GitLabの.gitlab-ci.yml、またはJenkinsのステージでも機能する。もしTravisから移行する場合でも、APIテストは変更なしで移行でき、異なるのは周囲のYAMLキーだけだ。その移植性は、テストロジックをCI固有の構文から切り離すことの静かだが確かなメリットだ。

よくある質問

CIボックスにApidogデスクトップアプリをインストールする必要がありますか？ いいえ。デスクトップアプリはテストの設計とデバッグ用です。Travisが必要とするのは、apidog-cli npmパッケージとNode 16以降のランタイムのみであり、これはnode_js言語環境で既に提供されています。CLIはクラウドに保存されたシナリオをヘッドレスで取得し、実行します。

アクセストークンとシナリオIDはどこで確認できますか？ アクセストークンはApidogアカウント設定のアクセストークンセクションで生成します。シナリオIDはデスクトップアプリの各テストシナリオで確認できます。組み込みの「CI/CDで実行」オプションを使用すると、IDが事前入力された完全なコマンドが生成され、これは動作するベースラインを素早く取得する最も速い方法です。

トークンをリポジトリから除外するにはどうすればよいですか？ TravisのWeb UIで、ビルドログ表示をオフにしてリポジトリ環境変数として設定し、設定で$APIDOG_ACCESS_TOKENとして参照します。または、travis encryptを使用して.travis.ymlに暗号化された値を保存します。生のトークンをコミットすることは絶対に避けてください。

テストが失敗した場合、実際にビルドは失敗しますか？ はい。アサーションが失敗するとapidog runコマンドはゼロ以外の終了コードで終了し、Travisはscriptフェーズでのゼロ以外の終了をビルド失敗として扱います。終了コードを|| trueで抑制しないようにしてください。1回の実行ですべての失敗を報告しつつビルドを失敗させたい場合は、--on-error continueを使用してください。

複数の環境や複数のデータセットに対してテストを実行できますか？ はい。環境を切り替えるには-e（プッシュ時にステージング、夜間cronで本番環境）、データ駆動型イテレーションのためにCSVまたはJSONデータファイルを供給するには-d、複数のシナリオを並列ジョブで実行するにはTravisビルドマトリックスを使用します。

Travis CIを使用していない場合でも、これを利用できますか？ はい。CLIコマンドはプラットフォーム間で同一です。周囲のYAMLをGitHub Actions、GitLab CI、またはJenkins向けに交換するだけで、apidog runの行は同じままです。

まとめ

Travis CIにAPIテストを導入することは、4つの手順に集約される。アクセストークンを暗号化された変数として保存し、installステップでapidog-cliをインストールし、scriptステップでapidog runを使ってシナリオを実行し、ゼロ以外の終了コードでビルドを失敗させる。そこから、スイートの成長に合わせてHTMLレポート、複数の環境、データ駆動型イテレーション、並列マトリックスを重ねていく。

専用のランナーを使用し、curl呼び出しの羅列ではなくテストを行う理由は、唯一の信頼できる情報源（Single Source of Truth）にある。視覚的に設計・デバッグし、その後、エクスポートステップによる乖離なしに、コミットごとにそれらの正確なテストのライブバージョンを実行する。あなたの/checkoutの回帰バグは、本番環境ではなくプルリクエストで捕捉されるのだ。

最初のテストシナリオを構築し、Apidogをダウンロードして、次のプッシュに組み込んでみてください。最初のビルドがグリーンになれば、それ以降のすべてのコミットは安全ネット付きでリリースされます。

ボタン