DEV Community

Cover image for Hoppscotch CLIとは
Akira
Akira

Posted on • Originally published at apidog.com

Hoppscotch CLIとは

HoppscotchはオープンソースのAPIエコシステムです。Webアプリ、デスクトップアプリ、CLI、セルフホスト可能なバックエンドを提供し、PostmanやInsomniaのオープンな代替としてよく紹介されます。Hoppscotch CLIは、Hoppscotchで作成したコレクションをターミナルから実行するためのツールで、CI/CDでAPIテストを自動化する用途に向いています。

今すぐApidogを試す

この記事では、Hoppscotch CLIの役割、インストール方法、hopp testの使い方、CIでの実行例を実装ベースで整理します。他のランナーと比較したい場合は、Hoppscotch CLIの最適な代替品や、Apidog CLI vs Hoppscotch CLIも参考になります。

Hoppscotch CLIとは

Hoppscotch CLIは、npmパッケージ@hoppscotch/cliとして提供されています。主な役割は次のとおりです。

  • Hoppscotchコレクションを読み込む
  • コレクション内のリクエストを実行する
  • 各リクエストに紐づくテストスクリプトを実行する
  • 成功または失敗を終了コードで返す

Hoppscotch CLI

つまり、Hoppscotch CLIはPostmanのNewmanやInsomniaのinsoと同じカテゴリの「コレクションランナー」です。API設計、モック、ドキュメント生成を行うツールではありません。リクエストを実行し、アサーションを評価することに特化しています。

Hoppscotchはオープンソースなので、スタック全体をセルフホストし、CLIを自社のHoppscotchインスタンスに向けて実行できます。APIリクエストやコレクションを外部クラウドに置きたくないチームには、この構成が適しています。ただし、インフラ運用は自分たちで担う必要があります。

Hoppscotch CLIをインストールする

Hoppscotch CLIはnpmからグローバルインストールできます。

npm i -g @hoppscotch/cli
Enter fullscreen mode Exit fullscreen mode

現在のCLIにはNode.js v22以降が必要です。Node 20を使っている場合はCLI v0.26.0に留まる選択肢がありますが、最新リリースはv22以降を前提としています。

CIに組み込む前に、ローカルまたはビルドエージェントでバージョンを確認してください。

node --version
hopp --version
Enter fullscreen mode Exit fullscreen mode

CIイメージに古いNode.jsが入っていると、APIテストの失敗ではなく、CLIのインストールや実行時エラーとして失敗する可能性があります。CIではNode.js v22を明示的に固定するのが安全です。

hopp testでコレクションを実行する

Hoppscotch CLIの実行は、基本的にhopp testコマンドで行います。

ローカルのコレクションファイルを実行する最小構成は次のとおりです。

hopp test ./my-collection.json
Enter fullscreen mode Exit fullscreen mode

環境ファイルを指定し、リクエスト間に遅延を入れる場合は次のようにします。

hopp test ./my-collection.json -e ./staging.env.json -d 500
Enter fullscreen mode Exit fullscreen mode

各オプションの意味は次のとおりです。

  • -e / --env: 環境ファイルを指定する
  • -d / --delay: リクエスト間で待機する時間をミリ秒で指定する

--delayは、レート制限があるAPIや、短時間に連続リクエストを投げたくない環境で役立ちます。

Hoppscotchインスタンス上のコレクションを実行する

コレクションがローカルファイルではなく、Hoppscotchクラウドまたはセルフホスト環境にある場合は、コレクションIDとアクセストークンを使って実行します。

hopp test <collection-id> --token <access_token> --server https://hoppscotch.your-company.com
Enter fullscreen mode Exit fullscreen mode

オプションの役割は次のとおりです。

  • --token: パーソナルアクセストークンを指定する
  • --server: セルフホストしたHoppscotchサーバーのURLを指定する

ホストされたHoppscotchクラウドを使う場合は、--serverを省略します。

hopp test <collection-id> --token <access_token>
Enter fullscreen mode Exit fullscreen mode

CIで使う場合、アクセストークンはリポジトリに直書きせず、GitHub Actions Secretsなどのシークレット管理機能に保存してください。

データ駆動型テストを実行する

hopp testではCSVを使ったデータ駆動型実行ができます。

hopp test ./my-collection.json --iteration-data ./users.csv --iteration-count 3
Enter fullscreen mode Exit fullscreen mode

主なオプションは次のとおりです。

  • --iteration-data: 各実行で変数として使うCSVファイルを指定する
  • --iteration-count: コレクションを繰り返す回数を指定する

たとえば、複数ユーザーでログインフローを検証したい場合、users.csvにテストデータを用意して実行できます。

email,password
alice@example.com,password1
bob@example.com,password2
carol@example.com,password3
Enter fullscreen mode Exit fullscreen mode

この考え方はNewmanの-dオプションに近く、「同じAPIフローを複数データで検証する」ケースに向いています。

JUnitレポートを出力する

CIでテスト結果を扱う場合は、JUnit XMLを出力します。

hopp test ./my-collection.json --reporter-junit ./report.xml
Enter fullscreen mode Exit fullscreen mode

多くのCIサービスはJUnit XMLをテスト結果として読み込めるため、ビルド画面上で成功・失敗を確認できます。

ただし、Hoppscotch CLIが生成する構造化レポート形式はJUnit XMLのみです。HTMLレポートやホストされた共有レポートが必要な場合は、この点を事前に把握しておく必要があります。Apidog CLIのようなツールでは、CLI、HTML、JSONレポートを比較できます。

実行時に何が行われるか

hopp testを実行すると、CLIはコレクション内のリクエストを順番に処理します。

各リクエストでは、主に次の処理が行われます。

  1. プリリクエストスクリプトを実行する
  2. HTTPリクエストを送信する
  3. テストスクリプトを実行する
  4. アサーションを評価する
  5. 結果に応じて終了コードを返す

テストスクリプトではHoppscotchのスクリプティングAPIを使います。pw.test()でテストブロックを定義し、pw.expect()でアサーションを記述します。

例:

pw.test("Status is 200", () => {
  pw.expect(pw.response.status).toBe(200);
});
Enter fullscreen mode Exit fullscreen mode

いずれかのアサーションが失敗すると、hopp testはゼロ以外の終了コードで終了します。すべて成功した場合は0で終了します。

CIではこの終了コードが重要です。

  • 終了コード0: ビルド成功
  • 終了コードがゼロ以外: ビルド失敗

つまり、APIテストの失敗をそのままパイプラインの失敗として扱えます。

GitHub Actionsで実行する

GitHub ActionsでHoppscotch CLIを実行する例です。Node.js v22をセットアップし、CLIをインストールしてからコレクションを実行します。

name: API tests

on: [push]

jobs:
  hopp:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 22

      - run: npm i -g @hoppscotch/cli

      - run: hopp test ./collection.json -e ./ci.env.json --reporter-junit ./report.xml
Enter fullscreen mode Exit fullscreen mode

ポイントはactions/setup-nodeでNode.js v22を明示することです。これを忘れると、ランナーのデフォルトNode.jsが古く、CLIの実行前に失敗する可能性があります。

JUnitレポートをGitHub Actionsの成果物として保存したい場合は、次のようにupload-artifactを追加できます。

      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: hopp-junit-report
          path: ./report.xml
Enter fullscreen mode Exit fullscreen mode

if: always()を付けることで、テストが失敗した場合でもレポートを保存できます。

セルフホスト環境をCIから実行する例

セルフホストしたHoppscotchインスタンスからコレクションを取得する場合、トークンはGitHub Secretsに保存します。

name: API tests

on: [push]

jobs:
  hopp:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 22

      - run: npm i -g @hoppscotch/cli

      - run: |
          hopp test ${{ secrets.HOPP_COLLECTION_ID }} \
            --token ${{ secrets.HOPP_TOKEN }} \
            --server https://hoppscotch.your-company.com \
            --reporter-junit ./report.xml
Enter fullscreen mode Exit fullscreen mode

この構成では、コレクションファイルをリポジトリに置かず、Hoppscotchインスタンス側で管理できます。

留意すべき制限事項

Hoppscotch CLIはコレクションランナーとしては有用ですが、範囲は明確です。

  • コレクションランナーであり、APIプラットフォームではありません。

    API設計、モック、ドキュメント生成は別の仕組みが必要です。

  • コレクションのエクスポートまたはホスティングは自分で管理します。

    CLIはローカルファイルを実行するか、指定したHoppscotchインスタンスからコレクションを取得して実行します。

  • 構造化レポートはJUnit XMLのみです。

    組み込みのHTMLレポートやホストされたレポート機能はありません。

  • Node.js v22以降が必要です。

    現在のリリースでは必須要件です。CIではバージョン固定を推奨します。

これらは欠点というより、小さく、無料で、オープンソースのツールであることのトレードオフです。

「CIでHoppscotchコレクションを実行する」だけであれば、Hoppscotch CLIは十分にシンプルです。一方で、設計、モック、データ駆動型実行、リッチなレポート、APIリソースのコード管理までまとめて扱いたい場合は、統合型プラットフォームの方が適している場合があります。ApidogはAPIライフサイクル全体をカバーし、Apidog CLIの完全ガイドではCLI側の機能を確認できます。ApidogをダウンロードしてHoppscotchコレクションをインポートし、直接比較することもできます。移行手順は移行ウォークスルーで確認できます。

FAQ

Hoppscotch CLIは無料ですか？

はい。Hoppscotchプロジェクトのオープンソースツールです。エコシステム全体をセルフホストすることもできます。詳細は公式CLIドキュメントとGitHubリポジトリを参照してください。

hopp testとNewmanの違いは何ですか？

どちらもデータ駆動型イテレーションに対応したコレクションランナーです。NewmanはPostmanコレクションを実行し、hopp testはHoppscotchコレクションを実行します。CSVイテレーションデータや終了コードによる合格・不合格判定など、概念は近いです。

Hoppscotch CLIはセルフホスト型サーバーからコレクションを実行できますか？

はい。次の形式で、自分のHoppscotchインスタンスからコレクションを取得して実行できます。

hopp test <collection-id> --token <access_token> --server <your-url>
Enter fullscreen mode Exit fullscreen mode

HTMLレポートを生成できますか？

直接は生成できません。Hoppscotch CLIは--reporter-junitでJUnit XMLを出力します。CLI、HTML、JSONレポートをまとめて確認したい場合は、Apidog CLIテストレポートと比較してください。

まとめ

Hoppscotch CLIは、HoppscotchコレクションをCIで実行するためのシンプルで無料の方法です。特に、すでにHoppscotchを使っているチームや、セルフホスト環境でAPIテストを回したいチームに向いています。

実装時は次の点を押さえておくと安定します。

  • Node.js v22以降を使う
  • hopp testでコレクションを実行する
  • 環境ファイルは-eまたは--envで指定する
  • データ駆動型テストには--iteration-dataを使う
  • CI連携には--reporter-junitでJUnit XMLを出力する
  • アクセストークンはシークレットとして管理する

Hoppscotch CLIの役割を「APIコレクションを実行し、終了コードで結果を返すツール」と理解しておけば、CI/CDパイプラインに無理なく組み込めます。

Top comments (0)