Tests de contrat : mythe, réalité et pièges
Cet article est le troisième d’une série dédiée aux test d’API.
Les autres articles exploreront les thèmes suivant :
- Tester une API, ce n’est pas faire que du Postman
- Que tester dans une API ?
- Concevoir une stratégie de test d'API efficace
Les tests de contrat sont probablement le sujet le plus mal compris du test d'API. Tout le monde en parle, beaucoup prétendent les pratiquer, mais peu les maîtrisent vraiment. Pire, nombreux sont ceux qui pensent faire des tests de contrat alors qu'ils font quelque chose de complètement différent.
Si vous avez déjà entendu "j'ai ajouté une validation de schéma JSON, donc mes tests de contrat sont en place", cet article va clarifier les choses. Non, valider un schéma n'est pas faire du contract testing. Et oui, il existe des situations où les tests de contrat font plus de mal que de bien.
Qu'est-ce vraiment qu'un contrat API ?
Avant de parler de tests, parlons d'abord de ce qu'est un contrat API. Un contrat est un accord explicite entre deux parties : le producteur (celui qui expose l'API) et le consommateur (celui qui l'utilise). Ce contrat définit précisément ce que le producteur promet de fournir et ce que le consommateur s'attend à recevoir.
Concrètement, un contrat spécifie la structure des requêtes et réponses, les types de données, les champs obligatoires et optionnels, les codes de statut HTTP possibles, et les règles de validation. Mais il va au-delà de la simple structure. Il inclut aussi les comportements attendus et les garanties sémantiques.
L'idée fondamentale est simple : si le producteur respecte le contrat, le consommateur doit pouvoir fonctionner sans problème. C'est une promesse mutuelle qui permet aux équipes de travailler en parallèle sans coordination constante.
Mais voilà où ça se complique : un contrat n'est pas une documentation. La documentation Swagger ou OpenAPI décrit ce que votre API fait, mais ne garantit pas que l'implémentation respecte cette description. Un contrat, lui, est testé et vérifié automatiquement.
Validation de schéma : nécessaire mais insuffisant
C'est ici que survient la première grande confusion. Beaucoup d'équipes implémentent une validation de schéma JSON et pensent avoir mis en place des tests de contrat. Ce n’est pas suffisent pour du contract testing.
La validation de schéma vérifie que la structure d'une réponse correspond à un format défini. Elle s'assure qu'un champ "userId" est bien de type string, qu'un champ "price" est un nombre, et que tous les champs obligatoires sont présents. C'est essentiel, mais ce n'est qu'une partie du puzzle.
Le contract testing va plus loin. Il vérifie non seulement la structure, mais aussi que le producteur et le consommateur ont la même compréhension du contrat. Il teste les interactions réelles, valide que les changements du producteur ne cassent pas les consommateurs, et garantit l'alignement des attentes.
Exemple concret : votre API retourne un champ "status" qui peut valoir "pending", "completed" ou "failed". La validation de schéma vérifie que c'est une chaîne de caractères. Le contract testing vérifie que le consommateur gère correctement ces trois valeurs et que le producteur ne va pas soudainement ajouter "processing" sans prévenir.
La validation de schéma est un outil technique qui détecte les malformations. Le contract testing est une approche collaborative qui garantit que les services peuvent travailler ensemble. L'un n'est pas un substitut de l'autre.
Producer-driven vs Consumer-driven : deux philosophies opposées
Maintenant que nous avons clarifié ce qu'est un contrat, parlons de qui le définit. Il existe deux approches fondamentalement différentes : les contrats pilotés par le producteur et les contrats pilotés par le consommateur.
Dans l'approche producer-driven, c'est le producteur de l'API qui définit le contrat. Il décide de la structure des réponses, des champs disponibles, et des règles. Les consommateurs doivent s'adapter. C'est l'approche traditionnelle avec OpenAPI ou Swagger. Simple à mettre en place, le producteur garde le contrôle total. Mais elle ne garantit pas que l'API répond réellement aux besoins des consommateurs.
L'approche consumer-driven inverse cette dynamique. Ce sont les consommateurs qui définissent leurs attentes sous forme de contrats, et le producteur doit les respecter. Chaque consommateur spécifie exactement ce dont il a besoin. Le producteur vérifie qu'il satisfait tous ces contrats avant de déployer.
Consumer-Driven Contract Testing, popularisé par Pact, est puissant dans les architectures microservices. Imaginez un service utilisateur consommé par trois services : web, mobile, et notification. Chacun crée un contrat décrivant ses besoins. Le service utilisateur exécute ces trois contrats à chaque changement, garantissant qu'il ne casse aucun consommateur.
L'avantage majeur ? Le producteur sait immédiatement si un changement va casser un consommateur, avant même de déployer. Les contrats agissent comme un filet de sécurité automatisé.
Pact : le standard du consumer-driven contract testing
Quand on parle de consumer-driven contract testing, impossible de ne pas mentionner Pact. C'est devenu le standard de facto dans ce domaine, et pour de bonnes raisons. Comprendre comment Pact fonctionne vous donnera une idée concrète de ce qu'est vraiment le contract testing en pratique.
Le principe de Pact est élégant. Le consommateur définit ses attentes en écrivant des tests qui décrivent exactement les requêtes qu'il va faire et les réponses qu'il attend. Ces tests génèrent un fichier de contrat au format JSON. Ce fichier est ensuite partagé avec le producteur, qui doit prouver qu'il peut satisfaire ces attentes en exécutant le contrat contre son API réelle.
Concrètement, côté consommateur, vous écrivez un test qui dit : "Quand je fais un GET sur /users/123, j'attends un 200 avec un objet contenant userId, name et email". Pact enregistre cette interaction dans un fichier de contrat. Côté producteur, vous exécutez ce contrat : Pact fait réellement l'appel GET /users/123 sur votre API et vérifie que la réponse correspond aux attentes du consommateur.
La vraie force de Pact, c'est le Pact Broker. C'est un serveur central où tous les contrats sont publiés et versionnés. Chaque fois qu'un consommateur modifie ses attentes, il publie un nouveau contrat. Chaque fois qu'un producteur se déploie, il vérifie tous les contrats de ses consommateurs. Si un contrat échoue, le déploiement est bloqué. C'est cette boucle de feedback automatique qui change tout.
Pact n'est pas une solution miracle et demande un investissement initial important : il faut former les équipes, mettre en place le Broker, adapter les processus de développement. Mais dans un environnement microservices mature avec de nombreuses équipes, cet investissement est rapidement rentabilisé par la réduction drastique des bugs d'incompatibilité entre services.
Où les tests de contrat brillent vraiment
Les tests de contrat ne sont pas une solution universelle, mais dans certains contextes, ils sont brillants.
Premier contexte : les architectures microservices avec multiples équipes. Quand vous avez quinze services développés par dix équipes différentes, les tests de contrat créent une documentation vivante et vérifiable.
Deuxième contexte : les API publiques avec nombreux consommateurs externes. Les tests de contrat vous donnent une visibilité sur ce que vos clients utilisent réellement.
Troisième contexte : les environnements avec déploiements fréquents. Les tests automatisés dans votre CI/CD donnent un feedback immédiat sur les incompatibilités.
Les tests de contrat excellent dans la détection précoce des régressions, vous permettant de découvrir les problèmes au commit plutôt qu'en production.
Quand les tests de contrat deviennent contre-productifs
Maintenant, parlons des situations où les tests de contrat peuvent faire plus de mal que de bien.
Premier piège : la sur-spécification. Quand les contrats deviennent trop rigides, ils empêchent toute évolution. Chaque changement mineur nécessite une mise à jour coordonnée.
Deuxième piège : la maintenance excessive. Dans une petite équipe avec deux ou trois services simples, le coût peut dépasser les bénéfices.
Troisième piège : le faux sentiment de sécurité. Les contrats vérifient la compatibilité des interfaces, pas la logique métier. Un contrat peut passer au vert alors que votre système est cassé fonctionnellement.
Quatrième piège : l'implémentation incorrecte. Si vos tests ne vérifient pas les deux côtés du contrat, vous ratez le point essentiel.
Les tests de contrat sont aussi contre-productifs quand les APIs changent très rarement. Si votre API est stable depuis trois ans, investir dans une infrastructure élaborée est probablement inutile.
Un cas réel qui fait réfléchir
Laissez-moi vous raconter un cas réel qui illustre les limites des tests de contrat mal compris.
Une équipe avait des "tests de contrat" pour leur API de commandes. Le contrat spécifiait qu'un champ "total" devait être un nombre décimal avec deux chiffres après la virgule. Les tests vérifiaient ce format.
L'équipe backend décide d'optimiser en arrondissant certains calculs internes. Le champ "total" respectait toujours le contrat. Déploiement en production.
Problème : l'application mobile comparait le total calculé côté client avec le total reçu de l'API. Avec les arrondis différents, les totaux ne matchaient plus. Message "Montant invalide" à chaque commande. Désastre.
Le contrat vérifiait le format, mais pas le comportement sémantique. Il ne capturait pas l'attente implicite : "le total que tu me donnes doit correspondre à ce que je calcule". Un consumer-driven contract aurait pu capturer cette garantie si le consommateur l'avait exprimée.
Alors, faut-il faire des tests de contrat ?
La réponse est : ça dépend. Les tests de contrat sont puissants mais pas universels. Si vous avez une architecture microservices avec plusieurs équipes et des déploiements fréquents, ils apportent une réelle valeur.
Si vous avez une petite application avec trois services développés par la même équipe, les tests de contrat sont probablement du over-engineering. Des tests d'intégration classiques feront l'affaire.
Commencez simple. Ne tentez pas d'implémenter Pact sur tous vos services dès le premier jour. Commencez par des validations de schéma. Puis, si vous constatez des problèmes d'incompatibilité fréquents, envisagez les tests de contrat pour les interfaces critiques.
Et surtout : les tests de contrat ne remplacent pas les autres types de tests. Ils sont un complément. Vous avez besoin de tests unitaires, d'intégration, et end-to-end. Les contrats vous protègent contre l'incompatibilité d'interface entre services.
Démystifier pour mieux utiliser
Les tests de contrat ne sont ni une solution miracle ni une mode passagère. Ce sont un outil spécifique qui répond à des problèmes spécifiques, principalement dans les architectures distribuées.
Retenez ces points : validation de schéma et contract testing ne sont pas la même chose. Consumer-driven contracts offrent plus de garanties mais demandent plus d'effort. Les contrats brillent dans les environnements complexes. Ils peuvent devenir contre-productifs si mal utilisés.
Dans le prochain article de cette série, nous assemblerons tous ces concepts pour concevoir une stratégie de test d'API efficace et adaptée à votre contexte.
FAQ
1) Est-ce que valider OpenAPI / JSON Schema suffit pour dire “on fait du contract testing” ?
Non. Ça valide surtout la structure. Un vrai contract testing vise la compatibilité réelle entre un consumer et un provider, avec des attentes minimales basées sur l’usage.
2) Producer-driven ou consumer-driven : lequel choisir ?
Si tu as plusieurs consumers et une organisation multi-équipes, le consumer-driven apporte souvent plus de signal, parce qu’il encode la dépendance réelle.
3) Est-ce que les tests de contrat remplacent les tests d’intégration / E2E ?
Non. Ils réduisent le risque de casse d’interface, mais ils ne testent pas tous les effets de bord ni la réalité d’un environnement complet.
4) Pourquoi dit-on que “les schémas ne sont pas des contrats” ?
Parce qu’un schéma décrit une forme, mais pas forcément les comportements, la sémantique, ni ce qu’un consumer utilise réellement. On peut rester “valide” et casser quand même.
5) Quel outil devrais-je utiliser pour les tests de contrat ?
Pour le consumer-driven contract testing, Pact est le leader du marché avec une communauté active et des implémentations dans de nombreux langages. Pour le producer-driven, vous pouvez utiliser des outils comme Spring Cloud Contract ou Specmatic. Le choix dépend de votre stack technique et de votre approche (consumer vs producer driven).
6) Comment gérer les changements de contrat ?
Utilisez le versioning sémantique pour vos contrats. Les changements non cassants (ajout de champs optionnels) peuvent être des versions mineures. Les changements cassants nécessitent une nouvelle version majeure. Maintenez plusieurs versions simultanément pendant une période de transition pour permettre aux consommateurs de migrer progressivement.