Des spécifications OpenAPI/Swagger à la suite de tests en quelques secondes avec Kiro

Les API sont l'épine dorsale des applications modernes. Au fur et à mesure que les équipes construisent et itèrent sur les API REST, le maintien d'une couverture de tests complète devient un défi persistant. Les spécifications OpenAPI/Swagger font un travail remarquable pour décrire ce qu'une API devrait faire : les points de terminaison, les formes de requêtes, les schémas de réponses et les codes de statut. Ce qu'elles ne font pas, c'est prouver que tout cela fonctionne.

Combler cet écart incombe traditionnellement aux développeurs. Vous lisez les spécifications, vous traduisez chaque point de terminaison en cas de test, vous tenez compte des chemins normaux et des cas limites, vous configurez un exécuteur de tests, vous simulez les dépendances et vous construisez suffisamment de rapports pour que les résultats aient un sens. Pour une API de taille modérée, disons 40 points de terminaison, c'est une semaine de travail avant même d'avoir écrit une seule ligne de code produit. Et cela suppose que la spécification reste stable, ce qui est rarement le cas.

Le défi central est que les spécifications d'API et leurs suites de tests correspondantes sont maintenues indépendamment. Avec le temps, elles divergent inévitablement. Les tests écrits au lancement deviennent obsolètes à mesure que les points de terminaison changent. De nouveaux points de terminaison sont mis en service sans couverture de tests correspondante.

Des outils comme OpenAPI Generator peuvent produire un échafaudage de tests à partir d'une spécification, mais ils vous donnent généralement des ébauches à compléter vous-même. Kiro adopte une approche différente en traitant la spécification comme la source de vérité pour la génération de tests. Fournissez-lui un fichier OpenAPI/Swagger, et il produit une suite de tests fonctionnelle, une couverture des points de terminaison, des cas limites, une validation de schéma et un échafaudage de rapports, dans le temps qu'il vous faudrait pour configurer un fichier de test. De plus, Kiro réduit le coût de la synchronisation des tests avec la spécification en rendant la régénération rapide et peu exigeante en efforts, et les hooks peuvent révéler la dérive tôt. Le reste de cet article explique exactement comment cela fonctionne et ce que cela produit.

Swagger a été créé comme un moyen de documenter les API REST à l'aide de JSON structuré. Il a défini un vocabulaire : voici mes points de terminaison, voici les paramètres que chacun accepte, voici ce que je retourne en cas de succès, voici ce que je retourne en cas de problème.

Un document OpenAPI minimal spécifie, pour chaque point de terminaison : le chemin d'URL et la méthode HTTP, les paramètres qu'il accepte (type, emplacement, requis/facultatif), le schéma d'une réponse réussie et les réponses d'erreur possibles avec leurs codes.

Un document OpenAPI est plus que de la documentation — c'est un fichier de définition structuré (JSON ou YAML) qui décrit entièrement l'interface d'une API REST. Il agit comme un contrat entre les producteurs et les consommateurs d'API, et parce qu'il est lisible par machine, les bons outils peuvent l'analyser, raisonner sur celui-ci et générer de véritables artefacts à partir de lui. Cette distinction compte pour tout ce qui suit.

Dans cet article, nous vous montrons comment utiliser Kiro, un système de développement agentif, pour générer automatiquement une suite de tests Node.js complète et exécutable directement à partir d'une spécification d'API Swagger — incluant un serveur simulé, des commutateurs de configuration et des rapports de tests HTML.

Si vous avez déjà travaillé avec des spécifications OpenAPI, vous avez probablement rencontré OpenAPI Generator ou Swagger Codegen. Pour le contexte, OpenAPI Generator a été créé par bifurcation (fork) de Swagger Codegen en 2018 en raison de différences de gouvernance — ils partagent des objectifs similaires mais sont maintenus séparément avec des cadences de publication et des ensembles de fonctionnalités différents. Les deux sont des outils open-source qui prennent un fichier de spécification et génèrent des bibliothèques clientes, des ébauches de serveur ou du code SDK dans le langage de votre choix. Ils sont excellents pour réduire le code répétitif HTTP, mais ils ne sont pas conçus pour vérifier le comportement de l'API. Si vous essayez de les utiliser pour la génération de tests, vous obtiendrez généralement des ébauches de méthodes avec des assertions minimales, une simulation limitée et peu de validation de schéma — bien que le résultat exact dépende du langage, du modèle et de la configuration utilisés. Les tests peuvent compiler et s'exécuter, mais ils ne fournissent souvent pas de couverture significative des cas limites, de la gestion des erreurs ou des contrats de schéma.

Cela compte plus qu'il n'y paraît. Un test sans assertion réussit toujours en CI et compte pour la couverture — mais il ne vérifie pas réellement les codes de statut, les formes de réponses ou les cas d'erreur. Vous pouvez vous retrouver avec des builds verts et des chiffres de couverture élevés alors que certains bogues, comme un 400 retourné comme un 500, passent inaperçus.

Kiro aborde le problème différemment. Plutôt que de faire du templating à partir d'une spécification, il raisonne sur celle-ci — résolvant les valeurs d'énumération en charges utiles réalistes, générant des assertions liées aux contrats de schéma réels et produisant un serveur simulé qui reflète le comportement défini par la spécification. Le résultat n'est pas un échafaudage à compléter plus tard; ce sont des tests exécutables avec une couverture significative.

Comparaison des capacités : générateurs basés sur des modèles vs approche pilotée par agent de Kiro.

Avec une approche basée sur des modèles, certaines catégories de problèmes peuvent passer inaperçues — par exemple, une erreur 400 retournée comme un 500, ou un point de terminaison d'authentification acceptant des jetons malformés — particulièrement lorsque les tests générés ne font aucun appel réel au point de terminaison et n'effectuent aucune validation de réponse. Ces outils sont principalement conçus pour la génération de code, pas pour la vérification comportementale. Kiro, en revanche, génère des tests qui exercent chaque point de terminaison et vérifient que la réponse correspond à ce que la spécification définit — offrant un signal plus fiable de la conformité réelle de l'API.

Notre solution prend une URL de spécification exemple PetStore Swagger/OpenAPI comme entrée et utilise Kiro pour générer un projet de tests entièrement fonctionnel. Le projet généré comprend les composants suivants :

• Client de test utilisant axios — Tests HTTP couvrant chaque point de terminaison défini dans la spécification Swagger, incluant les opérations GET, POST, PUT et DELETE avec des charges utiles de requêtes et des assertions de réponses appropriées.
• Serveur Express simulé — Un serveur local qui simule l'API, retournant des réponses réalistes pour chaque point de terminaison afin que les tests puissent s'exécuter sans accès réseau ni dépendance à un service en direct.
• Commutateur de configuration — Un interrupteur simple pour exécuter la même suite de tests contre le serveur simulé (pour le développement local) ou l'API réelle (pour les tests d'intégration).
• Rapport de tests HTML — Un rapport stylisé et partageable montrant le statut réussite/échec et les détails d'erreur pour chaque cas de test, adapté aux pipelines CI/CD ou aux révisions de pull request.
• Zéro cadre de test externe — Les tests s'exécutent sur du Node.js pur avec un exécuteur personnalisé léger, éliminant les conflits de versions de cadres et réduisant les frictions de configuration.

Pour suivre ce tutoriel, vous avez besoin des éléments suivants :

• Node.js
• Kiro installé et configuré
• Une URL de spécification Swagger/OpenAPI (nous utilisons l'API Petstore comme exemple)

Générons maintenant une suite de tests complète à partir de la spécification Swagger Petstore. Au lieu d'intégrer toutes les règles de génération de tests dans la requête, nous utilisons un fichier de steering Kiro. Les fichiers de steering se trouvent dans « .kiro/steering/ » et fournissent des instructions persistantes que Kiro suit dans toutes les requêtes de l'espace de travail. Cela signifie que vous définissez vos normes de génération de tests une seule fois et que chaque requête en bénéficie. Pour ce billet, nous avons utilisé cet exemple de fichier de steering. Personnalisez-le selon les besoins et les normes de votre équipe.

Un exemple de requête est présenté pour le mode Vibe de Kiro.

Generate a Node.js test suite from https://petstore.swagger.io/index.html using axios, Express for mocking, and no external test frameworks

Kiro lit la spécification Swagger, analyse chaque point de terminaison et génère le projet complet.

Kiro produit un projet avec une structure semblable à la suivante :

• config.js — Contient le commutateur de configuration. Définissez useMockServer: true pour exécuter les tests contre le serveur simulé Express local, ou useMockServer: false pour cibler l'API Petstore en direct.
• mock-server/server.js — Une application Express avec des gestionnaires de routes pour chaque point de terminaison Petstore. Chaque gestionnaire retourne des données de réponse réalistes correspondant aux schémas définis dans la spécification Swagger.
• test/ — Fichiers de test individuels organisés par ressource d'API (pet, store, user). Chaque fichier contient des tests pour chaque opération sur cette ressource, avec des assertions sur les codes de statut de réponse et la structure de la charge utile.
• test-runner.js — Un exécuteur de tests Node.js pur et léger qui découvre et exécute tous les fichiers de test, suit les comptes de réussite/échec et capture les détails d'erreur.

Kiro ne se contente pas de générer des ébauches de tests génériques. Il lit la spécification Swagger et les instructions du fichier de steering pour :

1. Identifier chaque point de terminaison et méthode HTTP — Pour l'API Petstore, cela inclut des opérations comme POST /pet, GET /pet/{petId}, PUT /pet, DELETE /pet/{petId}, GET /store/inventory, POST /user/createWithList, et plus encore.
2. Déduire les charges utiles de requêtes à partir des définitions de schéma — Pour les opérations POST et PUT, Kiro construit des corps de requêtes valides basés sur les définitions de modèle dans la spécification (par exemple, un objet Pet avec les champs id, name, category, photoUrls, tags et status).
3. Générer des assertions basées sur les codes de réponse attendus — Chaque test affirme le code de statut HTTP correct (200, 201, 404, 405) tel que défini dans les définitions de réponse de la spécification.
4. Créer les routes de serveur simulé correspondantes — Chaque point de terminaison de la spécification obtient un gestionnaire de route Express correspondant qui retourne des données cohérentes avec le schéma de réponse défini.

Pour exécuter la suite de tests contre le serveur simulé local, dans l'interface de clavardage, fournissez la requête

« Run the tests with the mock server ».

Vous verrez des résultats similaires à ceux inclus ci-dessous.

L'exécuteur de tests démarre le serveur Express simulé, exécute tous les cas de test et génère le rapport. Ouvrez le fichier test-report.md généré dans votre navigateur pour voir les résultats.

La suite de tests générée contient des cas de test couvrant chaque point de terminaison défini dans la spécification Swagger Petstore. Ce sont des tests d'intégration, pas des tests unitaires. Chaque test effectue une véritable requête HTTP via axios vers un serveur Express en cours d'exécution, exerçant l'ensemble de la pile : transport TCP, analyse des intergiciels (middleware), correspondance de routes, logique du gestionnaire, mutation d'état et sérialisation JSON. Rien à l'intérieur du serveur n'est simulé au niveau de la fonction. Plusieurs tests enchaînent même plusieurs requêtes ensemble — par exemple, les tests DELETE effectuent d'abord un POST sur une ressource, puis un DELETE, puis un GET pour confirmer le 404 — vérifiant que les effets secondaires persistent correctement à travers le cycle de vie de la requête. Cette approche multi-requêtes en boîte noire est la caractéristique déterminante des tests d'intégration.

Sur le plan de la qualité, la suite présente des forces claires. Elle couvre systématiquement à la fois les chemins normaux et les chemins d'erreur pour chaque point de terminaison, en affirmant les codes de statut HTTP spécifiques documentés dans la spécification OpenAPI (200, 400, 404, 405). L'utilisation d'un port éphémère et de données d'amorçage en mémoire rend la suite entièrement autonome et déterministe — aucune dépendance réseau, aucune collision de port, reproductible sur n'importe quelle machine. Les opérations destructrices sont vérifiées par des lectures de suivi plutôt qu'en se fiant uniquement au code de réponse.

En bref, il s'agit d'une suite d'intégration pratique au niveau du contrat, bien adaptée pour une rétroaction CI rapide sur la forme de l'API et la gestion des erreurs. Pour atteindre une confiance de niveau production, elle bénéficierait d'une isolation d'état par test, d'une validation complète du schéma JSON, d'une couverture d'authentification et d'exécutions périodiques contre le service réel.

Un des tests les plus intéressants générés par Kiro va au-delà de la simple invocation d'un point de terminaison et de la vérification d'un code de statut. Il valide un cycle de vie complet de ressource dans un seul cas de test :

Ce qui rend ce test intéressant, c'est qu'il ne se fie pas uniquement à la réponse DELETE. De nombreuses suites de tests naïves s'arrêteraient à affirmer le code de statut 200 — « le serveur a dit que ça a fonctionné, donc ça a fonctionné ». Mais cela ne prouve rien sur le fait que l'état a réellement changé. Un serveur défectueux pourrait retourner 200 et échouer silencieusement à supprimer l'enregistrement.

Au lieu de cela, Kiro a généré un test en trois phases :

1. Arranger — POST un nouvel animal avec un ID connu, confirmant qu'il a été créé avec succès.
2. Agir — DELETE cet animal et affirmer que le serveur reconnaît l'opération.
3. Vérifier — GET le même ID et affirmer que le serveur retourne maintenant 404.

Ce modèle, parfois appelé « vérification aller-retour », est ce qui distingue un test d'intégration significatif d'un test superficiel. Il prouve que la machine à états de l'API transitionne réellement : une ressource qui existe peut être détruite, et une fois détruite, elle est véritablement disparue. Si une couche de la pile (routage, logique du gestionnaire, magasin de données) avale silencieusement la suppression, l'assertion GET le détecte.

C'est aussi un bon exemple d'autosuffisance des tests. Le test crée sa propre configuration plutôt que de dépendre de données d'amorçage qui auraient pu être modifiées par un test antérieur. Cela rend le résultat réussite/échec du test indépendant de l'ordre d'exécution, ce qui est un signal de qualité petit mais important dans une suite sans réinitialisations d'état par test.

Pour valider si les tests générés tiennent la route au-delà de la simulation, les développeurs peuvent pointer la suite vers le véritable serveur Petstore en définissant une seule variable d'environnement :

PETSTORE_URL=https://petstore.swagger.io npm test

ou demander à Kiro « Run the tests with the real server ». Cela exécute exactement les mêmes tests — aucun changement de code requis — mais maintenant contre un backend en direct et partagé plutôt que contre la simulation Express locale.

Lorsque des échecs apparaissent, ils se répartissent généralement en quelques catégories reconnaissables :

• L'API réelle est plus permissive que la spécification. La définition Swagger peut documenter 405 pour une entrée invalide, mais le serveur en direct l'accepte silencieusement et retourne 200. La simulation était plus stricte que la réalité.
• La sémantique des codes d'erreur diffère. La simulation pourrait retourner 400 pour un ID non numérique alors que le serveur réel retourne 404. Les deux sont défendables — ils représentent simplement des interprétations différentes de la même spécification.
• Les formes de réponses ne correspondent pas aux attentes. Un champ que le test attend comme une chaîne revient comme un objet JSON, ou une propriété imbriquée est entièrement absente.
• Les hypothèses d'état partagé échouent. Les tests qui dépendent de données amorcées (comme des utilisateurs ou des animaux préchargés) échouent parce que le serveur en direct ne porte pas ces données de test.

Lorsque cela se produit, la recommandation n'est pas de « corriger » aveuglément les échecs. Au lieu de cela, traitez chacun comme une question de triage : est-ce la simulation qui a tort, le test qui a tort, ou la documentation qui a tort? À partir de là :

• Si le serveur réel est plus permissif, décidez si votre simulation devrait s'assouplir pour correspondre, ou si le test devrait être marqué comme réservé à la simulation.
• Si les codes d'erreur diffèrent, alignez-vous sur une seule source de vérité, généralement le comportement réel du serveur en direct, et mettez à jour à la fois la simulation et les attentes du test.
• Si l'état partagé est le problème, rendez les tests autosuffisants : créez leurs propres données de test avant d'affirmer, et ne comptez pas sur des données qui n'existent que localement.

Le but n'est pas d'obtenir un taux de réussite vert dans les deux modes dès le premier jour. C'est que l'exécution contre les deux cibles révèle où vos hypothèses divergent de la réalité — et vous donne une voie structurée pour combler ces écarts.

L'API Petstore est un bac à sable public qui n'impose pas l'authentification. Les API internes du monde réel le font presque toujours. Voici comment adapter cette approche pour les points de terminaison authentifiés.

Tout d'abord, étendez la configuration de test pour prendre en charge les paramètres d'authentification. Plutôt que de codifier en dur les identifiants, définissez-les de manière externe afin que la même suite fonctionne dans tous les environnements :

Ensuite, construisez une fabrique de client partagée qui attache les bons identifiants selon le type d'authentification configuré :

Maintenant, chaque fichier de test utilise le client partagé, et les identifiants restent hors du code :

Avec cela en place, vous pouvez également ajouter des tests dédiés qui vérifient l'application de l'authentification elle-même — que les requêtes sans identifiants sont rejetées, que les jetons expirés retournent 401, et que les portées insuffisantes retournent 403. Ce sont les tests que le bac à sable Petstore ne peut pas exercer, mais ils sont souvent les plus critiques pour les services internes.

Générer une suite de tests une fois est utile. La maintenir synchronisée à mesure que l'API évolue est là où réside la véritable valeur. Le mode sans interface de Kiro CLI vous permet d'exécuter Kiro de manière programmatique dans les pipelines CI/CD — aucun navigateur, aucun terminal interactif. Vous définissez une clé API comme variable d'environnement, transmettez une requête, et Kiro l'exécute de bout en bout.

Dans cet article, nous vous avons montré comment utiliser Kiro pour générer une suite de tests d'API Node.js complète à partir d'une spécification Swagger en quelques secondes. Le projet généré comprend un client de test HTTP, un serveur Express simulé, un commutateur de configuration pour basculer entre les API simulées et en direct, et un rapport de test — tout cela sans dépendances à des cadres de test externes.

Cette approche élimine l'effort manuel de traduction des spécifications d'API en code de test et offre un moyen systématique et reproductible d'atteindre une couverture de tests d'API complète. Vous pouvez appliquer ce même modèle à toute API disposant d'une spécification Swagger ou OpenAPI.

Pour commencer avec Kiro, visitez kiro.dev.