Hoppscotch CLIとは

HoppscotchはオープンソースのAPIエコシステムです。ウェブアプリ、デスクトップアプリ、CLI、そしてセルフホスト可能なバックエンドを提供し、しばしばPostmanやInsomniaのオープンな代替として説明されます。Hoppscotch CLIは、このエコシステムで構築したコレクションをターミナルから実行する部分であり、まさにCI/CDに必要なものです。

このガイドでは、Hoppscotch CLIが何か、そのインストール方法、そしてhopp testコマンドが実際のフラグと動作するCI例を交えてどのように機能するかを説明します。他のランナーと比較検討している場合は、Hoppscotch CLIの最適な代替品の投稿でオプションが比較されており、Apidog CLI vs Hoppscotch CLIでは直接対決が解説されています。

ボタン

Hoppscotch CLIとは

Hoppscotch CLIはnpmパッケージ@hoppscotch/cliとして提供されています。その役割は限定的で有用です。Hoppscotchコレクションを受け取り、その中のすべてのリクエストを実行し、それらのリクエストに添付されたテストスクリプトを実行し、パイプラインが読み取れる合格/不合格コードで終了します。

これにより、PostmanのNewmanやInsomniaのinsoと同じカテゴリのコレクションランナーとなります。APIを設計したり、エンドポイントをモックしたり、ドキュメントを生成したりすることはありません。リクエストを実行し、アサーションをチェックします。無料でオープンソースのツールであり、セルフホストも可能なため、この集中が重要な点です。

Hoppscotchはオープンソースであるため、スタック全体を自分で実行し、CLIを自身のインスタンスに向けることができます。リクエストデータをベンダーのクラウドに置きたくないチームは、これを好む傾向があります。そのトレードオフとして、ホスティングは自分で行うことになります。

Hoppscotch CLIのインストール

npmからグローバルにインストールします。

npm i -g @hoppscotch/cli

注意すべき要件が1つあります。現在のCLIにはNode.js v22以降が必要です。もしNode 20を使用している場合はCLI v0.26.0に留まることができますが、最新リリースはv22以降を前提としています。ビルドエージェントに組み込む前にバージョンを確認してください。

node --version
hopp --version

CIイメージが古いNodeを搭載している場合、パイプラインでランタイムをv22に固定しないと、テストとは無関係に見えるインストールまたはランタイムエラーが発生する可能性があります。

hopp testコマンド

すべてhopp testを通じて実行されます。基本的な形式は、コレクションファイルを指定します。

hopp test ./my-collection.json

環境ファイルとリクエスト間の遅延を渡すことができます。

hopp test ./my-collection.json -e ./staging.env.json -d 500

ここで、-e（または--env）は環境を提供し、-d（または--delay）はリクエスト間に指定されたミリ秒数だけ待機します。これは、レート制限のあるAPIにアクセスする際に役立ちます。

コレクションがローカルファイルではなくHoppscotchインスタンス（クラウドまたはセルフホスト）にある場合、IDで参照し、パーソナルアクセストークンで認証します。

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

--tokenはパーソナルアクセストークンを渡し、--serverはセルフホストURLを指します。ホストされたHoppscotchクラウドを使用している場合は--serverを削除してください。

データ駆動型実行とレポート

2つのフラグにより、hopp testは単一の実行からCIにやさしいものへと変わります。

データ駆動型テストの場合、CSVを渡し、実行する反復回数を設定します。

hopp test ./my-collection.json --iteration-data ./users.csv --iteration-count 3

--iteration-dataは、その列が各実行で変数となるCSVを受け取り、--iteration-countはコレクションが繰り返される回数を制御します。これはNewmanの-dと同じ考え方で、「このログインフローを50アカウントに対して実行する」という一般的なケースをカバーします。

レポートの場合、CLIはJUnit XMLを出力し、ほとんどのCIシステムはこれをインポートしてテスト結果をネイティブに表示できます。

hopp test ./my-collection.json --reporter-junit ./report.xml

JUnitはCLIが生成する唯一の構造化レポート形式です。HTML成果物やホストされたリンク可能なレポートが必要な場合、これはコミットする前に知っておくべきギャップです。Apidog CLIのようなツールは、CLI、HTML、およびJSONレポートを出力して比較できます。

実行中に実際に実行されること

hopp testを実行すると、CLIはコレクションを順番にたどり、各リクエストに対して次の処理を行います。

プリリクエストスクリプトを実行し、
リクエストを送信し、
テストスクリプトを実行し、各アサーションを評価します。

テストスクリプトはHoppscotchのスクリプティングAPIを使用します。pw.test()はテストブロックを定義し、pw.expect()はその中でアサーションを作成します。リクエストに添付された小さな例は次のようになります。

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

いずれかのアサーションが失敗すると、コマンドはゼロ以外のコードで終了します。すべてがパスすると、0で終了します。この終了コードの動作がCIとの完全な契約です。ゼロ以外の終了はビルドを失敗させ、これこそが望ましい動作です。

GitHub Actionsの例

hopp testをCIに組み込むのは簡単です。このワークフローは、Node 22ランナーに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

v22を固定するsetup-nodeステップは、人々が忘れがちな部分です。これがないと、デフォルトのランナーNodeが現在のCLIには古すぎる可能性があります。

留意すべき制限事項

Hoppscotch CLIはその役割において優れており、その範囲についても正直です。

これはコレクションランナーであり、プラットフォームではありません。設計、モック、ドキュメント生成機能はありません。これらは別の場所から提供する必要があります。
コレクションのエクスポートまたはホスティングは自分で行います。CLIはコレクションファイルを実行するか、指定したインスタンスからコレクションを取得して実行します。
JUnitが唯一の構造化レポートです。組み込みのHTMLやホストされたレポート機能はありません。
Node v22以降が必要です。現在のリリースでは必須要件です。

これらは批判ではなく、小さく、無料で、オープンソースのツールのコストです。「CIでコレクションを実行する」というニーズを超えて、設計、モック、リッチなレポートによるデータ駆動型実行、APIリソースのコードとしての管理へとニーズが拡大する場合、統合されたプラットフォームが役立ちます。ApidogはAPIライフサイクル全体をカバーし、Apidog CLIの完全ガイドではターミナル側の機能が示されています。ApidogをダウンロードしてHoppscotchコレクションをインポートし、直接比較したり、移行ウォークスルーを読んだりすることができます。

FAQ

Hoppscotch CLIは無料ですか？ はい。Hoppscotchプロジェクトのオープンソースであり、エコシステム全体をセルフホストできます。公式CLIドキュメントとGitHubリポジトリを参照してください。

hopp testとNewmanの違いは何ですか？ どちらもデータ駆動型イテレーションを備えたコレクションランナーです。NewmanはPostmanコレクションを実行し、hopp testはHoppscotchコレクションを実行します。CSVイテレーションデータや終了コードに基づく合格/不合格など、概念は密接にマッピングされています。

Hoppscotch CLIはセルフホスト型サーバーからコレクションを実行できますか？ はい。hopp test <collection-id> --token <access_token> --server <your-url>を使用して、自身のインスタンスからコレクションを取得して実行できます。

HTMLレポートを生成しますか？ 直接は生成しません。--reporter-junitを介してJUnit XMLを出力します。CLI、HTML、およびJSONレポートをまとめて取得するには、Apidog CLIテストレポートと比較してください。

Hoppscotch CLIは、特にHoppscotchをすでに使用している場合やセルフホストしている場合に、CIでAPIコレクションを実行するためのクリーンで無料の方法です。その範囲を理解し、Node v22を固定し、JUnit出力を活用すれば、その唯一の役割をうまく果たします。

ボタン