Postman est l'un des outils les plus largement utilisés pour envoyer des requêtes HTTP et vérifier le comportement d'une API. Il a commencé comme une extension de navigateur et est devenu une application de bureau complète qui gère tout, d'une requête GET rapide à des suites de tests scriptées qui s'exécutent en CI. Si vous développez ou consommez des API, vous le rencontrerez presque certainement.
Ce guide vous expliquera comment tester une API dans Postman, comme vous le feriez au quotidien. Vous enverrez une requête, inspecterez la réponse, écrirez des assertions dans l'onglet **Tests**, configurerez des environnements pour pouvoir basculer entre la préproduction et la production, et exécuterez une collection entière en une seule fois avec le Collection Runner. Les exemples utilisent une API publique afin que vous puissiez suivre sans rien configurer au préalable.
Configurer Postman et envoyer votre première requête
Téléchargez Postman depuis le site officiel et installez l'application de bureau. Vous pouvez l'utiliser sans compte pour le travail local, bien que la connexion synchronise vos collections sur tous vos appareils. Ouvrez l'application et cliquez sur le bouton Nouveau, puis choisissez Requête HTTP.
Une requête nécessite au minimum trois éléments : une méthode, une URL et parfois un corps. Choisissez GET dans le menu déroulant des méthodes et entrez un véritable endpoint. Le service JSONPlaceholder est pratique pour s'exercer :
GET https://jsonplaceholder.typicode.com/users/1
Cliquez sur Envoyer. Le panneau de réponse se remplit avec le corps, le code de statut (200 OK), le temps de réponse et la taille. Basculez la vue du corps entre Pretty, Raw et Preview pour voir le JSON formaté ou tel qu'il a été envoyé par le serveur.
Pour une requête POST, changez la méthode, ouvrez l'onglet Corps (Body), choisissez brut (raw), et sélectionnez JSON dans le menu déroulant du format. Collez une charge utile comme celle-ci :
{
"name": "Maria Chen",
"email": "maria.chen@example.com"
}
Les en-têtes tels que Content-Type: application/json sont ajoutés automatiquement lorsque vous choisissez le type de corps JSON. L'onglet En-têtes (Headers) vous permet d'ajouter tout autre élément dont l'API a besoin, comme un en-tête Authorization. Si vous ne savez pas quels codes de réponse attendre, le guide sur les codes de statut HTTP que les API REST devraient utiliser est une référence utile.
Organiser les requêtes en collections
Une seule requête suffit pour une vérification rapide. Le vrai test implique de nombreuses requêtes qui vont ensemble : créer un utilisateur, récupérer cet utilisateur, le mettre à jour, le supprimer. Postman les regroupe en collections.
Cliquez sur Collections dans la barre latérale, puis sur l'icône + pour en créer une. Donnez-lui un nom concret comme « Tests de fumée de l'API utilisateur ». Enregistrez chaque requête dans la collection avec Ctrl/Cmd + S et donnez-lui un nom clair. Vous pouvez imbriquer des dossiers à l'intérieur d'une collection pour séparer, par exemple, les requêtes d'authentification des requêtes de ressources.
Les collections sont aussi l'unité que vous partagez. Exportez-en une en tant que fichier JSON, ou partagez un lien si vous synchronisez vers le cloud. Les membres de l'équipe l'importent et disposent des mêmes requêtes que vous. C'est la base de tout le reste, car le Collection Runner et les tests automatisés fonctionnent tous deux sur des collections plutôt que sur des requêtes isolées.
Une collection peut également comporter un comportement partagé. Postman vous permet d'attacher des scripts au niveau de la collection ou du dossier, et pas seulement à une seule requête. Un script de pré-requête (pre-request script) sur la collection s'exécute avant chaque requête qu'elle contient, ce qui est utile pour rafraîchir un jeton ou ajouter un horodatage. Un script de test au niveau de la collection s'exécute après chaque requête, ce qui est pratique pour une assertion que vous voulez partout, comme « le temps de réponse est raisonnable ». Définir ces éléments une seule fois permet à vos requêtes individuelles de se concentrer sur ce qui leur est propre.
Écrire des tests dans l'onglet Tests
L'envoi d'une requête vous indique ce qui est revenu. Un test vous indique si ce qui est revenu est correct, automatiquement, à chaque fois. Postman exécute du JavaScript dans la zone Scripts d'une requête (les anciennes versions appelaient cela l'onglet Tests) après l'arrivée de la réponse.
Postman expose un objet pm pour écrire des assertions. Le modèle principal est pm.test(name, callback), où la fonction de rappel lève une erreur si une attente échoue. Voici des assertions que vous utiliserez constamment :
// Check the status code
pm.test("Status code is 200", function () {
pm.response.to.have.status(200);
});
// Check response time
pm.test("Response is under 500ms", function () {
pm.expect(pm.response.responseTime).to.be.below(500);
});
// Check a field in the JSON body
pm.test("User has the expected email", function () {
const body = pm.response.json();
pm.expect(body.email).to.eql("maria.chen@example.com");
});
// Check a header
pm.test("Content-Type is JSON", function () {
pm.expect(pm.response.headers.get("Content-Type"))
.to.include("application/json");
});
La syntaxe d'assertion provient de Chai, donc pm.expect prend en charge .to.eql, .to.include, .to.be.above, et le reste. Cliquez sur Envoyer et les résultats apparaîtront dans l'onglet Résultats des tests, chaque test étant vert ou rouge.
Quelques habitudes permettent de maintenir l'utilité des tests. Nommez chaque bloc pm.test d'après le comportement qu'il vérifie, et non l'endpoint, afin qu'un message d'échec se lise comme une phrase. Vérifiez les éléments qui casseraient réellement un consommateur de l'API : le code de statut, la structure du corps et les champs dont un client dépend. Évitez d'affirmer des valeurs que vous ne contrôlez pas, comme un horodatage généré par le serveur, car cela produit des échecs instables qui incitent les gens à ignorer le rouge. Postman propose également un panneau Snippets (extraits) à côté de l'éditeur avec des assertions prêtes à l'emploi que vous pouvez cliquer pour insérer, ce qui est le moyen le plus rapide d'apprendre l'API pm. Si vous souhaitez une analyse plus approfondie de la conception des assertions, consultez la section sur les assertions d'API et comment bien les écrire. Pour l'idée plus large de structurer les vérifications en cas nommés, le guide sur l'exemple de cas de test d'API mérite d'être lu en parallèle.
Utiliser les environnements et les variables
Coder en dur https://api.staging.example.com dans chaque requête devient pénible dès que vous devez pointer vers la production. Les environnements résolvent ce problème. Un environnement est un ensemble nommé de variables.
Cliquez sur l'icône des environnements dans la barre latérale et créez-en un appelé « Staging » (Préproduction). Ajoutez une variable base_url avec la valeur https://jsonplaceholder.typicode.com. Créez un deuxième environnement appelé « Production » avec une base_url différente. Référencez maintenant la variable dans vos requêtes en utilisant des doubles accolades :
GET {{base_url}}/users/1
Choisissez l'environnement actif dans le menu déroulant en haut à droite, et chaque requête utilisant {{base_url}} basculera avec lui.
Les variables transportent également des données entre les requêtes. Une requête de connexion peut capturer un jeton à partir de sa réponse et le stocker pour que les requêtes ultérieures puissent l'utiliser :
pm.test("Save the auth token", function () {
const token = pm.response.json().token;
pm.environment.set("auth_token", token);
});
Toute requête ultérieure peut alors envoyer Authorization: Bearer {{auth_token}}. Cet enchaînement est la façon dont vous testez des flux qui dépendent d'un état, comme la création d'une ressource puis la vérification de son existence.
Postman propose deux portées de variables connexes à connaître. Les variables d'environnement (Environment variables) appartiennent à l'environnement sélectionné et changent lorsque vous basculez d'environnement. Les variables de collection (Collection variables) appartiennent à une collection quel que soit l'environnement, ce qui convient aux valeurs constantes pour cette API. Il existe également des variables globales, qui s'appliquent partout, et des variables locales de courte durée qui n'existent que pour une seule exécution. Choisir la bonne portée permet de maintenir une valeur là où elle doit être et d'éviter les surprises lorsque vous changez de cible.
Exécuter une collection entière avec le Collection Runner
Cliquer sur Envoyer pour chaque requête devient vite fastidieux. Le Collection Runner exécute chaque requête d'une collection dans l'ordre, exécute tous leurs tests et vous fournit un résumé de réussite/échec.
Ouvrez une collection, cliquez sur le bouton Exécuter (Run) (ou sur le menu à trois points, puis sur Exécuter la collection (Run collection)). Le runner affiche vos requêtes en séquence. Choisissez l'environnement, définissez le nombre d'itérations à exécuter et attachez éventuellement un fichier de données. Cliquez sur Exécuter et Postman déclenche chaque requête, de haut en bas, en exécutant les tests de chaque requête.
La page des résultats liste chaque assertion pour chaque requête, avec les totaux pour les réussites et les échecs. C'est votre vérification de régression. Exécutez-la après un déploiement et vous saurez en quelques secondes si l'API se comporte toujours correctement. Le runner conserve également un historique des exécutions passées, afin que vous puissiez comparer le résultat d'aujourd'hui à celui d'hier et repérer quand une suite auparavant verte a commencé à échouer.
L'ordre compte dans le runner. Comme les requêtes s'exécutent de haut en bas, vous pouvez placer une requête de connexion en premier afin qu'elle remplisse un auth_token, puis laisser chaque requête en dessous utiliser ce jeton. Il en va de même pour la configuration et le nettoyage : créez une ressource au début, utilisez-la au milieu, supprimez-la à la fin. Une collection bien ordonnée script efficacement un parcours utilisateur complet.
Pour les tests basés sur les données, joignez un fichier CSV ou JSON dans le runner. Chaque ligne devient une itération, et vous référencez les colonnes comme des variables telles que {{username}}. Cela permet à une seule requête de tester des dizaines de combinaisons d'entrée sans dupliquer la requête. Un endpoint de connexion, par exemple, peut être sollicité avec une ligne de justificatifs valides et plusieurs lignes de mauvais, chaque ligne affirmant le code de statut qu'elle attend. L'article sur les tests d'API basés sur les données avec CSV et JSON couvre le modèle en détail. Pour exécuter la même collection en CI sans l'interface graphique, Postman fournit l'outil en ligne de commande Newman, décrit dans la comparaison Newman versus Postman.
Là où Postman devient lourd, et ce qu'il faut considérer
Postman est excellent pour les tests exploratoires et les suites de petite à moyenne taille. Deux points de friction apparaissent à mesure que les projets grandissent. Premièrement, les assertions résident en JavaScript, ce qui implique une courbe d'apprentissage pour les non-développeurs et les personnes de l'assurance qualité qui préfèrent une approche visuelle. Deuxièmement, Postman conserve la conception de l'API, les tests, les mocks et la documentation dans des endroits distincts, ce qui signifie que vos données de test et votre contrat d'API peuvent diverger.
Apidog est une plateforme API tout-en-un qui répond à ces deux problèmes. Il importe directement les collections Postman, de sorte que la migration n'est pas une réécriture. Les assertions peuvent être construites visuellement sans code, tout en permettant l'utilisation de scripts lorsque vous en avez besoin. Comme la conception, le débogage, les mocks, les tests et la documentation partagent une source unique de vérité, vos tests restent alignés avec la spécification réelle de l'API. Si vous évaluez les options, la présentation des alternatives à Postman pour les tests d'API expose les compromis. Vous pouvez télécharger Apidog et importer une collection existante pour comparer directement.
Rien de tout cela ne signifie que vous devriez abandonner Postman. Il reste un choix solide, en particulier pour les vérifications rapides et les équipes qui y sont déjà investies. L'essentiel est de savoir où chaque outil s'insère.
Foire aux questions
Dois-je écrire du code pour tester les API dans Postman ?
Pour envoyer des requêtes et lire les réponses, non. Pour les assertions automatisées, oui, du moins un peu. L'onglet **Tests** de Postman exécute du JavaScript et utilise l'objet pm. Les modèles sont simples et vous pouvez les copier depuis le panneau d'extraits intégré de Postman, mais cela reste du JavaScript. Si vous souhaitez un constructeur d'assertions visuel sans code, une plateforme dédiée comme Apidog s'en charge.
Quelle est la différence entre une collection Postman et un environnement ?
Une collection est un ensemble de requêtes regroupées, souvent avec leurs tests. Un environnement est un ensemble nommé de variables, comme base_url ou auth_token. Les collections contiennent ce que vous envoyez. Les environnements contiennent les valeurs qui changent entre la préproduction, la production et le local. Vous pointez une collection vers différents environnements pour tester les mêmes requêtes sur différents serveurs.
Comment exécuter automatiquement les tests Postman en CI ?
Utilisez Newman, le runner en ligne de commande de Postman. Exportez votre collection et votre environnement, puis exécutez newman run collection.json -e environment.json. Newman se termine avec un code non nul si un test échoue, ce que votre pipeline CI vérifie. Le guide sur l'automatisation des tests d'API en CI/CD explique comment intégrer cela dans un pipeline.
Postman peut-il tester plus que des API REST ?
Oui. Le Postman moderne prend en charge les requêtes GraphQL, gRPC, WebSocket et SOAP en plus des requêtes HTTP et REST classiques. L'onglet **Tests** et les assertions fonctionnent pour la plupart d'entre eux, bien que la configuration exacte de la requête diffère selon le protocole.
Combien d'assertions une requête devrait-elle avoir ?
Assez pour confirmer que la réponse est correcte, mais pas trop pour qu'un seul changement ne casse pas une douzaine de tests. Une base courante est le code de statut, le temps de réponse et les deux ou trois champs qui sont importants pour cet endpoint. Gardez chaque bloc pm.test concentré sur une seule attente afin qu'un échec vous indique précisément ce qui n'a pas fonctionné.