Vous avez un point de terminaison GraphQL et vous devez vous assurer qu'il fonctionne. Pas seulement que « le serveur est en ligne », mais que les requêtes user renvoient les champs lus par votre application, qu'une mutation createOrder persiste réellement une commande, et que les structures restent valides lorsque vous modifiez une variable. Un outil REST qui ne connaît que les appels chemin-et-verbe rend cela difficile. GraphQL envoie tout à une seule URL en tant que corps de requête POST, vous avez donc besoin d'un client qui comprend le langage de requête lui-même, vous donne des suggestions de champs et vous permet de faire des assertions sur le JSON renvoyé.
Apidog gère GraphQL comme un type de requête de première classe, à côté de HTTP, gRPC, WebSocket, SSE et SOAP. Ce guide vous expliquera comment construire une requête GraphQL de A à Z : écrire une requête, récupérer le schéma pour l'auto-complétion, passer des variables, exécuter une mutation et faire des assertions sur la réponse. L'exemple utilisé est une API e-commerce où vous interrogez un utilisateur et ses commandes, puis créez une nouvelle commande. Si vous souhaitez des informations conceptuelles sur la raison pour laquelle GraphQL envoie une seule requête typée au lieu de plusieurs points de terminaison, la documentation officielle de GraphQL est la référence canonique, et notre comparaison entre REST et GraphQL couvre les cas où chacun convient le mieux.
Ce que vous testez et pourquoi GraphQL est différent
REST vous offre de nombreux points de terminaison, chacun renvoyant une forme fixe. GraphQL vous donne un seul point de terminaison et permet à l'appelant de demander exactement les champs qu'il souhaite. Cette flexibilité est l'objectif principal, et c'est aussi ce qui rend les tests différents.
Deux choses changent. Premièrement, la requête est un document de requête dans le corps, et non une URL que vous modifiez. Un GET /users/42 devient une sélection user(id: 42) { ... } envoyée par POST. Deuxièmement, GraphQL ne renvoie presque jamais un statut non-200 pour une erreur métier. Une requête échouée revient tout de même avec un statut 200 OK et un tableau errors dans le JSON. Il ne suffit donc pas de vérifier le code de statut. Vous devez lire le corps. Ce fait unique détermine la manière dont vous ferez des assertions plus loin dans ce guide.
Apidog vous offre un type de corps de requête GraphQL dédié, une auto-complétion consciente du schéma, des variables pour des requêtes réutilisables, et les mêmes outils d'assertion et de scénario de test que vous utiliseriez pour REST. Vous concevez et exécutez la requête dans l'application, puis vous l'enregistrez dans un scénario que vous pourrez réexécuter. Construisons-en un.
Créer une requête GraphQL dans Apidog
D'abord, téléchargez Apidog ou ouvrez-le dans votre navigateur, puis ouvrez votre projet. Si vous partez de zéro, créez un projet pour que la requête ait un endroit où résider.
Étape 1 : Créer une nouvelle requête et basculer le corps en GraphQL
Cliquez sur le bouton + et choisissez New Request (Nouvelle Requête). Cela ouvre le constructeur de requêtes standard, le même que vous utiliseriez pour un appel REST : méthode, URL, paramètres et Authorization (Autorisation).
Définissez la méthode sur POST et collez votre point de terminaison GraphQL dans la barre d'URL. Un exemple typique ressemble à ceci :
https://api.yourstore.com/graphql
Indiquez maintenant à Apidog qu'il s'agit d'une requête GraphQL. Dans la zone du corps de la requête, cliquez sur Body (Corps), puis sélectionnez GraphQL. L'éditeur de corps passe à une vue compatible GraphQL avec une boîte Query (Requête), où réside le langage de requête.
Si votre point de terminaison nécessite un jeton, ouvrez la section Authorization (Autorisation) et ajoutez-le là, par exemple un jeton Bearer. L'authentification sur une requête GraphQL fonctionne de la même manière que toute autre requête HTTP dans Apidog, car en coulisses, il s'agit toujours d'une requête HTTP POST.
Étape 2 : Écrire votre première requête
Dans l'onglet Run (Exécuter), tapez votre requête dans la boîte Query (Requête). Commencez par quelque chose de concret. Ici, vous voulez un utilisateur et les commandes qui lui sont attachées :
query GetUserWithOrders {
user(id: "usr_1024") {
id
name
email
orders {
id
total
status
createdAt
}
}
}
Ceci demande un utilisateur et une liste imbriquée de ses commandes. Les noms des champs doivent correspondre exactement au schéma de votre serveur. Si votre schéma l'appelle emailAddress au lieu de email, cette requête échouera. C'est le rôle de l'étape suivante de l'éviter.
Étape 3 : Récupérer le schéma pour l'auto-complétion
Deviner les noms de champs est ce qui ralentit les tests GraphQL. Apidog peut lire votre schéma afin que l'éditeur suggère des champs et des types valides au fur et à mesure que vous tapez, au lieu de devoir vérifier un document dans un autre onglet.
Il s'agit d'une action manuelle, à la demande. Cliquez sur le bouton Fetch Schema (Récupérer le schéma) dans la boîte de saisie. Apidog exécute une requête d'introspection sur votre point de terminaison et extrait le système de types. Une fois réussi, l'auto-complétion s'active : commencez à taper un champ à l'intérieur d'une sélection et vous obtiendrez des suggestions de type IntelliSense pour ce qui est réellement disponible sur ce type.
Deux choses à savoir. L'auto-complétion n'est pas automatique ; elle ne s'active qu'après avoir cliqué sur Fetch Schema (Récupérer le schéma). Et si l'introspection est désactivée sur votre point de terminaison (certains serveurs de production le font pour des raisons de sécurité), la récupération ne renverra pas de schéma, vous devrez donc écrire les champs manuellement en vous basant sur votre propre documentation. Si la récupération fonctionne, refaites-la après chaque modification du schéma afin que les suggestions restent à jour.
Étape 4 : L'exécuter et lire la réponse
Cliquez sur Send (Envoyer). La réponse apparaît dans la partie inférieure de l'interface. Un résultat sain ressemble à ceci :
{
"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" }
]
}
}
}
Notez la clé de niveau supérieur data. Chaque réponse GraphQL imbrique votre résultat sous data, et tout problème apparaît dans un tableau errors frère. Gardez cette structure à l'esprit, car vos assertions pointeront vers data.user..., et non vers la racine.
Passer des variables pour rendre la requête réutilisable
Le codage en dur de "usr_1024" dans la requête fonctionne une fois. Pour une requête que vous réexécuterez sur différents utilisateurs et environnements, déplacez cette valeur dans une variable. GraphQL dispose d'une syntaxe de variable de première classe pour cela, et Apidog la prend en charge. La syntaxe elle-même est du GraphQL standard plutôt qu'une invention d'Apidog, de sorte que la documentation officielle de GraphQL sur les variables est la source de vérité.
Déclarez la variable dans la signature de la requête avec un préfixe $ et un type, puis utilisez-la dans les arguments :
query GetUserWithOrders($userId: ID!) {
user(id: $userId) {
id
name
orders {
id
total
status
}
}
}
Ensuite, fournissez la valeur sous forme d'un petit objet JSON de variables :
{
"userId": "usr_1024"
}
Désormais, la même requête s'exécute pour n'importe quel utilisateur en modifiant une seule valeur JSON. Associez cela aux variables d'environnement Apidog et vous pourrez pointer la requête identique vers les environnements de staging et de production sans modifier la requête. C'est ce qui transforme un appel ponctuel en quelque chose que vous pouvez enregistrer, partager et exécuter dans une suite.
Écrire une mutation pour créer une commande
Une mutation modifie les données. Dans GraphQL, il n'y a pas de protocole ou d'interface utilisateur séparée pour cela ; une mutation est écrite en GraphQL dans la même boîte Query (Requête), avec le mot-clé mutation au lieu de query. Ainsi, le flux de travail que vous connaissez déjà se transpose directement.
Ici, vous créez une commande pour l'utilisateur que vous avez interrogé précédemment :
mutation CreateOrder($input: CreateOrderInput!) {
createOrder(input: $input) {
id
total
status
createdAt
}
}
Les variables transportent la charge utile :
{
"input": {
"userId": "usr_1024",
"items": [
{ "sku": "TSHIRT-BLK-M", "quantity": 2 },
{ "sku": "MUG-CERAMIC", "quantity": 1 }
],
"currency": "USD"
}
}
Cliquez sur Send (Envoyer). Une bonne réponse renvoie la commande créée :
{
"data": {
"createOrder": {
"id": "ord_5003",
"total": 42.30,
"status": "PENDING",
"createdAt": "2026-07-15T10:22:11Z"
}
}
}
Étant donné que les mutations écrivent des données réelles, exécutez-les sur un environnement de test ou de staging, et non en production. Un modèle courant consiste à exécuter la mutation, à capturer l'id renvoyé, puis à exécuter à nouveau votre requête GetUserWithOrders et à confirmer que la nouvelle commande apparaît dans la liste. Cette boucle requête-mutation-requête est une vérification de bout en bout réaliste, et c'est exactement le genre de chose que vous voudrez enregistrer comme scénario dans la section suivante.
Faire des assertions sur la réponse plutôt que de la vérifier visuellement
Lire le JSON manuellement est acceptable pendant l'exploration. Pour un test qui s'exécute sans surveillance, vous avez besoin d'assertions qui passent ou échouent d'elles-mêmes. Apidog vous permet d'ajouter des assertions à une requête afin qu'une exécution soit jugée automatiquement, ce que vous configurez dans les assertions d'API.
Pour GraphQL, trois vérifications couvrent la plupart des cas :
- Affirmer que le statut HTTP est
200. Nécessaire mais pas suffisant, puisque GraphQL renvoie 200 même en cas d'erreurs métier. - Affirmer que le champ
errorsest absent. C'est la véritable porte de réussite ou d'échec de GraphQL. Sierrorsexiste, l'opération a échoué, quel que soit le statut. - Affirmer sur des valeurs spécifiques à l'intérieur de
data, en utilisant un JSONPath comme$.data.createOrder.statusest égal àPENDING, ou$.data.user.ordersa une longueur supérieure à zéro.
Cette combinaison intercepte les modes d'échec qu'une simple vérification de statut manquerait : une requête qui renvoie 200 avec un tableau errors, ou une qui réussit mais renvoie la mauvaise forme. Orientez vos assertions de valeur vers le chemin imbriqué sous data, correspondant à la structure de réponse que vous avez vue précédemment.
Enregistrer dans un scénario de test
Une seule requête assertée est un bon test de fumée. Le véritable avantage est d'enchaîner les requêtes dans un scénario : interroger l'utilisateur, créer une commande, puis interroger à nouveau pour confirmer qu'elle a persisté. Les scénarios de test Apidog vous permettent de séquencer ces étapes, de passer des données entre elles (capturer l'id de la mutation, l'injecter dans la requête de confirmation) et d'exécuter l'ensemble du flux en un seul clic. Le guide complet se trouve dans comment écrire un scénario de test avec Apidog.
À un niveau élevé : créez un nouveau scénario de test, ajoutez votre requête et mutation GraphQL comme étapes dans l'ordre, extrayez l'id de la commande de la réponse de la mutation dans une variable, et référencez cette variable dans l'étape de requête finale. Attachez les assertions de la section précédente à chaque étape. Vous disposez maintenant d'un test de régression reproductible pour votre API GraphQL qu'un humain, un planificateur ou un pipeline peut exécuter.
Pour les équipes qui comparent GraphQL à d'autres styles avant de s'engager, notre analyse de REST vs GraphQL vs gRPC et le récapitulatif des outils de test et de simulation GraphQL vous aident tous deux à replacer ce flux de travail dans son contexte. Et si votre pile technologique utilise également SOAP, le même modèle de requête et d'assertion s'applique dans comment tester les API SOAP dans Apidog.
Automatiser le flux de travail avec l'interface CLI d'Apidog
Une fois que vos scénarios GraphQL résident dans le projet, vous pouvez exécuter les scénarios de test enregistrés du projet depuis un terminal ou un exécuteur CI avec l'interface CLI d'Apidog. Installez-la et connectez-vous :
npm install -g apidog-cli
apidog login --with-token <your-token>
Exécutez ensuite un scénario enregistré par son ID, ciblé sur un environnement :
apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli
Ici, -t est l'ID du scénario de test, -e est l'ID de l'environnement, et -r est le rapporteur (cli, html ou junit ; séparez-les par des virgules, comme -r html,cli, pour plusieurs). La CLI exécute les scénarios enregistrés et les suites de tests de votre projet cloud et signale les succès ou les échecs, ce qui intègre Apidog dans un processus de build. Une mise en garde honnête : la documentation de la CLI confirme l'exécution de scénarios HTTP, et elle n'indique pas si les scénarios contenant des étapes GraphQL s'exécutent en mode headless. Considérez la CLI comme votre moteur pour les exécutions de régression HTTP et pour maintenir les spécifications synchronisées via sa commande import (OpenAPI, HAR, Postman, et plus), et effectuez votre travail de requête, de mutation et d'assertion GraphQL dans l'application. Consultez le guide d'installation de la CLI Apidog pour la configuration des jetons et Apidog CLI dans un pipeline GitHub Actions pour l'intégrer à votre CI.
FAQ
Ai-je besoin d'un forfait payant pour tester GraphQL dans Apidog ? La documentation des requêtes GraphQL n'impose pas cette fonctionnalité derrière un niveau de forfait, et elle ne trace pas non plus de ligne entre le cloud et l'auto-hébergement. Vous pouvez commencer avec le niveau gratuit : essayez-le gratuitement, aucune carte de crédit requise, et consultez Apidog pour les détails des forfaits actuels.
Pourquoi ma requête GraphQL renvoie-t-elle 200 mais échoue-t-elle quand même ? C'est un comportement GraphQL normal. Le transport a réussi, donc le statut HTTP est 200, mais l'opération a rencontré une erreur métier ou de validation qui se trouve dans le tableau errors du corps JSON. Assurez-vous toujours que errors est absent en plus de vérifier le statut, comme expliqué dans les assertions d'API.
Comment obtenir des suggestions de champs lors de l'écriture d'une requête ? Cliquez sur le bouton Fetch Schema (Récupérer le schéma) dans la boîte de saisie. Apidog introspecte votre point de terminaison et active l'auto-complétion afin que l'éditeur suggère des champs et des types valides. C'est une étape manuelle, non automatique, alors cliquez dessus une fois que votre URL de point de terminaison est définie, et refaites la récupération après tout changement de schéma.
Où vont les mutations ? Je ne vois pas d'onglet de mutation séparé. Il n'y en a pas. Une mutation est écrite en GraphQL dans la même boîte Query (Requête), en utilisant le mot-clé mutation au lieu de query. Transmettez sa charge utile via des variables, puis cliquez sur Send (Envoyer), tout comme pour une requête.
Comment passer différentes valeurs sans réécrire la requête ? Utilisez les variables GraphQL. Déclarez-les dans la signature de l'opération avec un préfixe $ et fournissez un objet JSON de valeurs. La syntaxe suit la spécification GraphQL standard, et le support des variables d'Apidog s'associe aux variables d'environnement afin qu'une requête s'exécute sur les environnements de staging et de production.
En résumé
Tester GraphQL se résume à quelques bonnes pratiques : écrire la requête dans la boîte Query (Requête), récupérer le schéma pour que l'éditeur vous aide, déplacer les valeurs fixes dans des variables, et faire des assertions sur le corps de la réponse plutôt que de faire confiance au code de statut. Exécutez une mutation de la même manière qu'une requête, puis enchaînez les deux dans un scénario enregistré afin que la vérification se répète. Téléchargez Apidog pour suivre, construisez le flux utilisateur-et-commandes ci-dessus, et vous aurez un test de régression GraphQL que vous pourrez réexécuter à chaque évolution de votre schéma.