Comment exécuter des tests API sans le boilerplate YAML de Tavern

Tavern est une ingénierie intelligente. Il s'intègre à pytest, vous permet de décrire un test d'API comme un fichier YAML, et exécute ce fichier comme s'il s'agissait d'un test pytest normal. Vous bénéficiez gratuitement de tout l'écosystème de pytest : les fixtures, les plugins, les exécutions parallèles avec pytest-xdist, la couverture de code, la même commande que votre équipe Python utilise déjà. Pour une équipe backend qui vit avec pytest, écrire un fichier test_*.tavern.yaml de plus à côté des tests unitaires semble naturel.

Les frictions apparaissent une fois que le YAML s'agrandit. Une seule requête qui envoie un corps, enregistre un jeton et vérifie quelques champs de réponse se transforme en un bloc imbriqué de clés request, response, save et verify_response_with que vous devez indenter parfaitement. Les flux multi-étapes (se connecter, créer une ressource, la relire, la supprimer) empilent ces blocs dans un long fichier où un espace mal placé rompt l'analyse, et le contrat d'API que le test vérifie se trouve ailleurs : un fichier Swagger, une page wiki, une collection Postman devenue obsolète il y a des mois.

bouton

Ce que Tavern fait bien

Commençons par le crédit, car Tavern le mérite.

Il s'appuie sur pytest au lieu de le remplacer. Tavern est un plugin pytest. Vous l'installez avec pip install tavern, déposez un fichier YAML dans votre répertoire de test, et pytest le découvre et l'exécute comme n'importe quel autre test. Cela signifie que vous conservez toutes les habitudes pytest que votre équipe a déjà : -k pour filtrer, -x pour arrêter à la première erreur, pytest-html pour les rapports, pytest-xdist pour les exécutions parallèles, les fixtures pour la configuration partagée. Rien ne change dans votre exécuteur. Pour une entreprise Python, c'est un réel avantage, et peu d'outils de test d'API s'intègrent aussi proprement à une suite existante.

Le YAML est déclaratif et lisible. Un test Tavern simple est vraiment facile à parcourir :

test_name: Get a single order

stages:
  - name: Fetch order 1042
    request:
      url: https://api.shop.test/orders/1042
      method: GET
    response:
      status_code: 200
      json:
        id: 1042
        status: shipped

Pas de code de liaison, pas de bibliothèque d'assertion à importer, pas de harnais de test à écrire. La requête et la réponse attendue sont côte à côte. Pour vérifier un code de statut et quelques champs, cela se lit mieux que l'équivalent Python requests plus assert.

Enregistrement et enchaînement de variables. Tavern peut extraire une valeur d'une réponse et l'injecter dans l'étape suivante avec save et la substitution {variable}, de sorte qu'un flux de connexion-puis-appel fonctionne sans code personnalisé :

stages:
  - name: Log in
    request:
      url: https://api.shop.test/auth/login
      method: POST
      json:
        username: tester
        password: hunter2
    response:
      status_code: 200
      save:
        json:
          token: access_token

  - name: Read the profile with the saved token
    request:
      url: https://api.shop.test/me
      method: GET
      headers:
        Authorization: "Bearer {token}"
    response:
      status_code: 200

Il fait plus que du HTTP. Tavern teste également MQTT, ce qui est important si vous travaillez avec l'IoT ou des systèmes basés sur des messages. Et comme il repose sur pytest, vous pouvez mélanger des tests d'API YAML et des tests Python réguliers dans la même exécution et le même rapport.

Rien de tout cela n'est du marketing. Tavern est un outil solide. La question est de savoir si ses hypothèses correspondent aux vôtres.

Où le code passe-partout YAML s'accumule

Trois coûts sont associés au modèle Tavern, et leur importance dépend de la taille de votre suite de tests.

Le YAML est sensible aux espaces blancs, et le schéma est profond. L'exemple simple ci-dessus est propre. Un test réaliste ne l'est pas. Une fois que vous ajoutez des en-têtes, des paramètres de requête, un corps de requête, des assertions sur le corps de réponse, des vérifications de type, des variables enregistrées et des fonctions externes verify_response_with, vous vous retrouvez avec une imbrication de quatre ou cinq niveaux dans un format où un espace incorrect est une erreur d'analyse, et non un message clair. Les éditeurs ne complètent pas automatiquement les clés de Tavern comme un IDE complète une méthode Python, vous devez donc vérifier la documentation pour savoir s'il s'agit de status_code ou status, json ou body, pour chaque nouveau champ.

Le test et le contrat d'API sont deux artefacts distincts. Votre fichier YAML Tavern code en dur l'URL, la méthode, les champs attendus et leurs types. La définition réelle de l'API se trouve dans un fichier OpenAPI, des décorateurs de routes de framework, ou on ne sait trop où. Lorsque l'API change un nom de champ, rien ne le signale au YAML. Le test continue d'affirmer l'ancienne structure jusqu'à ce qu'il échoue en CI ou, pire, continue de passer contre une attente obsolète. Quelqu'un doit maintenir les deux synchronisés manuellement, et ce quelqu'un est généralement celui sur qui l'échec retombe à 2 heures du matin.

Il suppose une chaîne d'outils Python et des personnes connaissant Python. Tavern est excellent si vos testeurs écrivent du Python. Si votre groupe QA, vos ingénieurs frontend ou vos responsables produit veulent ajouter ou lire un test, ils se heurtent à pip, aux virtualenvs, aux conventions pytest et aux règles de schéma YAML tout cela en même temps juste pour envoyer une requête HTTP et vérifier une réponse. La courbe d'apprentissage est raide pour quiconque en dehors du monde Python.

La voie sans YAML

L'alternative est d'arrêter de rédiger des tests sous forme de fichiers texte et de commencer à les construire à partir de la définition d'API que vous avez déjà.

Dans Apidog, la spécification d'API, la requête et le test sont le même objet. Vous importez ou concevez votre API une fois (OpenAPI, Swagger, ou une collection Postman s'importe en un clic), et chaque endpoint transporte son véritable schéma avec lui. Vous construisez un scénario de test en enchaînant ces endpoints visuellement : faites glisser l'appel de connexion, faites glisser l'appel qui a besoin du jeton, et transmettez la valeur sans écrire manuellement des blocs save: ou des chaînes {variable}. Les assertions sont des cases à cocher et des expressions dans un panneau, et non des clés YAML indentées dont vous devez vous souvenir.

Parce que le test est construit par rapport à la spécification, la spécification est la seule source de vérité. Changez un champ de réponse dans la conception et les scénarios de test qui s'y réfèrent feront apparaître le changement au lieu de dériver silencieusement. C'est la partie que Tavern ne peut structurellement pas faire : son YAML n'a aucun lien avec le contrat.

Et quand il est temps d'automatiser, vous ne perdez pas la propriété headless et compatible CI qui a rendu Tavern attrayant. L'Apidog CLI exécute ces mêmes scénarios depuis la ligne de commande, en CI, sans interface graphique, exactement comme pytest exécute vos fichiers Tavern aujourd'hui.

Installation et exécution de l'Apidog CLI

L'exécuteur est un package npm gratuit appelé apidog-cli. Installez-le globalement :

npm install -g apidog-cli

Exécutez ensuite un scénario de test avec la commande apidog run :

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli

Voici ce que chaque élément fait :

--access-token authentifie l'exécution auprès de votre compte Apidog. Générez le jeton depuis l'onglet CI/CD du scénario et stockez-le comme un secret, jamais dans le fichier.
-t est l'ID du scénario de test.
-e est l'ID de l'environnement (développement, staging, production), afin que le même scénario utilise la bonne URL de base et les bonnes variables.
-r choisit les rapporteurs. cli affiche une sortie lisible dans le terminal.

Vous n'avez pas besoin de mémoriser ces ID. Ouvrez le scénario de test dans Apidog, passez à son onglet CI/CD, choisissez l'option de ligne de commande et cliquez sur Générer le jeton. Apidog construit pour vous la commande apidog run complète avec l'ID du scénario et l'ID de l'environnement déjà renseignés. Copiez-la, puis déplacez le jeton dans un secret CI.

Si vous préférez ne pas l'installer globalement, surtout sur un exécuteur CI éphémère, exécutez-le avec npx :

npx apidog-cli run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli

Les rapporteurs incluent cli, html, json et junit. Pour la CI, la combinaison utile est -r html,junit : junit émet le XML standard que presque tous les tableaux de bord CI analysent en un arbre de réussite/échec, et html produit un rapport consultable que vous pouvez archiver comme artefact de build. Ajoutez --out-dir pour contrôler l'emplacement :

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r html,junit --out-dir ./apidog-reports

Pour la liste complète des options de votre version installée, exécutez apidog run --help.

Comparaison

	Tavern	Apidog
Format des tests	Fichiers YAML (`*.tavern.yaml`)	Scénarios visuels construits à partir de la spécification
Environnement d'exécution	Python + pytest	Exécution sans interface graphique `apidog run` (package npm)
Rédaction des tests	Écriture et indentation manuelles du YAML	Enchaînement d'endpoints par glisser-déposer, assertions par cases à cocher
Contrat d'API	Artefact séparé, synchronisé manuellement	La spécification est la source de vérité du test
Enchaînement des variables	Blocs `save:` et substitution `{var}`	Transfert de valeurs entre les étapes dans l'interface utilisateur
Rapporteurs	`pytest-html`, JUnit via les plugins pytest	`cli`, `html`, `json`, `junit` intégrés
Qui peut écrire des tests	Testeurs à l'aise avec Python	Toute personne de l'équipe, y compris les non-codeurs
Protocoles	HTTP et MQTT	HTTP, plus SOAP, WebSocket, gRPC, et plus encore

Tavern est gagnant si votre équipe est entièrement dédiée à Python et que vous voulez que les tests résident dans le même dépôt et la même exécution pytest que vos tests unitaires. Apidog l'emporte si vous voulez abandonner la maintenance du YAML, garder le contrat et le test comme une seule entité, et permettre à des personnes qui ne codent pas en Python de contribuer aux tests.

Intégration dans la CI

L'exécution sans interface graphique est tout l'intérêt de passer d'un fichier de test local à un pipeline. Voici la structure pour GitHub Actions :

name: API tests
on: [push, pull_request]

jobs:
  api-tests:
    runs-on: ubuntu-latest
    steps:
      - name: Install Apidog CLI
        run: npm install -g apidog-cli

      - name: Run API test scenario
        run: |
          apidog run \
            --access-token "$APIDOG_ACCESS_TOKEN" \
            -t 605067 \
            -e 1629989 \
            -r html,junit \
            --out-dir apidog-reports
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}

      - name: Upload report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: apidog-report
          path: apidog-reports

Le jeton provient des secrets du dépôt et atteint l'étape en tant que variable d'environnement. Le if: always() sur l'étape de téléchargement signifie que vous obtenez toujours le rapport même si les tests échouent, ce qui est exactement le moment où vous voulez le lire. Si une assertion échoue, l'étape apidog run se termine avec un code de sortie non nul, le job passe au rouge, et la pull request affiche un échec de vérification.

Ce comportement de code de sortie est la porte de qualité, et il fonctionne de la même manière que celui de Tavern : la CI lit le code de sortie de chaque étape, une sortie non nulle fait échouer le job, et un job échoué bloque la fusion ou le déploiement. Vous ne configurez rien de plus. Pour des configurations de pipeline plus approfondies, l'Apidog CLI dans votre pipeline CI/CD et le tutoriel GitHub Actions couvrent également les variantes GitLab CI et Jenkins.

Une note sur pytest et le monde plus large des tests Python

S'éloigner du YAML de Tavern ne signifie pas abandonner pytest. De nombreuses équipes conservent leurs tests unitaires et d'intégration purement Python dans pytest et utilisent Apidog pour la couche de contrat d'API, la partie où le test doit suivre la spécification et s'exécuter également pour les contributeurs non-Python. Les deux ne sont pas mutuellement exclusifs. La valeur de Tavern a toujours été de permettre aux utilisateurs de pytest d'écrire des tests d'API dans un format plus léger que le code requests brut ; la valeur d'Apidog est de faire en sorte que ces tests d'API suivent le contrat et restent lisibles à mesure que la suite s'étend au-delà de quelques fichiers.

Si vous évaluez d'autres exécuteurs, la même logique s'applique à l'approche en ligne de commande de Postman dans Postman CLI vs Newman et à l'exécution de collections sans outils supplémentaires dans Tests d'API sans Postman.

FAQ

L'Apidog CLI est-il gratuit ? Oui. Le package npm apidog-cli est gratuit à installer et à exécuter avec npm install -g apidog-cli. Il exécute les scénarios de test de votre projet Apidog, donc ce que vous pouvez exécuter dépend de votre plan Apidog, mais l'exécuteur en ligne de commande lui-même n'est pas un produit payant séparé.

Puis-je toujours utiliser pytest en parallèle d'Apidog ? Oui. Conservez vos tests unitaires et d'intégration Python dans pytest et utilisez Apidog pour la couche de test du contrat d'API. De nombreuses équipes utilisent les deux. La différence est que les tests Apidog suivent la spécification au lieu de la coder en dur dans un fichier séparé.

Comment Apidog bloque-t-il une mauvaise fusion en CI ? Grâce au code de sortie. Lorsqu'une assertion échoue, apidog run se termine avec un code non nul. La CI lit ce code de sortie, marque l'étape comme ayant échoué et bloque la fusion ou le déploiement. Vous n'avez rien à configurer de plus pour que cela fonctionne.

Quel rapporteur dois-je utiliser pour la CI ? Utilisez junit pour le résultat lisible par machine que votre tableau de bord CI analyse en un arbre de réussite/échec, et ajoutez html si vous souhaitez un rapport consultable enregistré comme artefact. Un choix courant est -r html,junit, avec cli activé pour une sortie de journal de build lisible.

Apidog teste-t-il uniquement HTTP, comme le mode HTTP de Tavern ? Non. Apidog couvre HTTP plus SOAP, WebSocket, les Server-Sent Events et gRPC. Tavern ajoute MQTT à HTTP, ce qui est le seul domaine où sa couverture de protocole va là où celle d'Apidog ne va pas, donc gardez cela à l'esprit si MQTT est central à votre pile technologique.

Le mot de la fin honnête

Tavern est un moyen propre d'écrire des tests d'API si vous pensez déjà en termes de pytest et de YAML, et son intégration à pytest est véritablement sa meilleure fonctionnalité. Le coût est le YAML lui-même : il devient profond et fragile à mesure que les suites de tests grandissent, et il n'a aucun lien avec le contrat d'API qu'il vérifie. Si vous voulez le même comportement sans interface graphique, avec échec bruyant en CI, sans indenter manuellement le YAML et sans maintenir une deuxième copie de votre spécification, construire des tests basés sur le contrat et les exécuter avec apidog run est la voie la plus légère.

Téléchargez Apidog et importez une API existante pour ressentir le flux de travail "la spécification est le test" avant de vous engager. C'est gratuit pour commencer.