Tester vos API swagger/openAPI avec Postman/Newman

Pouvoir tester ces endpoint d’API fait parti des impératifs avant tout déploiement d’une nouvelle version pour voir si une régression entre autre n’est pas survenue avec cette mise jour.

A ce jour il existe peu d’outils permettant de le faire assez rapidement. L’idée est de pouvoir à partir du fichier de description de votre API générer en quelques clics voir automatiquement les tests. Ce traitement pourra bien sur être intégré dans votre CI via une image docker. Nous verrons aujourd’hui la solution Postman et de son compagnon Newman.

Installation de Postman sur Ubuntu

Installation via snap

Comme souvent, Postman est disponible en package snap.

sudo snap install postman --classic

Installation depuis le site

Si vous souhaitez installer une version plus récente :

apt-get install libgconf-2-4 postman
cd /tmp
wget https://dl.pstmn.io/download/latest/linux64 -O postman.tar.gz
sudo tar -xzf postman.tar.gz -C /opt
sudo ln -s /opt/Postman/Postman /usr/bin/postman
cd
postman

Création d’un lanceur (optionnel)

cat > ~/.local/share/applications/postman.desktop <<EOF
[Desktop Entry]
Encoding=UTF-8
Name=Postman
Exec=postman
Icon=/opt/Postman/app/resources/app/assets/icon.png
Terminal=false
Type=Application
Categories=Development;
EOF

Prise en main

Faisons un rapide tour du propriétaire :

L’écran principal de Postman

L’écran de Postman se décompose en plusieurs parties dont voici les plus importantes :

  1. Ici on retrouve les collections qui permet de classer vos requêtes de manière fonctionnelle.
  2. Ici on a sous forme d’onglets les différentes requêtes ouvertes.
  3. Une liste déroulante permettant de choisir le type de requête à envoyer : GET, POST, PUT, et à coté l’URL de l’API
  4. Les paramètres à passer à l’URL.
  5. La réponse à la requête
  6. Ici vous trouverez les paramètres de l’environnement.

Importation d’un fichier de définition d’une API

En cliquant sur le menu [import] il est possible de convertir un fichier de définition d’API (swagger, openAPI) en une collection postman

Prenons comme exemple le petstore au format OpenAPI 2. Il est possible de charger des fichiers au format v3

wget https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore.yaml

Création d’un environnement

En cliquant sur la roue dentelé dans la zone 6 il est possible de créer des variables d’environnement, ici baseUrl.

L’écran principal de Postman

  1. Cliquer sur Add et donner un nom à votre environnement
  2. Cliquer dans la première case de la première ligne et taper baseUrl
  3. Dans la case suivante entrer ceci : https://petstore.swagger.io/v2
  4. Cliquer sur Add et fermer cette fenêtre
  5. Dans la liste déroulante environnement choisir prod.

Envoi de notre première requête

  1. Cliquer dans la collection petstore petid POST Find pet by ID
  2. Dans la partie params / Path variable entrer 112273
  3. Cliquer sur send et vous devriez recevoir cette réponse :
{
    "id": 112273,
    "category": {
        "id": 0,
        "name": "string"
    },
    "name": "doggie",
    "photoUrls": [
        "string"
    ],
    "tags": [
        {
            "id": 0,
            "name": "string"
        }
    ],
    "status": "available"
}

Écriture du premier test

Il suffit de cliquer sur la partie Test au bout de la ligne des params :

A coté de l’éditeur se trouve une zone de raccourci (snippets) permettant de créer rapidement des tests

L’écran principal de Postman

Cliquer sur status Code Code is 200

Vous devriez voir apparaître ces lignes :

pm.test("Status code is 200", function () {
    pm.response.to.have.status(200);
});

Ensuite cliquer sur Response headers Content-Type header check

Vous pouvez tester à tout moment tester en cliquant sur send. Vous devriez obtenir cet affichage :

L’écran principal de Postman

Automatisation des tests avec Newman

Il est possible d’automatiser les tests avec un outil fourni par postman. Dans un premier temps il faut exporter sa collection sous forme de fichier json. Il faut cliquer sur les … de votre collection et choisir Export. Garder le format proposé et appelez le petstore-collection.json. Avant n’oubliez pas de sauvegarder les modifications de la requête en cliquant sur Save en haut à droite de l’écran.

L’écran principal de Postman

Plutôt que d’installer Newman en local nous allons l’utiliser sous forme d’image docker:

docker run -v ~/collections:/etc/newman -t postman/newman_ubuntu run "petstore-collection.json"

Vous devriez obtenir ceci :

newman

Swagger Petstore

❏ pet / {pet Id}
↳ Find pet by ID
  GET https://petstore.swagger.io/v2/pet/112273 [200 OK, 436B, 1089ms]
  ✓  Status code is 200
  ✓  Content-Type is present
  1. Response time is less than 200ms

↳ Updates a pet in the store with form data
  POST https://petstore.swagger.io/v2/pet/<long> [404 Not Found, 403B, 553ms]
  ...
┌─────────────────────────┬────────────────────┬────────────────────┐
│                         │           executed │             failed │
├─────────────────────────┼────────────────────┼────────────────────┤
│              iterations │                  1 │                  0 │
├─────────────────────────┼────────────────────┼────────────────────┤
│                requests │                 20 │                  0 │
├─────────────────────────┼────────────────────┼────────────────────┤
│            test-scripts │                  1 │                  0 │
├─────────────────────────┼────────────────────┼────────────────────┤
│      prerequest-scripts │                  0 │                  0 │
├─────────────────────────┼────────────────────┼────────────────────┤
│              assertions │                  3 │                  1 │
├─────────────────────────┴────────────────────┴────────────────────┤
│ total run duration: 10.7s                                         │
├───────────────────────────────────────────────────────────────────┤
│ total data received: 2.59MB (approx)                              │
├───────────────────────────────────────────────────────────────────┤
│ average response time: 492ms [min: 316ms, max: 2.2s, s.d.: 422ms] │
└───────────────────────────────────────────────────────────────────┘

  #  failure                           detail

 1.  AssertionError                    Response time is less than 200ms
                                       expected 1089 to be below 200
                                       at assertion:2 in test-script
                                       inside "pet / {pet Id} / Find pet by ID"
bob@bob-HP:~/Projets/blog$

Dans mon cas le résultat de mon test a partiellement fonctionné avec une assertion négative !!!

Il ne reste plus qu’a écrire vos tests et à intégrer cette étape dan votre CI avant déploiement en prod. De même New peut parfaitement servir à tester votre API avant de le pousser dans votre repo de code.


Alimenter un blog comme celui-ci est aussi passionnant que chronophage. En passant votre prochaine commande (n'importe quel autre article) au travers des liens produits ci-contre, je touche une petite commission sans que cela ne vous coûte plus cher. Cela ne me permet pas de gagner ma vie, mais de couvrir les frais inhérents au fonctionnement du site. Merci donc à vous!

comments powered by Disqus