Si vous avez un schéma OpenAPI ou GraphQL, Schemathesis peut le transformer en des milliers de cas de test sans que vous n'ayez à écrire une seule assertion. Il lit la spécification, génère des entrées variées et valides, les envoie à votre API et signale les endroits où les réponses rompent le contrat. Ce guide explique ce qu'est Schemathesis, comment l'installer et l'exécuter, ce que signifie réellement les tests basés sur les propriétés, et comment il s'intègre à un flux de travail de tests fonctionnels et de tests de contrat dans Apidog.
Qu'est-ce que Schemathesis ?
Schemathesis est un outil Python open-source qui génère automatiquement des tests API à partir d'un schéma. Vous le dirigez vers une définition OpenAPI ou GraphQL, et il construit des cas de test à partir des types, formats et contraintes que vous avez déjà déclarés. Il est construit sur Hypothesis, la bibliothèque de tests basés sur les propriétés pour Python, et il est distribué sous la licence MIT.
L'idée principale est simple. Votre spécification décrit déjà à quoi ressemblent une requête et une réponse valides. Schemathesis traite cette description comme une source de vérité et vérifie si votre API en cours d'exécution la respecte réellement. Lorsque l'API renvoie une erreur 500, envoie une réponse qui viole le schéma déclaré, ou accepte une entrée qu'elle aurait dû rejeter, Schemathesis le signale.
Vous l'exécutez depuis la ligne de commande avec schemathesis run (ou l'alias plus court st run). Il existe également une intégration Python si vous souhaitez l'utiliser via pytest plutôt que l'interface en ligne de commande. La plupart des équipes commencent avec l'interface en ligne de commande car elle ne nécessite presque aucune configuration.
Ce que signifie les tests basés sur les propriétés
La plupart des tests API sont basés sur des exemples. Vous écrivez une requête, vous affirmez une réponse spécifique, et le test passe ou échoue sur ce cas précis. C'est utile, mais vous ne détectez que les bugs pour lesquels vous avez pensé à écrire un test.
Les tests basés sur les propriétés inversent l'approche. Au lieu d'un exemple fixe, vous décrivez une propriété qui devrait toujours être vraie, puis vous laissez l'outil générer des centaines d'entrées pour tenter de la casser. Pour Schemathesis, la propriété est grosso modo : « aucune requête valide ne devrait jamais faire planter le serveur ni produire une réponse qui viole le schéma. »
Schemathesis génère des entrées à partir des contraintes de votre spécification. Si un champ est un entier avec un minimum de 1, il essaiera 1, de grands nombres, des valeurs limites, et les types d'entrées qui déjouent une validation naïve. Lorsqu'un test échoue, Hypothesis réduit l'entrée au cas le plus petit qui reproduit encore le bug, de sorte que vous obteniez une reproduction minimale et lisible au lieu d'une charge utile aléatoire de 4 Ko.
Ceci est différent du monkey testing, qui jette des entrées aléatoires sur une interface pour voir ce qui s'écroule. Les tests basés sur les propriétés sont structurés. Il utilise le schéma pour générer des entrées plausibles et ciblées, et il sait à quoi ressemble un résultat correct parce que la spécification le lui a dit.
Installation et exécution de Schemathesis
Schemathesis est un package Python, vous avez donc besoin de Python 3 et de pip. Installez-le de la manière habituelle :
pip install schemathesis
Vous pouvez également l'exécuter sans installation permanente en utilisant uvx schemathesis si uv est configuré. Une fois installé, la commande de base pointe vers un schéma et une URL de base :
st run http://127.0.0.1:8000/openapi.json
Si votre schéma se trouve sur le disque plutôt que derrière une URL, passez le chemin du fichier et indiquez à Schemathesis où se trouve l'API en direct :
st run ./openapi.yaml --url http://127.0.0.1:8000
Pour une API authentifiée, ajoutez un en-tête :
st run http://127.0.0.1:8000/openapi.json \
--header 'Authorization: Bearer your-token'
Schemathesis découvre chaque opération de la spécification, génère des cas pour chacune d'elles et affiche un résumé des vérifications réussies et échouées. Les échecs sont accompagnés de la requête exacte qu'il a envoyée, vous pouvez donc les rejouer avec curl ou dans n'importe quel client API. Les noms des drapeaux et les valeurs par défaut changent entre les versions majeures, alors vérifiez st run --help par rapport à votre version installée plutôt que de faire confiance à un extrait de blog, y compris celui-ci.
Ce que Schemathesis détecte
Les vérifications par défaut ciblent l'écart entre ce que votre spécification promet et ce que votre serveur fait. Voici ce qui a tendance à remonter à la surface.
| Problème | À quoi cela ressemble |
|---|---|
| Erreurs serveur | Une requête déclenche une erreur 500 au lieu d'une erreur 4xx gérée ou d'une réponse valide |
| Violations de schéma | Le corps de la réponse ne correspond pas au schéma que vous avez déclaré pour ce code de statut |
| Incohérences de code de statut | L'API renvoie un code de statut que la spécification n'a jamais documenté |
| Dérive du Content-type | Le type de contenu de la réponse ne correspond pas à ce que la spécification annonce |
| Bugs d'état | Une opération fonctionne seule mais échoue dans un flux de travail réaliste en plusieurs étapes |
Ce dernier point mérite un examen plus approfondi. Schemathesis peut exécuter des tests d'état, où il enchaîne les opérations en se basant sur les liens dans votre spécification, par exemple créer une ressource, puis la récupérer, puis la supprimer. Les bugs qui n'apparaissent qu'en séquence, comme une ressource qui signale un état incorrect après une mise à jour, sont difficiles à trouver avec des tests à requête unique. La phase d'état pilote ces séquences comme une machine à états.
Vous pouvez étendre le comportement par défaut avec des hooks. Les hooks sont des fonctions Python qui vous permettent de personnaliser la génération de données, d'ajouter vos propres vérifications ou de filtrer les opérations à tester. C'est ainsi que les équipes adaptent Schemathesis aux API avec des flux d'authentification ou des contraintes non évidentes que la spécification ne peut pas exprimer.
Quand utiliser Schemathesis
Schemathesis trouve sa place lorsque vous disposez d'une spécification OpenAPI ou GraphQL raisonnablement précise et que vous souhaitez une couverture large et économique des cas limites. Il est performant pour trouver les échecs pour lesquels vous n'écririez jamais de test manuel : entrées non gérées, formes d'erreur non documentées et dérive du contrat entre la spécification et l'implémentation.
Il convient bien lorsque :
- Vous maintenez une spécification OpenAPI et souhaitez qu'elle soit appliquée sur le serveur réel.
- Vous vous inquiétez des erreurs 500 non gérées et souhaitez une couche de fuzzing dans l'intégration continue.
- Votre API a des flux de travail avec état où l'ordre est important.
- Votre équipe travaille déjà en Python et est à l'aise avec
pipetpytest.
Il est moins adapté lorsque votre spécification est mince ou obsolète, car Schemathesis ne peut tester que ce que le schéma décrit. Si l'entrée est mauvaise, la sortie le sera aussi. Il ne remplacera pas non plus vos tests fonctionnels basés sur des exemples. Savoir qu'un endpoint ne plante jamais n'est pas la même chose que savoir qu'il renvoie la bonne valeur pour une entrée connue. Vous voulez les deux.
Schemathesis et Apidog : où chacun s'intègre
Apidog et Schemathesis résolvent des problèmes différents, et ils fonctionnent bien côte à côte. Apidog est une plateforme tout-en-un pour la conception, le débogage, le test, la simulation et la documentation des API. Schemathesis est un fuzzer ciblé basé sur les propriétés. Être honnête sur la limite est important ici.
Apidog ne fait pas de fuzzing basé sur les propriétés. Sa fonctionnalité la plus proche est le monkey testing, qui envoie des entrées aléatoires pour faire apparaître des plantages. C'est utile, mais ce n'est pas la même chose que les tests basés sur les propriétés et pilotés par le schéma. Schemathesis génère des entrées à partir des contraintes de votre spécification et vérifie les réponses par rapport au schéma. Donc, si le fuzzing basé sur les propriétés est ce dont vous avez besoin, optez pour Schemathesis, pas pour Apidog.
Apidog s'intègre au reste du cycle de vie autour de cette passe de fuzzing.
| Étape du workflow | Schemathesis | Apidog |
|---|---|---|
| Fuzzing basé sur les propriétés à partir d'une spécification | Oui, fonctionnalité principale | Non |
| Conception visuelle d'API et édition de spécifications | Non | Oui |
| Tests fonctionnels basés sur des exemples | Limité | Oui, constructeur de tests visuel |
| Tests de contrat par rapport à une spécification | Partiel, via les vérifications de schéma | Oui, flux de travail dédié |
| Serveurs de simulation à partir d'un schéma | Non | Oui, simulation intelligente |
| Exécuteur de tests CI | Oui, st run |
Oui, apidog run |
| Documentation générée automatiquement | Non | Oui |
Un couplage pratique ressemble à ceci. Vous concevez et maintenez la spécification dans Apidog, en générez des cas de test fonctionnels et un serveur de simulation, et les exécutez en CI avec apidog run. Ensuite, vous ajoutez une passe Schemathesis qui effectue un fuzzing de la même spécification pour détecter les plantages de cas limites et les violations de contrat. Les deux couches détectent différentes classes de bugs. Apidog confirme que l'API fait ce qu'il faut pour les cas connus ; Schemathesis recherche les cas inconnus qui la brisent.
Si votre objectif est de transformer une spécification en une suite fonctionnelle exécutable plutôt qu'une exécution de fuzzing, Apidog peut générer directement des collections de tests API à partir de vos spécifications OpenAPI, et vous pouvez télécharger Apidog pour essayer ce flux.
Foire aux questions
Schemathesis est-il gratuit ?
Oui. Schemathesis est open source sous la licence MIT, et l'interface en ligne de commande est gratuite à installer et à exécuter via pip install schemathesis. Il existe également une offre commerciale hébergée pour les équipes qui souhaitent une expérience gérée, mais l'outil principal que vous exécutez localement et en CI ne coûte rien.
Quelle est la différence entre schemathesis run et st run ?
Ce sont les mêmes commandes. st est un alias court pour schemathesis, donc st run et schemathesis run font exactement la même chose. Utilisez celui que vous préférez. Les deux acceptent un chemin de schéma ou une URL, ainsi que des options comme --url et --header.
Schemathesis peut-il remplacer mes tests API fonctionnels ?
Non, et ce n'est pas son but. Schemathesis vérifie que votre API ne plante pas et que les réponses correspondent au schéma. Il ne vérifie pas la logique métier, par exemple si un calcul de remise est correct. Vous avez toujours besoin de tests fonctionnels basés sur des exemples et de tests de contrat pour cela, que vous pouvez construire et exécuter dans Apidog. Considérez Schemathesis comme une couche de fuzzing supplémentaire, et non comme un remplacement.
Schemathesis fonctionne-t-il avec GraphQL ?
Oui. Schemathesis prend en charge les schémas OpenAPI et GraphQL. Pour GraphQL, il génère des requêtes à partir des définitions de types du schéma et vérifie les réponses de la même manière qu'il le fait pour les API REST définies en OpenAPI.
Conclusion
Schemathesis est un outil précis pour une tâche : prendre votre spécification OpenAPI ou GraphQL et soumettre votre API en direct à des tests de stress basés sur la génération de propriétés. Il trouve les plantages et les violations de contrat que les tests basés sur des exemples manquent, et ne coûte presque rien à ajouter à l'intégration continue. Ce qu'il ne fait pas, c'est concevoir, simuler, documenter ou vérifier la logique métier.
C'est là qu'Apidog le complète. Concevez la spécification, générez des tests fonctionnels et des simulations, exécutez-les en CI avec apidog run, et documentez le résultat, le tout en un seul endroit, puis superposez Schemathesis pour le fuzzing. Téléchargez Apidog pour construire le côté conception et fonctionnel de ce flux de travail, et laissez Schemathesis gérer la chasse aux cas limites.