DEV Community

Cover image for inso (Insomnia CLI) から Apidog CLI への移行方法
Akira
Akira

Posted on • Originally published at apidog.com

inso (Insomnia CLI) から Apidog CLI への移行方法

inso（Kong の Insomnia CLI）で API テストを実行していて Apidog CLI への移行を検討している場合は、次の手順で進めます。Insomnia から仕様書とテスト資産をエクスポートし、Apidog にインポートし、CI 上の inso run を apidog run に置き換えます。

今すぐApidogを試す

なぜ inso から Apidog CLI に移行するのか

inso は、リクエスト実行、Spectral による OpenAPI リント、単体テスト実行を CLI から扱える堅牢なツールです。Insomnia の Git Sync で作成された .insomnia ディレクトリからデータを読み取れます。

既存ワークフローに問題がなければ、移行は必須ではありません。移行を検討する主な理由は次の通りです。

  • Insomnia 8 以降のクラウドアカウント要件

    ローカルファーストで使いたいチームにとって、強制ログインは運用上の制約になります。

  • データ損失や移行トラブルへの対応

    Insomnia 8 への移行時にデータ損失や移行問題を経験した場合は、まず復旧とエクスポートを優先してください。参考: Insomniaデータの回復とエクスポート、Insomnia 8のデータ損失回復と移行

  • ツールチェーンを統合したい

    inso は CLI 実行に強い一方、設計、モック、ドキュメント、テストを別ツールで組み合わせる構成になりがちです。Apidog は設計、デバッグ、テスト、モック、ドキュメントを 1 つのプラットフォームで扱い、CLI からテストを実行できます。

アプリ全体の比較は、ApidogとInsomniaの比較 と InsomniaとApidogの選択 も参照してください。

始める前に：移行できるものとできないもの

Insomnia のアセット Apidog に移行できるか 方法
OpenAPI / 設計ドキュメント はい YAML / JSON にエクスポートして Apidog にインポート
リクエストコレクション はい Insomnia からエクスポートして Apidog にインポート
環境と変数 はい Apidog の環境として再作成
単体テストスイート（inso run test） 部分的に可能 Apidog のテストシナリオとして再構築
Spectral リント設定（inso lint spec） 1 対 1 では不可 CI に Spectral を残す

重要な点として、inso lint spec は Spectral を実行します。Apidog CLI には、スタンドアロンの仕様リンター、スタイルガイド、分割、結合、バンドル用の CLI コマンドはありません。

Apidog はインポート時に OpenAPI 仕様を検証しますが、カスタム Spectral ルールセットの代替ではありません。CI で仕様品質をゲートしている場合は、Spectral を残したまま Apidog CLI を追加してください。

ステップ1：Insomnia から仕様書とテスト資産をエクスポートする

まず、OpenAPI 設計ドキュメントをファイルに書き出します。

# OpenAPI 設計ドキュメントを YAML にエクスポート
inso export spec "My API Design" --output my-api.yaml
Enter fullscreen mode Exit fullscreen mode

inso がデータを見つけられない場合は、.insomnia ディレクトリの場所を指定します。

inso export spec "My API Design" \
  --workingDir ./design \
  --output my-api.yaml
Enter fullscreen mode Exit fullscreen mode

または --src を使ってソースを明示します。

inso export spec "My API Design" \
  --src ./path/to/.insomnia \
  --output my-api.yaml
Enter fullscreen mode Exit fullscreen mode

リクエストコレクションや CLI で扱いづらい資産は、Insomnia アプリからエクスポートします。

  1. Insomnia を開く
  2. 対象ワークスペースを選択
  3. Export を実行
  4. OpenAPI または Insomnia v4 形式で保存
  5. 設計ドキュメントとコレクションの両方を保持する

アプリが起動できない、Git Sync やクラウドアカウントで問題がある場合は、エクスポートと復旧のウォークスルー を先に確認してください。

ステップ2：Apidog にインポートする

Apidog を開き、プロジェクトを作成して、エクスポートした YAML または JSON をインポートします。

Apidog は OpenAPI をネイティブに読み取ります。インポート後、次の要素を Apidog 上で編集、モック、テストできます。

  • エンドポイント
  • スキーマ
  • サンプルデータ
  • リクエスト定義
  • 環境変数

CLI を使ってセットアップを自動化する場合は、認証とプロジェクト操作を先に準備します。初期設定は Apidog CLIインストールガイド と 完全なCLIガイド を参照してください。

インポート時に Apidog は仕様を検証します。OpenAPI の構造に問題がある場合は、この時点で検出できます。ただし、これは inso lint spec と同じではありません。Spectral のカスタムルールセットが必要な場合は、CI に Spectral を残します。

ステップ3：inso コマンドを apidog run に置き換える

移行の中心は、CI やローカルスクリプト内のコマンド置換です。

実行したい内容 inso コマンド Apidog CLI の同等コマンド
単体テストスイートを実行 inso run test "Smoke Suite" --env "Staging" apidog run --test-scenario "Smoke Suite" -e staging
コレクションを実行 inso run collection "Checkout Flow" --env "Staging" apidog run "Checkout Flow" -e staging
指定スクリプトを実行 inso script ci-smoke --env <env-id> apidog run -e <env-id> を CI や npm script に組み込む
OpenAPI 仕様をリント inso lint spec "My API Design" 1 対 1 の対応なし。Apidog はインポート時に検証
仕様をファイルにエクスポート inso export spec "My API Design" --output api.yaml Apidog のインポート / エクスポートで処理。実行時ステップではない

移行時は、特に次の点を確認してください。

環境の指定

inso では --env を使います。

inso run test "Smoke Suite" --env "Staging"
Enter fullscreen mode Exit fullscreen mode

Apidog CLI では -e または --env を使います。

apidog run --test-scenario "Smoke Suite" -e staging
Enter fullscreen mode Exit fullscreen mode

Insomnia の環境変数は、Apidog の環境として再作成します。その後、名前または ID で参照します。

テストスイートはテストシナリオに置き換える

inso run test は Insomnia の単体テストスイートを実行します。Apidog では、同等の構造をテストシナリオとして作成します。

基本的な対応は次の通りです。

  • Insomnia のリクエスト順序 → Apidog のステップ順序
  • Insomnia のアサーション → Apidog のアサーション
  • Insomnia の環境変数 → Apidog の環境変数
  • CI 実行 → apidog run

inso script は直接コマンドに展開する

inso script でコマンドをラップしていた場合は、CI 側で apidog run を直接呼び出すか、npm script や Makefile にまとめます。

{
  "scripts": {
    "test:api": "apidog run --test-scenario \"Smoke Suite\" -e ci -r cli,json"
  }
}
Enter fullscreen mode Exit fullscreen mode 
npm run test:api
Enter fullscreen mode Exit fullscreen mode

コマンドごとの詳細は、Apidog CLI vs inso (Insomnia CLI) を参照してください。Newman や Postman CLI からの移行も検討している場合は、Apidog CLI vs Newman と Apidog CLI vs Postman CLI も参考になります。

ステップ4：レポーターを移行する

inso では、CI 向けに CLI 出力や JUnit 形式のレポートを使うことが一般的です。

Apidog CLI では、CLI、HTML、JSON 形式のレポーターを使えます。

# CLI サマリーと HTML レポートを出力
apidog run --test-scenario "Smoke Suite" \
  -e staging \
  -r cli,html
Enter fullscreen mode Exit fullscreen mode

用途別には次のように選びます。

用途 レポーター
CI ログで結果を確認 cli
人間がブラウザで確認 html
下流ツールで解析 json
チームで実行結果を共有 --upload-report

例:

apidog run --test-scenario "Smoke Suite" \
  -e ci \
  -r cli,json \
  --upload-report
Enter fullscreen mode Exit fullscreen mode

レポート形式の詳細は テストレポートガイド を参照してください。

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

Insomnia 側で複数データを使ったテストを実行していた場合は、Apidog CLI の -d オプションで CSV または JSON データセットを渡します。

apidog run --test-scenario "Login Matrix" \
  -e staging \
  -d ./users.csv \
  -r cli,json
Enter fullscreen mode Exit fullscreen mode

たとえば users.csv は次のような形式にできます。

email,password,expectedStatus
user1@example.com,password123,200
user2@example.com,wrong-password,401
Enter fullscreen mode Exit fullscreen mode

テストシナリオ内では、データセットの列を変数として使います。

{{email}}
{{password}}
{{expectedStatus}}
Enter fullscreen mode Exit fullscreen mode

データセット形式と変数バインディングは、データ駆動型テストガイド を確認してください。

ステップ6：CI に組み込む

最後に、CI パイプライン内の inso コマンドを apidog run に置き換えます。

変更前:

# CI での inso
inso run test "Smoke Suite" --env "CI" --reporter junit
Enter fullscreen mode Exit fullscreen mode

変更後:

# CI での Apidog CLI
apidog run --test-scenario "Smoke Suite" \
  -e ci \
  -r cli,json \
  --upload-report
Enter fullscreen mode Exit fullscreen mode

認証には、CI シークレットに保存したアクセストークンを使います。

GitHub Actions では、概念的には次のような構成になります。

name: API Tests

on:
  push:
    branches:
      - main
  pull_request:

jobs:
  api-test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Run Apidog tests
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}
        run: |
          apidog run --test-scenario "Smoke Suite" \
            -e ci \
            -r cli,json \
            --upload-report
Enter fullscreen mode Exit fullscreen mode

完全な CI/CD 例は CI/CDパイプラインガイド と GitHub Actionsガイド を参照してください。認証については Apidog CLIの認証 にまとまっています。

Spectral を CI に残す

inso lint spec を使っていた場合、Apidog CLI だけに置き換えるのではなく、Spectral をそのまま CI に残すのが安全です。

典型的なハイブリッド構成は次の通りです。

# OpenAPI 仕様を Spectral でリント
npx @stoplight/spectral-cli lint my-api.yaml

# API テストを Apidog CLI で実行
apidog run --test-scenario "Smoke Suite" \
  -e ci \
  -r cli,json
Enter fullscreen mode Exit fullscreen mode

これにより、次の責務分離になります。

  • Spectral: OpenAPI のスタイルガイド、カスタムルール、品質ゲート
  • Apidog: API テスト実行、レポート、設計・モック・ドキュメントとの統合

Apidog CLI に apidog lint のような代替コマンドがある前提で移行しないようにしてください。

inso vs Apidog CLI 概要

機能 inso（Insomnia CLI） Apidog CLI
コレクション / スイート実行 はい はい
環境指定 --env -e / --env
OpenAPI リンティング はい（Spectral） スタンドアロンコマンドなし。インポート時に検証
データ駆動型テスト 限定的 はい（-d、CSV / JSON）
レポート形式 CLI、JUnit CLI、HTML、JSON、クラウドアップロード
コードとしてのリソース .insomnia ディレクトリを読み込む エンドポイント、スキーマ、ブランチ、マージリクエスト
統合プラットフォーム Insomnia + 外部ツール 設計、モック、ドキュメント、テストを統合
アプリ利用時のアカウント Insomnia 8+ でクラウドアカウントが必要 Apidog アカウントを使用

移行チェックリスト

実作業では、次の順番で進めると安全です。

[ ] Insomnia から OpenAPI 仕様を YAML / JSON でエクスポート
[ ] リクエストコレクションをエクスポート
[ ] Insomnia の環境変数を棚卸し
[ ] Apidog プロジェクトを作成
[ ] OpenAPI 仕様を Apidog にインポート
[ ] 環境を Apidog に再作成
[ ] Insomnia のテストスイートを Apidog テストシナリオとして再構築
[ ] ローカルで apidog run を実行
[ ] レポーターを cli / html / json から選択
[ ] CI シークレットに Apidog アクセストークンを設定
[ ] CI の inso run を apidog run に置き換え
[ ] 必要なら Spectral を CI に残す
Enter fullscreen mode Exit fullscreen mode

FAQ

Insomnia の OpenAPI 仕様は、編集なしで Apidog にインポートできますか？

通常はできます。Apidog は OpenAPI をネイティブに読み取り、インポート時に検証します。検証でエラーが出る場合は、仕様内の構造的な問題である可能性があります。

Apidog CLI に inso lint spec のような lint コマンドはありますか？

ありません。Apidog はインポート時に仕様を検証しますが、スタンドアロンの CLI リンターやスタイルガイドコマンドはありません。カスタム Spectral ルールセットを使っている場合は、apidog run と並行して Spectral を CI に残してください。

Redocly CLI との違いを確認したい場合は、Apidog CLI vs Redocly CLI も参考になります。

CI で inso と同じように Apidog CLI を実行できますか？

はい。基本的にはコマンドを置き換え、CI シークレットからアクセストークンを渡し、必要なレポーターを指定します。

apidog run --test-scenario "Smoke Suite" \
  -e ci \
  -r cli,json \
  --upload-report
Enter fullscreen mode Exit fullscreen mode

Insomnia の単体テストスイートはどうなりますか？

Apidog のテストシナリオとして再構築します。構造は近く、順序付きリクエストとアサーションを組み合わせる形です。一度再構築すれば、その後は apidog run で継続的に実行できます。

データ損失が理由で Insomnia から移行しています。どこから始めるべきですか？

まず 復旧とエクスポートガイド を使って、可能な限りデータを取り出します。その後、OpenAPI 仕様とコレクションを Apidog にインポートしてください。

まとめ

inso から Apidog CLI への移行は、主にコマンドとテスト資産の置き換えです。

  • inso export spec で OpenAPI 仕様を取り出す
  • Insomnia アプリからコレクションをエクスポートする
  • Apidog に仕様とコレクションをインポートする
  • Insomnia の環境を Apidog 環境として再作成する
  • inso run test / inso run collection を apidog run に置き換える
  • --env を -e / --env に置き換える
  • レポートは cli、html、json、--upload-report から選ぶ
  • OpenAPI のカスタムリントが必要なら Spectral を残す

Apidog は inso lint spec の完全な代替ではありません。一方で、API の設計、モック、ドキュメント、テスト実行を 1 つのワークフローにまとめたい場合は、移行する価値があります。

まずは Apidogをダウンロード し、エクスポートした仕様に対して最初の apidog run を実行してください。

Top comments (0)