Section Mocks

La section Mocks est là où vous définissez les réponses simulées que Aseptic sert quand une dépendance est résolue en mock. Elle vous permet de travailler sans connexion au cloud et sans lancer le core que votre micro appelle.

Pas besoin de lancer quoi que ce soit pour éditer les mocks : le catalogue vit sur disque (.aseptic/mocks/<service>.json) et est servi avec rechargement à chaud, ainsi un changement s’applique instantanément même si le scénario est en cours.

L’arbre : services → endpoints

Le côté affiche un arbre de services (les cores mockables) et, dans chacun, ses endpoints dans une liste plate, triée par ordre alphabétique de chemin. Chaque ligne affiche le chemin complet relatif à la base du service, si bien que deux endpoints qui finissent pareil (/orders/lines et /invoices/lines) ne se confondent pas. Pour réduire un grand catalogue, la recherche du côté filtre par nom de service ou par chemin.

Un service est mockable s’il est une dépendance d’un micro (ou si vous créez son fichier dans .aseptic/mocks). Vous pouvez afficher ou masquer les services qui n’ont pas encore de stubs.

Créer un stub

Appuyez sur Nouveau stub (ou le menu « ⋮ ») et choisissez le service cible —un du catalogue ou un nouveau qui se crée à l’enregistrement—. Un endpoint se définit avec :

Méthode et chemin (relatif au chemin de base du service).
Une ou plusieurs variantes de réponse.

Il y a deux façons de remplir le corps :

Depuis OpenAPI : si le service déclare une spécification OpenAPI (dans le manifeste du micro, ou dérivée de son URL cloud), sélectionnez l’opération et Aseptic génère un modèle du corps.
Manuel : s’il n’y a pas d’OpenAPI, vous écrivez le corps JSON à la main.

L’icône OpenAPI à côté du service ouvre la spécification dans une vue dédiée, avec ses opérations navigables, au lieu de vous laisser le fichier brut.

Groupes et services

Chaque service de l’arbre a sa fiche (« Modifier le service » dans son menu, ou l’engrenage de l’éditeur d’un stub). Dans un groupe créé à la main —pour réunir des stubs qui n’appartiennent à aucune dépendance, comme tous les /notice/...— on modifie le nom, le préfixe, l’URL de base (l’adresse réelle à laquelle correspond le préfixe, c’est là que part l’appel réel) et l’OpenAPI. D’une dépendance, tout se modifie sauf le nom, qui est son identifiant dans les manifestes : le préfixe et l’URL de base sont enregistrés dans le manifeste de chaque micro qui la déclare, et les stubs sous l’ancien préfixe passent au nouveau.

En choisissant une opération de l’OpenAPI, Aseptic déduit le chemin qu’appelle le client même si la spécification déclare un autre préfixe (ses servers, le context-path, un segment commun avec le préfixe du service). Si cette opération a déjà un stub, il n’en crée pas un second : l’existant s’ouvre avec une nouvelle variante issue de l’OpenAPI.

En créant un stub, en plus de partir d’une opération OpenAPI, on peut partir d’un appel déjà arrivé au mock sans stub : il en reprend la méthode et la route.

Le port du serveur de mocks et le jeton pour OpenAPI (envoyé comme Authorization: Bearer pour télécharger des spécifications protégées) sont dans Configuration du mock, dans le menu « ⋮ » de la section.

Variantes : l’unité de travail

Un endpoint peut avoir plusieurs variantes (par exemple une 200 et une 500). Chaque variante a son étiquette, son code d’état, son corps, ses en-têtes et une latence optionnelle en millisecondes pour simuler de la lenteur.

La variante sélectionnée s’étend en ligne avec son corps, ses en-têtes et ses réglages ensemble. La variante qui est servie est marquée à part avec un basculement (elle est indépendante de celle que vous éditez) : c’est la réponse que Aseptic renverra à quiconque appelle cet endpoint.

Au-dessus du corps il y a trois boutons : Formater l’indente (et enregistre cette indentation), Remplir le modèle le génère depuis l’OpenAPI, et Voir formaté l’ouvre dans un grand visualiseur, qui n’édite rien et sert à lire une réponse qui ne tient pas dans le cadre.

Vous pouvez dupliquer une variante pour partir d’une similaire. Un endpoint que vous ne voulez plus servir se supprime depuis son menu.

Des corps de tout type : images, PDF, fichiers

Au-dessus du corps de chaque variante, vous choisissez Texte, Sans corps, Fichier ou Flux :

Texte : avec un sélecteur de format —JSON, texte brut, HTML, XML, JavaScript, CSS, CSV, YAML, Markdown ou formulaire— qui définit le Content-Type servi et donne à chacun sa coloration et son Formater (un formulaire est compacté en a=1&b=2). Un type saisi à la main dans les réglages de la variante rejoint sa famille (application/problem+json est du JSON).
Fichier : une image, un PDF, un zip, un son… n’importe quoi. Cliquez sur Choisir un fichier ou déposez-le dessus, et il est servi octet par octet. Pour une petite image, vous verrez la miniature.
Sans corps : seulement le code et les en-têtes, pour un 204 ou un 304 ; aucun Content-Type n’est inventé.
Flux : la réponse arrive par fragments, chacun après sa pause, pour tester un client qui affiche ou compte pendant la réception. Vous choisissez comment chaque fragment est écrit : Événements SSE (text/event-stream, avec nom d’événement et id facultatifs), NDJSON (un JSON par ligne) ou Texte fragmenté.

La taille décide où il est stocké : jusqu’à 256 Ko il reste dans le catalogue, et voyage donc avec lui ; au-delà, il est copié dans .aseptic/mocks/files/<service>/ et la variante le référence. Sans Content-Type, il est déduit de l’extension (.png → image/png, .pdf → application/pdf) ; les autres en-têtes —Content-Disposition pour forcer un téléchargement, Cache-Control…— se mettent dans En-têtes comme d’habitude. À l’export d’un service ou d’un scénario, les fichiers sont intégrés : ce que vous partagez ne dépend pas de ce dossier.

Règles : répondre selon la requête

Au-dessus des variantes il y a un bloc Règles. Chaque règle dit « quand ces conditions sont remplies, sers cette variante », et elles sont évaluées dans l’ordre : la première qui correspond gagne. Si aucune ne correspond, la variante active est servie — un endpoint sans règles se comporte donc exactement comme avant. La dernière ligne du bloc, fixe, le rappelle.

Une condition regarde une donnée de la requête, sans syntaxe à apprendre : query ou en-tête par leur nom, ou corps par un chemin à points (commande.client.type ; un nombre entre dans une liste, commande.lignes.0.sku). Elle compare avec est égal à, est différent de, existe ou n’existe pas. Toutes les conditions d’une règle doivent tenir ensemble ; pour un « ou », on ajoute une deuxième règle — c’est à ça que sert la liste ordonnée. L’ordre se change avec les flèches de chaque règle : déplacer une règle, c’est changer sa priorité.

Une règle pointe vers une variante par son étiquette, pas par sa position, pour que réordonner les variantes ne change pas en silence ce qui est servi. C’est pourquoi, dans un endpoint avec des règles, deux variantes ne peuvent pas porter la même étiquette. Si vous renommez une variante visée par une règle, la règle est signalée et cesse d’être servie jusqu’à correction.

Tester simule une requête sur place — query, en-têtes et corps — et dit quelle variante sortirait et quelle règle l’a choisie. Le scénario n’a pas besoin de tourner. Et quand il tourne, le dock Appels mock marque chaque appel avec la règle qui l’a décidé, si bien que deux appels identiques aux réponses différentes s’expliquent tout seuls.

Depuis le terminal c’est pareil : aseptic mock probe POST "/v1/commandes?type=premium", avec -H 'X-Vip: 1' pour les en-têtes et -d '{...}' pour le corps.

Enregistrement automatique

L’éditeur de mocks s’enregistre tout seul, avec un léger délai, pendant que vous tapez ; vous verrez un indicateur « Enregistré ». Garde-fous :

Seuls les états valides sont persistés : un corps JSON à moitié écrit ne casse pas le mock servi —le dernier valide est gardé sur disque et l’erreur est marquée en ligne—.
Un stub nouveau n’est pas persisté tant qu’il n’a pas une méthode et un chemin utilisables.
La suppression est toujours explicite, avec confirmation.

Mock Studio : d’un appel réel à un stub

Quand un scénario tourne et qu’un micro appelle un mock qui n’a pas encore de réponse, cet appel apparaît dans le dock Appels mock. De là, vous pouvez créer un stub en un clic à partir de l’appel observé : vous allez droit à l’endpoint que vous voulez compléter, sans le chercher. Vous pouvez aussi tester ce que le mock répondrait sans rien lancer.

Appel réel : capturer la réponse du service

Parfois tu ne veux pas inventer le corps : tu veux celui que renvoie le service réel. Chaque endpoint dispose d’un interrupteur Appel réel. Tant qu’il est activé, cet endpoint ne sert plus sa variante : la requête part vers le service réel, sa réponse est renvoyée telle quelle à l’appelant et enregistrée comme variante « Real » avec son code, qui devient active. Une fois désactivé, le mock rejoue ce que le service a dit en dernier, sans ressortir sur le réseau.

Où il appelle : le microservice du scénario s’il tourne, sinon l’URL cloud de la dépendance. L’icône « i » de l’interrupteur indique la destination exacte ; si le service n’en a aucune, l’interrupteur reste éteint et explique pourquoi.
Verbes qui modifient des données : l’activer sur un POST, un PUT ou un DELETE demande confirmation en nommant la destination. Ce n’est pas interdit —capturer la réponse d’une création est un cas légitime— mais cela s’exécute vraiment là-bas.
Une variante par code : Real 200, Real 404… Capturer mille appels ne crée pas mille variantes ; celle du code reçu est rafraîchie.
Ce qui n’est pas du texte (une image, un PDF) est enregistré comme fichier de la variante ; ce qui dépasse 1 Mo est servi mais pas enregistré.

Les endpoints en capture portent l’étiquette real dans l’arbre, pour qu’aucun ne reste à sortir sur le réseau sans que tu t’en aperçoives.

Importer et exporter

Avec les icônes d’import/export du panneau :

Exporter les endpoints d’un service (ou de plusieurs) vers un fichier JSON.
Importer votre propre JSON ou une collection Postman (ses dossiers se mappent aux services).

Utile pour partager un catalogue de mocks ou le réutiliser entre scénarios.

La même chose depuis le CLI

Tout cela existe aussi dans le CLI : aseptic mock services, mock catalog, mock save, mock set-active, mock skeleton, mock from-call, mock probe, mock capture, mock put-file, mock import / export. Voir la référence du CLI.