Tests d'API avec Postman

Theorie 45 min

Qu'est-ce que Postman ?

Postman est une plateforme collaborative de developpement d'API qui permet de concevoir, tester et documenter des API via une interface visuelle. Pour les ingenieurs IA/ML, c'est le moyen le plus rapide de tester l'API de votre modele sans ecrire de code.

L'analogie de la salle de controle

Imaginez Postman comme une salle de controle de mission pour votre API :

Vous pouvez envoyer tout type de signal (GET, POST, PUT, DELETE) a votre API
Vous pouvez surveiller la reponse en temps reel (code de statut, corps, en-tetes, duree)
Vous pouvez automatiser des sequences de signaux (collection runner)
Vous pouvez partager votre tableau de bord avec votre equipe (export de collections)

Postman vs autres outils de test

Fonctionnalite	Postman	curl	httpx (Python)	Thunder Client (VS Code)
Interface visuelle	✅ GUI complete	❌ CLI uniquement	❌ Code uniquement	✅ Dans VS Code
Scripts de test	✅ JavaScript	❌ Verification manuelle	✅ Assertions Python	⚠️ Limite
Environnements	✅ Multiples	❌ Manuel	✅ Gere par code	✅ Basique
Collections	✅ Dossiers organises	❌ Scripts shell	✅ Classes de test	⚠️ Basique
Collaboration	✅ Espaces de travail equipe	❌ Aucune	✅ Via Git	❌ Aucune
Integration CI/CD	✅ Newman CLI	✅ Natif	✅ pytest	❌ Aucune
Courbe d'apprentissage	🟢 Faible	🟡 Moyenne	🟡 Moyenne	🟢 Faible
Ideal pour	Tests manuels + automatises	Tests rapides ponctuels	Tests programmatiques	Tests rapides dans VS Code

Quand utiliser quoi

Postman : Exploration interactive, partage en equipe, tests manuels avec capacites d'automatisation
curl : Tests rapides en une ligne dans le terminal, scripts CI
httpx/TestClient : Tests programmatiques dans pytest, pipelines CI/CD
Thunder Client : Verifications rapides sans quitter VS Code

Demarrer avec Postman

Installation

Telechargez sur postman.com/downloads
Installez et creez un compte gratuit
Ouvrez Postman — vous verrez l'espace de travail principal

Apercu de l'interface Postman

Creation de requetes

Requete de verification de sante (GET)

Cliquez sur New → HTTP Request
Definissez la methode sur GET
Saisissez l'URL : http://localhost:8000/health
Cliquez sur Send

Reponse attendue :

{
  "status": "healthy",
  "model_loaded": true,
  "model_version": "1.0.0",
  "timestamp": "2025-01-15T10:30:00Z"
}

Requete de prediction (POST)

Definissez la methode sur POST
Saisissez l'URL : http://localhost:8000/api/v1/predict
Allez dans l'onglet Body → selectionnez raw → definissez le type sur JSON
Saisissez le corps :

{
  "features": [5.1, 3.5, 1.4, 0.2, 2.3]
}

Cliquez sur Send

Reponse attendue :

{
  "prediction": 1,
  "confidence": 0.87,
  "model_version": "1.0.0"
}

Requete de prediction par lot (POST)

{
  "instances": [
    {"features": [5.1, 3.5, 1.4, 0.2, 2.3]},
    {"features": [6.7, 3.0, 5.2, 2.3, 1.1]},
    {"features": [4.9, 2.4, 3.3, 1.0, 0.5]}
  ]
}

Environnements et variables

Les environnements permettent de basculer entre local, staging et production sans modifier vos requetes.

Configuration des environnements

Cliquez sur l'onglet Environments dans la barre laterale
Creez un nouvel environnement nomme Local
Ajoutez les variables :

Variable	Valeur initiale	Valeur actuelle
`base_url`	`http://localhost:8000`	`http://localhost:8000`
`api_version`	`v1`	`v1`
`auth_token`	`test-token-123`	`test-token-123`

Creez un autre environnement nomme Staging :

Variable	Valeur initiale	Valeur actuelle
`base_url`	`https://staging-api.example.com`	`https://staging-api.example.com`
`api_version`	`v1`	`v1`
`auth_token`	`staging-token-456`	`staging-token-456`

Utilisation des variables dans les requetes

Remplacez les URL en dur par des variables en utilisant des accolades doubles :

GET {{base_url}}/health
POST {{base_url}}/api/{{api_version}}/predict

En-tetes avec variables :

Authorization: Bearer {{auth_token}}

Portee des variables

Postman dispose de 5 portees de variables (de la plus large a la plus etroite) :

Global — disponible partout
Collection — disponible dans une collection
Environment — disponible lorsque l'environnement est selectionne
Data — depuis des fichiers CSV/JSON lors des executions de collection
Local — definie dans les scripts, disponible uniquement pendant l'execution

ecriture de scripts de test

Postman utilise JavaScript pour les scripts de test. Les tests s'executent apres la reception de la reponse.

Assertions de test de base

Allez dans l'onglet Scripts → Post-response et ecrivez :

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

// Test 2: Response time is acceptable
pm.test("Response time is under 500ms", function () {
    pm.expect(pm.response.responseTime).to.be.below(500);
});

// Test 3: Response has correct content type
pm.test("Content-Type is JSON", function () {
    pm.response.to.have.header("Content-Type", "application/json");
});

Test du corps de la reponse

// Parse the JSON response
const response = pm.response.json();

// Test prediction format
pm.test("Prediction is an integer", function () {
    pm.expect(response.prediction).to.be.a("number");
    pm.expect(Number.isInteger(response.prediction)).to.be.true;
});

// Test confidence range
pm.test("Confidence is between 0 and 1", function () {
    pm.expect(response.confidence).to.be.at.least(0);
    pm.expect(response.confidence).to.be.at.most(1);
});

// Test model version exists
pm.test("Model version is present", function () {
    pm.expect(response).to.have.property("model_version");
    pm.expect(response.model_version).to.be.a("string");
});

// Test prediction class is valid
pm.test("Prediction is class 0 or 1", function () {
    pm.expect(response.prediction).to.be.oneOf([0, 1]);
});

Test des reponses d'erreur

Pour les requetes avec entree invalide :

pm.test("Status code is 422 for invalid input", function () {
    pm.response.to.have.status(422);
});

pm.test("Error detail is present", function () {
    const response = pm.response.json();
    pm.expect(response).to.have.property("detail");
});

Scripts pre-requete

Les scripts pre-requete s'executent avant l'envoi de la requete. Utilisez-les pour generer des donnees dynamiques :

// Generate a random set of features for testing
const features = [];
for (let i = 0; i < 5; i++) {
    features.push(parseFloat((Math.random() * 10).toFixed(2)));
}

pm.variables.set("dynamic_features", JSON.stringify(features));
console.log("Generated features:", features);

Utilisation dans le corps de la requete :

{
  "features": {{dynamic_features}}
}

Definition de variables a partir des reponses

// After a prediction request, save the result for the next request
const response = pm.response.json();
pm.collectionVariables.set("last_prediction", response.prediction);
pm.collectionVariables.set("last_confidence", response.confidence);

Creation de collections

Une collection est un groupe organise de requetes apparentees. Voyez-la comme une suite de tests pour votre API.

Structure de collection recommandee

📁 AI Prediction API
├── 📁 Health & Status
│   ├── GET Health Check
│   └── GET Model Info
├── 📁 Predictions
│   ├── POST Single Prediction
│   ├── POST Batch Prediction
│   └── POST Prediction with Metadata
├── 📁 Error Handling
│   ├── POST Empty Features
│   ├── POST Wrong Types
│   ├── POST Missing Body
│   └── POST Invalid JSON
└── 📁 Performance
    ├── POST Stress Test (10 requests)
    └── POST Large Batch (100 instances)

Creation d'une collection

Cliquez sur New → Collection
Nommez-la AI Prediction API
Ajoutez une description :

Test suite for the AI Prediction API built with FastAPI.
Base URL: {{base_url}}
Endpoints:
- GET /health
- POST /api/v1/predict
- POST /api/v1/predict/batch

Ajoutez des dossiers et des requetes comme indique ci-dessus

Collection Runner

Le Collection Runner permet d'executer toutes les requetes d'une collection sequentiellement, avec les resultats des tests pour chacune.

Execution d'une collection

Cliquez sur le bouton Run de votre collection
Configurez :
- Iterations : Nombre de fois pour executer la collection complete (utile pour les tests de charge)
- Delay : Millisecondes entre chaque requete
- Environment : Selectionnez Local, Staging ou Production
Cliquez sur Run AI Prediction API

Utilisation de fichiers de donnees

Vous pouvez alimenter vos requetes avec differentes entrees via des fichiers CSV ou JSON :

feature_1,feature_2,feature_3,feature_4,feature_5,expected_class
1,3.5,1.4,0.2,2.3,1
7,3.0,5.2,2.3,1.1,0
9,2.4,3.3,1.0,0.5,1

Dans le corps de la requete, referencez les variables de donnees :

{
  "features": [
    {{feature_1}}, {{feature_2}}, {{feature_3}},
    {{feature_4}}, {{feature_5}}
  ]
}

Dans le script de test :

const expectedClass = parseInt(pm.iterationData.get("expected_class"));
const response = pm.response.json();

pm.test("Prediction matches expected class", function () {
    pm.expect(response.prediction).to.equal(expectedClass);
});

Chainage de requetes

Certains flux de travail necessitent des requetes sequentielles ou la sortie de l'une devient l'entree de la suivante.

Exemple : Train → Predict → Explain

Requete 1 — Script post-reponse :

pm.test("API is healthy", function () {
    pm.response.to.have.status(200);
    const data = pm.response.json();
    pm.collectionVariables.set("model_version", data.model_version);
});

Requete 2 — Script pre-requete :

console.log("Using model version:", pm.collectionVariables.get("model_version"));

Requete 2 — Script post-reponse :

const data = pm.response.json();
pm.collectionVariables.set("prediction_result", data.prediction);
pm.collectionVariables.set("prediction_confidence", data.confidence);

Requete 3 — Corps :

{
  "features": [5.1, 3.5, 1.4, 0.2, 2.3],
  "prediction": {{prediction_result}},
  "model_version": "{{model_version}}"
}

Partage de collections

Export / Import

Export :

Clic droit sur la collection → Export
Choisissez le format Collection v2.1
Enregistrez sous ai-prediction-api.postman_collection.json

Import :

Cliquez sur Import → glissez le fichier JSON
La collection apparait dans votre espace de travail

Controle de version

Exportez vos collections Postman et fichiers d'environnement vers votre depot Git. Ainsi, vos tests d'API vivent aux cotes de votre code :

project/
├── app/
├── tests/
├── postman/
│   ├── ai-prediction-api.postman_collection.json
│   ├── local.postman_environment.json
│   └── staging.postman_environment.json
└── README.md

Newman CLI pour CI/CD

Newman est le compagnon en ligne de commande de Postman. Il execute les collections depuis le terminal — ideal pour les pipelines CI/CD.

Installation

npm install -g newman
npm install -g newman-reporter-htmlextra  # optionnel : rapports HTML

Execution des collections

# Execution de base
newman run postman/ai-prediction-api.postman_collection.json

# Avec environnement
newman run postman/ai-prediction-api.postman_collection.json \
  -e postman/local.postman_environment.json

# Avec iterations et fichier de donnees
newman run postman/ai-prediction-api.postman_collection.json \
  -e postman/local.postman_environment.json \
  -n 5 \
  -d postman/test-data.csv

# Avec rapport HTML
newman run postman/ai-prediction-api.postman_collection.json \
  -e postman/local.postman_environment.json \
  -r htmlextra \
  --reporter-htmlextra-export reports/api-test-report.html

Newman dans GitHub Actions

# .github/workflows/api-tests.yml

name: API Tests (Postman/Newman)

on:
  push:
    branches: [main]

jobs:
  api-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Start API server
        run: |
          pip install -r requirements.txt
          uvicorn app.main:app --host 0.0.0.0 --port 8000 &
          sleep 5

      - name: Install Newman
        run: npm install -g newman newman-reporter-htmlextra

      - name: Run Postman tests
        run: |
          newman run postman/ai-prediction-api.postman_collection.json \
            -e postman/local.postman_environment.json \
            -r cli,htmlextra \
            --reporter-htmlextra-export reports/report.html

      - name: Upload test report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: api-test-report
          path: reports/report.html

Exemple de sortie Newman

AI Prediction API

→ Health Check
  GET http://localhost:8000/health [200 OK, 234B, 45ms]
  ✓ Status code is 200
  ✓ Response time is under 500ms
  ✓ API is healthy

→ Single Prediction
  POST http://localhost:8000/api/v1/predict [200 OK, 189B, 123ms]
  ✓ Status code is 200
  ✓ Prediction is an integer
  ✓ Confidence is between 0 and 1
  ✓ Prediction is class 0 or 1

→ Empty Features (Error)
  POST http://localhost:8000/api/v1/predict [422 Unprocessable Entity, 312B, 12ms]
  ✓ Status code is 422 for invalid input
  ✓ Error detail is present

┌─────────────────────────┬────────────────┬───────────────┐
│                         │       executed │        failed │
├─────────────────────────┼────────────────┼───────────────┤
│              iterations │              1 │             0 │
├─────────────────────────┼────────────────┼───────────────┤
│                requests │              8 │             0 │
├─────────────────────────┼────────────────┼───────────────┤
│            test-scripts │             16 │             0 │
├─────────────────────────┼────────────────┼───────────────┤
│              assertions │             22 │             0 │
└─────────────────────────┴────────────────┴───────────────┘

Techniques avancees Postman

Authentification des requetes

Pour les API avec authentification :

Allez dans l'onglet Authorization
Selectionnez Bearer Token
Saisissez {{auth_token}}

Cela ajoute automatiquement l'en-tete : Authorization: Bearer <token>

Surveillance des API

Les Monitors Postman executent vos collections selon un planning (par ex. toutes les 5 minutes) :

Selectionnez votre collection → Monitor → Create a Monitor
Definissez la frequence et l'environnement
Recevez des alertes lorsque les tests echouent

Documentation d'API

Generez une documentation elegante a partir de votre collection :

Ouvrez votre collection → cliquez sur View Documentation
Publiez-la — obtenez une URL partageable
Incluez des exemples, des descriptions et des extraits de tests

Points cles a retenir

Postman est la salle de controle visuelle pour tester les API — aucun code requis pour les tests de base
Utilisez les environnements pour basculer facilement entre local, staging et production
Ecrivez des scripts de test (JavaScript) pour automatiser la validation des reponses
Organisez vos requetes en collections avec des dossiers descriptifs
Utilisez les scripts pre-requete pour generer des donnees dynamiques et chainer les requetes
Exportez les collections vers Git pour le controle de version
Utilisez Newman pour executer les tests Postman dans les pipelines CI/CD
Choisissez le bon outil : Postman pour l'exploration, pytest pour l'automatisation, curl pour les verifications rapides

Qu'est-ce que Postman ?​

L'analogie de la salle de controle​

Postman vs autres outils de test​

Demarrer avec Postman​

Installation​

Apercu de l'interface Postman​

Creation de requetes​

Requete de verification de sante (GET)​

Requete de prediction (POST)​

Requete de prediction par lot (POST)​

Environnements et variables​

Configuration des environnements​

Utilisation des variables dans les requetes​

ecriture de scripts de test​

Assertions de test de base​

Test du corps de la reponse​

Test des reponses d'erreur​

Scripts pre-requete​

Definition de variables a partir des reponses​

Creation de collections​

Structure de collection recommandee​

Creation d'une collection​

Collection Runner​

Execution d'une collection​

Utilisation de fichiers de donnees​

Chainage de requetes​

Exemple : Train → Predict → Explain​

Partage de collections​

Export / Import​

Newman CLI pour CI/CD​

Installation​

Execution des collections​

Newman dans GitHub Actions​

Exemple de sortie Newman​

Techniques avancees Postman​

Authentification des requetes​

Surveillance des API​

Documentation d'API​

Points cles a retenir​

Ressources complementaires​

Qu'est-ce que Postman ?

L'analogie de la salle de controle

Postman vs autres outils de test

Demarrer avec Postman

Installation

Apercu de l'interface Postman

Creation de requetes

Requete de verification de sante (GET)

Requete de prediction (POST)

Requete de prediction par lot (POST)

Environnements et variables

Configuration des environnements

Utilisation des variables dans les requetes

ecriture de scripts de test

Assertions de test de base

Test du corps de la reponse

Test des reponses d'erreur

Scripts pre-requete

Definition de variables a partir des reponses

Creation de collections

Structure de collection recommandee

Creation d'une collection

Collection Runner

Execution d'une collection

Utilisation de fichiers de donnees

Chainage de requetes

Exemple : Train → Predict → Explain

Partage de collections

Export / Import

Newman CLI pour CI/CD

Installation

Execution des collections

Newman dans GitHub Actions

Exemple de sortie Newman

Techniques avancees Postman

Authentification des requetes

Surveillance des API

Documentation d'API

Points cles a retenir

Ressources complementaires