DEV Community

Cover image for Hoppscotch CLIからApidog CLIへの移行方法
Akira
Akira

Posted on • Originally published at apidog.com

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

Hoppscotch CLIは、ターミナルやCIパイプラインでAPIコレクションを実行するための無料のCLIランナーです。hopp testはコレクションファイルを読み込み、リクエスト、事前リクエストスクリプト、テストスクリプトを実行し、アサーション失敗時はゼロ以外の終了コードを返します。CIでAPIテストを回すだけなら、これで十分なケースも多いです。

今すぐApidogを試す

ただし、API開発が進むと「設計」「モック」「ドキュメント」「テスト実行」が別々のツールに分散しがちです。単一の信頼できる定義を共有できないと、スキーマのズレ、古いモック、更新されないドキュメントが発生します。そこで、Hoppscotch CLIからApidog CLIへ移行すると、APIの設計、デバッグ、モック、ドキュメント、テストを同じプロジェクト定義に集約できます。

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

まず、移行が本当に必要かを確認します。

Hoppscotch CLIを使い続けてよいケースは次の通りです。

  • CIでコレクションを実行できれば十分
  • 無料のCLIランナーだけが必要
  • セルフホスト可能なオープンソースツールを使いたい
  • API設計、モック、ドキュメントは別運用でも問題ない

一方、次の課題があるならApidog CLIへの移行を検討できます。

  • API設計、モック、ドキュメント、テストが別ツールに分かれている
  • コレクションとOpenAPI定義の同期を手作業で行っている
  • テスト結果をHTMLやJSONで共有したい
  • CI実行履歴をクラウド上で確認したい
  • CLIが実行する対象を、単なるJSONファイルではなくプロジェクト定義として管理したい

移行の目的は「ランナーを置き換えること」ではなく、「API開発の信頼できる情報源を統一すること」です。

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

まず、Hoppscotchで使っているコレクションと環境をJSONとして取り出します。

Hoppscotchアプリ（Webまたはデスクトップ）で対象コレクションを開き、コレクションメニューからエクスポートします。CIで -e に渡している環境も、環境パネルからJSONとしてエクスポートします。

既にローカルファイルを使ってCIを実行している場合は、以下のような構成になっているはずです。

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

移行に必要なファイルは主に次の2つです。

collections/
  checkout-api.json

environments/
  staging.json
Enter fullscreen mode Exit fullscreen mode

checkout-api.json がコレクション、staging.json が環境変数です。Apidog側でも同じ変数名を使うため、ファイルは削除せず残しておきます。

注意点として、現在のHoppscotch CLIはNode.js v22以降が必要です。Node 20に固定している環境ではCLI v0.26.0を使い続ける必要があります。移行時は、Nodeバージョン制約も合わせて見直すとよいでしょう。

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

Apidogでプロジェクトを作成し、Hoppscotchからエクスポートしたコレクションをインポートします。

作業手順は次の通りです。

  1. Apidogで新規プロジェクトを作成する
  2. HoppscotchからエクスポートしたコレクションJSONをインポートする
  3. OpenAPIスペックがある場合は、それもインポートする
  4. Hoppscotchの環境変数をApidog環境に再作成する
  5. 変数名を既存のリクエストやテストスクリプトと一致させる

例えば、Hoppscotchの staging.json に次のような変数がある場合：

{
  "base_url": "https://api.example.com",
  "api_token": "xxxxx"
}
Enter fullscreen mode Exit fullscreen mode

Apidogの Staging 環境にも同じキーを作成します。

base_url
api_token
Enter fullscreen mode Exit fullscreen mode

変数名を変えなければ、URLやテストスクリプトの修正を最小限にできます。

インポート後、エンドポイントは単なる実行対象ではなく、設計・モック・ドキュメント・テストに共有されるAPI定義になります。セットアップ後のCLI利用については、Apidog CLI完全ガイドとインストールガイドを参照できます。

ステップ3：hopp testをapidog runに置き換える

Hoppscotch CLIでは、ローカルのコレクションファイルを指定して実行します。

hopp test ./collections/checkout-api.json -e ./environments/staging.json
Enter fullscreen mode Exit fullscreen mode

Apidog CLIでは、Apidogプロジェクト内のテストシナリオまたはコレクションを実行します。

apidog run --access-token "$APIDOG_TOKEN" -e "Staging"
Enter fullscreen mode Exit fullscreen mode

基本的な実行モデルは同じです。

  • リクエストを実行する
  • 事前リクエストスクリプトを実行する
  • テストアサーションを評価する
  • 失敗時はゼロ以外の終了コードを返す

CI/CDで重要なのは終了コードです。Apidog CLIもアサーション失敗時にジョブを失敗させられるため、既存のCIの合否判定ロジックは大きく変える必要がありません。

認証方法は少し異なります。Hoppscotchでは --token を使いますが、Apidogではログインまたはアクセストークンを使ってプロジェクトにアクセスします。

apidog run \
  --access-token "$APIDOG_TOKEN" \
  -e "Staging"
Enter fullscreen mode Exit fullscreen mode

認証方式の詳細は、認証ウォークスルーで確認できます。

ステップ4：データ駆動型テストを移行する

HoppscotchでCSVを使って反復実行している場合、Apidogでも同じようにデータセットを渡せます。

Hoppscotch CLIの例：

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

Apidog CLIでは -d でデータファイルを指定します。

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

CSVのヘッダー行は、リクエストやアサーションで参照する変数名になります。

例：

order_id,amount,currency
1001,2500,JPY
1002,4800,JPY
Enter fullscreen mode Exit fullscreen mode

テスト内では、各行の値を変数として扱います。既存のCSVヘッダー名を維持すれば、テストロジックの変更を抑えられます。

データ駆動型テストの詳細は、データ駆動型テストガイドを参照してください。

ステップ5：レポート出力を置き換える

Hoppscotch CLIでは、JUnit XMLを出力できます。

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

Apidog CLIでは、CLI表示、HTML、JSONなどのレポート形式を選択できます。HTMLレポートは人間が読みやすく、JSONは機械処理向けです。

apidog run --access-token "$APIDOG_TOKEN" \
  -e "Staging" \
  -r html \
  --upload-report
Enter fullscreen mode Exit fullscreen mode

--upload-report を使うと、クラウド上で実行履歴を確認できます。チームやステークホルダーに結果を共有する場合、HTMLレポートやクラウド履歴は生のXMLより扱いやすいことが多いです。

ただし、既存のCIダッシュボードがJUnit XML前提の場合は、移行時にレポート連携の見直しが必要です。Apidogのレポート形式については、テストレポートガイドを確認してください。

移行前と移行後：コマンドの対応表

タスク 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 はデータ駆動型実行のデータセットを表します。同じ短縮オプションでも意味が異なるため、CI YAMLをそのまま置換しないようにしてください。

ステップ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
Enter fullscreen mode Exit fullscreen mode

実装時のポイントは次の通りです。

  • APIDOG_TOKEN はGitHub Secretsに保存する
  • YAMLにアクセストークンを直書きしない
  • 最初はHoppscotchジョブとApidogジョブを並行実行する
  • Apidogジョブが安定してからHoppscotchのインストールと実行ステップを削除する
  • 失敗時の終了コードでCIを落とす

GitHub Actionsでの使い方は、GitHub Actionsガイドを参照してください。GitLabやJenkinsなどを含むCI/CD全般については、CI/CDパイプラインガイドで確認できます。

移行チェックリスト

移行時は、次の順序で確認すると安全です。

[ ] HoppscotchのコレクションJSONをエクスポートした
[ ] Hoppscotchの環境JSONをエクスポートした
[ ] Apidogプロジェクトを作成した
[ ] コレクションまたはOpenAPI定義をインポートした
[ ] 環境変数名をApidog側で再作成した
[ ] ローカルで apidog run が成功した
[ ] CSVなどのデータ駆動型テストを確認した
[ ] レポート形式を決めた
[ ] CIにAPIDOG_TOKENをSecretsとして登録した
[ ] GitHub ActionsでApidogジョブを並行実行した
[ ] 数回グリーンになってからHoppscotchジョブを削除した
Enter fullscreen mode Exit fullscreen mode

Hoppscotchについての公平な見方

Hoppscotch CLIは、無料で高速なオープンソースのAPIテストランナーです。CIでコレクションを実行するだけなら、十分に実用的です。スタック全体をセルフホストしたいチームにも適しています。

Apidog CLIへ移行する理由は、CLI単体の優劣ではなくスコープの違いです。API設計、モック、ドキュメント、テストを同じ定義から扱いたい場合、統合されたプラットフォームの方が運用しやすくなります。

CLI同士の比較はApidog CLI vs Hoppscotch CLIで確認できます。CLIではなくAPIクライアント全体を比較している場合は、Postman vs HoppscotchとHoppscotchの代替案も参考になります。

Top comments (0)