GraphQLエンドポイントがあり、それが機能していることを確認する必要があります。「サーバーが稼働している」だけでなく、実際のところ、userクエリがアプリが読み取るフィールドを返すか、createOrderミューテーションが実際に注文を永続化するか、変数を変更したときに形状が維持されるかを確認する必要があります。パスと動詞の呼び出ししか知らないRESTツールでは、これはやりにくいです。GraphQLはすべてをPOSTボディとして1つのURLに送信するため、クエリ言語自体を理解し、フィールドの提案を提供し、返されるJSONをアサートできるクライアントが必要です。
Apidogは、HTTP、gRPC、WebSocket、SSE、SOAPと並んで、GraphQLを第一級のリクエストタイプとして扱います。このガイドでは、GraphQLリクエストをゼロから構築する方法を説明します。クエリの記述、コード補完のためのスキーマの取得、変数の渡し方、ミューテーションの実行、およびレスポンスのアサートについてです。実行例は、ユーザーとその注文をクエリし、新しい注文を作成するEコマースAPIです。GraphQLが多数のエンドポイントの代わりに単一の型付きクエリを送信する理由に関する概念的背景を知りたい場合は、公式のGraphQLドキュメントが信頼できる情報源であり、RESTとGraphQLの比較では、それぞれがどのような場合に適しているかを説明しています。
テスト内容とGraphQLの違い
RESTは多くのエンドポイントを提供し、それぞれが固定された形状を返します。GraphQLは1つのエンドポイントを提供し、呼び出し元が بالضبط 必要なフィールドを要求できるようにします。その柔軟性こそが重要な点であり、テストの感覚が異なる理由でもあります。
2つの点が異なります。まず、リクエストは可変のURLではなく、ボディ内のクエリドキュメントです。GET /users/42は、POSTで送信されるuser(id: 42) { ... }選択に変わります。次に、GraphQLはビジネスエラーに対して非200ステータスを返すことはほとんどありません。失敗したクエリでも、JSONにerrors配列を含む200 OKで返されます。そのため、ステータスコードの確認だけでは不十分です。ボディを読み取る必要があります。この1つの事実が、このガイドの後半でどのようにアサートを行うかを決定づけます。
Apidogは、専用のGraphQLボディタイプ、スキーマ対応のコード補完、再利用可能なクエリ用の変数、そしてRESTで使用するのと同じアサーションおよびテストシナリオツールを提供します。アプリでリクエストを設計・実行し、再実行可能なシナリオとして保存できます。さっそく構築してみましょう。
ApidogでGraphQLリクエストを作成する
まず、Apidogをダウンロードするか、ブラウザで開いてからプロジェクトを開きます。新しく始める場合は、リクエストを保存する場所としてプロジェクトを作成してください。
ステップ1：新しいリクエストを作成し、ボディをGraphQLに切り替える
+ボタンをクリックし、New Requestを選択します。これにより、REST呼び出しで使用するものと同じ標準のリクエストビルダーが開きます。そこにはメソッド、URL、パラメータ、およびAuthorizationが含まれます。
メソッドをPOSTに設定し、GraphQLエンドポイントをURLバーに貼り付けます。一般的なものは次のようになります。
https://api.yourstore.com/graphql
さて、ApidogにこれがGraphQLリクエストであることを伝えます。リクエストボディ領域でBodyをクリックし、次にGraphQLを選択します。ボディエディタがGraphQL対応ビューに変わり、クエリ言語を入力するQueryボックスが表示されます。
エンドポイントにトークンが必要な場合は、Authorizationセクションを開き、そこにBearerトークンなどを追加します。GraphQLリクエストの認証は、Apidogの他のHTTPリクエストと同様に機能します。なぜなら、内部的には依然としてHTTP POSTだからです。
ステップ2：最初のクエリを作成する
Runタブで、Queryボックスにクエリを入力します。具体的なものから始めましょう。ここでは、ユーザーとそのユーザーに紐付けられた注文を取得します。
query GetUserWithOrders {
user(id: "usr_1024") {
id
name
email
orders {
id
total
status
createdAt
}
}
}
これは、1人のユーザーとそのネストされた注文のリストを要求します。フィールド名はサーバーのスキーマと正確に一致する必要があります。スキーマでemailの代わりにemailAddressと呼んでいる場合、このクエリは失敗します。それを防ぐのが次のステップの役割です。
ステップ3：コード補完のためにスキーマを取得する
フィールド名を推測することは、GraphQLテストの速度を低下させます。Apidogはスキーマを読み取ることができるため、別のタブでドキュメントを相互参照する代わりに、入力中にエディタが有効なフィールドと型を提案します。
これは手動のオンデマンドアクションです。入力ボックス内のFetch Schemaボタンをクリックします。Apidogはエンドポイントに対してイントロスペクションクエリを実行し、型システムを取得します。成功すると、コード補完がオンになります。選択内でフィールドの入力を開始すると、その型で実際に利用可能なものに対するIntelliSenseスタイルの提案が得られます。
知っておくべき2つのことがあります。コード補完は自動ではありません。Fetch Schemaをクリックした後にのみ有効になります。エンドポイントでイントロスペクションが無効になっている場合（セキュリティのために一部のプロダクションサーバーで無効になっています）、取得はスキーマを返さないため、独自のドキュメントに基づいてフィールドを手動で記述する必要があります。取得が機能する場合は、スキーマの変更後に再度取得して、提案が最新の状態に保たれるようにしてください。
ステップ4：実行してレスポンスを読み取る
Sendをクリックします。インターフェースの下半分にレスポンスが表示されます。正常な結果は次のようになります。
{
"data": {
"user": {
"id": "usr_1024",
"name": "Dana Whitfield",
"email": "dana@example.com",
"orders": [
{ "id": "ord_5001", "total": 89.90, "status": "SHIPPED", "createdAt": "2026-07-01T09:14:00Z" },
{ "id": "ord_5002", "total": 12.50, "status": "PENDING", "createdAt": "2026-07-12T16:03:00Z" }
]
}
}
}
最上位のdataキーに注目してください。すべてのGraphQLレスポンスは、結果をdataの下にネストし、問題は兄弟要素のerrors配列に表示されます。その構造を覚えておいてください。なぜなら、あなたのアサートはルートではなくdata.user...を指すからです。
リクエストを再利用可能にするために変数を渡す
クエリに"usr_1024"をハードコーディングする方法は一度は機能します。複数のユーザーや環境で再実行するリクエストの場合、その値を変数に移動させます。GraphQLにはこのための第一級の変数構文があり、Apidogはそれをサポートしています。構文自体はApidogの独自の発明ではなく標準のGraphQLであるため、変数の詳細については公式のGraphQLドキュメントが正しい情報源です。
クエリのシグネチャで`$`プレフィックスと型を指定して変数を宣言し、それを引数で使用します。
query GetUserWithOrders($userId: ID!) {
user(id: $userId) {
id
name
orders {
id
total
status
}
}
}
次に、変数の小さなJSONオブジェクトとして値を指定します。
{
"userId": "usr_1024"
}
これで、1つのJSON値を変更するだけで、任意のユーザーに対して同じクエリを実行できます。これをApidogの環境変数と組み合わせると、クエリを編集することなく、同一のリクエストをステージング環境と本番環境に適用できます。これにより、単発の呼び出しを、保存、共有、およびスイートで実行できるものに変えることができます。
注文を作成するミューテーションを作成する
ミューテーションはデータを変更します。GraphQLでは、これに対する個別のプロトコルやUIはありません。ミューテーションは、queryキーワードの代わりにmutationキーワードを使用して、同じQueryボックスにGraphQLとして記述されます。そのため、すでにご存知のワークフローをそのまま適用できます。
ここでは、以前にクエリしたユーザーの注文を作成します。
mutation CreateOrder($input: CreateOrderInput!) {
createOrder(input: $input) {
id
total
status
createdAt
}
}
変数がペイロードを運びます。
{
"input": {
"userId": "usr_1024",
"items": [
{ "sku": "TSHIRT-BLK-M", "quantity": 2 },
{ "sku": "MUG-CERAMIC", "quantity": 1 }
],
"currency": "USD"
}
}
Sendをクリックします。良好なレスポンスは、作成された注文を反映します。
{
"data": {
"createOrder": {
"id": "ord_5003",
"total": 42.30,
"status": "PENDING",
"createdAt": "2026-07-15T10:22:11Z"
}
}
}
ミューテーションは実際のデータを書き込むため、本番環境ではなくテスト環境またはステージング環境に対して実行してください。一般的なパターンは、ミューテーションを実行し、返されたidをキャプチャし、次にGetUserWithOrdersクエリを再度実行して、新しい注文がリストに表示されることを確認することです。そのクエリ→ミューテーション→クエリのループは現実的なエンドツーエンドチェックであり、次のセクションでシナリオとして保存したいと考える種類のものです。
目視確認ではなくレスポンスをアサートする
探索中にJSONを手動で読むのは問題ありません。無人実行されるテストでは、それ自体で合格または失敗するアサーションが必要です。Apidogを使用すると、リクエストにアサーションを追加して、実行が自動的に判断されるようになります。これはAPIアサーションで設定する内容です。
GraphQLの場合、3つのチェックがほとんどのケースをカバーします。
- HTTPステータスが
200であることをアサートします。GraphQLはビジネスエラーでも200を返すため、これは必要ですが十分ではありません。 errorsフィールドが存在しないことをアサートします。これが実際のGraphQLの合否を分けるポイントです。errorsが存在する場合、ステータスに関わらず操作は失敗しています。data内の特定の値をアサートします。例えば、$.data.createOrder.statusがPENDINGに等しいことや、$.data.user.ordersの長さがゼロより大きいことなどをJSONPathを使用して確認します。
この組み合わせにより、ステータスのみのチェックでは見逃してしまう失敗モード（例えば、`errors`配列を含む200を返すクエリや、成功したにもかかわらず間違った形状を返すクエリ）を捕捉できます。値のアサーションは、以前に見たレスポンス構造に合わせて、`data`の下のネストされたパスを指すようにします。
テストシナリオとして保存する
単一のアサートされたリクエストは、良いスモークテストになります。本当の価値は、リクエストをシナリオに連鎖させることです。ユーザーをクエリし、注文を作成し、再度クエリしてそれが永続化したことを確認します。Apidogのテストシナリオを使用すると、これらのステップを順序付けし、それらの間でデータを渡し（ミューテーションからidをキャプチャし、それを確認クエリに供給する）、ワンクリックでフロー全体を実行できます。完全なウォークスルーはApidogでテストシナリオを作成する方法にあります。
大まかに言えば、新しいテストシナリオを作成し、GraphQLクエリとミューテーションを順番にステップとして追加し、ミューテーションレスポンスから注文のidを変数に抽出し、その変数を最終クエリステップで参照します。前のセクションのアサーションを各ステップにアタッチします。これで、人間、スケジュール、またはパイプラインが実行できる、GraphQL APIの繰り返し可能なリグレッションテストができました。
コミットする前にGraphQLを他のスタイルと比較検討しているチームのために、REST vs GraphQL vs gRPCの比較と、GraphQLテストおよびモックツールのまとめは、このワークフローを文脈に位置付けるのに役立ちます。また、スタックがSOAPもサポートしている場合は、ApidogでSOAP APIをテストする方法で同じリクエストとアサートのパターンが適用されます。
Apidog CLIでワークフローを自動化する
GraphQLシナリオがプロジェクトに保存されると、Apidog CLIを使用して、ターミナルまたはCIランナーからプロジェクトの保存されたテストシナリオを実行できます。インストールしてログインします。
npm install -g apidog-cli
apidog login --with-token <your-token>
次に、環境を指定してIDで保存されたシナリオを実行します。
apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli
ここで、-tはテストシナリオID、-eは環境ID、-rはレポーター（cli、html、またはjunit。複数指定する場合は-r html,cliのようにコンマで区切ります）です。CLIは、クラウドプロジェクトから保存されたシナリオとテストスイートを実行し、合否を報告します。これによりApidogがビルドに組み込まれます。正直な注意点として：CLIのドキュメントはHTTPシナリオの実行を確約していますが、GraphQLステップを含むシナリオがヘッドレスで実行されるかどうかは明記されていません。CLIはHTTPリグレッション実行と、importコマンド（OpenAPI、HAR、Postmanなど）による仕様の同期のためのエンジンとして扱い、GraphQLクエリ、ミューテーション、およびアサーション作業はアプリで行ってください。トークン設定についてはApidog CLIインストールガイドを、CIへの組み込みについてはGitHub ActionsパイプラインでのApidog CLIを参照してください。
FAQ
ApidogでGraphQLをテストするために有料プランが必要ですか？ GraphQLリクエストのドキュメントでは、この機能が特定のプラン層で制限されているとは記載されておらず、クラウド版と自己ホスト版の区別もありません。無料プランから始めることができます。無料で試すことができ、クレジットカードは不要です。Apidogで現在のプランの詳細を確認してください。
GraphQLリクエストが200を返すのに失敗するのはなぜですか？ それは通常のGraphQLの挙動です。転送は成功したためHTTPステータスは200ですが、操作がビジネスエラーまたは検証エラーに遭遇し、それがJSONボディのerrors配列に格納されています。APIアサーションで説明されているように、ステータスチェックに加えて、常にerrorsが存在しないことをアサートしてください。
クエリ作成中にフィールドの提案を取得するにはどうすればよいですか？ 入力ボックス内のFetch Schemaボタンをクリックします。Apidogはエンドポイントをイントロスペクトし、コード補完を有効にして、エディタが有効なフィールドと型を提案するようにします。これは自動ではなく手動のステップですので、エンドポイントURLを設定したらクリックし、スキーマ変更後には再取得してください。
ミューテーションはどこに入力しますか？別のミューテーションタブが見当たりません。 別のタブはありません。ミューテーションは、queryキーワードの代わりにmutationキーワードを使用して、同じQueryボックスにGraphQLとして記述されます。変数を介してペイロードを渡し、クエリと同様にSendをクリックします。
クエリを書き換えずに異なる値を渡すにはどうすればよいですか？ GraphQL変数を使用します。オペレーションシグネチャで$プレフィックスを付けて宣言し、値のJSONオブジェクトを提供します。構文は標準のGraphQL仕様に従っており、Apidogの変数サポートは環境変数と連携するため、1つのリクエストをステージング環境と本番環境の両方で実行できます。
まとめ
GraphQLのテストは、いくつかの正直な習慣に要約されます。Queryボックスにクエリを記述し、エディタが役立つようにスキーマを取得し、固定値を変数に移動させ、ステータスコードを信頼するのではなくボディをアサートします。クエリを実行するのと同じ方法でミューテーションを実行し、両方を保存されたシナリオに連鎖させて、チェックを繰り返すようにします。Apidogをダウンロードして上記の手順に従い、ユーザーと注文のフローを構築すれば、スキーマが変更されるたびに再実行できるGraphQLリグレッションテストが完成します。