Si vous maintenez un fichier OpenAPI mais que votre service en cours d'exécution s'en écarte lentement, Specmatic est conçu précisément pour combler cette lacune. Il traite votre spécification comme un contrat exécutable, puis teste un service réel par rapport à celle-ci et exécute la même spécification comme un stub intelligent. Ce guide explique ce que fait Specmatic, comment les tests de contrat diffèrent des tests basés sur des exemples, et où l'outil s'intègre, avec une note sur la façon dont il se compare à une approche de plateforme plus large comme le test de contrat d'API d'Apidog. Pour le format de spécification sous-jacent à tout cela, l' OpenAPI Specification est la source de vérité à partir de laquelle Specmatic lit.
Qu'est-ce que Specmatic
Specmatic est un outil open source pour le développement axé sur le contrat. L'idée centrale est simple : votre spécification d'API est le contrat, et Specmatic rend ce contrat exécutable. Pointez-le vers un fichier OpenAPI et il peut effectuer deux tâches complémentaires.
- Exécuter la spécification comme des tests par rapport à un service en direct, vérifiant que le service respecte chaque chemin, code d'état et schéma promis par la spécification.
- Exécuter la spécification comme un serveur de stub, afin que les consommateurs puissent développer contre un mock qui répond exactement comme le dit le contrat.
Les deux tâches lisent le même fichier. Il n'y a pas de "définition de test" et de "spécification" distinctes à maintenir synchronisées, ce qui est tout l'intérêt. Specmatic va également au-delà d'OpenAPI. La version 2.0 a ajouté GraphQL et gRPC, et il prend en charge AsyncAPI pour les contrats d'événements de type Kafka, ainsi que des formats comme WSDL et Avro. Pour la plupart des équipes, cependant, le point d'entrée est un simple fichier OpenAPI YAML ou JSON.
Vous l'exécutez depuis la ligne de commande ou une image Docker, de sorte qu'il s'intègre dans CI sans trop de cérémonie. L'entreprise derrière l'outil propose des modules complémentaires commerciaux, mais le moteur de contrat lui-même est gratuit et open source.
Test de contrat vs test basé sur des exemples
C'est la distinction qui embrouille la plupart des gens, il est donc utile d'être précis.
Le test basé sur des exemples est ce que vous faites avec la plupart des clients API. Vous écrivez une requête, vous vérifiez la réponse que vous avez reçue, peut-être vérifiez-vous un code d'état et un ou deux champs. Chaque test est un exemple écrit à la main. Si votre spécification a 40 points de terminaison, vous écrivez et maintenez beaucoup d'exemples, et les lacunes sont faciles à manquer.
Le test de contrat inverse le modèle. Au lieu de vérifier des exemples spécifiques, vous vérifiez que le service correspond au contrat. Specmatic lit le schéma et en génère des tests. Il vérifie que les réponses sont conformes aux types déclarés, que les champs requis sont présents, que les codes d'état correspondent, et que le service rejette les requêtes mal formées de la manière que la spécification implique. Vous n'écrivez pas les assertions une par une. La spécification est l'assertion.
| Aspect | Test basé sur des exemples | Test de contrat avec Specmatic |
|---|---|---|
| Source de vérité | Cas de test écrits à la main | La spécification OpenAPI elle-même |
| Ce que vous maintenez | Chaque requête et assertion | La spécification, que vous conservez de toute façon |
| Couverture | Seulement ce que vous avez pensé à écrire | Chaque opération déclarée par la spécification |
| Détection de dérive | Manuelle | Automatique lorsque la spécification change |
| Échec typique | Un exemple spécifique a échoué | Le service ne correspond plus au contrat |
Il y a un deuxième axe à nommer. Le test de contrat se présente sous différentes formes, et Specmatic se situe dans une forme spécifique. Le test de contrat axé sur le consommateur de style Pact fait que les consommateurs publient leurs attentes à un courtier, et les fournisseurs vérifient par rapport à celles-ci. Specmatic, lui, effectue des tests axés sur le contrat : la spécification est le contrat unique que les deux parties acceptent, et Specmatic valide le fournisseur par rapport à celle-ci et "stubbe" le fournisseur pour les consommateurs. Ce n'est pas un courtier Pact, et il ne gère pas les pactes publiés par les consommateurs. Si vous voulez une vue d'ensemble plus large, consultez cette présentation des outils de test de contrat et de mocking d'API.
Comment Specmatic fonctionne
Vous pouvez installer la CLI directement ou récupérer l'image Docker. Docker est le choix courant en CI car il évite la configuration locale du runtime.
Exécution des tests de contrat
La commande de test pointe Specmatic vers une spécification et un service en cours d'exécution. Une exécution locale minimale ressemble à ceci :
# CLI native
specmatic test api.yaml --testBaseURL=http://localhost:8080
# Docker
docker run -v "$(pwd):/usr/src/app" specmatic/specmatic \
test api.yaml --testBaseURL=http://host.docker.internal:8080
Specmatic lit api.yaml, génère des requêtes pour les opérations qu'il décrit, les envoie à l'URL de base et valide chaque réponse par rapport au schéma. Un test échoué signifie que le service et le contrat sont en désaccord. Vous réparez l'un ou l'autre. C'est le cycle.
Exécution de la spécification comme un stub
Le serveur de stub est l'autre moitié. Démarrez-le et Specmatic sert des réponses qui correspondent au contrat, de sorte qu'un frontal ou un service en aval peut se construire contre lui avant que le vrai backend n'existe.
specmatic stub api.yaml --port=9000
Par défaut, il génère des réponses valides par rapport au schéma à la volée. Vous pouvez également enregistrer des exemples concrets dans un répertoire _examples à côté de la spécification, et le stub renverra ceux-ci lorsqu'une requête correspondra. Cela vous donne des données réalistes et contrôlables sans avoir à monter un vrai backend. Si vous comparez les options de stub et de mock entre les outils, le résumé des serveurs de test de contrat et de mock replace Specmatic dans son contexte.
Specmatic peut également vous aider à créer la spécification en premier lieu. Il peut fonctionner comme un proxy devant un service existant, capturer le trafic réel et générer un document OpenAPI ainsi que des fichiers d'exemple à partir de ce qu'il voit. C'est pratique lorsque vous avez un service mais pas encore de spécification.
Le modèle de spécification en tant que contrat et stub
Voici pourquoi exécuter un seul fichier à la fois comme test et comme stub est important. Lorsque la spécification est le contrat, le côté test et le côté stub ne peuvent jamais être en désaccord, car ils lisent le même document.
- L'équipe du fournisseur exécute
specmatic testen CI. Si elle modifie l'API sans mettre à jour la spécification, les tests de contrat échouent. - L'équipe du consommateur exécute
specmatic stublocalement. Elle développe contre des réponses qui sont garanties de correspondre au même contrat.
La spécification devient ainsi un accord dynamique, et non un document obsolète auquel personne ne fait confiance. C'est la différence entre un stub et un mock plus riche, et il est utile de comprendre les idées sous-jacentes du stubbing vs mocking d'API avant de concevoir un workflow autour de cela.
Specmatic ajoute également une vérification de la compatibilité ascendante. La commande `backward-compatibility-check` démarre un stub à partir de la nouvelle version d'une spécification, génère des tests à partir de la version précédente et les exécute sur le nouveau stub. Si quelque chose qui fonctionnait auparavant ne fonctionne plus, vous le savez avant de déployer. C'est une solide garantie pour les microservices qui se déploient indépendamment, et c'est une variante de l'idée plus large couverte par le test de contrat bidirectionnel.
Où Specmatic s'intègre
Specmatic trouve sa place lorsque les conditions suivantes sont vraies pour votre équipe :
- Votre spécification OpenAPI (ou AsyncAPI, GraphQL, gRPC) est réelle et raisonnablement complète.
- Vous avez des équipes ou des services fournisseurs et consommateurs distincts qui doivent rester synchronisés.
- Vous voulez que la dérive de spécification fasse échouer une build automatiquement, et non qu'elle soit détectée lors d'une révision.
- Vous êtes à l'aise avec un flux de travail axé sur la CLI et la CI.
Il est moins adapté si vous ne tenez pas de spécification, si vous voulez un espace de travail visuel pour concevoir et explorer des API, ou si vous voulez un seul outil pour gérer également le débogage ad-hoc, la documentation et la collaboration d'équipe. Specmatic se concentre sur le moteur de contrat, et il fait bien ce seul travail.
Cette focalisation est aussi ce qui donne une forme différente à une plateforme comme Apidog. Apidog est également axé sur le schéma : il lit votre spécification OpenAPI, valide les réponses par rapport au schéma et lance un serveur de maquette à partir de votre schéma OpenAPI sans code. La différence honnête est la portée. Specmatic est un outil de contrat précis, natif de la CLI. Apidog regroupe la conception, les tests, le mocking et la documentation dans un seul espace de travail avec un éditeur visuel, de sorte que la spécification, les tests et la maquette vivent ensemble et restent synchronisés pendant que vous travaillez. Apidog n'est pas non plus un courtier de contrats axé sur le consommateur de style Pact, donc si votre équipe a spécifiquement besoin d'un courtier Pact, aucun des deux outils n'est celui-là.
Si vous souhaitez générer des tests exécutables directement à partir d'une spécification au sein de ce type d'espace de travail, découvrez comment Apidog gère la génération de collections de tests d'API à partir de spécifications OpenAPI.
Foire aux questions
Specmatic est-il gratuit ?
Oui. Le moteur de contrat principal est open source et gratuit à utiliser depuis la CLI ou Docker. Il existe des offres commerciales autour de lui, mais vous pouvez exécuter des tests de contrat et des serveurs de stub à partir de spécifications OpenAPI sans payer. Consultez le site officiel et GitHub pour les détails actuels sur les niveaux payants.
Specmatic fonctionne-t-il uniquement avec OpenAPI ?
Non. OpenAPI est le point d'entrée le plus courant, mais Specmatic prend également en charge AsyncAPI pour les contrats événementiels, ainsi que GraphQL et gRPC depuis la version 2.0, et des formats comme WSDL et Avro. Le modèle est le même pour tous : la spécification est le contrat exécutable. Si vous êtes nouveau sur le format lui-même, commencez par ce tutoriel sur la spécification OpenAPI.
Specmatic est-il identique à Pact ?
Pas tout à fait. Pact est axé sur le consommateur : les consommateurs publient leurs attentes à un courtier et les fournisseurs les vérifient. Specmatic est axé sur le contrat : la spécification est le contrat partagé unique, et Specmatic valide le fournisseur par rapport à celle-ci tout en créant des stubs pour le fournisseur pour les consommateurs. Les deux réduisent les surprises d'intégration, mais ils organisent le contrat différemment.
Specmatic peut-il générer une spécification OpenAPI pour moi ?
Oui. Specmatic peut fonctionner comme un proxy devant un service existant, capturer le trafic réel des requêtes et des réponses, et générer un document OpenAPI ainsi que des fichiers d'exemple à partir de celui-ci. C'est utile lorsque vous avez un service fonctionnel mais pas encore de spécification formelle à tester.
Conclusion
Specmatic répond à un problème spécifique et réel : maintenir un service en fonctionnement honnête par rapport à la spécification OpenAPI qu'il est censé suivre. En rendant la spécification exécutable, il vous fournit des tests de contrat et un stub correspondant à partir d'un seul fichier, avec des vérifications de compatibilité ascendante en prime. Si vous travaillez dans le terminal et la CI et que vous maintenez une spécification solide, c'est un excellent choix.
Si vous préférez avoir le contrat, les tests, le mock et la documentation dans un seul espace de travail visuel qui lit le même fichier OpenAPI, essayez Apidog. Il valide les réponses par rapport à votre schéma, simule des points de terminaison sans code et transforme les spécifications en collections de tests exécutables. Téléchargez Apidog pour le pointer vers votre spécification et voir le cycle complet de la conception au test en un seul endroit.