DEV Community

Cover image for insoとは？ Insomnia CLI
Akira
Akira

Posted on • Originally published at apidog.com

insoとは？ Insomnia CLI

Insomnia API クライアントでは、リクエスト送信、OpenAPI 仕様の設計、テスト作成をGUIで行えます。ただし、GUI上の操作だけではCIパイプラインやプルリクエスト時の自動チェックに組み込みにくいです。そこで使うのが、Insomniaの操作をターミナルから実行できる inso CLIです。

今すぐApidogを試す

この記事では、inso の役割、インストール方法、よく使うコマンド、CIでの実行例、データソースの解決方法、そして実運用上の制限を整理します。

insoとは？

inso は、KongがメンテナンスしているInsomnia向けのCLIです。InsomniaのGUIで行う以下の作業を、スクリプトやCIから実行できます。

  • APIテストスイートの実行
  • リクエストコレクションの実行
  • OpenAPI仕様のLint
  • 仕様ファイルのエクスポート
  • Insomnia内で定義したスクリプトの実行

inso CLI

短く言うと、inso は「Insomniaを開かずにInsomniaのデータを実行するためのCLI」です。Insomnia内の設計ドキュメント、コレクション、テストスイートを名前またはIDで指定して実行します。

inso CLIのインストール

公式に使いやすいインストール方法は主に3つあります。ローカル開発、CI、固定バージョン管理のどれを重視するかで選びます。

Homebrewでインストールする

macOSまたはLinuxではHomebrewが簡単です。

brew install inso
Enter fullscreen mode Exit fullscreen mode

インストール後、バージョンを確認します。

inso --version
Enter fullscreen mode Exit fullscreen mode

Dockerで使う

CIランナーではDockerイメージを使うと、環境差分を減らせます。

docker pull kong/inso:latest
Enter fullscreen mode Exit fullscreen mode

実行例です。

docker run --rm -v "$PWD:/app" -w /app kong/inso:latest inso --version
Enter fullscreen mode Exit fullscreen mode

zipアーカイブを直接使う

Windows、Linux、macOS向けのzipアーカイブは、inso CLIのドキュメントサイトから取得できます。

CIやビルド環境で特定バージョンを固定したい場合は、直接ダウンロード方式が扱いやすいです。

以前は insomnia-inso としてnpmでも配布されていましたが、新規セットアップではHomebrew、Docker、直接ダウンロードを優先するのが無難です。

insoの主要コマンド

inso は機能が絞られているため、覚えるコマンドは多くありません。日常的に使うものを中心に説明します。

inso run test

Insomniaで作成したテストスイートを、指定した環境に対して実行します。

inso run test "Payments API tests" --env "Staging"
Enter fullscreen mode Exit fullscreen mode

テストスイート名と環境名は、Insomnia内に表示されている名前を指定します。

アサーションが失敗するとコマンドは非ゼロで終了するため、CIのゲートとして使えます。

inso run test "Payments API tests" --env "CI"
Enter fullscreen mode Exit fullscreen mode

GitHub ActionsやGitLab CIで実行すれば、テスト失敗時にジョブを失敗させられます。

inso run collection

コレクション内のリクエストを順番に実行します。

inso run collection "Checkout flow" --env "Staging"
Enter fullscreen mode Exit fullscreen mode

これは、Insomnia GUIでフォルダやコレクションをまとめて実行する操作に近いです。

用途としては、以下のようなスモークテストに向いています。

  • 主要エンドポイントが200系を返すか
  • 認証付きリクエストが通るか
  • ステージング環境のAPIが最低限動作しているか

inso lint spec

OpenAPI設計ドキュメントをLintします。

inso lint spec "Orders API"
Enter fullscreen mode Exit fullscreen mode

inso lint spec は内部的に、StoplightのOpenAPI / JSONリンターであるSpectralを使用します。

そのため、単なる構文チェックではなく、ルールベースの仕様チェックを実行できます。OpenAPIのスタイルガイドや設計ルールをCIで強制したい場合に有効です。

例：

inso lint spec "Orders API" --workingDir .
Enter fullscreen mode Exit fullscreen mode

inso export spec

Insomnia内の設計ドキュメントをファイルとして出力します。

inso export spec "Orders API" --output orders.yaml
Enter fullscreen mode Exit fullscreen mode

使いどころは次のようなケースです。

  • OpenAPI Generatorなど別ツールに渡す
  • 仕様ファイルをリポジトリにスナップショットとして保存する
  • YAMLファイルを前提とするCIステップに渡す

例：

inso export spec "Orders API" --output ./openapi/orders.yaml
Enter fullscreen mode Exit fullscreen mode

inso script

Insomniaデータ内で定義された名前付きスクリプトを実行します。

inso script deploy-smoke --env env_9f2a
Enter fullscreen mode Exit fullscreen mode

独自の処理をつなぎ込みたい場合の拡張ポイントとして使えます。

insoが仕様とコレクションを見つける仕組み

inso はCLI自体に仕様やコレクションを保存しません。実行時に、Insomniaのデータソースから対象を探します。

主な読み取り元は2つです。

  1. 作業ディレクトリ内の .insomnia ディレクトリ
  2. ローカルマシンにインストールされたInsomniaアプリのデータディレクトリ

CIで使う場合は、.insomnia ディレクトリをリポジトリに含める構成が基本です。これはInsomniaのGit同期によって生成されます。

repo/
  .insomnia/
  src/
  package.json
Enter fullscreen mode Exit fullscreen mode

この状態であれば、CI上でも次のように実行できます。

inso lint spec "Orders API" --workingDir .
Enter fullscreen mode Exit fullscreen mode

データソースを明示することもできます。

inso run test "Payments API tests" --src ./api-project/.insomnia
Enter fullscreen mode Exit fullscreen mode

重要なのは、inso が名前またはIDで対象を解決するという点です。

たとえば次のコマンドでは、

inso run test "Payments API tests" --env "Staging"
Enter fullscreen mode Exit fullscreen mode

Payments API tests というテストスイートと、Staging という環境が、inso が読み取ったInsomniaデータ内に存在する必要があります。

.insomnia ディレクトリやローカルアプリデータにその名前が存在しない場合、inso は実行できません。

つまり、単体のOpenAPIファイルだけを渡して「これをテストして」と実行するツールではありません。対象はInsomniaプロジェクト構造内に存在している必要があります。

最小限のCI例

以下は、Git同期された .insomnia ディレクトリがリポジトリにコミットされている前提のGitHub Actions例です。

プッシュごとにOpenAPI仕様をLintし、テストスイートを実行します。

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 .
Enter fullscreen mode Exit fullscreen mode

どちらのコマンドも失敗時に非ゼロで終了します。

そのため、以下のような状態をCIで検出できます。

  • OpenAPI仕様がルールに違反している
  • テストアサーションが失敗している
  • 指定した環境でAPIが期待どおりに応答していない

Dockerを使ったCI実行例

CI環境に inso を直接インストールしたくない場合は、Dockerで実行できます。

name: API checks
on: [push]

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

      - name: Lint the spec
        run: |
          docker run --rm \
            -v "$PWD:/app" \
            -w /app \
            kong/inso:latest \
            inso lint spec "Orders API" --workingDir .

      - name: Run tests
        run: |
          docker run --rm \
            -v "$PWD:/app" \
            -w /app \
            kong/inso:latest \
            inso run test "Payments API tests" --env "CI" --workingDir .
Enter fullscreen mode Exit fullscreen mode

CIランナーにCLIを直接置かずに済むため、環境を再現しやすくなります。

運用時の注意点

inso は便利ですが、実運用ではいくつか注意点があります。

1. Insomniaデータソースに依存する

inso はInsomniaプロジェクト内の仕様、コレクション、テストスイートを実行します。

そのため、チームがInsomniaをAPI仕様やテストの真のソースとして使っていない場合、inso だけでは運用しにくくなります。

CIで安定させるには、.insomnia ディレクトリをリポジトリに含める構成を明確にしておく必要があります。

2. 名前参照は壊れやすい

inso のコマンドでは、次のように名前を指定することが多いです。

inso run test "Payments API tests" --env "Staging"
Enter fullscreen mode Exit fullscreen mode

これは読みやすい一方で、Insomnia UI上で名前を変更するとCIが壊れます。

たとえばテストスイート名を Payments API tests から Payment API tests に変更すると、CI側のコマンドも更新が必要です。

対策としては、次のようなルールを決めておくとよいです。

  • CIで参照するスイート名や環境名を不用意に変更しない
  • 変更時はCI定義も同じPRで更新する
  • 可能であればID参照を検討する
  • 名前の重複を避ける

3. スコープは意図的に狭い

inso が主に扱うのは次の操作です。

  • テスト実行
  • コレクション実行
  • 仕様Lint
  • 仕様エクスポート
  • スクリプト実行

API設計、モック、ドキュメント、テスト管理までを統合するプラットフォームではありません。

そのため、ワークフロー全体を自動化したい場合は、Insomnia、inso、Spectral、モックサーバー、ドキュメント生成ツールなどを組み合わせることになります。

insoと統合型ツールの比較

InsomniaをすでにAPIクライアントとして使っているなら、inso は自然なCLI選択肢です。

一方で、構成は複数ツールの組み合わせになりやすいです。

  • 設計とデバッグ：Insomnia
  • CI実行：inso
  • 仕様Lint：Spectral
  • モック：別ツール
  • ドキュメント：別ツール

Apidog

Apidogは、デザイン、モック、ドキュメント、テストを1つのプラットフォームにまとめるアプローチです。

また、Apidog CLIでは、同じソースからテストシナリオやコレクションを実行できます。データ駆動型テスト、複数のレポーター形式、コードとしてのリソースやブランチ管理にも対応します。

ただし、公平に言うと、Apidog CLIは inso lint spec のようなSpectralベースのスタンドアロン仕様リンターを提供していません。OpenAPIスタイルガイドの強制を最優先する場合、inso には明確な利点があります。

一方、複数ツールを接着せず、設計からテスト、ドキュメントまでを一元化したい場合は、Apidogのような統合型の選択肢が向いています。

さらに比較する

両者を詳しく比較したい場合は、次の記事が参考になります。

inso のセットアップと並行して統合アプローチも試したい場合は、Apidogを無料でダウンロードできます。

まとめ

inso は、InsomniaのデータをCIやターミナルから実行するための実用的なCLIです。

特に次の用途に向いています。

  • InsomniaのテストスイートをCIで実行する
  • コレクションをスモークテストとして回す
  • OpenAPI仕様をSpectralベースでLintする
  • Insomnia内の仕様をYAMLとしてエクスポートする

一方で、Insomniaのデータ構造に依存し、名前参照も壊れやすいため、CI運用では .insomnia ディレクトリの管理と命名ルールが重要です。

Insomnia中心のワークフローなら inso は有力です。設計、モック、ドキュメント、テストを1つの場所で管理したい場合は、統合型ツールも比較するとよいでしょう。

Top comments (0)