Une API est une promesse faite à d'autres programmes. Un contrat testé garantit que la promesse tient quand le code change.
⏱️ Durée : environ 100 minutes · 🎓 Niveau : intermédiaire · 🏅 Badge : Gardien du contrat
🎬 L'histoire
L'équipe mobile de HashBox appelle GET /cours/HEF-010. Mardi, Kodi renomme le champ titre en intitule « pour plus de clarté ». Mercredi, l'application mobile affiche « undefined » partout. Personne n'a cassé de test : l'API répondait bien… autre chose que ce que ses clients attendaient.
« Une API, c'est un contrat, dit Maya. Le changer sans le dire, c'est comme changer la forme d'une prise électrique. Un test de contrat détecte ce genre de rupture avant que les clients ne la subissent. »
Tu apprends à tester une API de bout en bout (statuts, formats, erreurs), à écrire un contrat vérifiable, et à faire évoluer une API sans casser ses clients.
🎯 Ta mission
À la fin, je serai capable de :
- tester une API HTTP avec un vrai serveur local et un client
- vérifier statuts, en-têtes, corps JSON, cas d'erreur
- écrire un schéma de contrat et le valider automatiquement
- distinguer changements compatibles et ruptures
- décrire le principe des tests de contrat côté consommateur (Pact)
🧩 Défi d'échauffement (5 XP)
Une prise électrique a un contrat : forme, tension, fréquence. Un fabricant décide de rendre la prise 2 mm plus large « parce que c'est plus joli ». Qui est cassé ? Comment chaque fabricant d'appareil peut-il vérifier à l'avance que son appareil continuera de s'y brancher ?
💡 Le concept
Que tester dans une API ?
| Aspect | Exemples |
|---|---|
| Statut HTTP | 200 OK, 201 créé, 400 requête invalide, 401/403, 404 introuvable, 409 conflit, 429, 500 |
| Corps | structure JSON, types, champs obligatoires et optionnels |
| En-têtes | Content-Type, Cache-Control, Location |
| Erreurs | format cohérent, message utile sans détail interne |
| Sécurité | authentification requise, autorisation, entrées malveillantes (HEF-100) |
| Idempotence | un PUT répété donne le même résultat |
| Performance | temps de réponse raisonnable |
Tester avec un vrai serveur local
Pour un test d'API, on démarre le serveur sur localhost, port éphémère (0 = le système en choisit un libre), dans un thread, et on l'appelle avec un client HTTP. Aucun accès à Internet.
setUpClass → démarrer le serveur | tests → appels HTTP | tearDownClass → arrêter
Le contrat d'une API
Un contrat décrit précisément ce que l'API promet :
- les routes et méthodes ;
- la forme des requêtes et réponses (champs, types, obligatoires/optionnels) ;
- les codes d'erreur et leur format ;
- les règles de versionnement.
Il se décrit en schéma (OpenAPI / JSON Schema) que des outils vérifient automatiquement.
Un validateur de schéma simplifié
Un schéma minimal :
{"type": "object", "required": ["code", "titre", "places"],
"properties": {"code": "str", "titre": "str", "places": "int"}}
Une réponse conforme a tous les champs obligatoires avec les bons types. Les champs en plus sont tolérés (principe de robustesse : les clients ignorent ce qu'ils ne connaissent pas).
Compatible ou cassant ?
| Changement | Verdict |
|---|---|
| Ajouter un champ optionnel dans la réponse | ✅ compatible |
| Ajouter un champ obligatoire dans la requête | ❌ cassant |
| Supprimer ou renommer un champ de réponse | ❌ cassant |
Changer un type (int → str) | ❌ cassant |
| Ajouter une nouvelle route | ✅ compatible |
| Rendre une valeur d'énumération plus restrictive | ❌ cassant |
| Changer un code de statut | ❌ généralement cassant |
Pour une rupture voulue : nouvelle version (/v2/…), période de transition, avertissement (en-tête Deprecation).
Tests de contrat côté consommateur
Dans une architecture de plusieurs services, le consommateur déclare ce qu'il utilise réellement (champs, formats) ; le fournisseur exécute ces attentes à chaque changement. Des outils (Pact) automatisent cela. Le principe :
- le consommateur écrit : « j'ai besoin de
code(texte) ettitre(texte) » ; - ce contrat est partagé ;
- le fournisseur rejoue le contrat contre sa vraie API dans son pipeline ;
- une rupture fait échouer la CI du fournisseur avant le déploiement.
Avantage : on teste l'accord entre services sans lancer tout le système.
Données de test et environnements
- Une API de test jetable, avec données fabriquées ;
- jamais la production ;
- authentification de test, jeton factice ;
- nettoyage ou isolation par test.
🧠 Astuce : écris le test d'API du point de vue du client : il ne sait rien de ton code, seulement de ta promesse.
🔍 Exemple pas à pas
Problème : démarrer une mini-API HTTP locale, la tester (statuts, JSON, erreurs), valider son contrat avec un schéma, et détecter une rupture de contrat.
import io, json, threading, unittest, urllib.error, urllib.request
from http.server import BaseHTTPRequestHandler, HTTPServer
COURS = {"HEF-010": {"code": "HEF-010", "titre": "Algorithmes", "places": 20}}
class Handler(BaseHTTPRequestHandler):
titre_champ = "titre" # sert plus loin à simuler une rupture
def _repondre(self, statut, corps, entetes=None):
donnees = json.dumps(corps).encode()
self.send_response(statut)
self.send_header("Content-Type", "application/json; charset=utf-8")
self.send_header("Content-Length", str(len(donnees)))
for k, v in (entetes or {}).items():
self.send_header(k, v)
self.end_headers()
self.wfile.write(donnees)
def do_GET(self):
morceaux = self.path.strip("/").split("/")
if morceaux[0] == "cours" and (morceaux) == :
cours = COURS.get(morceaux[])
cours :
._repondre(, {: })
visible = (cours)
.titre_champ != :
visible[.titre_champ] = visible.pop()
._repondre(, visible)
._repondre(, {: })
():
.path != :
._repondre(, {: })
taille = (.headers.get(, ))
:
corps = json.loads(.rfile.read(taille))
json.JSONDecodeError:
._repondre(, {: })
(corps, ) (corps.get(), ) (corps.get(), ):
._repondre(, {: })
corps[] COURS:
._repondre(, {: })
COURS[corps[]] = {: corps[], : corps[], : (corps.get(, ))}
._repondre(, COURS[corps[]], {: })
():
TYPES = {: , : }
():
erreurs = []
champ schema[]:
champ corps:
erreurs.append()
(corps[champ], TYPES[schema[][champ]]) (corps[champ], ):
erreurs.append()
erreurs
CONTRAT_COURS = {: [, , ], : {: , : , : }}
():
donnees = corps (corps (corps, ) json.dumps(corps).encode())
requete = urllib.request.Request(base + chemin, data=donnees, method=methode, headers={: })
:
urllib.request.urlopen(requete, timeout=) r:
r.status, (r.headers), json.loads(r.read())
urllib.error.HTTPError e:
e.code, (e.headers), json.loads(e.read())
(unittest.TestCase):
():
cls.serveur = HTTPServer((, ), Handler)
cls.base =
threading.Thread(target=cls.serveur.serve_forever, daemon=).start()
():
cls.serveur.shutdown()
cls.serveur.server_close()
():
statut, entetes, corps = appel(, .base, )
.assertEqual(statut, )
.assertTrue(entetes[].startswith())
.assertEqual(valider(corps, CONTRAT_COURS), [])
.assertEqual(corps[], )
():
statut, _, corps = appel(, .base, )
.assertEqual((statut, corps), (, {: }))
():
statut, entetes, corps = appel(, .base, , {: , : , : })
.assertEqual(statut, )
.assertEqual(entetes[], )
.assertEqual(valider(corps, CONTRAT_COURS), [])
():
appel(, .base, , {: , : })
statut, _, corps = appel(, .base, , {: , : })
.assertEqual(statut, )
():
corps (, {: , : }, {: }, [, ]):
.subTest(corps=corps):
statut, _, reponse = appel(, .base, , corps)
.assertEqual(statut, )
.assertIn(, reponse)
resultat = unittest.TextTestRunner(stream=io.StringIO()).run(unittest.defaultTestLoader.loadTestsFromTestCase(TestApiCours))
(, resultat.testsRun, , resultat.wasSuccessful())
resultat.wasSuccessful(), resultat.failures + resultat.errors
Handler.titre_champ =
resultat = unittest.TextTestRunner(stream=io.StringIO()).run(unittest.defaultTestLoader.loadTestsFromTestCase(TestApiCours))
(, (resultat.failures), )
(resultat.failures) >=
Lecture :
- Le serveur écoute sur
127.0.0.1et un port libre ; aucun accès au réseau externe. - Les tests parlent comme un client : méthode, chemin, statut, en-têtes, JSON.
valider(corps, CONTRAT_COURS)encode le contrat : champs obligatoires et types.- Après le renommage de
titreenintitule, le test de contrat échoue : c'est exactement la rupture qui avait cassé l'application mobile, mais détectée avant le déploiement.
✍️ À toi, avec aide (10 XP)
Écris comparer_contrats(ancien, nouveau) qui compare deux schémas (comme CONTRAT_COURS) pour une réponse d'API et classe les changements en compatibles et cassants selon le tableau du cours :
- champ ajouté (optionnel ou obligatoire dans la réponse) → compatible ;
- champ retiré → cassant ;
- type modifié → cassant.
Teste avec 4 paires de schémas.
💡 Indice 1
Compare les ensembles de clés de properties.
💡 Indice 2
Un champ présent dans les deux mais avec un type différent est cassant.
💡 Indice 3
Renvoie deux listes de messages.
✅ Réponse
def comparer_contrats(ancien, nouveau):
compat, cassant = [], []
a, n = ancien["properties"], nouveau["properties"]
for champ in sorted(set(n) - set(a)):
compat.append(f"champ ajouté : {champ}")
for champ in sorted(set(a) - set(n)):
cassant.append(f"champ retiré : {champ}")
for champ in sorted(set(a) & set(n)):
if a[champ] != n[champ]:
cassant.append(f"type modifié : {champ} ({a[champ]} → {n[champ]})")
return compat, cassant
base = {"required": ["code", "titre"], "properties": {"code": "str", "titre": "str"}}
assert comparer_contrats(base, {"required": ["code", "titre"], "properties": {"code": "str", "titre": , : }}) == ([], [])
comparer_contrats(base, {: [], : {: }}) == ([], [])
comparer_contrats(base, {: [, ], : {: , : }}) == ([], [])
comparer_contrats(base, base) == ([], [])
()
🚀 À toi, en solo (20 XP)
Test de contrat côté consommateur. Écris :
- un « consommateur »
AffichageCoursqui n'utilise quecodeettitred'une réponse ; - un contrat de consommateur (dictionnaire) listant exactement les champs et types dont il dépend ;
- une fonction
verifier_fournisseur(contrat, reponse)qui vérifie la réponse du fournisseur ; - trois versions de fournisseur : A (ajoute
places), B (renommetitre), C (ajouteplaceset changecodeen entier) ; - montre que A passe (pas de rupture pour ce consommateur), B et C échouent, et explique pourquoi un contrat « du consommateur » est plus précis que le schéma complet du fournisseur.
✅ Pistes de correction
CONTRAT_AFFICHAGE = {"code": "str", "titre": "str"} # ce dont le consommateur dépend, ni plus ni moins
def verifier_fournisseur(contrat, reponse):
problemes = []
for champ, type_attendu in contrat.items():
if champ not in reponse:
problemes.append(f"manque {champ}")
elif type(reponse[champ]).__name__ != type_attendu:
problemes.append(f"{champ} : {type(reponse[champ]).__name__} au lieu de {type_attendu}")
return problemes
class AffichageCours:
def ligne(self, reponse):
return f"{reponse['code']} — {reponse['titre']}"
A = {"code": "HEF-010", "titre": "Algorithmes", "places": 20}
B = {"code": "HEF-010", "intitule": "Algorithmes", "places": }
C = {: , : , : }
verifier_fournisseur(CONTRAT_AFFICHAGE, A) == []
verifier_fournisseur(CONTRAT_AFFICHAGE, B) == []
verifier_fournisseur(CONTRAT_AFFICHAGE, C) == []
AffichageCours().ligne(A) ==
()
⚠️ Pièges classiques
| Piège | Pourquoi c'est un problème | Comment l'éviter |
|---|---|---|
| Tester seulement le cas heureux (200) | Les erreurs sont aussi le contrat | Tester 400, 401/403, 404, 409 avec leur format |
| Tester l'API en production | Données réelles modifiées | Serveur de test avec données fabriquées |
| Renommer ou retirer un champ « sans impact » | Les clients sont cassés | Compatibilité ascendante, versionnement, test de contrat |
| Ignorer le format des erreurs | Les clients ne peuvent pas les traiter | Un format d'erreur unique et testé |
🐉 Mini-boss (40 XP)
Contrat et tests de l'API de HashBox. Implémente (avec http.server) une API de membres : GET /membres/<id>, POST /membres, PUT /membres/<id> (idempotent), DELETE /membres/<id>, avec authentification par jeton (Authorization: Bearer …).
- écris le contrat (schémas de requêtes/réponses, codes d'erreur, format unique d'erreur) ;
- écris 15+ tests d'API : statuts, en-têtes, corps, erreurs, idempotence du
PUT, authentification manquante/incorrecte (401), droits (403) ; - écris le test de non-régression de contrat (
comparer_contratssur les schémas versionnés) ; - écris un contrat de consommateur pour une application mobile ;
- simule 3 évolutions (ajout de champ, renommage, ajout d'un champ obligatoire dans la requête) et classe-les.
✅ Pistes de correction
Un bon travail : serveur lancé en setUpClass sur un port libre, client urllib, assertions précises sur statut + en-têtes + corps ; PUT répété deux fois donne la même réponse ; 401 sans jeton, 403 avec un jeton sans droit ; format d'erreur uniforme {"erreur": "…"}. Évolutions : ajout d'un champ de réponse = compatible ; renommage = cassant ; champ obligatoire de requête = cassant. Le contrat de consommateur ne contient que les champs réellement lus par l'application mobile.
⚡ Quiz éclair (15 XP si 4/5 ou plus)
1. Un changement compatible d'une API est :
- A. le renommage d'un champ de réponse
- B. le changement du type d'un champ
- C. l'ajout d'un champ optionnel dans la réponse
2. Le port 0 pour un serveur de test signifie :
- A. le système choisit un port libre
- B. aucun port
- C. le port de production
3. Un test de contrat côté consommateur :
- A. remplace tous les tests
- B. déclare ce dont le client dépend et le fait vérifier par le fournisseur
- C. teste la vitesse du réseau
4. 🔁 Révision mission 04 : Un test d'intégration vérifie surtout :
- A. la vitesse du processeur
- B. l'orthographe des messages
- C. que des composants réels fonctionnent ensemble
5. 🔁 Révision mission 04 : Pour isoler les tests de base de données, on peut :
- A. créer une base neuve (ou annuler la transaction) pour chaque test
- B. partager une seule base entre tous les tests
- C. tester en production
✅ Réponses
- C.
- A.
- B.
- C.
- A.
🪞 Je réfléchis (10 XP)
- Quelle API (interne ou externe) utilises-tu dont un changement silencieux te casserait ?
- Pourquoi vaut-il mieux que le consommateur déclare son contrat plutôt que le fournisseur devine ses clients ?
🎒 À retenir
- Tester une API : statut, en-têtes, corps, erreurs, idempotence, sécurité.
- Serveur local sur port éphémère dans un thread.
- Contrat = schéma vérifiable automatiquement.
- Ajout optionnel = compatible ; retrait, renommage, changement de type = cassant.
- Test de contrat côté consommateur : qui dépend de quoi.
flowchart LR
T(["Tests API et contrats"])
T --> R1["1. Tester une API : statut, en-têtes, corps, erreurs, idempotence,…"]
T --> R2["2. Serveur local sur port éphémère dans un thread."]
T --> R3["3. Contrat = schéma vérifiable automatiquement."]
T --> R4["4. Ajout optionnel = compatible ; retrait, renommage, changement de type…"]
T --> R5["5. Test de contrat côté consommateur : qui dépend de quoi."]
Description du schéma : la mission au centre, reliée aux cinq idées à retenir.
🏅 Récompenses
Total possible : 100 XP · 🏅 Badge Gardien du contrat
← Mission 04 — Tests d'intégration · Mission 06 — Tests E2E →
HEF-110 — Tests et qualité

