Une API instable échoue rarement parce que quelqu'un a oublié de la tester. Elle échoue parce que le test exécuté a vérifié la mauvaise chose, ou n'a rien vérifié du tout au-delà d'un code de statut 200. Un cas de test d'API bien écrit fait la différence entre détecter un contrat rompu avant le lancement et expliquer la panne après coup.
Ce guide explique ce qu'est un cas de test d'API, les champs dont un bon cas a besoin et comment en écrire un à partir de zéro. Vous verrez un exemple complet et détaillé pour un point de terminaison de connexion, puis construirez le même test dans Apidog sans écrire de script.
Qu'est-ce qu'un cas de test d'API concrètement
Un cas de test d'API est un ensemble défini d'entrées, d'actions et de résultats attendus utilisé pour confirmer qu'un point de terminaison se comporte correctement dans une condition spécifique. Il est plus étroit qu'un scénario de test. Un scénario dit "vérifier la connexion de l'utilisateur". Un cas de test dit "POSTer des identifiants valides à /auth/login et confirmer une réponse 200 avec un JWT dans le corps en moins de 800 ms".
Chaque cas cible un comportement unique. Cette focalisation est importante. Lorsqu'un test large et polyvalent échoue, vous devez toujours enquêter sur la partie qui a posé problème. Lorsqu'un cas ciblé échoue, le nom de l'échec vous donne la réponse. Si vous êtes encore en train de cartographier comment les cas se rapportent aux scénarios et aux scripts, les articles scénario de test vs cas de test et cas de test vs script de test tracent clairement les lignes.
Les tests d'API couvrent généralement cinq angles, et vos cas devraient les couvrir tous:
- Fonctionnel : le point de terminaison renvoie-t-il les bonnes données pour une entrée valide ?
- Négatif : rejette-t-il les mauvaises entrées avec l'erreur et le code de statut corrects ?
- Performance : répond-il dans un budget temps acceptable ?
- Sécurité : applique-t-il l'authentification, l'autorisation et les limites d'entrée ?
- Contrat : la réponse correspond-elle au schéma documenté ?
Une suite de tests qui ne vérifie que le "chemin heureux" passera jusqu'à ce qu'un utilisateur réel envoie un champ de mot de passe vide.
Pourquoi vous avez besoin d'un modèle de cas de test
Écrire chaque cas à partir d'une page blanche produit une couverture incohérente. Un ingénieur enregistre les codes de statut attendus ; un autre enregistre les corps de réponse ; un troisième écrit "devrait fonctionner". Un modèle résout cela en imposant la même structure à chaque fois.
Un modèle partagé vous apporte quatre avantages concrets. La couverture devient vérifiable, car chaque cas a les mêmes champs et les lacunes sont visibles. L'intégration est accélérée, car un nouveau testeur lit un format au lieu de cinq. Les cas deviennent réutilisables à travers les versions, car un cas structuré est facile à cloner et à ajuster. Et la traçabilité est maintenue, car chaque cas renvoie à une exigence ou à un point de terminaison.
Les modèles rendent également l'automatisation réaliste. Un cas structuré se traduit clairement par une étape de test automatisée ; un cas vague doit être réécrit avant qu'une machine puisse l'exécuter.
L'anatomie d'un cas de test d'API robuste
Un modèle complet de cas de test d'API contient ces champs. Vous n'avez pas besoin de tous pour chaque cas, mais l'ensemble de base est non négociable.
| Champ | Objectif |
|---|---|
| ID du cas de test | Référence unique, par ex. AUTH-LOGIN-001 |
| Titre | Une ligne décrivant le comportement testé |
| Point de terminaison | Méthode et chemin, par ex. POST /auth/login |
| Préconditions | État requis avant l'exécution, par ex. "l'utilisateur existe" |
| En-têtes | En-têtes de requête requis |
| Corps/paramètres de la requête | Charge utile d'entrée exacte |
| Statut attendu | Le code HTTP que vous attendez |
| Réponse attendue | Champs du corps, schéma ou valeurs à affirmer |
| Temps de réponse attendu | Le budget de latence |
| Priorité | Critique, haute, moyenne, basse |
| Type de test | Fonctionnel, négatif, sécurité, performance |
Les champs que les équipes ignorent le plus souvent sont le temps de réponse attendu et le corps de réponse attendu. Les ignorer explique comment un test "réussit" tout en renvoyant un 200 avec une charge utile vide, ou une charge utile correcte avec trois secondes de retard.
Comment écrire des cas de test d'API étape par étape
Lisez d'abord la documentation de l'API. Notez les paramètres requis, la méthode d'authentification, les codes de statut documentés et le schéma de réponse. Chaque cas de test est une affirmation sur le comportement documenté, la documentation est donc votre source de vérité. Les outils qui lisent une spécification OpenAPI pour générer des collections de tests peuvent vous donner un squelette de départ.
Listez les conditions à tester. Pour un seul point de terminaison, cela signifie généralement : entrée valide, chaque champ requis manquant, chaque champ malformé, une requête non autorisée, un jeton expiré et une charge utile trop volumineuse. Chaque condition devient un cas.
Préparez des données de test distinctes. Les cas négatifs nécessitent des données erronées d'une seule manière. Réutiliser la même charge utile pour plusieurs cas masque les bugs, car vous n'exercez qu'un seul chemin.
Écrivez le résultat attendu avec précision. "Renvoie le succès" n'est pas une assertion. "Renvoie 200, le corps contient une chaîne token non vide, expires_in égale 3600" l'est. La précision ici est ce qui rend le cas utile.
Ajoutez le cas à une suite exécutable. Un cas dans une feuille de calcul documente l'intention. Un cas dans un outil de test produit un succès ou un échec. Regroupez les cas liés afin que tout le point de terminaison s'exécute en un seul clic ; les suites de tests existent précisément pour cela.
Maintenez les cas à jour. Lorsque l'API change, les cas changent avec elle. Un cas obsolète qui affirme un ancien schéma est pire qu'aucun cas, car il échoue pour la mauvaise raison et habitue l'équipe à ignorer les builds rouges.
Un exemple détaillé : tester un point de terminaison de connexion
Prenons un point de terminaison d'authentification standard : POST /auth/login, qui accepte un e-mail et un mot de passe et renvoie un JWT. Voici quatre cas qui le couvrent correctement.
AUTH-LOGIN-001 : identifiants valides (fonctionnel, critique)
- Point de terminaison :
POST /auth/login - Préconditions : un utilisateur existe avec l'e-mail
dana@example.com - Corps :
{"email": "dana@example.com", "password": "Correct-Horse-9"} - Statut attendu :
200 - Réponse attendue : le corps contient un
tokennon vide (chaîne),token_typeégaleBearer,expires_inégale3600 - Temps de réponse attendu : moins de 800 ms
AUTH-LOGIN-002 : mauvais mot de passe (négatif, critique)
- Corps :
{"email": "dana@example.com", "password": "wrong"} - Statut attendu :
401 - Réponse attendue :
errorégaleinvalid_credentials; aucun champtokenprésent - Remarque : le message ne doit pas révéler si l'e-mail existe
AUTH-LOGIN-003 : champ de mot de passe manquant (négatif, élevé)
- Corps :
{"email": "dana@example.com"} - Statut attendu :
400 - Réponse attendue :
errorégalevalidation_error;detailsnomme le champpassword
AUTH-LOGIN-004 : e-mail malformé (négatif, moyen)
- Corps :
{"email": "not-an-email", "password": "Correct-Horse-9"} - Statut attendu :
400 - Réponse attendue :
errorégalevalidation_error
Quatre cas, un point de terminaison, et déjà vous vérifiez le contrat, la forme de l'erreur, les codes de statut et un budget de latence. Ajoutez un cas de sécurité pour une chaîne d'injection SQL dans le champ e-mail et vous avez une suite à exécuter à chaque commit.
Écrire le même cas de test dans Apidog
Vous pouvez exécuter les quatre cas ci-dessus sans écrire une ligne de script. Dans Apidog, un cas de test d'API est construit visuellement.
- Importez ou définissez le point de terminaison. Importez
POST /auth/logindepuis un fichier OpenAPI, une collection Postman, ou définissez-le directement. Le schéma de requête devient la base de chaque assertion. - Ajoutez les données de la requête. Saisissez le corps pour le cas AUTH-LOGIN-001. Pour une couverture basée sur les données, attachez un fichier CSV ou JSON afin qu'un cas s'exécute contre chaque ligne d'identifiants ; c'est ainsi que les tests d'API basés sur les données remplacent quatre cas quasi-identiques par un seul.
- Définissez visuellement les assertions. Cliquez pour affirmer que le statut est égal à 200, que
tokenexiste et est une chaîne non vide, queexpires_inest égal à 3600 et que le temps de réponse reste inférieur à 800 ms. Aucun script requis. - Regroupez les cas dans un scénario de test. Ajoutez les quatre cas de connexion à un seul scénario afin que le point de terminaison soit entièrement exercé en une seule exécution.
- Exécutez et lisez le rapport. Apidog exécute le scénario, génère un rapport de réussite/échec par cas et identifie l'assertion exacte qui a échoué. Vous pouvez exécuter le scénario localement, selon un calendrier ou dans un pipeline CI.
Le but n'est pas que le scriptage soit mauvais ; c'est qu'un cas visuel structuré est plus rapide à écrire, plus facile à réviser et plus difficile à rendre subtilement incorrect. Lorsque vous avez besoin de code, Apidog vous permet toujours d'utiliser des scripts personnalisés. Pour un flux de travail entièrement sans script, les tests d'API sans Postman couvrent l'approche plus large.
Erreurs courantes à éviter
Affirmer seulement le code de statut. Un 200 signifie que la requête a été traitée, pas que la réponse était correcte. Affirmez toujours les champs du corps.
Un cas géant par point de terminaison. Quand il échoue, vous n'apprenez rien. Divisez par condition.
Données de test réutilisées. Si chaque cas négatif envoie la même charge utile, vous ne testez qu'un seul mode d'échec.
Aucune assertion de latence. Les régressions de performance passent inaperçues lorsque rien ne mesure le temps de réponse.
Cas qui ne sont jamais automatisés. Un cas documenté qu'aucun exécuteur n'exécute est un commentaire, pas un test. Déplacez les cas dans une suite qui s'exécute à chaque build ; générer des scripts de test à partir d'une spécification OpenAPI est un moyen rapide de démarrer cette suite.
Téléchargez Apidog si vous souhaitez suivre l'exemple et construire vous-même les quatre cas de connexion.
Foire aux questions
Combien de cas de test un point de terminaison nécessite-t-il ? Assez pour couvrir le chemin heureux, chaque échec de champ requis, un échec d'authentification et une sonde de sécurité. Pour un point de terminaison simple, cela représente quatre à six cas ; pour un point de terminaison complexe, cela peut être plus.
Dois-je écrire des cas avant la construction de l'API ? Oui. Écrire des cas en fonction de la conception (design-first) permet de détecter les lacunes du contrat tôt. Associez cela à la génération de cas de test assistée par IA pour ébaucher rapidement un premier ensemble, puis affinez-le manuellement.
Feuille de calcul ou outil de test pour stocker les cas ? Une feuille de calcul documente l'intention mais ne peut pas être exécutée. Conservez les cas dans un outil qui les exécute et rapporte les résultats, de sorte qu'un cas soit toujours vert ou rouge.
Quelle est la différence entre un cas de test et un scénario de test ? Un scénario est l'objectif de haut niveau ("vérifier la connexion") ; un cas est une vérification concrète et exécutable à l'intérieur de celui-ci. Voir scénario de test vs cas de test.