Exemples d’utilisation de Postman/Newman

Comme tout le monde le sait, Postman est un outil très puissant surtout quand vous travaillez avec des API. Il possède beaucoup de fonctionnalités et peut vraiment vous aider dans le cycle de vie de vos API et de vos services REST. Voici des exemples d’utilisation de Postman et Newman chez un de nos clients.

Ayant travaillé plusieurs années chez un client sur le vaste sujet des API, je vais vous présenter ici comment nous utilisions Postman, dans quel but, sur quel périmètre et surtout comment cet outil nous a aidé dans notre démarche API.

Postman, un ami pour tout le cycle de vie

Nous avions spécifié un process de création d’API, de la conception au monitoring et cela a permis de couvrir l’ensemble du cycle de vie de l’API.

Pour chaque API à l’étape de développement, les développeurs devaient créer une collection Postman en accord avec la spécification de l’API en question. Cette collection, à ce stade, avait pour objectif de tester l’ensemble des ressources de l’API. L’équipe business fournissait les cas de tests.

Postman exécutait des tests pour chaque ressource. Ces derniers concernaient principalement :

• Le temps de réponse ;
• Le code de retour ;
• La conformité : le contenu de la réponse doit comporter des éléments spécifiques (nom de l’élément et valeur).

Nous avions défini plusieurs environements :

• Développement
• Intégration
• Pré-production
• Production

A cette étape du process, le développeur a implémenté l’API puis l’a testé très simplement et très rapidement en exécutant la collection Postman qu’il a également créé.

A la fin des tests, il publie l’API sur l’environement d’intégration. L’équipe métier peut valider l’API (que nous soyons en création ou en modification d’API) en exécutant la collection avec le bon environnement et en vérifiant que tous les tests soient au vert. La CI/CD peut exécuter cette tâche dans une démarche d’industrialisation.

L’environnement de pré-production servait à la réalisation des tests de charge. La validation du test de charge permet de valider, puis de publier l’API sur l’environnement de production.
Enfin, l’exécution de la collection permet de valider la publication de l’API en production.

Newman, les sanity checks

Une fois l’API en production, nous continuons à utiliser la collection pour réaliser des “sanity checks“.

Pour créer des “tests”, c’est simple.

Rendez-vous dans l’onglet “Tests”

Voici quelques exemples :

//Test d'un code retour 200, 201 ou 206
tests["ReturnCode_20X"] = responseCode.code === 200|| responseCode.code === 201 || responseCode.code === 206;

//Test sur l'existance du header ContentType
var contentTypeHeaderExists = responseHeaders.hasOwnProperty("Content-Type");
tests["Has_Content_Type"] = contentTypeHeaderExists;

//Test sur le Content-Type = application/json
if (contentTypeHeaderExists) {
     tests["Content_Type_application_json"] = responseHeaders["Content-Type"].has("application/json");
 }

//Test sur la présence de balise dans le body de retour
tests["Compliance0"] = responseBody.has("cardNumber");
 tests["Compliance1"] = responseBody.has("creationDate");
 tests["Compliance2"] = responseBody.has("lastUpdateDate");

//Test sur la valeur dans les balises de retour
var jsonData = JSON.parse(responseBody);
 tests["Compliance0"] = jsonData.cardNumber=== "123456789";
 tests["Compliance1"] = jsonData.creationDate === "20/01/98 12:34:00";
 tests["Compliance2"] = jsonData.lastUpdateDate === "26/11/04 10:2100";

Pour créer ces tests, vous avez beaucoup de snippets proposés sur le côté droit de l’outil :

Il est ensuite possible d’exécuter les tests d’une collection depuis Postman

Afin d’industrialiser l’exécution des tests, nous utilisions Newman, un puissant outil en ligne de commande pour exécuter les collections Postman. Toutes les minutes un job exécutait Newman avec chaque collection (pour chaque API) et générait un fichier de résultat pour chacune des API.

docker run -v ~/collections:/etc/postman -t postman/newman \
    myCollection.json \
    --iteration-count 5
    --timeout-request 30000
    --environment="PROD.json" \
    --reporters="json,html,junit" \
    --reporter-json-export="result.json" \
    --reporter-html-export="/path/to/apache/result.html"
    --reporter-junit-export="newman-report.xml"

// Execution de la collection ~/collections/myCollection.json
// 5 itérations de la collection
// Timeout de 30s sur les requests
// Utilisation du ficher d'environement PROD.json
// Génération de report en json ("result.json")
// Génération de report en JUnit
// Génération de report en HTML (/path/to/apache/result.html)

Nous avions créé un programme pour parcourir les résultats (result.json) et réaliser les actions suivantes :

• Récupérer les temps de réponse pour générer des graphes (à l’aide de graphite) ;
• Lever des alertes si certains tests ne passaient pas.

Nous avions des dashboards Grafana permettant de visualiser ces éléments. Ces graphes nous permettaient de mesurer et visualiser la latence subie par les magasins implantés sur les autres continents (Asie ou Amérique du sud par exemple).

Le système d’alerting prévenait les équipes métiers quand un problème survenait. Ces derniers pouvaient réaliser les tests nécessaires, grâce aux collections, pour réaliser les diagnostiques nécessaires à leurs résolutions. Très pratique !

Le mock

Collection Postman pour simuler les séquences métier

Nous utilisions également Postman pour analyser les problèmes sur certaines applications consommant des API. De plus en plus d’applications consomment massivement des API et lorsqu’un problème se présente, il est parfois difficile d’en trouver l’origine. Est-ce un problème sur le client ? Sur l’API ? Est-ce lié au réseau ?

Nous avons créé des collections pour reproduire les séquences d’appels aux API. Voici un exemple:

Avec Postman, ce type de scénario est simple a implémenter et les données retournées par une request peuvent être utilisées en entrée des autres requests.

Quand nous exécutions cette collection qui reproduisait les appels fait par l’application, nous pouvions rapidement voir ce qu’il se passait et si une API ne répondait pas comme attendu ou dans des délais trop importants.

Dans la section test, il assez simple de passer des données d’une request a une autre ou même de spécifier quel doit être la prochaine requête.

Dans l’exemple précédent, nous mettions en variable globale le client_card_id:

var data = JSON.parse(responseBody);
pm.globals.set("clientCardId", data.clientid);

Dans les appels suivants, cette variable peut être utilisée:

Elle peut également etre récupérée dans les autres tests:

clientCardId = pm.globals.get("clientCardId");

Il est également possible de spécifier la requête suivante:

var body = JSON.parse(responseBody);
if (body.reference == "XXX"){
    postman.setNextRequest("requestXXX");
}
 postman.setNextRequest("requestOthers");

Conclusion

Nous avons vu dans cet article comment il est possible d’utiliser Postman afin de

• Tester les API durant leur cycle de vie ;
• Obtenir les temps de réponse client/serveur au niveau monde ;
• Réaliser des sanity checks sur les API de production ;
• Développer des applications rapidement grâce au mocking ;
• Analyser les problèmes dans les séquences business.
• Intégrer les test à la CI/CD

En ce qui concerne des tests de charge, postman/newman ne le permet pas. Il est préférable d’utiliser des outils type apache jmeter, gattling, loadNinja ($), …

Il existe également des alternatives intéressantes à postman, comme postwoman qui est entièrement en ligne (pas d’installation mais les API testées doivent être accessibles sur internet). L’import/export est compatible de postman vers postwoman et vice versa.

Liens utiles

• Command Line Integration with Newman
• Setting up Mock
• Integration with Jenkins
• Branching and Looping
• Postwoman