Comment tester les APIs GraphQL dans Apidog (Requêtes, Mutations et Automatisation)

Vous avez un point de terminaison GraphQL à valider : vérifier qu’une requête user renvoie les champs consommés par votre application, qu’une mutation createOrder crée réellement une commande et que le schéma reste cohérent quand les variables changent. Comme GraphQL envoie généralement toutes les opérations vers une seule URL via POST, un client REST centré sur les chemins et verbes HTTP ne suffit pas. Vous avez besoin d’un outil qui comprend les documents GraphQL, suggère les champs du schéma et permet d’asserter la réponse JSON.

Essayez Apidog dès aujourd’hui

Apidog traite GraphQL comme un type de requête natif, aux côtés de HTTP, gRPC, WebSocket, SSE et SOAP. Ce guide montre comment créer une requête GraphQL, récupérer le schéma pour l’auto-complétion, utiliser des variables, exécuter une mutation et ajouter des assertions. L’exemple repose sur une API e-commerce : récupérer un utilisateur et ses commandes, puis créer une commande.

Pour les concepts GraphQL, consultez la documentation officielle GraphQL. Pour choisir entre les approches, consultez aussi la comparaison REST vs GraphQL.

Ce que vous testez avec GraphQL

Avec REST, plusieurs points de terminaison renvoient généralement des structures fixes. Avec GraphQL, un unique point de terminaison permet au client de sélectionner précisément les champs nécessaires.

Cela change vos tests sur deux points :

1. La requête est un document GraphQL envoyé dans le corps HTTP, pas une URL à modifier. Par exemple, GET /users/42 devient :

   user(id: 42) {
     ...
   }

1. Une erreur GraphQL peut répondre avec 200 OK. Le transport HTTP a réussi, mais le corps contient alors un tableau errors.

Ne vous limitez donc pas au statut HTTP : vérifiez aussi errors et les données attendues sous data.

Créer une requête GraphQL dans Apidog

Commencez par télécharger Apidog ou ouvrez-le dans votre navigateur. Créez ou ouvrez ensuite un projet.

Étape 1 : créer la requête

1. Cliquez sur +.
2. Sélectionnez New Request.
3. Choisissez la méthode POST.
4. Saisissez l’URL de votre endpoint GraphQL :

   https://api.yourstore.com/graphql

1. Ouvrez Body, puis sélectionnez GraphQL.

Apidog affiche alors un éditeur avec une zone Query.

Si votre API demande une authentification, configurez-la dans Authorization, par exemple avec un jeton Bearer. Une requête GraphQL reste une requête HTTP : les en-têtes et mécanismes d’authentification se configurent donc comme pour une API REST.

Étape 2 : écrire une requête

Dans l’onglet Run, écrivez une requête qui récupère un utilisateur et ses commandes :

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

Les noms de champs doivent correspondre exactement au schéma de votre serveur. Si le champ s’appelle emailAddress plutôt que email, la requête échoue.

Étape 3 : récupérer le schéma

Pour éviter de deviner les champs disponibles :

1. Vérifiez que l’URL de l’endpoint est correcte.
2. Dans l’éditeur GraphQL, cliquez sur Fetch Schema.
3. Attendez la fin de l’introspection.
4. Utilisez l’auto-complétion pour sélectionner les champs et types valides.

La récupération du schéma est manuelle. Si votre schéma évolue, relancez Fetch Schema afin d’actualiser les suggestions.

Si l’introspection est désactivée sur votre serveur — ce qui peut arriver en production — Apidog ne pourra pas récupérer le schéma. Dans ce cas, utilisez votre documentation GraphQL pour écrire la sélection manuellement.

Étape 4 : exécuter et lire la réponse

Cliquez sur Send. Une réponse réussie peut ressembler à ceci :

{
  "data": {
    "user": {
      "id": "usr_1024",
      "name": "Dana Whitfield",
      "email": "[e-mail]",
      "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"
        }
      ]
    }
  }
}

Retenez la structure :

• les résultats se trouvent sous data;
• les erreurs GraphQL sont généralement sous errors;
• vos assertions JSONPath doivent donc cibler des chemins tels que $.data.user.orders.

Utiliser des variables pour réutiliser la requête

Ne laissez pas l’identifiant utilisateur codé en dur dans le document. Déclarez une variable GraphQL, puis fournissez sa valeur séparément.

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

Dans la zone des variables, ajoutez :

{
  "userId": "usr_1024"
}

Vous pouvez maintenant tester un autre utilisateur sans modifier la requête elle-même.

La syntaxe est standard GraphQL ; consultez la documentation GraphQL sur les variables. En combinant ces variables avec les variables d’environnement Apidog, vous pouvez utiliser le même document pour vos environnements de staging et de production.

Exécuter une mutation pour créer une commande

Les mutations s’écrivent dans la même zone Query. Remplacez simplement le mot-clé query par mutation.

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

Passez la charge utile dans les variables :

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

Cliquez sur Send. Une réponse attendue ressemble à ceci :

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

Exécutez les mutations sur un environnement de test ou de staging, pas directement en production.

Un flux de test utile est le suivant :

1. Interroger l’utilisateur.
2. Créer une commande.
3. Capturer l’id retourné par la mutation.
4. Interroger à nouveau l’utilisateur.
5. Vérifier que la commande créée apparaît dans orders.

Ajouter des assertions GraphQL

Une inspection visuelle du JSON convient pour explorer une API. Pour un test reproductible, ajoutez des assertions à chaque requête.

Apidog permet de configurer ces contrôles dans les assertions d’API.

Pour une requête GraphQL, ajoutez au minimum les trois vérifications suivantes :

1. Le statut HTTP est 200
   
   Cette vérification confirme que le transport HTTP a abouti.

2. Le champ errors est absent
   
   C’est la vérification GraphQL essentielle. Un statut 200 avec un tableau errors reste un échec fonctionnel.

3. Les valeurs attendues existent sous data
   
   Exemples de chemins JSONPath :
   

   $.data.createOrder.status

Valeur attendue :

   PENDING

Ou vérifiez que la liste suivante contient au moins un élément :

   $.data.user.orders

Cette combinaison détecte les cas qu’un simple contrôle HTTP manquerait : erreurs de validation, erreurs métier ou réponse ayant une structure inattendue.

Enregistrer le flux dans un scénario de test

Une requête avec assertions est un bon test de fumée. Pour vérifier un parcours complet, enchaînez vos appels dans un scénario :

1. Ajoutez la requête GetUserWithOrders.
2. Ajoutez la mutation CreateOrder.
3. Extrayez l’id de $.data.createOrder.id.
4. Stockez-le dans une variable de scénario.
5. Ajoutez une requête finale de confirmation.
6. Référencez la variable dans cette dernière étape.
7. Attachez des assertions à chaque étape.

Les scénarios de test Apidog permettent de séquencer les requêtes et de transmettre des données entre elles. Consultez le guide comment écrire un scénario de test avec Apidog.

Pour comparer GraphQL avec d’autres styles d’API, consultez :

• REST vs GraphQL vs gRPC
• Outils de test et de simulation GraphQL
• Comment tester les API SOAP dans Apidog

Automatiser avec l’interface CLI Apidog

Une fois les scénarios enregistrés dans votre projet, vous pouvez exécuter les scénarios de test du projet depuis un terminal ou un environnement CI.

Installez la CLI, puis authentifiez-vous :

npm install -g apidog-cli
apidog login --with-token <your-token>

Exécutez ensuite un scénario enregistré sur un environnement donné :

apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli

Paramètres :

• -t : ID du scénario de test ;
• -e : ID de l’environnement ;
• -r : rapporteur, par exemple cli, html ou junit.

Pour produire plusieurs rapports :

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

La CLI exécute les scénarios et suites de tests enregistrés dans votre projet cloud, puis remonte les succès et échecs dans votre processus de build.

La documentation de la CLI confirme l’exécution de scénarios HTTP, mais n’indique pas explicitement si les scénarios contenant des étapes GraphQL s’exécutent en mode headless. Utilisez donc la CLI pour vos exécutions de régression HTTP et la synchronisation de spécifications via import (OpenAPI, HAR, Postman et autres), et validez les flux GraphQL dans l’application.

Consultez le guide d’installation de la CLI Apidog et le guide Apidog CLI dans GitHub Actions.

FAQ

Ai-je besoin d’un forfait payant pour tester GraphQL dans Apidog ?

La documentation des requêtes GraphQL ne présente pas cette fonctionnalité comme réservée à un forfait spécifique. Vous pouvez commencer avec le niveau gratuit et consulter Apidog pour les détails actuels des forfaits.

Pourquoi ma requête GraphQL renvoie-t-elle 200 mais échoue-t-elle ?

C’est un comportement GraphQL courant. Le transport HTTP a réussi, donc le serveur répond 200, mais l’opération a rencontré une erreur de validation ou une erreur métier présente dans errors.

Vérifiez toujours à la fois :

• le statut HTTP ;
• l’absence de errors ;
• les valeurs attendues sous data.

Comment obtenir des suggestions de champs ?

Cliquez sur Fetch Schema dans l’éditeur GraphQL. Apidog exécute une introspection et active l’auto-complétion avec les champs et types disponibles.

Relancez cette récupération après une évolution du schéma.

Où écrire les mutations ?

Dans la même zone Query que les requêtes. Utilisez simplement le mot-clé mutation :

mutation MyMutation {
  # ...
}

Ajoutez les données d’entrée dans les variables JSON, puis cliquez sur Send.

Comment tester plusieurs valeurs sans réécrire la requête ?

Déclarez des variables GraphQL avec le préfixe $, puis envoyez leurs valeurs dans un objet JSON. Vous pouvez ensuite combiner ces variables avec les environnements Apidog pour réutiliser le même document entre staging et production.

En résumé

Pour tester GraphQL efficacement :

1. Créez une requête POST et sélectionnez le corps GraphQL.
2. Récupérez le schéma avec Fetch Schema.
3. Remplacez les valeurs codées en dur par des variables.
4. Vérifiez le contenu de data, pas uniquement le statut HTTP.
5. Assertissez l’absence de errors.
6. Enchaînez requêtes et mutations dans un scénario de test.

Construisez le flux utilisateur → création de commande → vérification de commande, puis réexécutez-le à chaque évolution de votre schéma GraphQL.