Première partie : à quoi sert vraiment le test et le développement d'API avec Postman
Une collection est un ensemble de requêtes que l'on peut partager et exécuter. Elle excelle donc dans trois usages : explorer une API que l'on ne connaît pas, la documenter avec des exemples réellement exécutables, et transmettre à quelqu'un une reproduction directement exécutable. Ces trois usages méritent d'être bien faits et sont souvent sous-estimés.
L'erreur des équipes n'est pas d'utiliser des collections. Elle est de supposer que la collection peut devenir la suite de régression sans que rien d'autre ne change.
Deuxième partie : les quatre problèmes
Toute suite d'API, quel que soit l'outil, finit par se heurter aux quatre mêmes. Les connaître à l'avance constitue l'essentiel du savoir-faire.
Les sessions expirent
Les jetons arrivent à expiration en pleine exécution et les échecs ressemblent à des bugs du produit.
Sortez les identifiants des requêtes individuelles pour les placer dans l'environnement.
Les valeurs circulent d'un appel à l'autre
Une création renvoie un identifiant dont l'appel suivant a besoin.
Capturez-le, ne le codez jamais en dur, sinon la suite ne fonctionnera qu'une seule fois.
L'ordre compte
La couverture est un graphe, une collection est une liste.
Un seul échec en début de parcours se propage en un écran entier de rouge sans rapport.
Le quatrième est le nettoyage. Les enregistrements s'accumulent, les contraintes d'unicité se déclenchent et les assertions sur la pagination dérivent. Supprimer selon un motif de nom reste sans danger jusqu'au jour où deux exécutions se chevauchent.
Troisième partie : les assertions qui valent la peine d'être écrites
Faites porter vos assertions sur le corps de la réponse, pas seulement sur le statut. Un 200 accompagné d'une liste vide là où un enregistrement devrait figurer est un bug qu'une vérification de statut considère comme un succès.
Vérifiez que les échecs échouent correctement. Demandez une ressource qui n'existe pas et contrôlez le code ainsi que la structure de l'erreur. Les services qui renvoient un 200 contenant une erreur sont fréquents.
Faites porter vos assertions sur plusieurs endpoints. Si un enregistrement en référence un autre, allez le chercher. Les bugs intéressants se nichent entre deux appels.
Quatrième partie : quand la collection ne suffit plus
Le signal : vos scripts de pré-requête sont devenus un petit framework qu'une seule personne comprend. À ce stade, les quatre problèmes relèvent de votre infrastructure et non de celle de votre outil, et c'est le moment de déplacer la couverture de régression vers un endroit qui les traite comme faisant partie du produit. TestSprite les prend en charge sous les noms Auto-Authentication, Dynamic Variables, Dependency Chains et Auto-Cleanup, décrits dans la documentation sur les tests d'API.
Conservez la collection. Elle reste ce que vous avez de mieux pour explorer et documenter.
Quatrième partie et demie : les scripts que personne ne relit
Les scripts de pré-requête et de test contenus dans une collection méritent qu'on s'y arrête, car c'est là que se logent les défaillances intéressantes et ils ne sont presque jamais relus.
C'est du JavaScript, cela s'exécute dans un ordre précis, cela modifie des variables d'environnement partagées, et le tout est stocké dans un export JSON qui ne se compare pas utilement. Une modification du script de rafraîchissement de jeton peut casser quarante requêtes alors que la pull request n'affiche qu'une seule ligne de JSON modifiée. Les équipes le découvrent la première fois que deux personnes éditent une collection dans la même semaine.
Si vos scripts en sont au point où ce paragraphe vous parle, la collection est devenue du logiciel. Or le logiciel réclame des relectures, un contrôle de version et ses propres tests — une destination étrange quand l'objectif de départ était de tester autre chose.
Cinquième partie : faire tourner la suite sans vous
Connectez le dépôt depuis le tableau de bord et les exécutions démarrent à partir du déploiement que vous produisez déjà, ou ajoutez plutôt une étape à votre propre workflow.
Terminal
npm install -g @testsprite/testsprite-cli
testsprite setup
La même configuration est disponible dans le tableau de bord TestSprite si vous préférez ne rien installer en local. Le reste des commandes du CLI se trouve dans le dépôt du CLI.
Sixième partie : ce que TestSprite fait des quatre problèmes
Chacun des quatre porte un nom et est pris en charge par le produit plutôt que par vos scripts. Auto-Authentication configure le flux de connexion une seule fois et récupère un jeton à jour avant chaque exécution. Dynamic Variables capture une valeur dans une réponse et l'injecte dans la requête suivante. Dependency Chains déduit un ordre sûr à partir de ce dont chaque cas a besoin et de ce qu'il produit. Auto-Cleanup supprime exactement les enregistrements créés par une exécution.
La couverture part d'API Discovery appliqué au service en fonctionnement, complété par la spécification dont vous disposez, et le plan généré inclut les catégories autorisation, gestion des erreurs et cas limites — précisément celles que l'on saute.
L'intérêt pour qui a appris le sujet par les collections : vous gardez la collection pour explorer et documenter, ce qu'elle fait le mieux, et la suite de régression cesse d'être un bloc de JavaScript maintenu par une seule personne.
Existe-t-il un PDF gratuit officiel ?
Cela dépend des éditeurs et cela change. Cette page rassemble les connaissances utiles plutôt qu'une copie d'un livre.
Dois-je apprendre Postman en premier ?
Oui. C'est le moyen le plus rapide de se construire un modèle mental juste d'une API, et cette compréhension se transpose à tous les autres outils.
Dois-je apprendre le scripting ?
Assez pour savoir le lire. Dès que vous en écrivez beaucoup, c'est le signe que la collection ne suffit plus comme suite de régression.
Dans quel ordre aborder tout cela ?
Envoyer des requêtes, puis écrire des assertions sur les corps de réponse, puis gérer l'authentification, puis chaîner les appels, puis nettoyer. Les deux derniers points sont ceux où la plupart des gens s'arrêtent et ceux où réside la valeur.
Newman suffit-il pour la CI ?
Il exécute très bien les collections en CI. La question est de savoir qui maintient les scripts sous-jacents, pas quel exécuteur les lance.
Apprenez les quatre problèmes, pas le menu.
Le test et le développement d'API avec Postman tiennent surtout aux sessions, aux valeurs capturées, à l'ordonnancement et au nettoyage. Les collections sont excellentes pour explorer et documenter ; quand les scripts sous-jacents deviennent un framework, déplacez la couverture de régression vers un outil conçu pour cela.