Insomniaは、リクエストの送信とレスポンスの検査のためにKongが開発したAPIクライアントです。クリーンで集中できるインターフェースと、HTTP、REST、GraphQL、gRPC、SOAP、WebSocketをすべて一箇所でサポートすることで知られています。開発者は、重いIDEスタイルのツールよりも軽量でありながら、実際のテスト作業もこなせるツールを求める際に、これを利用します。
このガイドでは、InsomniaでAPIを最初から最後までテストする方法を説明します。リクエストコレクションの作成、レスポンスの送信と検査、ベースURLとトークンを切り替えられる環境の設定、そして自動的に実行されるアサーションを記述するためのテストスイート機能の使用方法を学びます。すぐに試せるように、例では公開APIを使用しています。
Insomniaのインストールとリクエストの作成
Kongの公式ウェブサイトからInsomniaをダウンロードし、お使いのプラットフォームにインストールしてください。初回起動時、Insomniaはサインインを求めます。必要であれば、アカウントなしでローカルで作業することを選択でき、Insomniaはデータを自分のマシンに保存します。クラウド同期はオプションであり、バージョン8で変更された点については後述します。
Insomniaは、作業をコレクションとドキュメントに整理します。ダッシュボードでCreateをクリックし、Request Collectionを選択します。「User API tests」のような分かりやすい名前を付けます。コレクション内で、+ボタンをクリックし、HTTP Requestを選択します。
リクエストにはメソッドとURLが必要です。GETを選択し、実際のエンドポイントを入力します。練習にはJSONPlaceholderサービスが最適です。
GET https://jsonplaceholder.typicode.com/users/1
Sendをクリックします。右ペインには、レスポンスボディ、ステータスコード、レスポンス時間、サイズが表示されます。InsomniaはJSONを自動的に整形表示し、レスポンスが大きい場合に便利なJSONPathまたはXPathクエリでボディをフィルタリングできます。
メソッド、パラメーター、認証の設定
単純な読み取り以外では、リクエストにさらに多くの設定を行います。Insomniaでは、これらはURLバーの下のタブにグループ化されています。
Bodyタブはリクエストペイロードを扱います。POSTの場合、JSONを選択してデータを入力します。
{
"name": "Daniel Okafor",
"email": "daniel.okafor@example.com"
}
ボディタイプを選択すると、Insomniaが自動的にContent-Typeヘッダーを設定します。Queryタブでは、URLを手動で編集することなくクエリ文字列パラメーターを追加でき、これにより長いURLの可読性が保たれ、個々のパラメーターをオン/オフで切り替えることができます。Headersタブは、カスタムのX-Request-Idやレスポンス形式をネゴシエートするためのAcceptヘッダーなど、APIが要求するその他のすべてのヘッダーに使用します。
Authタブは認証情報を扱います。Insomniaは、Bearer Token、Basic Auth、API Key、OAuth 1.0および2.0、AWS IAMなど、多くのスキームをサポートしています。APIが使用するスキームを選択し、フィールドに入力します。トークンで保護されたAPIの場合、Bearer Tokenを選択してトークンを貼り付けるか、より良い方法として環境変数を参照してトークンをハードコーディングしないようにします。どのステータスコードが返されるか不明な場合は、REST APIが使用すべきHTTPステータスコードの参照が役立ちます。
環境と変数の設定
環境を使用すると、値の繰り返しを避け、ターゲットの切り替えを容易にすることができます。Insomniaでは、環境はコレクションにアタッチされた変数のJSONオブジェクトです。
サイドバーの上部近くにある環境ドロップダウンをクリックし、Manage Environmentsを開きます。Base Environmentには共有値が保持されます。各ターゲットのサブ環境を追加します。
{
"base_url": "https://jsonplaceholder.typicode.com",
"auth_token": "your-token-here"
}
異なる値を持つ本番環境用に2つ目のサブ環境を作成します。{{ _.base_url }}というテンプレート構文を使用して、任意のリクエストで変数を参照すると、URLは次のようになります。
GET {{ _.base_url }}/users/1
ドロップダウンからアクティブな環境を切り替えると、その変数を使用するすべてのリクエストが更新されます。Insomniaはまた、テンプレートタグをサポートしており、これはタイムスタンプやUUIDを生成したり、以前のレスポンスから値を引き出したりするためにフィールドに挿入できる小さな関数です。後者の機能により、例えばログインレスポンスからトークンを取得し、それを後続のリクエストに渡すといった、リクエストの連鎖が可能になります。
レスポンステンプレートタグは、スクリプトを使わずにリクエストの依存関係をInsomniaがどのように処理するかを示すため、詳しく見る価値があります。「ログインリクエストのボディをJSONPath $.tokenで取得して使用する」というタグを追加し、すべての保護されたリクエストのAuthorizationヘッダーにそれを挿入します。保護されたリクエストを実行すると、必要に応じてInsomniaはまずログインリクエストを実行し、トークンを抽出し、それを置き換えます。この連鎖は宣言的であるため、維持すべき接着コードは不要です。関連するチェックをグループ化するというより広いアイデアについては、APIテストケースの例のウォークスルーを参照してください。
アサーションによるテストスイートの記述
リクエストを送信するとレスポンスが表示されます。レスポンスが正しいことを自動的にチェックするには、Insomniaのテストスイート機能を使用します。これは、コレクション上でUnit Testsタブとして表示されることもあります。
コレクションを開き、Testsビューに切り替えます。テストスイートを作成し、その中に個々のテストを追加します。各テストは小さなJavaScriptコードです。InsomniaはChaiアサーションライブラリを使用しており、リクエストを送信してそのレスポンスを取得するためのヘルパーを提供します。テストは次のようになります。
const response = await insomnia.send();
expect(response.status).to.equal(200);
ボディをパースしてフィールドをチェックすることで、より具体的にすることもできます。
const response = await insomnia.send();
const body = JSON.parse(response.data);
expect(response.status).to.equal(200);
expect(body.email).to.equal("daniel.okafor@example.com");
expect(body).to.have.property("id");
スイート内の各テストは、ドロップダウンから選択されたコレクション内のリクエストを対象とするため、テストは何を送信すべきかを知っています。Run Testsをクリックすると、Insomniaはスイート内のすべてのテストを実行し、それぞれのテストが合格したか失敗したか、およびかかった時間を表示します。これはリグレッションチェックです。変更後にスイートを実行すると、APIがまだ正しく動作しているかどうかをすぐに確認できます。
スイートの数が増えるにつれて、その構成方法は重要になります。一般的なパターンは、リソースごとに1つのスイートを作成することです。これにより、記事関連のテストはすべて一緒に、ユーザー関連のテストはすべて一緒にまとめられます。スイート内では、各テストを単一の動作に集中させます。例えば、正常系のテストは1つ、見つからないケースとバリデーションエラーのケースは個別のテストとします。テストが失敗した場合、その名前と狭いスコープから、アサーションコードを読むことなく何が壊れたかを把握できるはずです。より良いチェックの記述について深く掘り下げるには、APIアサーションに関するガイドで、何をアサートし、何をスキップすべきかを説明しており、APIテスト自動化のためのテストスイートの記事では、スイートが成長するにつれてどのように構成すべきかを扱っています。
Insoを使ったコマンドラインからの実行
GUIは開発には適していますが、自動化にはヘッドレスなものが必要です。Insomniaには、Insoと呼ばれるコマンドラインコンパニオンが付属しています。コレクションをエクスポートまたは同期した後、ターミナルからテストスイートを実行します。
inso run test "User API tests"
いずれかのテストが失敗した場合、Insoは非ゼロのステータスコードで終了します。これは、CIパイプラインがビルドを破損としてマークするために必要なものです。これをGitHub Actionsや他のどのランナーにも組み込むことで、プッシュごとにInsomniaテストが実行され、チームメイトや本番環境に到達する前に壊れたエンドポイントを検出できます。Insoは、API仕様のリンティングや標準形式でのテストレポート生成も可能であり、スイートの実行だけでなく、さらに役立ちます。CI/CDでのAPIテストの自動化に関する記事では、Insoにきれいに適用できる一般的なパターンが示されています。
バージョン8でのクラウドへの変更と代替案
Insomnia 8は、クラウドファーストのモデルへと移行しました。デフォルトでは、ユーザーにKongアカウントの作成とプロジェクトのクラウド保存を促しました。以前のバージョンが完全にローカルでオフラインでも利用可能だったため、この決定はコミュニティの一部を不満にさせました。後のリリースでは、より明確なローカル専用または「Scratch Pad」オプションが復活しましたが、この一件により、特にデータが組織外に出ることができない環境では、一部のチームが代替案を探すようになりました。
もしそれがあなたに当てはまるなら、Apidogは一見の価値があります。これは、設計、デバッグ、モック、テスト、ドキュメンテーションをカバーするオールインワンのAPIプラットフォームであり、Insomniaのエクスポートをインポートできるため、最初からやり直す必要はありません。Apidogでは、JavaScriptを記述することなく視覚的にアサーションを構築でき、必要に応じてスクリプトもサポートします。API仕様、テストデータ、モックサーバーが1つのプロジェクトを共有するため、テストは実際の契約と乖離することなく整合性を保ちます。ApidogをダウンロードしてInsomniaコレクションをインポートし、比較検討することができます。より広範な調査については、無料で利用できるオンラインAPIテストツールのリストがいくつかの選択肢をカバーしています。
Insomniaは依然として強力で焦点を絞ったクライアントであり、特にその最小限で集中できるインターフェースと素早い起動を評価する個人開発者や小規模チームに適しています。適切な選択は、チームの作業方法と、APIライフサイクルのどの部分を別々のツールに分散させるのではなく、一箇所で処理したいかにかかっています。
よくある質問
Insomniaは無料で使えますか？
Insomniaには、リクエストの送信やテストスイートのローカル実行を含む個人利用をカバーする無料プランがあります。有料プランでは、チームコラボレーションとより大きなクラウド同期制限が追加されます。コアクライアントは料金を支払うことなく使用でき、最近のバージョンではクラウド同期を利用しない場合でも完全にローカルで作業できます。
Insomniaはどのプロトコルをサポートしていますか？
InsomniaはHTTP、REST、GraphQL、gRPC、SOAP、WebSocketに対応しています。リクエストの設定はプロトコルによって異なりますが、レスポンスの検査と、HTTPベースのリクエストの場合はテストスイートのアサーションは、それらすべてで一貫して機能します。
Insomniaでアサーションを記述するにはどうすればよいですか？
テストスイート機能を使用します。コレクションで「Tests」ビューを開き、スイートを作成し、テストを追加します。各テストは、insomnia.send()を呼び出してリクエストを実行し、その後、ステータス、ヘッダー、または解析されたボディに対してChaiスタイルのexpectアサーションを使用するJavaScriptです。「Run Tests」ボタンでスイート全体を実行します。
Insomnia 8で何が変わりましたか？
Insomnia 8は、デフォルトでクラウドファーストへと移行し、ユーザーにKongアカウントへのサインインとプロジェクトのクラウド同期を促しました。一部のユーザーは、強制的なアカウントフローと純粋なローカルアプリからの移行を不満に思いました。後のアップデートで、より明確なローカル専用オプションが追加されましたが、この変更により一部のチームは代替案の検討を余儀なくされました。
InsomniaのテストをCIパイプラインで実行できますか？
はい、できます。コマンドラインコンパニオンであるInsoを使用します。コレクションをエクスポートまたは同期した後、パイプラインでinso run test "<suite name>"を実行します。Insoは失敗時に非ゼロの終了コードを返すため、APIテストが壊れた場合にCIが自動的にビルドを失敗させることができます。