DEV Community

Cover image for Schemathesis : Tests d'API basés sur les propriétés à partir de votre spécification OpenAPI
Antoine Laurent
Antoine Laurent

Posted on • Originally published at apidog.com

Schemathesis : Tests d'API basés sur les propriétés à partir de votre spécification OpenAPI

Si vous avez un schéma OpenAPI ou GraphQL, Schemathesis peut générer des milliers de cas de test sans écrire une seule assertion manuelle. Il lit votre spécification, produit des entrées valides et variées, les envoie à votre API, puis signale les réponses qui cassent le contrat. Dans ce guide, vous allez installer Schemathesis, l’exécuter sur une API locale ou distante, comprendre les tests basés sur les propriétés, puis l’intégrer à un workflow de tests fonctionnels et de tests de contrat avec Apidog.

Essayez Apidog aujourd’hui

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 OpenAPI ou GraphQL. Il s’appuie sur Hypothesis, la bibliothèque Python de tests basés sur les propriétés, et il est distribué sous licence MIT.

Démo Schemathesis

Le principe est direct : votre spécification décrit déjà les requêtes et réponses attendues. Schemathesis utilise cette spécification comme source de vérité, appelle votre API réelle, puis vérifie si l’implémentation respecte le contrat.

Il peut par exemple détecter :

  • une erreur 500 déclenchée par une entrée valide ;
  • une réponse qui ne correspond pas au schéma déclaré ;
  • un code de statut non documenté ;
  • un Content-Type différent de celui annoncé ;
  • des incohérences dans des scénarios avec état.

Vous pouvez l’utiliser en ligne de commande avec schemathesis run ou son alias court st run. Pour démarrer vite, l’interface CLI est généralement suffisante. Si vous voulez l’intégrer plus finement à vos tests Python, vous pouvez aussi l’utiliser avec pytest.

Comprendre les tests basés sur les propriétés

Les tests API classiques sont souvent basés sur des exemples :

POST /users
Content-Type: application/json

{
  "email": "alice@example.com",
  "age": 30
}
Enter fullscreen mode Exit fullscreen mode

Puis vous vérifiez une réponse attendue :

{
  "id": "usr_123",
  "email": "alice@example.com",
  "age": 30
}
Enter fullscreen mode Exit fullscreen mode

Cette approche est utile, mais elle ne couvre que les cas que vous avez pensés à écrire.

Les tests basés sur les propriétés inversent la logique. Au lieu de définir un seul exemple, vous définissez une propriété qui doit toujours rester vraie. Schemathesis applique cette idée à votre API :

Une requête valide selon le schéma ne doit pas faire planter le serveur ni produire une réponse qui viole le schéma.

À partir de vos contraintes OpenAPI, Schemathesis génère automatiquement des valeurs pertinentes. Par exemple, si votre schéma contient :

type: integer
minimum: 1
maximum: 100
Enter fullscreen mode Exit fullscreen mode

Schemathesis peut tester des valeurs limites comme 1, 100, mais aussi d’autres entrées générées pour exposer les failles de validation.

Lorsqu’un bug est trouvé, Hypothesis réduit le cas d’échec à une entrée minimale qui reproduit encore le problème. Vous obtenez donc une charge utile exploitable, au lieu d’un énorme payload aléatoire difficile à comprendre.

Ce n’est pas du monkey testing. Le monkey testing envoie des entrées aléatoires pour voir ce qui casse. Les tests basés sur les propriétés sont structurés : ils utilisent le schéma pour générer des données ciblées et savent quoi vérifier parce que la spécification définit le contrat attendu.

Installer Schemathesis

Schemathesis est un package Python. Vous avez besoin de Python 3 et de pip.

Installez-le avec :

pip install schemathesis
Enter fullscreen mode Exit fullscreen mode

Vérifiez ensuite que la commande fonctionne :

st --version
Enter fullscreen mode Exit fullscreen mode

Vous pouvez aussi l’exécuter sans installation permanente avec uvx, si uv est déjà configuré :

uvx schemathesis run http://127.0.0.1:8000/openapi.json
Enter fullscreen mode Exit fullscreen mode

Exécuter Schemathesis sur une API

1. Tester une API dont le schéma est exposé par URL

Si votre API expose son schéma OpenAPI à une URL comme /openapi.json, lancez :

st run http://127.0.0.1:8000/openapi.json
Enter fullscreen mode Exit fullscreen mode

Schemathesis va :

  1. charger le schéma ;
  2. découvrir les opérations disponibles ;
  3. générer des requêtes pour chaque opération ;
  4. envoyer les requêtes à l’API ;
  5. valider les réponses ;
  6. afficher les échecs reproductibles.

2. Tester une API avec un fichier OpenAPI local

Si votre fichier se trouve sur votre machine :

st run ./openapi.yaml --url http://127.0.0.1:8000
Enter fullscreen mode Exit fullscreen mode

Ici :

  • ./openapi.yaml est la spécification ;
  • --url indique l’URL de base de l’API réelle à tester.

3. Ajouter un header d’authentification

Pour une API protégée par token :

st run http://127.0.0.1:8000/openapi.json \
  --header 'Authorization: Bearer your-token'
Enter fullscreen mode Exit fullscreen mode

Vous pouvez également ajouter d’autres headers nécessaires à votre environnement :

st run ./openapi.yaml \
  --url https://api.example.com \
  --header 'Authorization: Bearer your-token' \
  --header 'X-Environment: staging'
Enter fullscreen mode Exit fullscreen mode

Les options peuvent varier selon les versions majeures. Avant de figer une commande dans votre CI, vérifiez toujours :

st run --help
Enter fullscreen mode Exit fullscreen mode

Lire un échec Schemathesis

Quand Schemathesis trouve un problème, il affiche la requête qui l’a déclenché. L’objectif est de vous permettre de reproduire rapidement le bug.

Un workflow de tri typique :

  1. copiez la requête générée ;
  2. rejouez-la avec curl, Apidog ou votre client API ;
  3. vérifiez si l’échec vient de l’implémentation ou du schéma ;
  4. corrigez l’API ou la spécification ;
  5. relancez st run.

Exemple de reproduction avec curl :

curl -X POST http://127.0.0.1:8000/users \
  -H 'Content-Type: application/json' \
  -d '{"age": 1,"email":"test@example.com"}'
Enter fullscreen mode Exit fullscreen mode

Si la réponse ne respecte pas votre schéma OpenAPI, vous avez deux possibilités :

  • l’API est incorrecte et doit être corrigée ;
  • la spécification est incomplète ou obsolète et doit être mise à jour.

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 réellement.

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 réponse ne correspond pas au schéma déclaré pour ce code de statut
Incohérences de code de statut L’API renvoie un code de statut non documenté dans la spécification
Dérive du Content-Type Le type de contenu de la réponse ne correspond pas à celui annoncé
Bugs d’état Une opération fonctionne seule mais échoue dans un workflow réaliste en plusieurs étapes

Les bugs d’état sont particulièrement intéressants. Schemathesis peut enchaîner des opérations à partir des liens déclarés dans la spécification. Par exemple :

  1. créer une ressource ;
  2. la récupérer ;
  3. la mettre à jour ;
  4. la supprimer ;
  5. vérifier son état après suppression.

Ce type de scénario trouve des bugs que les tests isolés endpoint par endpoint ratent souvent.

Personnaliser Schemathesis avec des hooks

Les hooks permettent d’adapter Schemathesis à votre contexte. Vous pouvez les utiliser pour :

  • filtrer certaines opérations ;
  • enrichir les données générées ;
  • ajouter des vérifications métier ;
  • gérer des contraintes que le schéma ne sait pas exprimer ;
  • préparer un état avant un test.

Par exemple, si certaines routes nécessitent un contexte particulier, vous pouvez écrire du code Python autour de Schemathesis au lieu de tout piloter uniquement en CLI.

C’est utile quand votre API a :

  • des flux d’authentification complexes ;
  • des dépendances entre ressources ;
  • des contraintes implicites ;
  • des données préexistantes obligatoires.

Ajouter Schemathesis à la CI

Schemathesis est facile à ajouter dans un pipeline CI, car la commande retourne un code d’erreur en cas d’échec.

Exemple GitHub Actions simplifié :

name: API fuzzing

on:
  pull_request:
  push:
    branches:
      - main

jobs:
  schemathesis:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - name: Install Schemathesis
        run: pip install schemathesis

      - name: Run API
        run: |
          # Démarrez votre API ici
          # Exemple :
          # uvicorn app.main:app --host 0.0.0.0 --port 8000 &
          echo "Start API"

      - name: Run Schemathesis
        run: |
          st run ./openapi.yaml --url http://127.0.0.1:8000
Enter fullscreen mode Exit fullscreen mode

En pratique, vous pouvez exécuter Schemathesis :

  • sur chaque pull request pour détecter vite les régressions ;
  • chaque nuit pour des campagnes plus longues ;
  • avant une release pour valider le contrat exposé.

Quand utiliser Schemathesis

Schemathesis est pertinent si vous disposez d’une spécification OpenAPI ou GraphQL suffisamment précise et que vous voulez couvrir beaucoup de cas limites sans écrire tous les tests à la main.

Utilisez-le si :

  • vous maintenez une spécification OpenAPI et voulez vérifier qu’elle est respectée par le serveur réel ;
  • vous voulez détecter les erreurs 500 non gérées ;
  • vous voulez ajouter une couche de fuzzing en CI ;
  • votre API contient des workflows avec état ;
  • votre équipe utilise déjà Python, pip ou pytest.

Évitez de l’utiliser comme unique stratégie de test. Schemathesis vérifie surtout la robustesse et la conformité au schéma. Il ne valide pas à lui seul la logique métier.

Par exemple, il peut détecter qu’une réponse ne respecte pas le schéma, mais il ne saura pas nécessairement vérifier qu’un calcul de remise, une règle de facturation ou une permission métier est correcte. Pour cela, vous avez toujours besoin de tests fonctionnels basés sur des exemples.

Schemathesis et Apidog : où chacun s’intègre

Apidog et Schemathesis couvrent des besoins différents.

Apidog est une plateforme pour concevoir, déboguer, tester, simuler et documenter des API. Schemathesis est un outil spécialisé dans le fuzzing basé sur les propriétés à partir d’un schéma.

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 équivalent à Schemathesis, qui génère des entrées à partir des contraintes du schéma et valide les réponses contre ce même schéma.

É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, workflow 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 workflow pratique peut ressembler à ceci :

  1. concevoir et maintenir la spécification dans Apidog ;
  2. générer des tests fonctionnels à partir de cette spécification ;
  3. créer un serveur de simulation pour les consommateurs d’API ;
  4. exécuter les tests en CI avec apidog run ;
  5. ajouter une passe Schemathesis sur la même spécification ;
  6. corriger les divergences entre contrat et implémentation.

Les deux couches ne cherchent pas les mêmes bugs. Apidog valide les scénarios connus et les contrats attendus. Schemathesis explore les cas limites et les entrées que vous n’auriez probablement pas écrites à la main.

Si votre objectif est de transformer une spécification en suite fonctionnelle exécutable plutôt qu’en campagne de fuzzing, Apidog peut générer directement des collections de tests API à partir de vos spécifications OpenAPI. Vous pouvez aussi télécharger Apidog pour tester ce workflow.

Foire aux questions

Schemathesis est-il gratuit ?

Oui. Schemathesis est open source sous licence MIT. Vous pouvez l’installer et l’exécuter gratuitement avec :

pip install schemathesis
Enter fullscreen mode Exit fullscreen mode

Il existe aussi une offre commerciale hébergée pour les équipes qui veulent une expérience gérée, mais l’outil principal utilisable localement et en CI est gratuit.

Quelle est la différence entre schemathesis run et st run ?

Ce sont les mêmes commandes. st est l’alias court de schemathesis.

Ces deux commandes sont équivalentes :

schemathesis run ./openapi.yaml --url http://127.0.0.1:8000
Enter fullscreen mode Exit fullscreen mode 
st run ./openapi.yaml --url http://127.0.0.1:8000
Enter fullscreen mode Exit fullscreen mode

Utilisez celle que vous préférez.

Schemathesis peut-il remplacer mes tests API fonctionnels ?

Non. Schemathesis vérifie que votre API ne plante pas et que les réponses respectent le schéma. Il ne remplace pas les tests fonctionnels qui valident la logique métier.

Vous avez toujours besoin de tests basés sur des exemples et de tests de contrat. Schemathesis doit être vu comme une couche complémentaire de fuzzing, pas comme un remplacement.

Schemathesis fonctionne-t-il avec GraphQL ?

Oui. Schemathesis prend en charge 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 selon le contrat attendu.

Conclusion

Schemathesis fait une chose précise : prendre une spécification OpenAPI ou GraphQL et tester votre API réelle avec des entrées générées automatiquement. Il trouve des plantages, des réponses invalides et des écarts de contrat que les tests manuels basés sur des exemples peuvent manquer.

Ajoutez-le à votre CI si vous voulez une couche de fuzzing pilotée par le schéma. Gardez vos tests fonctionnels pour valider les scénarios métier connus.

Apidog complète ce workflow côté conception, tests fonctionnels, simulation, exécution CI et documentation. Vous pouvez concevoir la spécification, générer des tests, les exécuter avec apidog run, documenter l’API, puis ajouter Schemathesis pour explorer les cas limites. Téléchargez Apidog pour construire la partie conception et tests fonctionnels de ce pipeline.

Top comments (0)