Hoppscotch CLIからApidog CLIへの移行方法

Hoppscotch CLIは、ターミナルやCIパイプラインでAPIコレクションを実行するための、クリーンで無料の方法です。hopp testコマンドは、コレクションファイルを読み込み、すべてのリクエストを実行し、事前リクエストおよびテストスクリプトを実行します。アサーションが失敗するとゼロ以外のコードで終了します。多くのチームにとって、それで十分です。

しかし、ランナーはAPI作業の一部に過ぎません。ある時点で、別々のデザインツール、モックサーバー、ドキュメントサイト、そしてランナーを使いこなすことになり、それらのどれもが単一の信頼できる情報源を共有していません。通常、このような状況でチームはHoppscotch CLIからApidog CLIへの移行を検討し始めます。Apidogは、デザイン、デバッグ、モック、ドキュメンテーション、テストを一つのプラットフォームに統合し、そのCLIはCIでテストを実行します。ランナーはこれまで慣れ親しんだ形を維持します。変わるのはその周辺のすべてです。

ボタン

移行すべき時（とそうでない時）

まず自分自身に正直になりましょう。もし「CIで無料でコレクションを実行し、必要であればセルフホストしたい」という要件だけなら、Hoppscotch CLIは本当に優れたツールです。オープンソースであり、ランナーは高速で、@hoppscotch/cliは通常のnpmパッケージとして提供されます。Hoppscotchを使い続けても全く問題ありません。

以下のいずれかで問題が生じ始めたら移行を検討してください：

APIをあるツールで設計し、別のツールでモックし、さらに別のツールでドキュメントを作成しており、それらの同期を手作業で行っている場合。
テスト実行、モックサーバー、公開されたドキュメントが単一のプロジェクト定義を共有するようにしたい場合。
より豊富なレポート（利害関係者向けのHTMLレポート、機械向けのJSON）と、クラウドホストされた実行履歴が必要な場合。
エンドポイント、スキーマ、環境、ブランチを、CLIが単に実行するだけでなく管理できるコードとして扱いたい場合。

もしこのリストがあなたの日常業務と重なるなら、移行の理由はランナーではなくプラットフォームにあります。クリーンな移行方法は以下の通りです。

ステップ1：Hoppscotchのコレクションと環境をエクスポートする

HoppscotchのすべてはJSONであり、エクスポートは簡単です。

Hoppscotchアプリ（ウェブまたはデスクトップ）から、CIで実行するコレクションを開きます。コレクションのメニューから「エクスポート」を選択すると、.jsonファイルが生成されます。-eで渡す環境についても同様に、環境パネルを開き、その環境を独自のJSONファイルにエクスポートします。

もしCLIをローカルファイルに対して既に実行しているなら、これらのファイルは既にディスク上にあります。一般的なHoppscotch CIのステップは以下のようになります：

npm i -g @hoppscotch/cli
hopp test ./collections/checkout-api.json -e ./environments/staging.json

両方のファイルを保持してください。checkout-api.jsonはあなたのコレクションであり、staging.jsonはあなたの環境です。この2つが、あなたが引き継ぐペイロードの全てです。

ここでNodeのバージョンについて一点注意です。現在のHoppscotch CLIはNode.js v22以降が必要です。Node 20に固定されているチームはCLI v0.26.0を使用し続けることになります。Apidog CLIはその制約に縛られないため、移行はバージョン制約を解除する機会でもあります。

ステップ2：コレクションをApidogにインポートする

Apidogでプロジェクトを作成し（または既存のものを開き）、Hoppscotchでエクスポートしたものをインポートします。Apidogは一般的なコレクション形式とOpenAPIを読み込むため、コレクションを直接取り込むことができます。もしあなたのAPIにOpenAPIスペックがあるなら、それもインポートしてください。Apidogはインポート時にスペックを検証するため、構造上の問題は実行中にサイレントに失敗するのではなく、すぐに明らかになります。

Hoppscotchの環境を、同じ変数名でApidog環境にマッピングします。もしstaging.jsonでbase_urlとapi_tokenが定義されているなら、対応するApidog環境でそれらのキーを再作成します。名前を同じに保つことで、テストスクリプトやリクエストURLを編集する必要がなくなります。

これは、プラットフォーム側のメリットが表れ始める瞬間でもあります。インポートしたエンドポイントは、今やデザイン成果物です。スキーマを添付したり、それらからモックサーバーを生成したり、テスト対象と同じ定義からドキュメントを公開したりできます。Apidog CLI完全ガイドは、セットアップ後のすべての機能について説明しており、インストールガイドはランナーバイナリの扱いについて説明しています。

ステップ3：`hopp test`を`apidog run`にマッピングする

メンタルモデルは直接引き継がれます。Hoppscotchがコレクションファイルを実行するのに対し、Apidogはプロジェクト内のテストシナリオまたはコレクションを実行します。同じジョブですが、信頼できる情報源が異なります。

# Hoppscotch
hopp test ./collections/checkout-api.json -e ./environments/staging.json

# Apidog
apidog run --access-token $APIDOG_TOKEN -e "Staging"

どちらのコマンドも、すべてのリクエストを順番に実行し、事前リクエストスクリプトを実行し、テストアサーションを実行し、何か失敗した場合はゼロ以外の終了コードを返します。この終了コードの契約はCIが依存する部分であり、これが維持されるため、パイプラインの合否判定ロジックは変更されません。

認証は便利な方法で異なります。Hoppscotchは、クラウドまたはセルフホストのコレクションに対して--tokenを使用して個人アクセストークンを渡します。Apidogはログインまたはアクセストークンで認証を行い、それによってCLIは単一のエクスポートファイルではなく、プロジェクト内のリソースにアクセスできるようになります。以前トークンの扱いに苦労したことがあるなら、認証ウォークスルーで利用可能なオプションが説明されています。

ステップ4：データ駆動型実行を変換する

両方のツールはデータ駆動型テストを行うため、入力CSVの繰り返し実行は移行後も維持されます。

Hoppscotchでは、反復データと回数を渡します：

hopp test ./collections/checkout-api.json \
  -e ./environments/staging.json \
  --iteration-count 50 \
  --iteration-data ./data/orders.csv

Apidogでは、ランナーは-dでデータセットを受け取ります。CSVとJSONに対応しているため、インポート後も同じorders.csvが動作します：

apidog run --access-token $APIDOG_TOKEN \
  -e "Staging" \
  -d ./data/orders.csv

CSVのヘッダー行は、リクエストやアサーション内で参照する変数名となり、Hoppscotchが使用するパターンと同じなので、テスト本体を書き換える必要はありません。Apidogのデータ駆動型テストに慣れていない場合は、データ駆動型テストガイドで、列を変数にバインドし、各イテレーションで1行を実行する方法が示されています。

ステップ5：レポーターを変換する

レポート機能はプラットフォームが優位に立つ点であり、変換は簡単です。

Hoppscotchは1つのフラグでJUnit XMLファイルを出力します。ほとんどのCIシステムはこのファイルをテストパネルのために解析します：

hopp test ./collections/checkout-api.json \
  -e ./environments/staging.json \
  --reporter-junit ./reports/results.xml

Apidogは複数のレポーターを選択できます：読みやすいCLIサマリー、利害関係者に渡せるHTMLレポート、そして機械向けのJSONレポートです。共有可能な実行履歴のために、結果をクラウドにプッシュすることもできます。

# 人間が読めるHTMLレポート
apidog run --access-token $APIDOG_TOKEN \
  -e "Staging" \
  -r html \
  --upload-report

もしあなたのCIダッシュボードが特にJUnit XMLを期待している場合、ApidogはJUnitフラグではなくCLI/HTML/JSONレポーターとクラウドレポートに依存しているため、切り替えの際にはその統合を考慮してください。ほとんどのチームにとって、HTMLレポートとアップロードされたクラウド履歴は、誰も開かない生のXMLファイルよりも優れています。テストレポートガイドは、各フォーマットとその使用時期について詳しく説明しています。

移行前と移行後：コマンドのマッピング

タスク	Hoppscotch CLI	Apidog CLI
インストール	`npm i -g @hoppscotch/cli`	インストールガイドに従って
コレクションを実行	`hopp test collection.json`	`apidog run`
環境を選択	`-e env.json`	`-e "Staging"`
認証トークン	`--token <pat>`	ログイン / `--access-token`
セルフホスト / クラウドターゲット	`--server <url>`	プロジェクト + アクセストークン
データ駆動型入力	`--iteration-data orders.csv`	`-d orders.csv`
繰り返し実行	`--iteration-count 50`	反復データセット
リクエスト間の遅延を追加	`-d <ms>`	シナリオごとの設定
JUnitレポート	`--reporter-junit results.xml`	`-r json` （またはCLI / HTML）
クラウド実行履歴	組み込みなし	`--upload-report`

その表の-dフラグに注目してください。Hoppscotchでは-dはミリ秒単位の遅延を表し、Apidogでは-dはデータ駆動型実行用のデータセットを表します。同じ文字ですが、役割が異なります。これはHoppscotchからApidogへの切り替え時に人々が引っかかりやすい注意点の一つです。

ステップ6：GitHub Actionsに組み込む

最後のステップです。目標は、最初から最後までグリーンビルドを維持することです。まず、古いHoppscotchジョブの隣にApidogジョブを立ち上げ、それが合格することを確認してから、古いステップを削除してください。決して闇雲に切り替えないでください。

name: API tests
on: [push, pull_request]

jobs:
  apidog-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Apidog CLI
        run: npm install -g apidog-cli

      - name: Run API tests
        env:
          APIDOG_TOKEN: ${{ secrets.APIDOG_TOKEN }}
        run: |
          apidog run \
            --access-token "$APIDOG_TOKEN" \
            -e "Staging" \
            -d ./data/orders.csv \
            -r html \
            --upload-report

アクセストークンはリポジトリのシークレットとして保存し、YAMLには決して書き込まないでください。CLIはアサーションが失敗するとゼロ以外の終了コードを返すため、テストが失敗した場合にジョブも失敗します。これはチームがHoppscotchから既に信頼している挙動です。GitHub Actionsガイドはキャッシュとマトリックス実行について説明しており、より広範なCI/CDパイプラインガイドはGitLab、Jenkinsなどについて扱っています。

Apidogジョブが数回の実行でグリーンになったら、Hoppscotchのステップとそのnpmインストールを削除します。移行完了、ビルドは赤になることなく成功しました。

Hoppscotchについての公平な意見

これらは決してHoppscotchを非難するものではありません。そのCLIランナーは高速で無料であり、プロジェクトは完全にオープンソースであり、スタック全体をセルフホストできます。もしあなたがシンプルなランナーだけを望むなら、それはその役割を十分に果たします。切り替える理由はスコープにあります。設計、モック、ドキュメント、テストのすべてが単一の定義を共有する必要がある場合、スタンドアロンのランナーではそれが提供できず、統合されたプラットフォームなら可能です。Apidog CLI vs Hoppscotch CLIで2つのランナーを直接比較し、CLIではなくアプリを比較している場合は、Postman vs HoppscotchとHoppscotchの代替案のまとめがさらなる情報を提供します。