« Scénario de test » et « cas de test » sont utilisés comme s'ils signifiaient la même chose. Ce n'est pas le cas. Les confondre fait que les plans de test deviennent soit trop vagues pour être exécutés, soit trop détaillés pour être lus. L'un décrit ce qu'il faut tester ; l'autre décrit exactement comment. Si vous comprenez bien cette relation, votre couverture deviendra à la fois auditable et exécutable.
Ce guide définit chaque terme, présente les différences côte à côte et montre comment les deux fonctionnent ensemble dans un véritable flux de travail de test d'API à l'aide d'Apidog.
Qu'est-ce qu'un scénario de test ?
Un scénario de test est une description de haut niveau de quelque chose qui mérite d'être testé. Il nomme un comportement ou une condition sans spécifier les étapes exactes, les entrées ou les valeurs attendues.
Considérez-le comme un titre. Pour le processus de paiement d'un site de commerce électronique, les scénarios pourraient être :
- Vérifier le paiement pour un utilisateur enregistré avec une carte enregistrée
- Vérifier le paiement pour un utilisateur invité
- Vérifier le paiement lorsqu'un article est en rupture de stock en cours d'achat
- Vérifier le paiement lorsque le paiement est refusé
Chaque ligne vous indique *ce qu'* il faut valider et *pourquoi* cela est important pour l'entreprise. Aucune ne vous dit quel point d'accès appeler ni quelle charge utile envoyer. Un scénario est écrit du point de vue de l'utilisateur ou de l'exigence, il reste donc lisible aussi bien par les chefs de produit que par les ingénieurs.
Les scénarios répondent à une question : avons-nous pensé à tout ce qui devrait fonctionner ? Ils sont la carte de couverture. Si un scénario est manquant, aucun nombre de cas de test détaillés ne couvrira cette lacune.
Qu'est-ce qu'un cas de test ?
Un cas de test est la vérification concrète et exécutable qui se trouve sous un scénario. Il spécifie l'entrée exacte, la précondition, l'action et le résultat attendu, avec suffisamment de précision pour que deux personnes l'exécutant obtiennent le même résultat.
Prenons le scénario « vérifier le paiement pour un utilisateur invité ». Il se décompose en cas comme :
POST /ordersavec une charge utile invité valide renvoie201et unorder_idPOST /orderssans adresse de livraison renvoie400et unvalidation_errorPOST /ordersavec un SKU en rupture de stock renvoie409eterror: out_of_stock
Chaque cas nomme le point d'accès, le corps, le statut attendu et les champs de réponse attendus. Il est suffisamment spécifique pour être automatisé. Si vous souhaitez l'anatomie complète d'un cas champ par champ, comment écrire des cas de test API couvre le modèle en détail, et cas de test vs script de test clarifie où s'insère le code exécutable.
La caractéristique déterminante d'un cas de test est la précision. « Le paiement fonctionne » est au mieux un fragment de scénario. « Effectuer un POST d'une commande invité valide, s'attendre à 201 avec un order_id non vide » est un cas de test.
Les principales différences
Les deux concepts diffèrent selon plusieurs dimensions. Ce tableau en est la version courte.
| Dimension | Scénario de test | Cas de test |
|---|---|---|
| Niveau | Haut niveau, quoi tester | Bas niveau, comment tester |
| Détail | Bref, une ligne | Étape par étape avec des données |
| Objectif | Objectif métier ou fonctionnel | Exécution technique |
| Entrées | Non spécifiées | Charges utiles et paramètres exacts |
| Résultat attendu | Implicite | Précisément indiqué (statut, corps, timing) |
| Audience | Produit, QA, ingénierie | Testeurs et outils d'automatisation |
| Nombre | Quelques-uns par fonctionnalité | Beaucoup par scénario |
| Créé | Pendant la planification des tests | Après accord sur les scénarios |
La relation est hiérarchique. Un scénario génère plusieurs cas. Le scénario contrôle l'étendue de la couverture ; les cas contrôlent la profondeur et la rigueur. Un mode d'échec courant est d'écrire des dizaines de cas détaillés sans carte de scénario au-dessus d'eux, ce qui rend impossible de dire si la fonctionnalité est entièrement couverte ou simplement fortement testée dans un seul coin.
Une autre façon de voir les choses : un scénario peut être marqué « couvert » ou « non couvert ». Un cas de test ne peut être marqué que « réussi » ou « échoué ». Vous avez besoin des deux états pour gérer la qualité.
Comment les scénarios et les cas fonctionnent ensemble
Un flux de travail pratique passe du général au spécifique en cinq étapes.
1. Identifier les scénarios à partir des exigences. Lisez les spécifications ou la documentation de l'API et listez chaque comportement qui mérite d'être vérifié, y compris les chemins d'erreur (unhappy paths). C'est là que les lacunes de couverture sont détectées, alors consacrez-y du temps.
2. Définir l'objectif de chaque scénario. Indiquez ce que signifie « terminé ». Pour « vérifier le paiement invité », l'objectif est qu'un invité puisse passer une commande et recevoir une confirmation, tandis que les commandes invalides sont proprement rejetées.
3. Écrire des cas de test pour chaque scénario. Développez chaque scénario en cas concrets avec des entrées et des résultats attendus. Couvrez le chemin nominal (happy path), chaque échec de validation et les conditions limites pertinentes.
4. Examiner la complétude. Remontez l'arbre. Chaque scénario a-t-il au moins un cas nominal et un cas négatif ? Chaque code de statut documenté apparaît-il dans un résultat attendu ? Les lacunes trouvées ici sont peu coûteuses ; celles trouvées en production ne le sont pas.
5. Exécuter et suivre les résultats. Exécutez les cas, enregistrez les succès et les échecs par cas, et regroupez les résultats au niveau du scénario afin que les parties prenantes voient la couverture, et pas seulement un décompte de coches vertes.
Pour les équipes axées sur le comportement, les scénarios s'adaptent naturellement au format Given-When-Then de Gherkin ; le guide Gherkin pour les tests d'API BDD montre comment cette structure maintient les scénarios lisibles tout en étant exécutables.
Un exemple pratique : du scénario aux cas
Prenons une API pour une application de notes, avec un seul comportement à tester : un utilisateur peut créer une note. C'est le scénario.
Scénario : un utilisateur peut créer une note. Une ligne. Cela fait partie du plan de test, lisible par tous. Cela ne mentionne pas les points d'accès, les charges utiles ou les codes de statut, et ça ne devrait pas.
Maintenant, développons-le en cas. Chaque cas est une vérification exécutable avec des entrées exactes et un résultat attendu exact.
- Cas 1, chemin nominal.
POST /notesavec{"title": "Courses", "body": "lait, œufs"}et un jeton valide. Attendre201, un corps de réponse avec unidnon vide, untitleégal àCourses, et un horodatagecreated_at. Réponse en moins de 600 ms. - Cas 2, champ requis manquant.
POST /notesavec{"body": "lait, œufs"}et un jeton valide. Attendre400,errorégal àvalidation_error, etdetailsnommant le champtitle. - Cas 3, non authentifié.
POST /notesavec un corps valide et sans jeton. Attendre401et pas d'iddans la réponse. - Cas 4, charge utile trop grande.
POST /notesavec unbodyde 2 Mo. Attendre413et un message d'erreur clair.
Un scénario, quatre cas. Le scénario vous a dit *quoi* ; les cas vous ont dit *comment*, avec suffisamment de précision pour que tout testeur ou exécuteur automatisé produise le même verdict. Si vous ajoutez plus tard « un utilisateur peut joindre un fichier à une note », c'est un nouveau scénario, et il générera son propre ensemble de cas. Le plan se développe de manière structurée et auditable au lieu de devenir une pile de vérifications désordonnées.
Construire des scénarios et des cas dans Apidog
Apidog modélise cette hiérarchie directement, de sorte que la structure de votre plan de test correspond à la structure de vos outils.
Un scénario de test dans Apidog est une séquence ordonnée de requêtes API, chacune avec ses propres assertions. Vous le construisez visuellement : ajoutez les points d'accès impliqués dans le comportement, enchaînez-les de sorte que la sortie d'une requête alimente la suivante (une connexion renvoie un jeton, la requête suivante l'utilise), et définissez des assertions à chaque étape.
Chaque bloc requête-plus-assertions est effectivement un cas de test. Vous affirmez les codes de statut, les champs du corps de la réponse, la conformité au schéma et le temps de réponse en cliquant, sans écrire de script. Les tests axés sur les données permettent à un cas de s'exécuter sur plusieurs lignes d'entrée à partir d'un fichier CSV ou JSON, de sorte qu'un seul cas négatif couvre toutes les combinaisons invalides.
Les scénarios sont ensuite regroupés en suites de tests pour des exécutions organisées et reproductibles sur l'ensemble d'une API. Vous pouvez exécuter une suite localement, selon un calendrier ou dans un CI, et Apidog produit un rapport qui montre les résultats au niveau du cas et au niveau du scénario. Cette double vue est le bénéfice : les ingénieurs voient quel cas a échoué, et les responsables voient quel scénario est maintenant en danger.
Téléchargez Apidog pour construire votre premier scénario et voir le regroupement des cas en scénarios en pratique.
Pourquoi vous avez besoin des deux, pas d'un seul
Les équipes essaient parfois de sauter une couche. Sauter les scénarios et n'écrire que des cas produit une longue liste plate sans carte de couverture ; vous ne pouvez pas répondre « avons-nous testé entièrement le paiement invité ? » sans relire chaque cas. Sauter les cas et ne garder que les scénarios produit un plan que personne ne peut exécuter de manière cohérente, car « vérifier le paiement » signifie quelque chose de différent pour chaque testeur.
Les deux couches servent également des lecteurs différents. Un chef de produit lit les scénarios pour confirmer que les bonnes choses sont testées. Un ingénieur en automatisation lit les cas pour construire les exécuteurs. Un rapport de test qui ne montre que les cas réussis ne dit rien aux dirigeants sur la couverture ; un rapport qui regroupe les cas en scénarios leur indique exactement quelles fonctionnalités peuvent être livrées en toute sécurité.
Gardez les scénarios stables et les cas à jour. Les scénarios ne changent que lorsque l'intention de la fonctionnalité change. Les cas changent chaque fois que le contrat d'API change. Lorsque vous les traitez comme des artefacts distincts avec des cycles de vie distincts, votre plan de test reste à la fois précis et maintenable.
Foire aux questions
Un scénario de test est-il la même chose qu'une suite de tests ? Non. Un scénario décrit un comportement à tester. Une suite est une collection de tests exécutables regroupés pour une exécution. Une suite peut contenir les cas de nombreux scénarios. Voir suite de tests vs cas de test.
Combien de cas de test un scénario devrait-il contenir ? Suffisamment pour couvrir le chemin nominal (happy path) ainsi que chaque mode d'échec que le scénario implique. Un scénario simple peut nécessiter trois ou quatre cas ; un scénario complexe en nécessite davantage.
Qui écrit les scénarios par rapport aux cas ? Les scénarios sont souvent rédigés conjointement par le produit et l'assurance qualité, car ils encodent l'intention. Les cas sont généralement écrits par l'assurance qualité ou les développeurs, car ils encodent les détails techniques. Le format de spécification des cas de test aide à maintenir la cohérence de la rédaction des cas.
Ai-je besoin de scénarios si mes tests sont automatisés ? Oui. L'automatisation exécute les cas, mais les scénarios répondent toujours à la question de savoir si les bons cas existent. L'automatisation sans carte de couverture échoue simplement plus rapidement.