Une requête API qui renvoie une réponse n'est pas un test réussi. C'est juste une réponse. Le test n'existe que lorsque quelque chose vérifie que la réponse est correcte. Cette vérification est une assertion, et la qualité de vos assertions détermine si votre suite de tests détecte de vrais bugs ou se contente de confirmer que le serveur est actif. Ce guide explique ce que sont les assertions API, les types qui valent la peine d'être écrits, où les équipes se trompent, et comment construire des assertions visuellement dans Apidog sans script.
Qu'est-ce qu'une assertion API
Une assertion est une déclaration concernant une réponse qui doit être vraie pour que le test réussisse. Vous envoyez une requête, l'API répond, et l'assertion compare une partie de cette réponse à une valeur attendue. Si elles correspondent, c'est réussi. Sinon, c'est un échec. Sans assertions, un test automatisé prouve seulement que le point d'accès est joignable. Avec elles, il prouve que le point d'accès est correct. L'écart entre ces deux points est l'endroit où la plupart des incidents de production se produisent : l'API était active, elle a renvoyé un 200, mais le corps était incorrect. Une assertion utile est spécifique et indépendante. Spécifique, afin qu'un échec pointe vers une seule chose. Indépendante, afin qu'elle ne dépende pas silencieusement du succès préalable d'une autre assertion. Une seule étape de test comporte généralement plusieurs assertions, chacune vérifiant une facette différente de la même réponse.
L'assertion de code de statut, et pourquoi elle n'est pas suffisante
L'assertion la plus courante vérifie le code de statut HTTP : attendre 200 pour une lecture réussie, 201 pour une ressource créée, 400 pour une entrée invalide, 401 pour une authentification manquante. C'est nécessaire. Bien gérer les codes de statut est une discipline en soi ; quels codes de statut HTTP les API REST devraient utiliser mérite d'être lu si votre API est incohérente à ce sujet. Mais une assertion de code de statut seule est faible. Une API peut renvoyer un 200 OK avec un corps vide, une valeur obsolète, un `null` là où un objet devrait être, ou un message d'erreur déguisé en succès. Le statut indique que la requête a été traitée. Il ne dit rien sur la justesse des données. Traitez l'assertion de statut comme la première ligne d'une étape de test, jamais la seule ligne.
Les types d'assertions qui valent la peine d'être écrits
Assertions de contenu du corps. Vérifient les valeurs réelles dans la réponse. Le champ id existe et n'est pas vide. L'email correspond à ce que vous avez envoyé. Le total est égal à la somme des articles. Celles-ci détectent les bugs logiques que les codes de statut manquent. Assertions de schéma. Valident la forme de la réponse par rapport à un schéma JSON ou une définition OpenAPI : les champs requis sont présents, les types sont corrects, aucun champ inattendu n'est apparu. Les assertions de schéma détectent la dérive de contrat, où le backend modifie discrètement un champ de chaîne à objet et brise tous les clients. Cela chevauche les tests de contrat API, qui formalisent l'idée entre producteur et consommateur. Assertions d'en-tête. Confirment que Content-Type est application/json, que les en-têtes de cache sont définis comme prévu, que les en-têtes CORS sont présents, et que les en-têtes de sécurité comme Strict-Transport-Security sont là. Assertions de temps de réponse. Définissent un budget de latence, par exemple 800 ms, et font échouer le test lorsque la réponse est plus lente. Les régressions de performance sont invisibles pour tous les autres types d'assertions, c'est donc le seul qui les détecte dans une suite fonctionnelle. Assertions de forme d'erreur. Pour les cas négatifs, affirment le corps de l'erreur, pas seulement le code 4xx. Le champ error est égal à validation_error, le tableau details nomme le champ incriminé, et aucune donnée sensible n'est divulguée dans le message. Assertions de sécurité. Confirment que le point d'accès rejette les requêtes sans jeton, rejette les jetons expirés, applique l'autorisation entre les utilisateurs et ne renvoie pas les charges utiles d'injection non échappées. Une étape de test qui affirme le statut, deux ou trois champs du corps, le schéma, et un budget de temps de réponse fait un vrai travail. Une étape qui affirme seulement le statut est décorative.
Où la logique d'assertion tourne mal
Sur-assertion sur des données volatiles. Affirmer un horodatage created_at exact ou un UUID généré fait échouer le test à chaque exécution sans raison. Affirmez que le champ existe et a le bon type, pas sa valeur exacte. Sous-assertion sur le chemin heureux. Le test de chemin heureux est celui qui est le plus susceptible d'affirmer uniquement le code de statut. C'est aussi celui que les utilisateurs rencontrent le plus souvent. Donnez-lui les assertions les plus complètes, pas les moins nombreuses. Assertions dépendantes de l'ordre. Si l'assertion B n'a de sens que si l'assertion A a réussi, mais que les deux s'exécutent aveuglément, un échec en A produit un deuxième échec déroutant en B. Structurez les étapes de sorte que les dépendances soient explicites. Une assertion qui fait deux choses. « La réponse est correcte » n'est pas une assertion. Divisez-la : le statut est 200, le token existe, expires_in est égal à 3600. Trois vérifications, trois messages d'échec clairs. Ignorer les cas négatifs. Les équipes font de fortes assertions sur le succès et presque aucune sur l'échec. Un cas négatif sans assertion de corps prouve seulement que l'API a dit « non », pas qu'elle a dit non correctement.
Construire des assertions dans Apidog
Dans Apidog, les assertions font partie du constructeur de tests visuel, vous les définissez donc en cliquant plutôt qu'en scriptant. Pour toute requête dans un scénario de test, ouvrez le panneau d'assertion et ajoutez des vérifications :
- Assertion de statut. Sélectionnez « statut de réponse » et définissez-le à égal à
200. - Assertions de champs de corps. Utilisez une expression JSONPath comme
$.tokenet affirmez qu'elle existe et est une chaîne non vide ; affirmez que$.expires_inest égal à3600. Apidog lit la structure de la réponse, vous choisissez donc les champs au lieu de taper des chemins à l'aveugle. - Assertion de schéma. Validez la réponse par rapport au schéma défini du point d'accès. Parce qu'Apidog conserve la conception de l'API et les tests dans un seul espace de travail, le schéma utilisé par votre assertion est le même schéma que votre documentation publie ; il n'y a pas de deuxième copie pour la dérive.
- Assertion de temps de réponse. Ajoutez une vérification que le temps de réponse est inférieur à votre budget.
- Script personnalisé, uniquement si nécessaire. Pour une logique que les vérifications visuelles ne peuvent pas exprimer, utilisez un post-processeur JavaScript. La plupart des assertions n'en ont jamais besoin.
Regroupez les assertions sur un scénario et Apidog les exécute ensemble. Pour une couverture évolutive, attachez un fichier de données afin qu'un ensemble d'assertions s'exécute sur chaque ligne d'entrée de test basée sur les données. Lorsque le scénario s'exécute, le rapport généré montre exactement quelle assertion a échoué, sur quelle requête, avec les valeurs attendues et réelles côte à côte. Le même scénario s'exécute sans modification en CI, de sorte que chaque commit revérifie chaque assertion ; l'automatisation des tests API en CI/CD couvre ce câblage. Téléchargez Apidog pour construire un ensemble d'assertions sur votre propre point d'accès.
Un ensemble d'assertions détaillé
Prenons GET /users/{id} renvoyant un objet utilisateur. Un ensemble d'assertions solides pour le chemin heureux :
- Le statut est
200 - L'en-tête
Content-Typecontientapplication/json $.idest égal à l'id demandé$.emailexiste et correspond à un motif d'e-mail$.roleest l'un des suivants :admin,member,viewer- Le corps de la réponse est conforme au schéma
User - Le temps de réponse est inférieur à 600 ms
Et pour GET /users/{id} avec un id inconnu :
- Le statut est
404 $.errorest égal ànot_found- Le corps de la réponse ne contient pas d'
email, d'id, ou d'autres champs utilisateur
Deux requêtes, onze assertions, et vous avez vérifié le contrat, les données, les en-têtes, la performance et le comportement d'erreur. C'est ce qui distingue une suite de tests qui protège une version d'une autre qui ne fait que pinguer le serveur.
Assertions dans un pipeline CI
Les assertions prennent toute leur valeur lorsqu'elles s'exécutent automatiquement. Une suite qu'une personne exécute manuellement une fois par semaine détecte les bugs une semaine trop tard. La même suite câblée en CI les détecte dès la pull request. Lorsque les assertions s'exécutent dans un pipeline, deux choix de conception sont importants. Premièrement, l'échec doit être sans ambiguïté. Un journal CI qui dit « test échoué » force un développeur à reproduire l'exécution localement ; un journal qui dit « attendu $.expires_in égal à 3600, obtenu 7200 sur POST /auth/login » leur dit immédiatement où chercher. Ce sont des assertions fortes et spécifiques qui produisent cet échec lisible. Deuxièmement, les assertions doivent être stables dans tous les environnements. Une assertion qui code en dur un identifiant d'utilisateur de production échouera en staging pour une raison qui n'a rien à voir avec le code. Conservez les valeurs spécifiques à l'environnement dans des variables et faites des assertions sur la structure et le type lorsque la valeur exacte dépend de l'environnement. Une assertion de schéma se déplace bien entre les environnements ; une assertion sur un identifiant généré spécifique, non. Le modèle pratique : affirmer le statut et le schéma sur chaque point d'accès comme base qui s'exécute partout, puis superposer des assertions de valeur tenant compte de l'environnement. La base détecte la dérive de contrat dans n'importe quel environnement ; les assertions de valeur détectent les bugs logiques là où vous avez des données stables. Exécutez les deux à chaque commit et la suite devient une porte plutôt qu'un rapport.
Foire aux questions
Quelle est la différence entre une assertion et un cas de test ? Un cas de test est la vérification complète : une requête plus son résultat attendu. Les assertions sont les comparaisons individuelles à l'intérieur qui décident du succès ou de l'échec. Voir comment écrire des cas de test API.
Combien d'assertions une requête doit-elle avoir ? Assez pour couvrir le statut, les champs clés du corps, le schéma et un budget de latence. Pour la plupart des points d'accès, c'est entre quatre et huit. Plus, c'est bien si chacune vérifie quelque chose de distinct.
Dois-je affirmer des corps de réponse exacts ? Affirmez les champs stables exactement et les champs volatils par type ou présence. Affirmer un corps complet incluant les horodatages et les ID générés crée des tests qui échouent à chaque exécution.
Puis-je affirmer la performance de l'API dans un test fonctionnel ? Oui. Une assertion de temps de réponse détecte les régressions de latence pendant les exécutions fonctionnelles normales, aucun test de charge séparé n'est requis pour la vérification du budget de base.
Les cas de test négatifs doivent-ils aussi avoir des assertions ? Absolument, et ce sont les cas les plus souvent laissés nus. Un cas négatif avec seulement une vérification de code de statut prouve que l'API a dit non, pas qu'elle a dit non correctement. Affirmez le champ d'erreur, le détail du champ incriminé et l'absence de toute donnée sensible dans le message.
Où les scripts d'assertion personnalisés doivent-ils être utilisés ? Réservez les scripts pour la logique que le constructeur visuel ne peut pas exprimer : comparaisons entre requêtes, valeurs dérivées ou vérifications conditionnelles qui dépendent de réponses antérieures. La plupart des assertions, statut, schéma, champs du corps et timing, sont plus propres et plus révisables en tant que vérifications visuelles.