# Newman rejoue une collection Postman de tests API dans votre pipeline CI

> Une collection Postman utilisée manuellement peut aussi tourner en ligne de commande à chaque build. Mise en place de Newman pour automatiser ces vérifications d'API.

- Auteur : WordPress Développement
- Publié le : 2021-07-08
- Mis à jour le : 2021-07-08
- Catégorie : Tests
- URL : https://www.wpmoderne.fr/tests/newman-collections-postman-ci/

## L’essentiel

- Newman exécute une collection Postman exportée en ligne de commande, sans interface
- Les variables d'environnement remplacent les valeurs saisies manuellement dans Postman
- Un rapport JUnit généré par Newman s'intègre directement à la plupart des pipelines CI

`newman run collection.json --environment recette.json` : cette commande unique suffit à rejouer, sans jamais ouvrir Postman, l'ensemble des requêtes qu'une équipe a l'habitude de tester à la main avant chaque mise en production. Newman est l'exécuteur en ligne de commande officiel de Postman, distribué en paquet Node.js.

Pour une équipe qui a déjà construit une collection Postman couvrant les principales routes de son API, mais qui la relance manuellement à chaque fois, Newman offre une automatisation directe sans réécrire ces tests dans un autre outil. Ce billet ne traite pas les tests de contrat figés par schéma, qui répondent à un besoin différent, centré sur la structure plutôt que sur le comportement.

## Exporter la collection existante

La première étape consiste à exporter la collection Postman construite manuellement, ainsi que l'environnement de variables associé (URL de base, jeton d'authentification, identifiants de test), au format JSON :

1. Dans Postman, ouvrir la collection concernée puis choisir « Export » au format Collection v2.1.
2. Exporter également l'environnement utilisé, qui contient les variables comme `{{base_url}}` ou `{{jeton_api}}`.
3. Committer ces deux fichiers JSON dans le dépôt du projet, dans un dossier dédié aux tests d'API.

## Installer et lancer Newman en ligne de commande

```
npm install --save-dev newman

npx newman run tests/api/collection.json \
  --environment tests/api/environnement-recette.json \
  --reporters cli,junit \
  --reporter-junit-export tests/api/rapport-newman.xml
```

Newman exécute chaque requête de la collection dans l'ordre défini, évalue les scripts de test associés (écrits en JavaScript dans l'onglet « Tests » de Postman) et affiche un résumé en ligne de commande, avec le nombre d'assertions réussies et échouées.

> L'essentiel à retenir : Newman exécute une collection Postman exportée en ligne de commande, sans interface ; Les variables d'environnement remplacent les valeurs saisies manuellement dans Postman ; Un rapport JUnit généré par Newman s'intègre directement à la plupart des pipelines CI

## Adapter les variables selon l'environnement cible

Le fichier d'environnement exporté depuis Postman contient généralement des valeurs de développement local. En intégration continue, il faut soit préparer un environnement dédié à la recette, soit surcharger certaines variables directement en ligne de commande sans toucher au fichier JSON :

```
npx newman run tests/api/collection.json \
  --environment tests/api/environnement-recette.json \
  --env-var "jeton_api=$CI_JETON_API"
```

Cette surcharge évite de committer un jeton d'authentification en clair dans le dépôt, en le récupérant plutôt depuis une variable secrète configurée dans le pipeline.

## Intégrer le rapport au pipeline

Le format JUnit produit par le rapporteur `junit` de Newman est compris nativement par la plupart des outils d'intégration continue, qui affichent alors les résultats de la collection Postman au même endroit que les tests PHPUnit, sans distinction visuelle particulière pour l'équipe qui consulte le résultat du build.

| Reporter Newman | Usage principal |
| --- | --- |
| cli | Sortie lisible dans les logs du pipeline |
| junit | Intégration au tableau de résultats de tests du pipeline |
| htmlextra | Rapport HTML détaillé, à générer en artefact séparé |

## Ce que Newman ne remplace pas

Newman rejoue fidèlement les requêtes telles que définies dans Postman, avec les scripts de test associés, mais il reste limité à ce que ces scripts vérifient explicitement. Une collection qui ne teste que le code de statut HTTP, sans vérifier le contenu de la réponse, continuera de passer même si le corps de la réponse a changé de structure de façon problématique :

- Vérifier que chaque requête de la collection contient au moins une assertion sur le corps de la réponse, pas seulement sur le code de statut.
- Ajouter des assertions sur les champs critiques métier, pas uniquement sur la présence d'un champ générique.
- Revoir périodiquement la collection pour supprimer les requêtes devenues obsolètes après un changement d'API.

> Une collection Postman qui vérifie uniquement le code 200 donne une fausse impression de couverture : le contenu de la réponse mérite au moins autant d'attention que son statut.

## En résumé

Newman permet de rejouer en ligne de commande, à chaque build, une collection Postman déjà construite manuellement, sans devoir la réécrire dans un autre outil de test. L'automatisation gagne surtout en valeur lorsque les scripts de test de la collection vérifient réellement le contenu des réponses, et pas seulement leur code de statut.