Automatisation de tests avec Newman

Dans mon précédent article, nous avons vu comment créer des tests d’API avec Postman. Mais un test, même s’il est très bien conçu, n’est vraiment utile que s’il est exécuté automatiquement par l’usine de build. Au travers de ce tutoriel, nous allons donc voir dans cet article comment mettre en place cette automatisation.

Si Postman est un formidable outil pour tester nos requêtes, nous allons utiliser un autre outil pour les automatiser : il s’agit de Newman. En effet, Newman est un petit utilitaire en ligne de commande qui permet d’exécuter des collections Postman.

Etape 1 – Préparation des tests

Pour être efficace, nos scénarios de test doivent être le plus paramétrés possible. Par exemple, pour une requête de ce type :

POST https://localhost:44317/api/Team/5

Il serait plus judicieux d’utiliser des variables :

POST {{ApiServer}}/api/Team/{{gameId}}

Ici, “ApiServer" est une variable d’environnement et “gameId", une variable de collection, remplie par la requête précédente :

Attention, si vous n’utilisez pas la syntaxe spécifique pour les tests, Newman ne générera aucun résultat :

Par ailleurs, comme on n’est pas chez les sauvages, quelques petites requêtes de ménage en fin de collection sont de mises.

Etape 2 – Exportation des collections

Un fois que notre collection fonctionne correctement, nous allons l’exporter pour automatiser les tests :

Pendant qu’on y est, exportons également les variables d’environnement :

Nous recevons alors 2 fichiers json avec respectivement les requêtes et les variables d’environnement utilisées par ces requêtes. Placez-les dans votre gestionnaire de version préféré.

Cette exportation vous permet également d’avoir une sauvegarde de vos requêtes. Cela est particulièrement utile si vous utilisez la fonctionnalité de travail en équipe de Postman sans licence payante. En effet, Postman à la fâcheuse manie d’archiver vos requêtes au moment le moins opportun et vous ne pourrez les retrouver qu’en payant votre obole.

 

Etape 3 – Test en local

Muni de ces fichiers, nous allons pouvoir « tester nos tests » hors de Postman. Pour cela, nous aurons besoin de Newman, le runner de tests Postman. Newman est une application tournant sous “npm”, donc, si ce n’est pas encore le cas, installez Node.js + npm au préalable et installez newman :

npm i -g newman

Une fois installé, on lance un test sur une collection :

newman run <myCollection.json> -e <myEnvironment.json>

On obtient alors le résultat suivant (en rouge, une indication de l’élément affiché):


Create a Team Nom de la collection
→ Login Nom de la requête
POST https://localhost:44317/api/Account/Login [200 OK, 1.63KB, 180ms]
→ Create game
Verbe + requête                          Résultat de la requête
POST https://localhost:44317/api/Game/ [201 Created, 646B, 4.8s]
→ Create team
POST https://localhost:44317/api/Team/5 [201 Created, 510B, 1411ms]
→ Add User
POST https://localhost:44317/api/Team/AddPlayer/1 [200 OK, 951B, 328ms]
→ Cleanup Game
DELETE https://localhost:44317/api/Game/5 [200 OK, 135B, 249ms]
→ Cleanup Team
DELETE https://localhost:44317/api/Team/1 [200 OK, 135B, 237ms]
┌─────────────────────────┬─────────────────────┬─────────────────────┐
│                         │            executed │              failed │
├─────────────────────────┼─────────────────────┼─────────────────────┤
│              iterations │                   1 │                   0 │
├─────────────────────────┼─────────────────────┼─────────────────────┤
│                requests │                   6 │                   0 │
├─────────────────────────┼─────────────────────┼─────────────────────┤
│            test-scripts │                  10 │                   0 │
├─────────────────────────┼─────────────────────┼─────────────────────┤
│      prerequest-scripts │                   6 │                   0 │
├─────────────────────────┼─────────────────────┼─────────────────────┤
│              assertions │                   0 │                   0 │
├─────────────────────────┴─────────────────────┴─────────────────────┤
│ total run duration: 7.4s                                            │
├─────────────────────────────────────────────────────────────────────┤
│ total data received: 2.02KB (approx)                                │
├─────────────────────────────────────────────────────────────────────┤
│ average response time: 1195ms [min: 180ms, max: 4.8s, s.d.: 1652ms] │
└─────────────────────────────────────────────────────────────────────┘

Penchons-nous sur les 2 résultats de la commande :

• Le résultat individuel de chaque requête,
• Le résultat global avec notamment le temps d’exécution (très pratique pour effectuer des tests de performance dans le temps).

De nombreuses options existent sur Newman. Cependant, il est probable, dans le cadre d’appels https avec des certificats auto signés d’avoir une erreur de ce type :

unable to verify the first certificate

L’option --insecure permet d’outrepasser le contrôle.

Etape 4 – Création de build de test

Une fois que nos tests fonctionnent en local, il est temps de les exécuter automatiquement, potentiellement à chaque build. Nous utiliserons Azure DevOps pour cette build. Le fonctionnement est similaire pour d’autres usine de build, comme TeamCity par exemple.

Création de la pipeline

Rien de particulier ici, on crée une pipeline basée sur le système de gestion de sources. Il est toutefois conseillé de partir sur des sources fraîches à chaque build :

Installation de Postman

Par défaut, Newman n’est pas installé dans Azure DevOps, mais Npm l’est. La première tache sera donc de l’installer :

npm install newman

Utilisation de Newman

Cette tâche va procéder aux tests des API.

On s’inspire de la ligne de commande utilisée en local :

newman run <myCollection.json> -e <myEnvironment.json> -x -k --reporters cli,junit --reporter-junit-export $(System.DefaultWorkingDirectory)/QA/Results/junitReport.xml

L’option -x permet d’éviter que la tache soit en erreur pour DevOps si l’un des tests exécuté est en erreur.

-k permet d’éviter un message d’erreur dans le cas où le certificat ssl n’est pas valide.

Attention de bien spécifier le Working Directory pour que Newman puisse accéder aux fichiers.

Les paramètres en plus spécifient le format et le fichier de sortie des résultats de tests en vue d’une exploitation ultérieure par la tâche de publication (cf. plus bas).

Publication des résultats de test

Pour être publiés au niveau des résultats de la pipeline, le fichier de résultat généré par Newman doit être fournis à une tâche de type Publish Test Result :

La build, une fois exécutée donnera le résultat des tests dans l’onglet réservé aux tests :

Etape 5 – Création des scénarios

La création de scénarios peut être assez fastidieuse et nécessite des connaissances techniques. Pour faciliter l’écriture des scénarios, un plugin Chrome permet l’enregistrement des requêtes effectuées (par exemple depuis un front-end Angular) dans une collection dédiée.

Une fois le plugin téléchargé et connecté à Postman, toutes les requêtes émises par Chrome qui respectent les filtres éventuels seront copiées dans Postman. Dans notre exemple, seules les requêtes comprenant « exemple » et de type POST, PUT, PATCH ou DELETE seront prises en compte.

Si le plugin facilite l’écriture des scénarios (un utilisateur non technique peut les enregistrer facilement), il ne remplace pas le travail du développeur pour variabiliser les requêtes ou éliminer celles qui sont inutiles.

Pour conclure

Nous venons de voir l’automatisation basique de tests d’API REST, mais l’outil Postman/Newman permet d’aller beaucoup plus loin. En effet, il permet le :

• Passage de fichier de données pour personnaliser les tests d’un run à l’autre,
• Faire des tests de charge en exécutant chaque collection un nombre défini de fois,
• Appeler des API lors du déclenchement d’un trigger,
• Etc.

A vous de jouer pour augmenter la qualité de vos applications !