inso（KongのInsomnia CLI）からAPIテストを実行していて、変更を考えている場合、このガイドが最初から最後までご案内します。Insomniaから仕様書とテストスイートをエクスポートし、Apidogに取り込み、inso runコマンドをapidog runコマンドに書き換える方法をご覧いただけます。既存のCIスクリプトを1行ずつマッピングできるよう、コマンドのビフォーアフター表も用意しています。
なぜチームはinsoからApidog CLIに移行するのか
insoは堅牢なツールです。リクエストの実行、Spectralによるリンティング、単体テストをターミナルにもたらし、InsomniaのGit Syncによって作成された.insomniaディレクトリから読み取ります。もしこのワークフローがあなたに合っているなら、移行する必要はありません。
通常、問題はCLIではなくInsomniaアプリから始まります。ほとんどの移行検索を促進する要因は次の2つです。
- 必須のクラウドアカウント。 2023年にリリースされたInsomnia 8では、強制的なログイン/クラウドアカウントが導入され、多くのチームを不意打ちしました。多くの開発者はローカルファーストのクライアントを望んでいましたが、代わりにサインインの壁に直面しました。
- データ損失と移行の苦痛。 一部のユーザーは、この移行中にデータ損失や移行の問題に遭遇しました。もしあなたが経験者なら、そのコストはすでに知っているでしょう。現在回復中であれば、これらのウォークスルーが役立ちます：Insomniaデータの回復とエクスポート、そしてより詳細なInsomnia 8のデータ損失回復と移行ガイド。
もう一つの理由は統合です。insoの場合、CLIはスタックの一部です。リクエストにはInsomnia、リンティングにはSpectral、モックやドキュメントには別々のツールを使用します。Apidogは設計、デバッグ、テスト、モック、ドキュメントを一つのプラットフォームに統合しており、CLIはそのプラットフォームのテスト側を実行します。可動部品が少なくなり、単一の信頼できる情報源となります。
コミットする前に広範なコンテキストを知りたい場合は、CLIではなくアプリ全体のトレードオフについて、ApidogとInsomniaの比較およびInsomniaとApidogの選択で説明しています。
始める前に：移行できるものとできないもの
移行の途中で驚くことがないよう、事前に期待値を設定しましょう。
| Insomniaのアセット | Apidogに移行できるか？ | 方法 |
|---|---|---|
| OpenAPI / 設計ドキュメント | はい | YAML/JSONにエクスポートし、Apidogにインポート |
| リクエストコレクション | はい | エクスポート後、インポート |
| 環境と変数 | はい | Apidog環境として再作成 |
単体テストスイート（inso run test） |
部分的に | Apidogテストシナリオとして再構築 |
Spectralリント設定（inso lint spec） |
1対1ではない | 下記の正直なメモを参照 |
正直なメモ：inso lint specは、StoplightのOpenAPIリンターであるSpectralを実行しますが、これは真の強みです。Apidog CLIには、スタンドアロンの仕様リンター、スタイルガイド、分割、結合、またはバンドルコマンドは含まれていません。 Apidogはインポート時に仕様を検証するため、構造上の問題はインポート時に明らかになりますが、パイプラインがカスタムSpectralルールセットをゲートとして依存している場合は、Apidogと一緒にCIにSpectralを保持してください。apidog lintは期待しないでください。それは存在せず、そうであるかのように振る舞うと後で痛い目に遭うだけです。
ステップ1：Insomniaから仕様書とテストをエクスポートする
insoは設計ドキュメントを直接ファイルに書き出すことができます。仕様は、Insomniaアプリで表示されるのと同じ名前で参照されます。
# OpenAPI設計ドキュメントをYAMLファイルにエクスポートする
inso export spec "My API Design" --output my-api.yaml
insoがデータを見つけられない場合は、正しいソースを指し示してください。デフォルトでは、作業ディレクトリまたはInsomniaアプリのデータディレクトリにある.insomniaディレクトリから読み取ります。--workingDirまたは--srcで上書きできます。
inso export spec "My API Design" --workingDir ./design --output my-api.yaml
リクエストコレクションやinsoがクリーンにエクスポートできないものについては、Insomniaアプリ自体を使用してください。アプリを開き、ワークスペースを選択し、Exportを使用してOpenAPIまたはInsomnia v4ファイルを生成します。設計ドキュメントとコレクションエクスポートの両方を保持してください。これらは別々にインポートします。
現在復旧中でアプリが協力してくれない場合、Git Syncやクラウドアカウントとの問題が発生した場合のデータ取り出しについては、エクスポートと復旧のウォークスルーで説明しています。
ステップ2：Apidogへのインポート
Apidogを開き、プロジェクトを作成し、先ほどエクスポートしたYAMLまたはJSONをインポートします。ApidogはOpenAPIをネイティブに読み取るため、エンドポイント、スキーマ、および例のデータは、編集、モック、テストが可能な構造化されたリソースとして取り込まれます。
CLIから自動セットアップの一部としてインポートすることもできます。これは、UIをクリックするのではなく、チーム全体の移行をスクリプト化する場合に便利です。ApidogはOpenAPIをインポートし、エンドポイント、スキーマ、環境、ブランチ、マージリクエストをコードとしてターミナルから管理します。認証はログインまたはアクセストークンを介して行われます。初めてCLIをセットアップする場合は、Apidog CLIインストールガイドと完全なCLIガイドでセットアップと認証フローについて説明しています。
インポート時に、Apidogは仕様を検証します。OpenAPIに構造上の問題がある場合、実行時ではなく今すぐにそれが見つかります。これはinso lint specに最も近い類似点ですが、1つの違いがあります。それは設定可能なSpectralルールセットではなく、検証であるという点です。
ステップ3：コマンドのマッピング（あなたが求めていた部分）
これが移行の核心です。insoコマンドがapidog runにどのように変換されるかを見ていきましょう。
| 実行したい内容 | 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スクリプトに組み込む) |
| OpenAPI仕様をリントする | inso lint spec "My API Design" |
1対1の対応なし。Apidogはインポート時に検証 |
| 仕様をファイルにエクスポートする | inso export spec "My API Design" --output api.yaml |
Apidogのインポート/エクスポートで処理され、実行時のステップではない |
マッピングに関するいくつかの注意点:
- 環境。
insoは--env "name"を使用します。Apidogは-e(--env) を使用します。どちらも適用する環境のベースURLと変数を選択します。まずInsomniaの環境をApidog環境として再作成し、その後名前またはIDで参照します。 - テストスイートはテストシナリオになります。
inso run testがInsomniaの単体テストスイートを実行するのに対し、Apidogはテストシナリオを実行します。この概念はきれいにマッピングされます: アサーションを伴う順序付けされたリクエスト。Apidogでスイートを一度再構築すれば、あとはすべてのapidog runで実行されます。 inso scriptは間接的なものでした。 コマンドを名前付きスクリプトの背後にラップしていた場合、CIステップで直接apidog runを呼び出すか、独自のnpm/makeスクリプトでラップするだけです。
コマンドごとの詳細な比較については、Apidog CLI vs inso (Insomnia CLI)でフラグごとに説明しています。もし以前NewmanまたはPostman CLIを使っていたなら、Apidog CLI vs NewmanとApidog CLI vs Postman CLIもそれらをカバーしています。
ステップ4：レポーターを移行する
insoはCIのためにテスト出力とJUnitスタイルのレポートに依存しています。ApidogはCLI、HTML、JSON形式でレポーターを提供するため、ビルドは人間が読める結果をコンソールに表示し、同時に機械が読めるアーティファクトを出力できます。
# シナリオを実行し、CLIサマリーとHTMLレポートの両方を出力する
apidog run --test-scenario "Smoke Suite" -e staging -r cli,html
下流ツールが結果を解析する必要がある場合はjsonを、人間がビルドをレビューする場合はhtmlを、ライブコンソールフィードにはcliを選択してください。また、--upload-reportを使用して結果をApidogのクラウドテストレポートにプッシュすることもできます。これにより、チーム全体がCIログを掘り起こすことなく実行結果を確認できます。テストレポートガイドでは、各形式について詳しく説明しています。
ステップ5：データ駆動型テストを移行する
Insomniaスイートがデータをループしていた場合、Apidogはデータ駆動型テストをネイティブにサポートします。-dでCSVまたはJSONデータセットをフィードすると、シナリオは行ごとに1回実行されます。
apidog run --test-scenario "Login Matrix" -e staging -d ./users.csv -r cli,json
ここは、Apidogがinsoを介して外部データを連結するよりも、より一体感があると感じられる場所の1つです。データ駆動型テストガイドでは、データセット形式と変数バインディングについて説明しています。
ステップ6：CIに組み込む
最後のステップは、パイプライン内のコマンドを入れ替えることです。以前のGitHub ActionsまたはGitLabステップは、おそらく次のようになっていたでしょう。
# 変更前: CIでのinso
inso run test "Smoke Suite" --env "CI" --reporter junit
Apidogの同等コマンド:
# 変更後: CIでのApidog CLI
apidog run --test-scenario "Smoke Suite" -e ci -r cli,json --upload-report
ランナーは、CIシークレットとして保存されたアクセストークンで認証します。これは、他の認証が必要なステップと同様の扱いです。CI/CDパイプラインガイドとGitHub Actionsガイドには、コピー＆ペースト可能なワークフローファイルがあります。トークンとログインの詳細は、Apidog CLIの認証を参照してください。
リンティングのためにSpectralを残した場合（カスタムルールがある場合は推奨）、パイプラインには2つのゲートができます。Spectralが仕様をリントし、Apidogがテストを実行します。これは完全に合理的な最終状態であり、各ツールが最も得意とすることを正直に示しています。
Spectralをループに保持する
ポートできない唯一の点について明確に言えば、リンティングが契約の一部である場合、それを放棄しないでください。Spectralはオープンソースであり、Insomniaの外部でも問題なく実行できます。典型的なハイブリッドCIは次のようになります。
# Spectralでリント（insoセットアップから引き継ぎ）
npx @stoplight/spectral-cli lint my-api.yaml
# Apidog CLIでテスト
apidog run --test-scenario "Smoke Suite" -e ci -r cli,json
リンティング側で何も失うことなく、残りのすべてでApidogの統合された設計-モック-テスト-ドキュメントプラットフォームを得ることができます。これが正確なトレードオフであり、ほとんどのチームにとって良いものです。
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アカウント、ローカルフレンドリー |
FAQ
InsomniaのOpenAPI仕様は、編集なしでApidogにインポートできますか？ 通常はできます。ApidogはOpenAPIをネイティブに読み取り、インポート時に検証します。検証で何かがフラグされた場合、それは通常、仕様内の実際の構造上の問題であり、一度修正すれば下流のすべてのツールに利益をもたらします。
Apidog CLIには、inso lint specのようなlintコマンドがありますか？ いいえ。Apidogはインポート時に仕様を検証しますが、スタンドアロンのCLIリンターやスタイルガイドコマンドはありません。カスタムSpectralルールセットに依存している場合は、apidog runの隣にSpectralをパイプラインに残してください。Redocly CLIにはリンターが含まれているため、Apidog CLI vs Redocly CLIを参考に比較検討してください。
insoを実行したのと同じ方法で、CIでApidog CLIを実行できますか？ はい、できます。コマンドを入れ替え、CIシークレットからのアクセストークンで認証し、レポーターを選択するだけです。CI/CDガイドには、完全なワークフローの例が記載されています。
Insomniaの単体テストスイートはどうなりますか？ それらはApidogのテストシナリオとして再構築されます。構造は直接引き継がれます。つまり、アサーションを含む順序付けられたリクエストです。これは一度限りの再構築であり、その後はすべてのapidog runで実行されます。
データ損失事故のためInsomniaから移行しています。どこから始めればよいですか？ まず、復旧とエクスポートガイドを使用してデータを復旧し、次に上記のステップ2に従ってクリーンアップされたエクスポートをApidogにインポートしてください。
まとめ
insoからApidog CLIへの移行は、ほとんどが翻訳作業です。仕様書とスイートをエクスポートし、Apidogにインポートし、inso run testとinso run collectionをapidog runに書き換え、--envを-eに切り替え、レポーターをApidogのCLI/HTML/JSON出力に向けます。リントする場合はSpectralを保持してください。Apidogはインポート時に検証しますが、カスタムルールセットを置き換えるものではないからです。
その結果、つなぎ合わせ続ける必要のあるスタックではなく、単一のプラットフォームが得られます。試してみませんか？Apidogをダウンロードして、エクスポートした仕様に対して最初のapidog runを実行してください。