Qu'est-ce que Specmatic ?

Si vous maintenez un fichier OpenAPI mais que votre service en production s’en écarte progressivement, Specmatic sert à transformer cette spécification en contrat exécutable. Il teste un service réel par rapport à ce contrat et peut exécuter la même spécification comme serveur de stub. Dans ce guide, vous allez voir comment l’utiliser concrètement, où il s’intègre dans un workflow CI, et comment cette approche se compare à une plateforme plus large comme le test de contrat d’API d’Apidog. Le format de référence reste l’OpenAPI Specification, que Specmatic lit comme source de vérité.

Essayez Apidog aujourd’hui

Qu’est-ce que Specmatic ?

Specmatic est un outil open source pour le développement orienté contrat. Son principe : votre spécification d’API devient le contrat, et ce contrat devient exécutable.

Avec un fichier OpenAPI, Specmatic peut faire deux choses principales :

• exécuter la spécification comme une suite de tests contre un service réel ;
• exécuter la spécification comme un serveur de stub pour les consommateurs.

Concrètement, le même fichier api.yaml peut servir à vérifier que votre backend respecte les chemins, codes HTTP et schémas déclarés, puis à fournir un mock contractuel à une équipe frontend ou à un autre service.

Specmatic ne se limite pas à OpenAPI. Il prend aussi en charge GraphQL et gRPC depuis la version 2.0, AsyncAPI pour les contrats événementiels de type Kafka, ainsi que des formats comme WSDL et Avro. Pour la plupart des équipes REST, le point d’entrée reste cependant un fichier OpenAPI YAML ou JSON.

Vous pouvez l’exécuter via la CLI ou Docker, ce qui le rend simple à intégrer dans une pipeline CI. Le moteur de contrat est gratuit et open source, avec des offres commerciales autour de l’outil.

Test de contrat vs test basé sur des exemples

La différence est importante avant d’intégrer Specmatic dans votre workflow.

Un test basé sur des exemples vérifie des cas précis écrits à la main :

GET /users/123
# attendre 200
# vérifier response.name
# vérifier response.email

Chaque requête, chaque assertion et chaque jeu de données doivent être maintenus. Si votre API contient 40 endpoints, vous devez décider vous-même quels cas écrire, et les trous de couverture sont faciles à manquer.

Le test de contrat inverse cette logique. La spécification devient l’assertion. Specmatic lit les opérations, paramètres, statuts et schémas déclarés dans OpenAPI, puis génère des tests à partir de ce contrat.

Il vérifie notamment que :

• les routes déclarées existent ;
• les codes HTTP retournés correspondent à la spécification ;
• les champs requis sont présents ;
• les types de données respectent le schéma ;
• les requêtes invalides sont rejetées conformément au contrat.

Aspect	Test basé sur des exemples	Test de contrat avec Specmatic
Source de vérité	Cas de test écrits à la main	Spécification OpenAPI
Ce que vous maintenez	Requêtes et assertions	La spécification
Couverture	Seulement les cas écrits	Les opérations déclarées
Détection de dérive	Manuelle	Automatique
Échec typique	Un exemple spécifique échoue	Le service ne respecte plus le contrat

Il faut aussi distinguer Specmatic de Pact. Le test de contrat orienté consommateur, comme avec Pact, repose sur des consommateurs qui publient leurs attentes dans un broker, puis sur des fournisseurs qui les vérifient.

Specmatic suit une approche orientée contrat : la spécification partagée est le contrat unique. Il ne joue pas le rôle d’un Pact Broker et ne gère pas des pactes publiés par les consommateurs. Pour comparer plusieurs approches, consultez aussi cette vue d’ensemble des outils de test de contrat et de mocking d’API.

Installer et lancer Specmatic

Vous pouvez utiliser la CLI native ou Docker.

En local, la CLI est pratique pour itérer rapidement. En CI, Docker évite d’installer un runtime spécifique sur l’agent de build.

Exemple de structure minimale :

project/
├── api.yaml
├── src/
└── .github/
    └── workflows/
        └── contract-tests.yml

Votre fichier api.yaml est la source de vérité. C’est ce fichier que Specmatic utilisera pour les tests et pour le stub.

Exécuter des tests de contrat

La commande de base consiste à pointer Specmatic vers :

1. votre spécification OpenAPI ;
2. l’URL du service en cours d’exécution.

Avec la CLI

specmatic test api.yaml --testBaseURL=http://localhost:8080

Avec 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 déclarées, les envoie au service, puis valide les réponses.

Un échec signifie que le service et le contrat divergent. Vous devez alors corriger :

• soit le code du service ;
• soit la spécification, si le contrat attendu a réellement changé.

Le point clé : la divergence devient visible automatiquement, au lieu d’être découverte plus tard par une équipe consommatrice.

Ajouter Specmatic à une pipeline CI

Un workflow typique ressemble à ceci :

1. démarrer l’application ;
2. attendre qu’elle soit disponible ;
3. lancer specmatic test ;
4. faire échouer la build si le contrat n’est pas respecté.

Exemple GitHub Actions simplifié :

name: Contract tests

on:
  pull_request:
  push:
    branches:
      - main

jobs:
  specmatic:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Start API
        run: |
          docker compose up -d
          sleep 10

      - name: Run Specmatic contract tests
        run: |
          docker run -v "${{ github.workspace }}:/usr/src/app" specmatic/specmatic \
            test api.yaml --testBaseURL=http://host.docker.internal:8080

Adaptez docker compose up et --testBaseURL à votre environnement. L’objectif est de faire échouer chaque pull request qui modifie le comportement de l’API sans mettre à jour le contrat.

Exécuter la spécification comme serveur de stub

Specmatic peut aussi servir des réponses conformes à la spécification. C’est utile quand un consommateur doit développer sans attendre que le backend soit terminé.

Commande minimale :

specmatic stub api.yaml --port=9000

Votre API simulée est alors disponible sur le port 9000.

Par défaut, Specmatic génère des réponses valides par rapport au schéma. Vous pouvez également fournir des exemples concrets dans un répertoire _examples à côté de la spécification. Le stub retournera ces réponses lorsqu’une requête correspondra.

Exemple de structure :

project/
├── api.yaml
└── _examples/
    └── users_get_200.json

Cette approche permet de donner aux consommateurs des données réalistes sans démarrer le backend réel.

Si vous comparez les options de stub et de mock entre plusieurs outils, ce résumé des serveurs de test de contrat et de mock replace Specmatic dans son contexte.

Générer une spécification à partir d’un service existant

Specmatic peut aussi aider quand vous avez déjà un service, mais pas encore de fichier OpenAPI fiable.

Il peut fonctionner comme proxy devant le service, capturer le trafic réel, puis générer :

• un document OpenAPI ;
• des fichiers d’exemple basés sur les requêtes et réponses observées.

Cette approche est utile pour initialiser un contrat à partir d’un système existant. Elle ne remplace pas une revue de la spécification, mais elle accélère la création d’un premier contrat testable.

Utiliser un seul fichier pour les tests et les stubs

L’intérêt principal de Specmatic est de faire lire le même fichier aux deux côtés du workflow :

• le fournisseur exécute specmatic test en CI ;
• le consommateur exécute specmatic stub localement.

Ainsi, les tests et les stubs ne peuvent pas diverger, car ils utilisent le même contrat.

Workflow recommandé :

1. Modifier api.yaml
2. Lancer le stub pour les consommateurs
3. Implémenter ou modifier le backend
4. Exécuter specmatic test
5. Bloquer la PR si le service ne respecte pas api.yaml

La spécification devient alors un contrat vivant, pas un document statique que personne ne consulte. Avant de concevoir ce workflow, il est aussi utile de comprendre les différences entre stubbing vs mocking d’API.

Vérifier la compatibilité ascendante

Specmatic propose aussi une vérification de compatibilité ascendante avec la commande backward-compatibility-check.

Le principe :

1. Specmatic démarre un stub à partir de la nouvelle version de la spécification ;
2. il génère des tests depuis l’ancienne version ;
3. il exécute ces tests contre le nouveau stub.

Si une opération qui fonctionnait auparavant ne fonctionne plus, vous le voyez avant de déployer.

C’est particulièrement utile dans une architecture microservices, où les services fournisseurs et consommateurs ne sont pas toujours déployés en même temps. Cette logique rejoint l’idée plus large du test de contrat bidirectionnel.

Où Specmatic s’intègre bien

Specmatic est pertinent si votre équipe remplit ces conditions :

• vous maintenez une spécification OpenAPI, AsyncAPI, GraphQL ou gRPC ;
• votre spécification est suffisamment complète pour servir de contrat ;
• vous avez des fournisseurs et des consommateurs à synchroniser ;
• vous voulez détecter la dérive d’API en CI ;
• vous êtes à l’aise avec un workflow CLI et pipeline.

Il est moins adapté si :

• vous ne maintenez pas encore de spécification ;
• vous cherchez d’abord un espace visuel pour concevoir des API ;
• vous voulez un outil unique pour conception, debug, tests, mocks, documentation et collaboration.

Specmatic se concentre sur le moteur de contrat. Il fait ce travail de manière ciblée.

Specmatic et Apidog : différence de portée

Apidog suit aussi une approche centrée sur le schéma : il lit une 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 principale est la portée :

• Specmatic est un outil de contrat précis, orienté CLI et CI ;
• Apidog regroupe conception, tests, mocking et documentation dans un espace de travail visuel.

Avec Apidog, la spécification, les tests et les mocks restent dans le même environnement pendant le cycle de développement. En revanche, Apidog n’est pas non plus un Pact Broker. Si votre besoin principal est un broker de contrats orienté consommateur au sens Pact, ce n’est pas le rôle de Specmatic ni celui d’Apidog.

Pour générer des tests exécutables directement depuis une spécification dans ce type d’espace de travail, consultez la génération de collections de tests d’API à partir de spécifications OpenAPI.

Checklist d’implémentation

Pour intégrer Specmatic dans un projet existant, vous pouvez suivre cette séquence :

1. Identifiez ou créez votre fichier OpenAPI principal.
2. Vérifiez que les chemins, paramètres, réponses et schémas sont à jour.
3. Lancez votre API localement.
4. Exécutez :

specmatic test api.yaml --testBaseURL=http://localhost:8080

1. Corrigez les écarts entre le service et la spécification.
2. Lancez un stub pour les consommateurs :

specmatic stub api.yaml --port=9000

1. Ajoutez la commande de test à votre pipeline CI.
2. Ajoutez une vérification de compatibilité ascendante si vos services sont consommés par d’autres équipes.

Foire aux questions

Specmatic est-il gratuit ?

Oui. Le moteur de contrat principal est open source et gratuit à utiliser depuis la CLI ou Docker. Des offres commerciales existent autour de l’outil, 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 aussi 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 reste le même : la spécification est le contrat exécutable. Si vous débutez avec le format, commencez par ce tutoriel sur la spécification OpenAPI.

Specmatic est-il identique à Pact ?

Non. Pact est orienté consommateur : les consommateurs publient leurs attentes à un broker, et les fournisseurs les vérifient. Specmatic est orienté contrat : la spécification partagée est le contrat unique, et Specmatic valide le fournisseur par rapport à celle-ci tout en fournissant des stubs aux consommateurs.

Specmatic peut-il générer une spécification OpenAPI ?

Oui. Specmatic peut fonctionner comme proxy devant un service existant, capturer le trafic réel des requêtes et réponses, puis générer un document OpenAPI et des fichiers d’exemple. C’est utile pour créer un premier contrat formel à partir d’un service déjà en fonctionnement.

Conclusion

Specmatic résout un problème précis : vérifier automatiquement qu’un service respecte la spécification OpenAPI qu’il est censé suivre. En rendant la spécification exécutable, il fournit des tests de contrat et un serveur de stub à partir du même fichier, avec une vérification de compatibilité ascendante en complément.

Si votre équipe travaille déjà avec une spécification fiable et une CI, Specmatic est un choix solide pour détecter la dérive d’API tôt.

Si vous préférez gérer le contrat, les tests, les mocks et la documentation dans un 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 endpoints sans code et transforme les spécifications en collections de tests exécutables. Téléchargez Apidog pour tester le cycle complet, de la conception au test.