Tests d'API REST : les conventions qu'il faut vérifier

Les tests d'API REST commencent par la sémantique des codes de statut

REST donne un sens aux codes de statut, et les clients dépendent de ce sens. Mieux vaut le vérifier explicitement que de le supposer acquis.

• 201 avec une location pour une création, pas 200 avec un corps et rien d'autre.

• 404 pour une ressource absente, 403 pour un accès interdit. Renvoyer 404 en cas d'accès interdit est un choix délibéré chez certaines équipes ; renvoyer 403 pour une ressource absente n'est qu'un bug.

• 422 ou 400 pour une entrée invalide, de façon cohérente. Choisissez-en un et vérifiez que tous les endpoints s'y tiennent.

• Jamais 200 avec une erreur dans le corps. C'est fréquent, et cela oblige chaque client à écrire un traitement particulier.

Idempotence

PUT et DELETE sont censés être idempotents. Les appeler deux fois doit laisser le même état et ne pas produire d'erreur au second appel. C'est facile à rater et facile à contrôler : appelez deux fois, puis faites l'assertion.

Même chose pour un second DELETE, qui doit renvoyer 404 plutôt que 500. Les clients réessaient, et un endpoint qui ne supporte pas les tentatives répétées transforme une micro-coupure réseau en panne visible par l'utilisateur.

Les conventions que votre service revendique

La vérification qui les sous-tend toutes

Faites porter vos assertions sur le corps, pas seulement sur le statut. Un 200 accompagné d'une liste vide là où un enregistrement devrait se trouver passe toutes les assertions de statut jamais écrites. À elle seule, cette habitude détecte plus de vrais défauts dans les tests d'API REST que n'importe quelle vérification de convention.

Les quatre problèmes

Quatre éléments déterminent si une suite de tests d'API survit à sa première année : les sessions qui expirent, les valeurs qui n'existent qu'à l'exécution, les appels qui dépendent les uns des autres et les enregistrements que personne ne nettoie. TestSprite les traite avec Auto-Authentication, Dynamic Variables, Dependency Chains et Auto-Cleanup, décrits dans la documentation sur les tests d'API.

Les conventions à formaliser en premier

Avant de tester si votre API respecte ses conventions, quelqu'un doit dire lesquelles elle suit, et la plupart des équipes découvrent à cette occasion qu'elles ne sont pas d'accord.

Quatre questions règlent l'essentiel. Quel statut renvoie une création, et inclut-elle une location ? Une ressource absente donne-t-elle 404 ou 403 lorsque l'appelant n'aurait de toute façon pas le droit de la voir ? Un paramètre de requête inconnu est-il rejeté ou ignoré ? PATCH considère-t-il un champ absent comme inchangé ou comme null ?

Aucune de ces questions n'a de réponse universellement juste, et toutes portent sur des choix dont vos clients dépendent. Noter les quatre réponses prend vingt minutes et transforme une vague intention d'être RESTful en quelque chose sur quoi vous pouvez réellement faire des assertions, ce qui est la condition préalable à tout test.

Obtenir de la couverture sans tout écrire

Les plans générés couvrent les catégories fonctionnelle, schéma, autorisation, gestion des erreurs et cas limites, à partir d'une spécification ou d'une passe de découverte, ce qui inclut par défaut la plupart des vérifications de conventions ci-dessus.

Si vous préférez ne rien installer, le tableau de bord fait la même chose. Tout le reste de ce que permet la ligne de commande se trouve dans le dépôt CLI.

Si le pipeline appartient à une autre équipe, la GitHub App est la voie de moindre résistance : c'est un webhook, elle ne change rien dans votre dépôt et elle se déclenche quand votre build signale la mise en ligne de la nouvelle version. Si vous préférez que la vérification soit visible dans le dépôt, une étape GitHub Actions s'en charge.

Comment TestSprite vérifie les conventions

Les plans générés couvrent les catégories fonctionnelle, schéma, autorisation, gestion des erreurs et cas limites sur le service en cours d'exécution, ce qui inclut la plupart des vérifications de conventions ci-dessus : la sémantique des statuts opération par opération, le rejet des entrées incorrectes, le comportement face à une ressource absente et une pagination dont les comptes tombent juste.

Auto-Authentication maintient les sessions actives pendant toute l'exécution, Dynamic Variables transporte les valeurs d'un appel à l'autre, Dependency Chains déduit l'ordre d'exécution de ce que chaque cas consomme et produit, et Auto-Cleanup supprime exactement ce que l'exécution a créé. Ce dernier point compte davantage pour REST qu'on ne le croit, car vérifier l'idempotence revient à appeler volontairement deux fois la même opération destructrice.

Ce que vous obtenez, ce sont vos propres conventions vérifiées à chaque modification plutôt que documentées puis espérées, et c'est ce qui empêche un endpoint de se mettre discrètement à renvoyer 200 là où tous les autres renvoient 201.