TwinStub apporte une simulation d'API déterministe et avec état pour les tests locaux

Un nouveau projet open source nommé TwinStub est apparu pour aider les équipes de développement à simuler localement des intégrations API complexes. Publié sur GitHub en octobre 2026, cet outil permet aux ingénieurs de définir des scénarios avec état dans des fichiers YAML qui sont rejoués comme de véritables serveurs HTTP. Il est conçu spécifiquement pour les équipes développant des logiciels interagissant avec des fournisseurs externes tels que des passerelles de paiement ou des plateformes logistiques.

Ce qui s'est passé

TwinStub répond à un point de douleur courant dans le développement logiciel : le test des chemins non standards (unhappy paths) des intégrations tierces. Lorsque les entreprises construisent des systèmes reposant sur des API externes, leurs bugs les plus difficiles surviennent souvent non pas lors des opérations standard, mais lors d'événements rares tels que les rétrofacturations (chargebacks), les échecs de vérification d'identité ou les webhooks retardés. Les serveurs de mock traditionnels traitent généralement une requête à la fois et manquent de mémoire, ce qui rend difficile la simulation d'une séquence d'événements se déroulant sur plusieurs jours ou semaines.

Ce nouvel outil modélise une intégration comme une machine à états. Il maintient l'état de session, ce qui signifie qu'un endpoint spécifique peut renvoyer différentes réponses en fonction des interactions précédentes. Par exemple, une requête pour vérifier le statut d'un paiement pourrait initialement retourner "processing", puis "succeeded", et enfin "chargeback" à mesure que la chronologie simulée progresse. Cela permet aux développeurs de compresser des processus à long terme en quelques secondes à des fins de test. L'outil fonctionne comme un binaire unique écrit en Go, ne nécessitant aucune inscription cloud ni service externe, et est distribué sous licence MIT.

La proposition de valeur principale est que TwinStub agit comme substitut du fournisseur externe. Le code sous test est l'application cliente elle-même, qui doit gérer les requêtes, analyser les réponses, vérifier les signatures webhook et mettre à jour les registres internes. En simulant le fournisseur, les développeurs peuvent déclencher des branches dans leur code autrement difficiles à atteindre, telles que la gestion de la livraison d'événements désordonnée ou la vérification des signatures HMAC sur les webhooks entrants. Le projet inclut une interface en ligne de commande pour servir les simulations, valider les fichiers de configuration et initialiser des scénarios de démonstration.

Détails clés

• Simulations avec état : Contrairement aux mocks statiques, TwinStub utilise des sessions identifiées par des en-têtes, des paramètres de requête ou des champs du corps pour suivre l'état de chaque interaction client dans le temps.
• Chaînes de webhooks : Il prend en charge les webhooks retardés et signés avec HMAC, avec des tentatives exponentielles et une gigue (jitter), imitant le comportement des principaux fournisseurs comme Stripe.
• Compression temporelle : Les développeurs peuvent utiliser un indicateur d'échelle de temps pour accélérer les flux de longue durée, transformant des processus de trente jours en heures ou minutes pour des tests rapides.
• Déploiement en binaire unique : L'outil est un binaire Go autonome qui fonctionne localement ou dans des pipelines d'intégration continue sans nécessiter Java, Electron ou une connectivité cloud.
• Retour diagnostique : Lorsqu'une requête ne correspond à aucun scénario défini, le serveur renvoie un message d'erreur détaillé expliquant quels matchers ont échoué et pourquoi, facilitant le débogage.
• Fonctionnalités d'ingénierie du chaos : Les utilisateurs peuvent injecter de la latence, interrompre des connexions TCP ou renvoyer des erreurs serveur arbitraires pour tester comment leur application gère les pannes de transport.

Contexte

Pour comprendre l'utilité de TwinStub, il est utile de distinguer le simple mocking de la simulation avec état. Un serveur de mock basique répond à une URL spécifique avec une charge utile prédéfinie. Il ne se souvient pas de ce qui s'est passé dans les requêtes précédentes. Cela fonctionne bien pour tester les chemins standards où une seule requête produit une seule réponse attendue. Cependant, les intégrations modernes sont souvent pilotées par événements et avec état. Un paiement peut être autorisé, capturé, remboursé, puis faire l'objet d'une rétrofacturation plusieurs semaines plus tard. Chaque étape change l'état de la transaction.

Les webhooks sont des notifications asynchrones envoyées par des services externes à votre application lorsqu'un événement se produit. Tester les webhooks est notoirement difficile car ils nécessitent une URL publiquement accessible et impliquent des signatures cryptographiques pour garantir l'authenticité. Dans un environnement de développement local, la réception de ces webhooks nécessite généralement des services de tunneling ou des configurations réseau complexes. TwinStub simplifie cela en agissant comme l'expéditeur, générant des webhooks signés qui se déclenchent selon le scénario défini. Cela permet aux développeurs de tester leurs gestionnaires de webhook, y compris la vérification de signature et la logique d'idempotence, sans dépendre du service tiers réel.

Pourquoi c'est important

Pour les équipes qui exécutent leur propre logiciel, la fiabilité des intégrations est critique. Les bugs dans le code d'intégration conduisent souvent à des divergences financières, telles que la double facturation des clients ou l'échec de libération des stocks réservés après un paiement échoué. Ces problèmes sont coûteux à corriger en production et difficiles à reproduire dans les environnements de préproduction. En fournissant un moyen déterministe de simuler ces événements rares, TwinStub permet aux développeurs de détecter ces bugs avant le déploiement. Il déplace la charge de test de la vérification manuelle contre des sandbox live vers des tests automatisés pouvant s'exécuter à chaque build.

De plus, la capacité d'exécuter ces simulations localement sans dépendances cloud améliore la sécurité et la vitesse. Les développeurs n'ont pas besoin de partager des clés API ou des données sensibles avec des services de mocking externes. La conception de l'outil garantit que l'état est conservé en mémoire, ce qui signifie que chaque exécution de test commence à neuf, empêchant la contamination entre les tests. Cette déterminisme est essentiel pour les pipelines d'intégration continue, où les tests instables (flaky tests) peuvent ralentir la vélocité de développement. L'inclusion d'une commande de validation permet aux équipes de vérifier leurs définitions de scénarios pour les erreurs avant leur exécution, garantissant que la simulation reflète fidèlement le comportement prévu.

Cependant, il existe une limitation à reconnaître. La précision de la simulation dépend entièrement de la qualité de la définition du scénario YAML. Si le scénario modélise mal le comportement réel du fournisseur, les tests passeront même si le code est incorrect pour le monde réel. Par conséquent, il est recommandé de valider les formes de réponse contre le sandbox du fournisseur une fois, puis d'utiliser TwinStub pour explorer les cas limites que le sandbox ne peut pas facilement déclencher.

Ce que vous pouvez faire

• Installez TwinStub en utilisant la chaîne d'outils Go ou Docker pour commencer à simuler des interactions API dans votre environnement local.
• Définissez vos scénarios d'intégration en YAML, en vous concentrant sur les transitions d'état et les séquences de webhooks plutôt que sur de simples réponses statiques.
• Utilisez la fonctionnalité d'échelle de temps pour accélérer les processus de longue durée, vous permettant de tester des workflows d'un mois en quelques minutes.
• Implémentez la vérification de signature dans vos gestionnaires de webhook et utilisez la signature HMAC de TwinStub pour garantir que votre logique de sécurité fonctionne correctement.
• Exécutez la commande de validation dans votre pipeline CI pour détecter les erreurs de configuration tôt et empêcher les simulations cassées de bloquer les builds.
• Testez les scénarios de chaos en injectant de la latence ou des coupures de connexion pour vérifier que votre application gère gracieusement les pannes réseau.