La plupart des tests d'API s'exécutent de manière linéaire. Appel à la connexion, appel au paiement, appel au point de terminaison de reçu, assertion en cours de route. Cela fonctionne jusqu'à ce qu'une étape puisse échouer d'une manière dont l'étape suivante dépend. Si la connexion renvoie un 401, l'exécution de la requête de paiement est inutile. Pire encore, cela masque la véritable défaillance derrière une seconde, trompeuse. Ce que vous voulez, c'est un test qui lit la réponse de connexion, décide si elle doit continuer et indique la vérité sur l'endroit où les choses ont échoué.
Cette décision est une logique conditionnelle, et vous la construisez avec le contrôle de flux. Ce guide vous montre comment ajouter une ramification if/else à un scénario de test d'API dans Apidog afin qu'une exécution puisse se ramifier en fonction d'une réponse précédente. Vous allez construire un scénario réel : se connecter, vérifier le code de statut, et ne procéder au paiement que si la connexion a réellement fonctionné. Si vous êtes novice en matière de scénarios Apidog, le guide sur la façon d'écrire un scénario de test avec Apidog couvre les bases linéaires sur lesquelles cet article s'appuie. Pour une définition du modèle de ramification lui-même, le guide MDN sur les instructions conditionnelles est une bonne introduction. Vous pouvez télécharger Apidog et suivre gratuitement.
Ce qu'est le contrôle de flux, et ce qu'il n'est pas
Dans Apidog, les tests automatisés se trouvent dans le module Tests. L'unité avec laquelle vous travaillez est un scénario de test (Test Scenario), que la documentation décrit comme analogue à une collection dans Postman. À l'intérieur d'un scénario, vous organisez les étapes de test (Test Steps) : chaque étape est soit une requête individuelle, soit un élément de contrôle de flux comme une branche, une boucle ou un délai.
Le contrôle de flux est l'ensemble des éléments de contrôle de flux. Il permet à un scénario de faire plus que d'exécuter des requêtes dans l'ordre. La documentation Apidog sur le contrôle de flux et le branchement conditionnel est la référence derrière chaque étiquette utilisée ici. Celle sur laquelle cet article se concentre est le Branchement Conditionnel (Conditional Branching), qui est le nom d'Apidog pour if/else. Une branche lit une valeur que vous lui donnez, teste cette valeur par rapport à une condition, et exécute un ensemble d'étapes lorsque la condition est remplie et un autre ensemble lorsque ce n'est pas le cas.
Une clarification d'emblée, car les deux sont souvent confondus. Le branchement n'est pas la bouclage. Une branche décide une seule fois si un bloc d'étapes s'exécute. Une boucle exécute un bloc plusieurs fois. Apidog dispose de fonctionnalités distinctes pour l'itération, appelées boucles For (For Loops) et boucles ForEach (ForEach Loops), et elles appartiennent à un problème différent : répéter la même requête sur une plage ou sur les éléments d'un tableau. Si vous devez parcourir un tableau d'identifiants de commande, il s'agit d'une boucle ForEach, couverte dans le tutoriel sur la boucle ForEach, et non d'une branche. Ce guide reste sur le if/else.
La documentation Apidog ne mentionne aucune restriction gratuite ou payante concernant le contrôle de flux, le branchement conditionnel, les boucles ou le passage de données entre les étapes. Il n'y a pas non plus de distinction cloud ou auto-hébergé notée pour ces fonctionnalités. Si vous pouvez construire un scénario, vous pouvez y ajouter une branche.
Construire un scénario qui se ramifie en fonction de la réponse de connexion
Voici l'objectif. Un utilisateur se connecte. Si le point de terminaison de connexion renvoie un 200, le scénario procède à la création d'un paiement. S'il renvoie autre chose, le scénario s'arrête et signale l'échec au lieu de prétendre que le paiement a eu lieu.
Étape 1 : créer le scénario de test
Ouvrez Apidog et accédez au module Tests. Cliquez sur le `+` à côté de la barre de recherche pour créer un nouveau scénario de test (Test Scenario), choisissez le répertoire dans lequel il doit se trouver et définissez une priorité pour finaliser la création. Vous disposez maintenant d'un scénario vide prêt pour les étapes.
Étape 2 : ajouter la requête de connexion comme première étape
Ajoutez votre première étape de test (Test Step). Apidog vous offre plusieurs façons d'intégrer une requête : l'importer depuis une spécification de point de terminaison existante, l'importer depuis un cas de point de terminaison enregistré, ajouter directement une requête personnalisée ou en ajouter une à partir d'une chaîne cURL. Pour un démarrage rapide, ajoutez une requête personnalisée. Définissez-la comme POST et pointez-la vers votre point de terminaison d'authentification avec un corps JSON :
POST https://api.your-store.com/v1/login
Content-Type: application/json
{
"email": "dana@example.com",
"password": "correct-horse-battery-staple"
}
Exécutez cette étape une fois seule pour confirmer qu'elle renvoie ce que vous attendez. Une bonne connexion renvoie un 200 et un jeton dans le corps, quelque chose comme :
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"userId": "usr_10482"
}
Étape 3 : entrer en mode orchestration
Cliquez sur n'importe quelle étape pour entrer en mode orchestration. Le panneau de gauche affiche le flux global du scénario ; le panneau de droite affiche les détails de l'étape que vous avez sélectionnée. Cette vue divisée est l'endroit où vous arrangez la branche. Si jamais vous avez besoin de réordonner les étapes, faites glisser l'icône `≡` sur une étape pour la déplacer.
Étape 4 : ajouter la branche conditionnelle
Cliquez sur le bouton `Ajouter une étape` (Add Step). C'est la principale façon d'insérer n'importe quel élément de contrôle de flux. Dans le menu, choisissez `Branchement Conditionnel` (Conditional Branching). Cela crée une instruction If, une branche vide attendant une condition et des étapes à exécuter.
Maintenant, construisez la condition. Vous devez alimenter la branche avec le code de statut de la réponse de connexion. Apidog construit des conditions à partir d'un ensemble fixe d'opérateurs de jugement. La liste complète est : Est égal à (Equals), N'est pas égal à (Does not equal), Existe (Exists), N'existe pas (Does not exist), Inférieur à (Less than), Inférieur ou égal à (Less than or equal), Supérieur à (Greater than), Supérieur ou égal à (Greater than or equal), Correspond à une expression régulière (Matches with Regex), Contient (Contains), Ne contient pas (Does not contain), Est vide (Is empty), N'est pas vide (Is not Empty), Dans la liste (In List), et Pas dans la liste (Not in List).
Pour cette branche, vous voulez que le code de statut de connexion soit égal à 200. La condition se lit donc : le statut de la réponse de connexion `Est égal à` `200`.
Étape 5 : référencer la réponse précédente dans la condition
Pour obtenir le résultat de la connexion dans le champ de condition, vous avez deux méthodes.
La première méthode ne nécessite aucune configuration. Cliquez dans le champ de valeur de la condition et cliquez sur l'icône de la baguette magique, puis sélectionnez `Récupérer les données de l'étape précédente` (Retrieve pre-step data). Apidog vous permet de pointer directement vers l'étape de connexion précédente et d'extraire une valeur de sa réponse. En interne, cela utilise une référence de pré-étape avec la syntaxe `{{$.<step id>.response.body.<field path>}}`. Si vous vouliez le jeton du corps de la connexion au lieu du statut, par exemple, vous feriez référence à `{{$.1.response.body.token}}`, où `1` est l'identifiant de l'étape de connexion.
Deux choses à savoir sur `Récupérer les données de l'étape précédente`. Cela ne fonctionne que dans le module Tests, et non dans le module APIs. Et cela ne se résout que lorsque vous exécutez le scénario entier, et non lorsque vous exécutez une seule étape isolément. Si une référence de pré-étape semble vide lors d'une exécution solo, c'est normal ; exécutez le scénario complet et elle se remplira.
La deuxième méthode utilise une variable nommée et fonctionne dans les modules Tests et APIs. Dans la requête de connexion, ouvrez ses post-processeurs et ajoutez une action `Extraire la variable` (Extract Variable). Extrayez le champ qui vous intéresse avec une expression JSONPath, par exemple `$.token`, et Apidog le stocke sous un nom. Vous le référencez ensuite n'importe où plus tard comme `{{token}}`. C'est l'approche la plus portable lorsque vous voulez que la même valeur soit disponible dans plusieurs modules ou dans plusieurs branches. Les mécanismes plus profonds du déplacement des valeurs entre les étapes sont couverts dans le guide sur comment passer des données entre les étapes de test.
Pour la branche du code de statut, `Récupérer les données de l'étape précédente` sur le statut de l'étape de connexion est le chemin le plus court.
Étape 6 : ajouter la branche "Sinon"
Passez la souris sur le bloc If et cliquez sur `+ Sinon`. Cela vous donne le chemin alternatif qui s'exécute lorsque la condition est fausse, ce qui signifie que la connexion n'a pas renvoyé 200.
Maintenant, remplissez les deux côtés :
- À l'intérieur du bloc If, ajoutez la requête de paiement comme étape de test (Test Step). C'est le chemin heureux. Elle ne s'exécute que lorsque la connexion a renvoyé 200. Si le paiement nécessite le jeton de connexion, référencez-le ici avec `{{token}}` (si vous l'avez extrait) ou avec une référence de pré-étape au corps de la connexion. Un véritable appel de paiement porte souvent un jeton de type "bearer" dans l'en-tête `Authorization`, le même modèle que les documents de l'API Stripe utilisent pour les requêtes authentifiées.
- À l'intérieur du bloc Sinon, ajoutez une étape qui rend l'échec évident. Un choix courant est une requête vers un point de terminaison de journalisation ou de notification, ou une requête personnalisée avec une assertion qui échoue toujours afin que le rapport de scénario signale clairement cette exécution.
Votre scénario se lit maintenant comme une logique simple : si la connexion est égale à 200, exécutez le paiement ; sinon, signalez et arrêtez.
Étape 7 : sauvegarder
Cliquez sur `Enregistrer tout` (Save All) pour persister le scénario. Les modifications non enregistrées affichent un indicateur de point, donc si vous voyez ce point, vous avez encore du travail à faire. Exécutez le scénario complet et observez la résolution de la branche. Pointez la connexion vers des identifiants valides et le bloc If s'exécute. Pointez-la vers de mauvais identifiants et le bloc Sinon s'exécute à la place.
Variantes et contrôle de flux avancé
Une fois que la branche de base fonctionne, les mêmes blocs de construction couvrent beaucoup de terrain.
- Branchez-vous sur un champ de corps, pas seulement sur le statut. Les codes de statut sont le cas courant, mais les conditions lisent toute valeur que vous pouvez référencer. Supposons que votre connexion renvoie `200` même pour un compte verrouillé, avec le véritable état dans un champ `status`. Récupérez `{{$.1.response.body.status}}` et utilisez l'opérateur `Est égal à` contre `"active"`, ou utilisez `Contient` contre une chaîne de message. La liste des opérateurs vous donne également des vérifications de plage : `Supérieur à` sur un solde renvoyé, `Dans la liste` pour tester si un rôle renvoyé est l'une des plusieurs valeurs autorisées.
- Combinez le branchement avec les boucles. Le branchement et l'itération se composent. À l'intérieur d'une boucle ForEach sur un tableau d'identifiants de produit, une étape de Branchement Conditionnel (Conditional Branching) peut ignorer les produits en rupture de stock et traiter le reste. La référence d'index de boucle `{{$.<loop step id>.index}}` commence à 0, et un élément ForEach est `{{$.<loop step id>.element.<field path>}}`. Les boucles sont un sujet en soi ; le tutoriel sur la boucle ForEach les aborde correctement.
- Arrêter une boucle tôt avec `Break If`. Lorsque vous itérez, l'élément `Break If condition` met fin à la boucle dès qu'une condition est remplie. Vous pouvez le faire glisser pour le repositionner et l'ajouter plusieurs fois dans une boucle.
- Gérer les erreurs avec `On Error`. Les boucles comportent un élément `On Error` fixé au début de la boucle, que vous ne pouvez pas déplacer. Ses options décident ce qui se passe lorsqu'une requête à l'intérieur de la boucle échoue : `Ignorer` (Ignore) continue avec la requête suivante, `Continuer` (Continue) ignore le reste des requêtes du cycle actuel, `Arrêter l'exécution` (Break execution) arrête la boucle et procède après elle, et `Terminer l'exécution` (End execution) arrête tout le scénario.
- Ajouter une attente entre les étapes. Parfois, un service en aval a besoin d'un instant avant de refléter une écriture. L'élément `Wait` ajoute un délai mesuré en millisecondes, utile entre un appel de création et la lecture qui le vérifie.
- Référencer des valeurs à l'intérieur des scripts. Si une branche nécessite une logique trop complexe pour la liste des opérateurs, un script de pré-traitement ou de post-traitement peut la calculer. À l'intérieur d'un script, vous ne pouvez pas utiliser la syntaxe `{{variable}}` directement. Utilisez plutôt `pm.variables.get("$.2.response.body.token")`, en faisant correspondre l'identifiant de l'étape et le chemin du champ. Pour le modèle plus large de chaînage de requêtes afin qu'une alimente la suivante, consultez le guide sur le chaînage de requêtes et l'article plus détaillé sur l'orchestration des tests d'API et le passage de données.
Une note sur l'auto-référence : un scénario ne peut pas référencer le scénario de test original lui-même. Cette garde empêche les boucles infinies accidentelles lorsque vous imbriquez des scénarios.
Automatiser le flux de travail avec l'interface CLI d'Apidog
Le scénario que vous venez de construire n'a pas à s'exécuter uniquement à l'intérieur de l'application. Apidog propose un exécuteur en ligne de commande qui exécute des scénarios enregistrés sans interface graphique, ce qui est exactement ce que vous voulez en CI. Installez-le et connectez-vous :
npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
Ensuite, exécutez votre scénario de branchement par identifiant, en le pointant vers un environnement et en choisissant un rapporteur :
apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli
Ici, `-t` est l'identifiant du scénario de test, `-e` est l'identifiant de l'environnement, et `-r` est le rapporteur. Utilisez `cli` pour la sortie console, ou `html` et `junit` pour les artefacts que votre pipeline peut publier ; séparez-les par des virgules comme `-r html,cli` pour en émettre plusieurs à la fois. La branche se résout de la même manière que dans l'application : l'exécuteur lit la réponse de connexion, prend le chemin If ou Sinon, et le code de sortie reflète le résultat afin qu'une connexion échouée fasse échouer la build. La configuration complète se trouve dans le guide d'installation de l'interface CLI d'Apidog, et son intégration dans un pipeline est couverte dans le guide Apidog CLI GitHub Actions. Si vous préférez exécuter le même scénario à un moment donné plutôt qu'à chaque commit, consultez comment planifier des tests d'API dans Apidog.
FAQ
Quelle est la différence entre le Branchement Conditionnel et une boucle dans Apidog ?
Le Branchement Conditionnel (Conditional Branching) décide une seule fois si un bloc d'étapes s'exécute, en fonction d'une condition. Une boucle exécute un bloc de manière répétée. Utilisez une branche lorsque vous avez une décision soit/soit, comme procéder au paiement seulement si la connexion a réussi. Utilisez une boucle For ou ForEach lorsque vous devez répéter une requête sur un nombre ou un tableau. Le tutoriel sur la boucle ForEach couvre l'itération en détail.
Pourquoi ma référence Récupérer les données de l'étape précédente (Retrieve pre-step data) est-elle vide ?
Deux causes courantes. Premièrement, Récupérer les données de l'étape précédente ne fonctionne que dans le module Tests, et non dans le module APIs. Deuxièmement, elle ne se résout que lorsque vous exécutez l'intégralité du scénario de test. Si vous exécutez une seule étape isolément, la référence n'a encore rien à pointer. Exécutez le scénario complet et la valeur se remplira.
Puis-je me brancher sur un champ à l'intérieur du corps de la réponse, et pas seulement sur le code de statut ?
Oui. Référencez le champ avec une expression de pré-étape comme {{$.1.response.body.status}} ou extrayez-le dans une variable nommée, puis choisissez un opérateur tel que `Est égal à`, `Contient`, ou `Dans la liste`. Toute valeur que vous pouvez référencer peut piloter une condition. Le déplacement de ces valeurs est couvert dans comment passer des données entre les étapes de test.
Comment utiliser une variable à l'intérieur d'un script au lieu d'un constructeur de conditions ?
Les scripts n'acceptent pas directement la syntaxe {{variable}}. Utilisez pm.variables.get("$.2.response.body.token") dans un script de pré-traitement ou de post-traitement, en faisant correspondre l'identifiant de l'étape et le chemin du champ souhaité.
Le branchement coûte-t-il plus cher ou nécessite-t-il la version auto-hébergée ?
La documentation Apidog ne mentionne aucune restriction de plan pour le contrôle de flux, le branchement conditionnel, les boucles ou le passage de données, et aucune distinction cloud ou auto-hébergée pour ces fonctionnalités. Si vous pouvez construire un scénario, vous pouvez y ajouter des branches.
En résumé
Un test linéaire vous indique que quelque chose a échoué. Un test de branchement vous dit où, et cesse de gaspiller des étapes sur un chemin qui ne peut plus réussir. Ajoutez une étape de Branchement Conditionnel (Conditional Branching), alimentez-la avec une réponse précédente via `Récupérer les données de l'étape précédente` (Retrieve pre-step data) ou une variable extraite, connectez le If et le `+ Sinon`, et votre scénario prendra désormais des décisions comme le ferait votre véritable API. Lorsque cela fonctionne dans l'application, une seule commande `apidog run` transfère la même logique à la CI. Essayez Apidog gratuitement, aucune carte de crédit requise, et transformez vos tests linéaires en scénarios qui réfléchissent.