Insomnia API クライアントをご利用になったことがある方は、リクエストの送信、OpenAPI 仕様の設計、テストの作成を行うためのグラフィカルな場所があることをご存知でしょう。しかし、グラフィカルツールはご自身のマシン内にとどまります。それらのテストをCIパイプライン内で実行したい場合や、プルリクエストごとに仕様をLintしたいと思った瞬間、ターミナル上で動作する何かが必要になります。それが inso です。
このガイドでは、insoとは何か、そのインストール方法、日常的に使う正確なコマンド、仕様やコレクションをどのように見つけるか、そしてその限界がどこにあるかを説明します。読み終える頃には、inso CLIがあなたのワークフローに適合するかどうか、そして適合しない場合にどのようなツールを選べばよいかがわかるでしょう。
insoとは？
inso は、Kongによって現在メンテナンスされているオープンソースのAPIクライアントであるInsomniaのコマンドライン版です。InsomniaがそのUIで行う3つの機能（テストの実行、リクエストコレクションの実行、API仕様のLint）をスクリプト可能にします。これにより、デスクトップ上のInsomniaと、CI/CDで必要とされる自動チェックとの間の橋渡しとなります。
「insoとは何か」の短いバージョン：それはInsomniaを開かずにInsomniaの作業を実行する方法です。名前で設計ドキュメントやコレクションを指定すると、アプリが既に知っているのと同じデータに対して実行されます。
inso CLIのインストール
いくつかの公式なインストールパスがあります。あなたの利用方法に合ったものを選んでください。
macOSおよびLinuxではHomebrewが最もシンプルです。
brew install inso
DockerはCIランナーにとって最もクリーンな選択肢です。ローカルのツールチェーンを管理したくない場合に適しています。
docker pull kong/inso:latest
直接ダウンロードすることも可能です。Kongは、ビルド成果物に固定バージョンを含めたい場合に便利な、Windows、Linux、macOS用のzipアーカイブをinso CLIのドキュメントサイトで公開しています。
歴史的にinsoはnpmでも insomnia-inso として配布されていました。そのルートもまだ存在しますが、現在推奨される公式パスはHomebrew、Docker、および直接ダウンロードです。新しく設定する場合は、これらを優先してください。
インストールが解決したことを確認します。
inso --version
insoの主要コマンド
insoは小さく、焦点を絞ったインターフェースを持っています。ここでは、実際に使用するであろうコマンドと具体的な例を紹介します。
inso run test
Insomniaで作成した単体テストスイートを、指定された環境に対して実行します。
inso run test "Payments API tests" --env "Staging"
スイートと環境は両方とも、Insomniaデータに表示されるとおりの名前で参照されます。アサーションが失敗すると inso run test コマンドは非ゼロで終了するため、CIゲートとして利用できます。
inso run collection
コレクション内のすべてのリクエストを順番に、指定された環境に対して実行します。
inso run collection "Checkout flow" --env "Staging"
これはUIの「フォルダ全体を再生」に最も近い機能です。一連のエンドポイントがすべて期待どおりに応答することを確認するスモークテストに役立ちます。
inso lint spec
OpenAPI設計ドキュメントを検証します。
inso lint spec "Orders API"
内部的には、 inso lint spec はStoplight製のオープンソースOpenAPIおよびJSONリンターであるSpectralを使用します。これは、明白に言及する価値のある真の強みです。浅い構文チェックではなく、成熟したルールセットを備えた本格的なルールベースの仕様リンティングが得られます。チームが仕様のスタイルガイド強制を重視する場合、このコマンドは多くの人々がinsoを使い続ける理由です。
inso export spec
設計ドキュメントをディスク上のファイルに出力します。
inso export spec "Orders API" --output orders.yaml
この機能は、仕様を別のジェネレーターにフィードしたり、スナップショットをコミットしたり、プレーンなYAMLファイルを期待するツールに渡したりする場合に便利です。
inso script
Insomniaデータで定義された名前付きスクリプトを、IDで環境を渡して実行します。
inso script deploy-smoke --env env_9f2a
これは、独自のカスタムステップを連結するためのエスケープハッチです。
insoが仕様とコレクションを見つける方法
これは人々が戸惑う部分なので、正確に説明する価値があります。insoはそれ自体何も保存しません。以下の2つの場所から読み取ります。
- 作業ディレクトリ内の
.insomniaディレクトリ。これはInsomniaのGit同期が生成するもので、APIプロジェクトをリポジトリにコミットすると、insoはチェックアウトから直接それを読み取ることができます。これはCI向けのパターンです。 - アプリがマシンにインストールされている場合、Insomniaアプリケーションのデータディレクトリ。これはローカルでは便利ですが、アプリがインストールされていないクリーンなCIランナーでは役に立ちません。
ソースを明示的に上書きできます。
inso lint spec "Orders API" --workingDir ./api-project
# または正確なソースを指す
inso run test "Payments API tests" --src ./api-project/.insomnia
重要なメンタルモデル：insoはすべてを名前（またはID）で参照し、それらの名前はinsoが見つけたデータソースに対して解決されます。 .insomnia ディレクトリまたはアプリデータに名前が存在しない場合、insoはそれを実行できません。insoを単一のOpenAPIファイルにポイントして「これをテストしろ」と言う概念は、そのファイルがInsomniaプロジェクト構造内に存在しない限りありません。
最小限のCIの例
以下は、Git同期された .insomnia ディレクトリがリポジトリにコミットされていることを利用して、プッシュごとに仕様をLintし、テストスイートを実行するGitHub Actionsジョブです。
name: API checks
on: [push]
jobs:
inso:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install inso
run: |
curl -sSL https://github.com/Kong/insomnia/releases/latest/download/inso-linux-x64.zip -o inso.zip
unzip inso.zip && sudo mv inso /usr/local/bin/
- name: Lint the spec
run: inso lint spec "Orders API" --workingDir .
- name: Run the test suite
run: inso run test "Payments API tests" --env "CI" --workingDir .
どちらのコマンドも失敗時に非ゼロで終了するため、壊れた仕様や失敗したアサーションはジョブを失敗させます。これこそが、これらのチェックをGUIから移動させる目的です。
正直な限界
insoはその役割を十分に果たしますが、明確な限界もあります。
Insomniaのデータソースに縛られます。あなたの仕様、コレクション、スイートはInsomniaプロジェクト内に存在し、Git同期またはインストールされたアプリを通じて表面化される必要があります。チームがInsomniaを真のソースとして使用しない場合、insoは動作するものがありません。
すべてが名前で参照されます。これは読みやすいですが、脆いです。UIでスイートの名前を変更すると、古い名前をハードコードしたCIジョブは、次の実行までサイレントに壊れてしまいます。名前はまた、クリーンに解決されるのに十分なユニークさが必要です。
スコープは意図的に狭められています。insoはテストの実行、コレクションの実行、仕様のLint、エクスポート、スクリプトの実行を行います。これはデザイン・モック・ドキュメント・テストプラットフォームではありません。これらの動詞以外のことは、GUIに戻るか、他のツールに頼ることになります。
insoと統合された代替ソリューションの比較
Insomniaがすでにあなたのクライアントである場合、insoは強力なターミナルコンパニオンです。トレードオフとしては、複数のピースを繋ぎ合わせることになります。設計とデバッグにはInsomnia、CIにはinso、LintにはSpectralルール、モックとドキュメントには別のツールといった具合です。
Apidogは真逆のスタンスを取っています。デザイン、モック、ドキュメント、テストを1つのプラットフォームに統合し、そのApidog CLIは、データ駆動型テスト、複数のレポーター形式、コードとしてのリソースとブランチを備え、同じ真のソースからテストシナリオとコレクションを実行します。ここで公平を期すなら、Apidog CLIはinsoがSpectralで行うようなスタンドアロンの仕様リンターを提供していません。したがって、Spectralスタイルのスタイルガイド強制が優先事項である場合、insoは真の優位性を持っています。Apidogが優位に立つのは統合です。5つのツールを接着する必要はありません。
両者を比較したい場合は、Apidog CLI vs inso (Insomnia CLI)を参照するか、inso (Insomnia CLI)とは何かで詳細な背景をお読みください。insoが適切な解決策ではないと判断した場合、最適なinso代替ツールのまとめとinsoからApidog CLIへの移行ガイドで、ステップバイステップでの移行が説明されています。GUIクライアント自体に関するより広範な文脈については、Apidog vs InsomniaとInsomniaを使ったAPIテスト方法が良い出発点です。
insoのセットアップと並行して統合アプローチを試したい場合は、Apidogを無料でダウンロードできます。