API開発の盲点！InsomniaでGraphQLのクエリとサブスクリプションを快適にテストする方法
こんにちは！日々の開発、本当にお疲れ様です。
突然ですが、皆さんは GraphQL のAPIをテストするとき、どんなツールを使っていますか？
「とりあえずブラウザ上のPlaygroundを使っているけれど、認証情報の管理が面倒……」
「REST APIと同じツールで管理したいけれど、GraphQLのクエリを書くのが億劫……」
そんな悩みを抱えてはいないでしょうか。
実は、API開発クライアントとして絶大な人気を誇る 「Insomnia（インソムニア）」 を使えば、GraphQLのテスト環境は劇的に快適になります。特に、難易度が高いと思われがちな 「Subscription（サブスクリプション：リアルタイム通信）」 のテストも、驚くほど直感的に行えるのです。
この記事では、GraphQLに初めて触れる方に向けて、Insomniaを使った効率的なテスト方法を、基礎のセットアップからリアルタイム監視まで、優しく丁寧に解説します。
これをマスターすれば、毎日のAPI開発とテストの作業が劇的に楽になりますよ。さあ、一緒に新しい扉を開けてみましょう！
—
なぜGraphQLテストに「Insomnia」を選ぶべきなのか？
GraphQLは、クライアントが必要なデータ構造を自由に定義して取得できる、非常に強力な技術です。しかしその自由度の高さゆえに、テスト時には以下の 「3つの盲点（壁）」 にぶつかりがちです。
1. スキーマ（型定義）迷子: 「どんなクエリやフィールドが使えるのか」が分からず、ドキュメントを往復してしまう。
2. タイポ（打ち間違い）の温床: カッコ `{ }` が多いGraphQLのクエリを手書きすると、構文エラーが多発する。
3. リアルタイム通信のテスト難度: WebSocketを使う「Subscription」は、通常のHTTPリクエストツールではテストできない。
Insomniaは、これらすべての課題を美しいUIと強力な機能で解決します。
軽量で動作が速く、GraphQLのスキーマを自動的に読み込んでコード補完（インテリセンス）を提供してくれるため、まるで高機能なIDE（統合開発環境）でコードを書いているかのような心地よさでテストができるのです。
—
ステップ1：検証用「GraphQLローカルサーバー」の準備
「まずは手元で動かして、完璧に理解したい！」というあなたのために、Query（取得）とSubscription（リアルタイム購読）の両方に対応した、極めてシンプルなGraphQLサーバーのコードを用意しました。
Node.js環境があれば、以下の手順で5分で起動できます。
1. プロジェクトの作成とライブラリのインストール
適当なフォルダを作成し、以下のコマンドを実行します。
プロジェクト初期化
npm init -y
必要なパッケージのインストール（Apollo ServerとWebSocket対応パッケージ）
npm install @apollo/server graphql graphql-ws ws cors body-parser
2. サーバーコード（`index.js`）の作成
以下のコードを `index.js` として保存してください。1秒ごとに現在時刻を配信する、完璧なSubscription機能付きのGraphQLサーバーです。
import { ApolloServer } from ‘@apollo/server’;
import { expressMiddleware } from ‘@apollo/server/express4’;
import { ApolloServerPluginDrainHttpServer } from ‘@apollo/server/plugin/drainHttpServer’;
import { makeExecutableSchema } from ‘@graphql-tools/schema’;
import { WebSocketServer } from ‘ws’;
import { useServer } from ‘graphql-ws/lib/use/ws’;
import express from ‘express’;
import http from ‘http’;
import cors from ‘cors’;
import bodyParser from ‘body-parser’;
// 1. スキーマ（型定義）の設計
// Query（一度きりの取得）と Subscription（リアルタイム監視）を定義します
const typeDefs = `#graphql
type Query {
hello: String!
}
type Subscription {
currentTime: String!
}
`;
// 2. リゾルバ（データ処理の実態）の定義
const resolvers = {
Query: {
hello: () => ‘Hello, Insomnia world!’,
},
Subscription: {
currentTime: {
// 1秒ごとに現在時刻をパブリッシュ（配信）する無限ループ
subscribe: async function () {
while (true) {
await new Promise((resolve) => setTimeout(resolve, 1000));
yield { currentTime: new Date().toLocaleTimeString() };
}
},
},
},
};
// 3. サーバーの起動設定
const schema = makeExecutableSchema({ typeDefs, resolvers });
const app = express();
const httpServer = http.createServer(app);
// WebSocketサーバーのセットアップ（Subscription用）
const wsServer = new WebSocketServer({
server: httpServer,
path: ‘/graphql’,
});
const serverCleanup = useServer({ schema }, wsServer);
// Apollo Serverの初期化
const server = new ApolloServer({
schema,
plugins: [
ApolloServerPluginDrainHttpServer({ httpServer }),
{
async serverWillStart() {
return {
async drainServer() {
await serverCleanup.dispose();
},
};
},
},
],
});
await server.start();
app.use(‘/graphql’, cors(), bodyParser.json(), expressMiddleware(server));
const PORT = 4000;
httpServer.listen(PORT, () => {
console.log(`🚀 Server ready at http://localhost:${PORT}/graphql`);
});
(※ ES Modulesを使用するため、`package.json` に `”type”: “module”` を追記して実行してください。)
サーバーの起動
node index.js
これで、`http://localhost:4000/graphql` でGraphQLサーバーが起動しました！
—
ステップ2：Insomniaのインストールと基本設定
まだInsomniaを持っていない方は、公式サイトからお使いのOSに合ったものをダウンロードしてインストールしてください。
- 公式サイト:
(https://insomnia.rest/)The Collaborative API Development PlatformLeading Open Source API Development Platform for HTTP, REST, GraphQL, gRPC, SOAP, and WebSocketsinsomnia.rest
起動したら、早速テスト環境を作っていきましょう。
1. リクエストの新規作成
1. 画面左側の「+」ボタンをクリックし、「HTTP Request」（または単にリクエスト）を新規作成します。
2. リクエストの名前を `GraphQL Hello` など、分かりやすい名前に変更します。
3. メソッドを `POST` に設定し、URLに `http://localhost:4000/graphql` を入力します。
2. ボディの形式を「GraphQL」に設定する
ここが最も重要なポイントです。URL入力欄の下にある「Body」のドロップダウンメニューから、「GraphQL」 を選択してください。
これで、Insomniaが「このリクエストはGraphQLだ」と認識し、専用の超強力なインターフェースに切り替わります。
—
ステップ3：スキーマ自動取得とインテリセンスの感動を味わう
まずは基本となる `Query` を投げてみましょう。
スキーマの自動取得（イントロスペクション）
ボディの形式を「GraphQL」に設定すると、Insomniaは自動的に指定されたURLのサーバーに対して「スキーマ情報を教えて！」と問い合わせを行います（これをイントロスペクションと呼びます）。
画面右側、または入力欄付近にある 「Schema」 というボタンや緑色のインジケータを確認してください。ここが「緑色（Loaded）」になっていれば、Insomniaがサーバーの設計図を完全に把握した証拠です。
インテリセンス（自動補完）でクエリを書く
クエリの入力欄に、以下のように打ち込んでみてください。
query {
}
`{` の中で `Ctrl + Space`（Macは `Cmd + Space`）を押してみましょう。
なんと、サーバー側で定義した `hello` というフィールドが、候補として自動的にポップアップ表示されます！
query {
hello
}
手入力をしなくても、候補を選択するだけでクエリが完成します。スペルミスによるエラーはこれで100%防げますね。
クエリを実行する
上部にある大きな 「Send」 ボタンを押してみましょう。
右側のレスポンスエリアに、美しいJSON形式で結果が返ってきます。
{
“data”: {
“hello”: “Hello, Insomnia world!”
}
}
初めてのGraphQLテストが、完璧な精度で成功しました！
—
ステップ4：難関「Subscription（サブスクリプション）」をリアルタイム監視する
さて、ここからが今回の本番であり、多くのエンジニアが「どうやってテストすればいいんだ？」と頭を抱えるポイントです。
GraphQL Subscriptionは、HTTPではなく WebSocket（`ws://` または `wss://`） プロトコルを使用して、サーバーからイベントをリアルタイムにプッシュ受信する技術です。
Insomniaは、このSubscriptionのテストにも完全対応しています。
1. Subscription用の新規リクエストを作成する
1. 左側のリストで「+」ボタンを押し、今度は 「WebSocket Request」（または最新バージョンでは通常のRequestを作成してプロトコルを変更）を選択します。
2. リクエスト名を `Subscription Watcher` にします。
3. URLのプロトコル部分を `http` から `ws` に書き換え、以下のように入力します。
`ws://localhost:4000/graphql`
2. サブスクリプションクエリを送信する
WebSocket接続を開く前に、サーバーに対して「このデータを購読します」というGraphQLの命令を送る必要があります。
1. リクエストの「JSON」または「Plain Text」タブ（あるいはGraphQL専用タブ）を開きます。今回はわかりやすく、プレーンテキスト、またはWebSocketのペイロードとして、GraphQL-WSプロトコルに則ったメッセージを送信します。
2. ですが、もっと簡単な方法があります。実は、先ほど作成した通常の「GraphQLリクエスト」のURLを `ws://localhost:4000/graphql` に書き換え、クエリを以下のように書き換えるだけでも、Insomniaは自動的にWebSocketとして処理してくれるのです！
subscription {
currentTime
}
この状態で 「Send」（または 「Connect」）ボタンを押してみましょう。
3. リアルタイムに流れるデータを監視する
接続が確立されると、画面下部、またはレスポンスエリアに タイムライン が表示されます。
1秒ごとに、サーバーから新しい時刻データが「シュッ、シュッ」と流れてくるのが目に見えるはずです。
{ “data”: { “currentTime”: “15:30:01” } }
{ “data”: { “currentTime”: “15:30:02” } }
{ “data”: { “currentTime”: “15:30:03” } }
「本当にリアルタイムにつながっている！」という興奮と安心感を、これほど簡単な操作で得られるのはInsomniaならではの体験です。テストを終了するときは、「Disconnect」 ボタンを押すだけで安全に切断できます。
—
現場で差がつくプロのTips
最後に、明日からの実務で先輩エンジニアやチームメンバーを「おっ、やるな」と唸らせるプロのテクニックを2つご紹介します。
1. GraphQL Variables（変数）を使いこなす
クエリの中に検索IDなどのパラメータを直接ハードコードするのは避けましょう。Insomniaのクエリ入力欄の下には、「Query Variables」 というJSONを入力するエリアがあります。
クエリ側は変数（$id）で定義
query GetUser($id: ID!) {
user(id: $id) {
name
email
}
}
// Variablesエリアに定義
{
“id”: “user-99”
}
このように分けて管理することで、本番環境やテスト環境でのIDの切り替えが格段にスムーズになります。
2. 環境変数（Environments）でのエンドポイント一元管理
開発環境（Local）、ステージング環境（Staging）、本番環境（Production）でURLや認証トークン（Authorizationヘッダー）は変わるものです。
Insomniaの画面左上にある 「Manage Environments」 から環境変数を作成し、以下のように定義しておきましょう。
{
“base_url”: “localhost:4000”,
“protocol”: “http”,
“ws_protocol”: “ws”
}
リクエストのURL欄には `{{ _.protocol }}://{{ _.base_url }}/graphql` と入力するだけで、環境を切り替えるだけで一瞬にして接続先を切り替えることができます。
—
まとめ
お疲れ様でした！
一見、難解そうに見えるGraphQLのクエリ構築や、WebSocketを伴うサブスクリプションのテストも、Insomniaを使えばこんなにもシンプルで、かつビジュアルに確認できることがお分かりいただけたかと思います。
API開発において、「確実かつ素早くモックや実機で動作確認ができること」 は、開発速度を倍速にするための最大の武器です。
今回学んだ知識があれば、実務でGraphQLが導入されても、慌てることなくスマートに開発を進められるはずです。ぜひ、日々のプロジェクトでこの快適さを体感してみてくださいね。
あなたの開発ライフが、より豊かで楽しいものになりますように！