DEV Community

Cover image for ApidogでのGraphQL APIテスト：クエリ、ミューテーション、自動化
Akira
Akira

Posted on • Originally published at apidog.com

ApidogでのGraphQL APIテスト：クエリ、ミューテーション、自動化

GraphQLエンドポイントが期待どおりに動作しているかを確認するには、「サーバーが稼働している」だけでは不十分です。たとえば、userクエリがアプリで使うフィールドを返すか、createOrderミューテーションが注文を永続化するか、変数を変えてもレスポンスの形状が維持されるかを検証する必要があります。GraphQLでは、通常は単一URLにPOSTするため、クエリ構文を扱い、スキーマに基づく補完を提供し、返却JSONをアサートできるクライアントが必要です。

今すぐApidogを試す

Apidogは、HTTP、gRPC、WebSocket、SSE、SOAPと並んで、GraphQLを専用のリクエストタイプとして扱えます。この記事では、GraphQLリクエストを作成し、スキーマを取得して補完を有効化し、変数・ミューテーション・アサーションを使って再実行可能なテストにする手順を説明します。

例として、ユーザーと注文を取得し、新しい注文を作成するEコマースAPIを使用します。GraphQLの基本は公式のGraphQLドキュメントを参照してください。RESTとGraphQLの比較では、使い分けも確認できます。

テスト内容とGraphQLの違い

RESTでは複数のエンドポイントがあり、それぞれが固定的なレスポンスを返します。一方、GraphQLでは通常1つのエンドポイントに対し、呼び出し側が必要なフィールドを選択します。

テスト時に特に意識する点は次の2つです。

  1. リクエスト本体はURLではなくクエリドキュメントです。

    RESTのGET /users/42は、GraphQLではPOSTボディ内のuser(id: 42) { ... }になります。

  2. HTTP 200だけでは成功を判断できません。

    GraphQLはビジネスエラーや検証エラーがあっても、200 OKとJSON内のerrors配列を返すことがあります。

したがって、GraphQLテストではステータスコードだけでなく、レスポンスボディのerrorsとdataを検証する必要があります。

Apidogでは、GraphQL専用ボディ、スキーマ対応のコード補完、変数、アサーション、テストシナリオを利用できます。

ApidogでGraphQLリクエストを作成する

まず、Apidogをダウンロードするか、ブラウザ版を開きます。リクエストを保存するプロジェクトを作成または選択してください。

ステップ1：新しいリクエストを作成してGraphQLを選択する

  1. + をクリックし、New Request を選択します。
  2. HTTPメソッドを POST に設定します。
  3. GraphQLエンドポイントを入力します。 
https://api.yourstore.com/graphql
Enter fullscreen mode Exit fullscreen mode
  1. Body を開き、GraphQL を選択します。
  2. Query ボックスにGraphQLクエリを入力します。

認証が必要な場合は、Authorization セクションでBearerトークンなどを設定します。GraphQLリクエストもHTTP POSTとして送信されるため、認証設定は通常のHTTPリクエストと同じです。

ステップ2：最初のクエリを実行する

Query ボックスに、ユーザーとその注文を取得するクエリを入力します。

query GetUserWithOrders {
  user(id: "usr_1024") {
    id
    name
    email
    orders {
      id
      total
      status
      createdAt
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

このクエリは、1人のユーザーと注文一覧をネストして取得します。

フィールド名はサーバーのスキーマと完全に一致している必要があります。たとえば、スキーマ上のフィールドがemailではなくemailAddressなら、上記のクエリは失敗します。次の手順でスキーマを取得して、入力ミスを減らします。

ステップ3：スキーマを取得してコード補完を有効にする

GraphQLではフィールド名や型を推測せず、スキーマから補完を使うのが効率的です。

  1. GraphQLリクエストの入力画面で Fetch Schema をクリックします。
  2. Apidogがイントロスペクションクエリを実行します。
  3. 成功すると、フィールドや型の候補がエディタに表示されます。

注意点は次のとおりです。

  • コード補完は自動ではなく、Fetch Schema の実行後に有効になります。
  • 本番環境などでイントロスペクションが無効な場合、スキーマは取得できません。
  • スキーマが変更されたら、再度取得して補完内容を更新します。

ステップ4：送信してレスポンスを確認する

Send をクリックすると、レスポンスが表示されます。成功時の例は次のとおりです。

{
  "data": {
    "user": {
      "id": "usr_1024",
      "name": "Dana Whitfield",
      "email": "dana@example.com",
      "orders": [
        {
          "id": "ord_5001",
          "total": 89.9,
          "status": "SHIPPED",
          "createdAt": "2026-07-01T09:14:00Z"
        },
        {
          "id": "ord_5002",
          "total": 12.5,
          "status": "PENDING",
          "createdAt": "2026-07-12T16:03:00Z"
        }
      ]
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

GraphQLの結果は通常、最上位のdataに入ります。問題がある場合は、同じ階層にerrors配列が含まれます。

{
  "data": null,
  "errors": [
    {
      "message": "..."
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

アサーションでJSONPathを使う場合は、ルートではなく$.data.userのようにdata配下を参照します。

リクエストを再利用可能にするために変数を渡す

ユーザーIDをクエリに直接書く方法は、単発確認では使えます。しかし、環境やテスト対象を切り替える場合はGraphQL変数を使います。

GraphQL変数の構文は標準仕様です。詳細は公式のGraphQL変数ドキュメントを参照してください。

クエリのシグネチャで変数を宣言します。

query GetUserWithOrders($userId: ID!) {
  user(id: $userId) {
    id
    name
    orders {
      id
      total
      status
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

次に、変数の値をJSONで指定します。

{
  "userId": "usr_1024"
}
Enter fullscreen mode Exit fullscreen mode

これでクエリ本体を編集せずに、変数値だけを切り替えて別のユーザーを取得できます。

Apidogの環境変数と組み合わせれば、同じリクエストをステージング環境や本番環境に向けて再利用できます。

注文を作成するミューテーションを実行する

GraphQLのミューテーションはデータを変更します。専用の画面や別タブは不要です。Query ボックス内でqueryの代わりにmutationを使用します。

以下は注文を作成する例です。

mutation CreateOrder($input: CreateOrderInput!) {
  createOrder(input: $input) {
    id
    total
    status
    createdAt
  }
}
Enter fullscreen mode Exit fullscreen mode

入力値は変数として渡します。

{
  "input": {
    "userId": "usr_1024",
    "items": [
      {
        "sku": "TSHIRT-BLK-M",
        "quantity": 2
      },
      {
        "sku": "MUG-CERAMIC",
        "quantity": 1
      }
    ],
    "currency": "USD"
  }
}
Enter fullscreen mode Exit fullscreen mode

Send をクリックすると、作成された注文が返ります。

{
  "data": {
    "createOrder": {
      "id": "ord_5003",
      "total": 42.3,
      "status": "PENDING",
      "createdAt": "2026-07-15T10:22:11Z"
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

ミューテーションは実データを書き換えるため、原則としてテスト環境またはステージング環境で実行してください。

実用的なE2Eテストでは、次の順序にします。

  1. ユーザーと既存注文を取得する
  2. ミューテーションで注文を作成する
  3. 作成レスポンスから注文IDを取得する
  4. ユーザーを再取得し、新しい注文が存在することを確認する

目視確認ではなくレスポンスをアサートする

手動確認ではレスポンスJSONを読むだけでも問題ありません。しかし、CIや定期実行では、自動で成功・失敗を判定するアサーションが必要です。

Apidogでは、リクエストにAPIアサーションを設定できます。

GraphQLでは、少なくとも次の3つを検証してください。

  • HTTPステータスが200である
  • errorsフィールドが存在しない
  • data配下の必要な値が期待どおりである

たとえば、以下のようなJSONPathで確認します。

$.data.createOrder.status
Enter fullscreen mode Exit fullscreen mode

期待値:

PENDING
Enter fullscreen mode Exit fullscreen mode

また、注文配列が空ではないことを確認する場合は、$.data.user.ordersの長さが0より大きいことをアサートします。

HTTP 200だけを確認すると、以下のような失敗を見逃します。

  • errorsを含むGraphQLレスポンス
  • ステータスは成功だが、必要なフィールドが返っていないレスポンス
  • ミューテーションの結果が想定した状態ではないケース

テストシナリオとして保存する

単一リクエストのアサーションはスモークテストとして有効です。より実践的には、複数のGraphQLリクエストをテストシナリオとして連鎖させます。

たとえば、次のフローです。

  1. ユーザーを取得する
  2. 注文を作成する
  3. ミューテーションレスポンスから注文IDを変数として保存する
  4. 再度ユーザーを取得する
  5. 作成済み注文が一覧に含まれることをアサートする

Apidogのテストシナリオでは、ステップを順序付けし、前のレスポンスから抽出した値を次のステップで利用できます。具体的な作成方法は、Apidogでテストシナリオを作成する方法を参照してください。

GraphQLを他のAPIスタイルと比較する場合は、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>
Enter fullscreen mode Exit fullscreen mode

保存済みシナリオを、環境IDを指定して実行します。

apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli
Enter fullscreen mode Exit fullscreen mode

主なオプションは次のとおりです。

オプション 内容
-t テストシナリオID
-e 環境ID
-r レポーター。cli、html、junitを指定可能

複数のレポーターを使う場合は、コンマ区切りで指定します。

apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r html,cli
Enter fullscreen mode Exit fullscreen mode

CLIはクラウドプロジェクトの保存済みシナリオやテストスイートを実行し、合否を出力します。

ただし、CLIのドキュメントではHTTPシナリオの実行は明記されていますが、GraphQLステップを含むシナリオのヘッドレス実行については明記されていません。GraphQLクエリ、ミューテーション、アサーションの作成はアプリで行い、CLIはHTTPリグレッション実行やimportコマンドによるOpenAPI、HAR、Postmanなどの同期に利用するのが安全です。

トークン設定はApidog CLIインストールガイド、CI統合はGitHub ActionsパイプラインでのApidog CLIを参照してください。

FAQ

ApidogでGraphQLをテストするために有料プランは必要ですか？

GraphQLリクエストのドキュメントでは、この機能が特定のプランに限定されているとは記載されていません。無料プランから開始でき、クレジットカードは不要です。詳細はApidogで確認してください。

GraphQLリクエストがHTTP 200を返すのに失敗するのはなぜですか？

GraphQLでは通常の挙動です。HTTP通信自体は成功しているため200が返りますが、クエリの検証エラーやビジネスエラーはレスポンスボディのerrors配列に格納されます。

そのため、ステータスコードに加え、errorsが存在しないことを必ずアサートしてください。

クエリ入力中にフィールド候補を表示するにはどうすればよいですか？

Fetch Schema をクリックしてください。Apidogがイントロスペクションを実行し、コード補完を有効にします。スキーマが変更された場合は、再度取得してください。

ミューテーションはどこに入力しますか？

別タブはありません。通常のQueryボックスに、queryではなくmutationキーワードを使って記述します。

mutation CreateOrder($input: CreateOrderInput!) {
  createOrder(input: $input) {
    id
  }
}
Enter fullscreen mode Exit fullscreen mode

クエリを書き換えずに異なる値を渡すにはどうすればよいですか？

GraphQL変数を使用します。オペレーション定義で$付きの変数を宣言し、別のJSONオブジェクトで値を渡します。

query GetUser($userId: ID!) {
  user(id: $userId) {
    id
    name
  }
}
Enter fullscreen mode Exit fullscreen mode 
{
  "userId": "usr_1024"
}
Enter fullscreen mode Exit fullscreen mode

変数構文は標準のGraphQL仕様に従います。

まとめ

GraphQLテストを実装するときは、次の流れを基本にしてください。

  1. Query ボックスにクエリまたはミューテーションを書く
  2. Fetch Schema でスキーマを取得し、補完を有効にする
  3. 固定値をGraphQL変数へ移す
  4. HTTPステータスだけでなくerrorsとdataをアサートする
  5. クエリとミューテーションをテストシナリオとして連鎖させる
  6. 必要に応じてCLIやCIで繰り返し実行する

ユーザー取得、注文作成、作成結果の再取得までを1つのシナリオにすれば、スキーマ変更やAPI改修後にも再利用できるGraphQLリグレッションテストになります。

Top comments (0)