Mocks

Un mock est un serveur, sur un port de votre Mac, qui répond comme une API. Les front-ends, les apps et les tests peuvent l’utiliser avant que l’API n’existe, ou pendant que la vraie est en panne. Un mock répond à partir de deux sources, seules ou ensemble :

• Des routes que vous créez à la main : une méthode, un chemin, et le JSON, le XML ou le texte qu’il répond. Les corps peuvent contenir des données fictives ({{$randomFullName}}, {{$randomEmail}}) qui changent à chaque requête, et des éléments de la requête ({{request.params.id}}). Aucune spec n’est nécessaire. Voir routes et données fictives.
• Une spec OpenAPI : chaque opération répond avec les réponses que la spec documente, ses exemples ou un corps généré à partir de ses schémas. Les requêtes qui ne respectent pas la spec reçoivent un 400 qui explique pourquoi : le mock vous dit donc aussi quand un client envoie quelque chose d’incorrect.

Pour des réponses qui demandent du code ou un état, un mock peut aussi avoir des routes en JavaScript.

Ouvrez la page avec Mocks dans le sélecteur de module de la barre latérale, ou avec ⌘4.

Créer un mockCopy Anchor Link

Cliquez sur + dans l’en-tête Mocks de la barre latérale, ou utilisez les boutons de la page vide :

• Nouveau mock crée un mock de routes. Il démarre avec une route, GET /users, qui répond avec cinq utilisateurs fictifs : vous pouvez le démarrer et voir ce qu’un corps peut faire. Modifiez-la ou ajoutez les vôtres ; voir routes et données fictives.
• Mock de spec (dans le menu +, ou Mock d’une spec sur la page vide) crée un mock d’une spec de l’espace de travail, par exemple Mock de Alpenglow demo shop.

Le nouveau mock prend le premier port libre à partir de 4010. Ses réglages et ses routes sont un fichier du dossier mocks de l’espace de travail : une équipe partage donc ses mocks par Git.

Un mock de routes peut aussi servir une spec, et un mock de spec peut avoir des routes : Servir une spec dans la carte Réglages en ajoute une, Changer › Ne plus servir la spec la retire.

Démarrer et arrêterCopy Anchor Link

Cliquez sur Démarrer (⌘R). La barre en haut indique l’adresse du mock, par exemple http://127.0.0.1:4010. Quand le mock sert une spec dont l’URL de serveur comporte un chemin (https://demo.echolot.dev/v1), l’adresse se termine par ce chemin (http://127.0.0.1:4010/v1) et le mock répond en dessous ; les requêtes peuvent aussi omettre ce chemin. Le bouton de copie à côté de l’adresse la copie.

Essayez-le depuis Terminal :

curl http://127.0.0.1:4010/users

Arrêter l’arrête. La barre latérale indique quels mocks tournent : un point vert, et le port à côté du titre de la spec ou du nombre de routes (Alpenglow demo shop · :4010, 3 routes · stopped). Faites un clic droit sur un mock pour Démarrer ou Arrêter et Supprimer…. Supprimer demande d’abord confirmation ; le fichier de réglages va dans la corbeille et la spec reste.

Les mocks tournent tant que la fenêtre de leur espace de travail est ouverte. Un mock en cours d’exécution prend en compte les changements de ses routes, de sa spec et de ses réglages sans s’arrêter. Un port qu’un autre programme utilise ne peut pas être pris : Echolot vous le dit ; choisissez un autre port.

Envoyer des requêtes au mockCopy Anchor Link

• Créer des requêtes dans la carte Routes crée un dossier de requêtes qui appellent les routes du mock, avec {{baseUrl}} réglé sur l’adresse du mock. Voir requêtes à partir de routes.
• Utiliser dans un environnement (pendant que le mock tourne) crée un environnement nommé Mock: <name> dont {{baseUrl}} est l’adresse du mock, et le rend actif. Les requêtes qui commencent par {{baseUrl}}, comme celles que Générer les requêtes crée à partir d’une spec, vont alors au mock jusqu’à ce que vous choisissiez un autre environnement. Voir Environnements.

RéglagesCopy Anchor Link

Quelle réponse reçoit une requêteCopy Anchor Link

Une requête va au premier de ces éléments qui a une réponse pour sa méthode et son chemin :

1. Les routes en JavaScript du mock. Une route qui ne définit rien transmet la requête.
2. Ses routes créées à la main. Une route peut avoir plusieurs réponses ; une requête peut en demander une par son nom ou son état, des règles sur la requête en choisissent d’autres, et sinon c’est la réponse par défaut de la route qui répond.
3. Les opérations de la spec, comme ci-dessous.

Les segments de chemin littéraux l’emportent sur les paramètres : /pets/mine est choisi avant /pets/{id}, pour les routes comme pour les opérations.

Pour une opération de la spec, le mock choisit la réponse dans cet ordre :

1. Ce que la requête demande : un en-tête Prefer: code=404, example=empty, ou les en-têtes x-mock-response-code et x-mock-response-name de Postman.
2. La réponse choisie pour l’opération dans la carte Réponses de la spec.
3. La première réponse de succès de l’opération.

La carte Réponses de la spec liste chaque opération avec un menu : Premier succès, ou l’un des états documentés, et pour un état qui a plusieurs exemples, l’exemple. Le choix est enregistré avec le mock.

Le corps est l’exemple nommé de la réponse (celui qui est demandé, ou le premier), son unique example, ou à défaut un corps généré à partir de son schéma : des données fictives adaptées au type, au format et au nom de chaque champ (une adresse e-mail pour un champ de format email), dans les limites du schéma, régénérées à chaque requête. Un champ nommé comme un paramètre de chemin le reprend. Quand la spec documente plusieurs types de média, l’en-tête Accept de la requête en choisit un. Les en-têtes documentés et le type de contenu sont envoyés eux aussi. Un 204, un 304 et les réponses à HEAD n’ont pas de corps.

Autres réponses que donne le mock :

Les navigateurs peuvent appeler le mock depuis une page sur un autre port : il répond aux requêtes preflight et envoie les en-têtes CORS.

Le journalCopy Anchor Link

Le bas de la page liste les requêtes auxquelles le mock sélectionné a répondu, la plus récente d’abord : l’heure, l’état, la méthode et le chemin, la réponse utilisée (le nom de la réponse d’une route, le nom d’un exemple de la spec, ou generated quand le corps vient du schéma) et le temps que cela a pris. Les problèmes sont sur les lignes sous une requête : là où elle ne respectait pas la spec, ou une valeur fictive que le corps d’une route n’a pas pu produire. Placez le pointeur sur une requête pour voir le corps de la réponse, le corps de la requête et le type de contenu ; Copier la réponse copie le corps. Effacer vide le journal.

Là où le modèle intégré d’Apple est disponible, le bouton à côté de Effacer résume le journal.

Enregistrer des exemples dans la specCopy Anchor Link

Pour les opérations d’une spec, la spec est la seule source de ce que le mock répond : une vraie réponse que vous avez obtenue y est donc enregistrée comme exemple. Dans l’historique, faites un clic droit sur un échange d’une requête qui suit la spec et choisissez Enregistrer comme exemple de mock…. Donnez-lui un nom, par exemple two tents, et cliquez sur Enregistrer.

La réponse devient un exemple nommé de la réponse de son opération dans la spec que suit la requête. Choisissez-le dans la carte Réponses de la spec, ou demandez-le avec Prefer: example=two tents.

Pour un chemin que la spec n’a pas, ou pour un mock sans spec, créez une route et collez le corps.

Partager sur le réseauCopy Anchor Link

Activez Répondre aux autres appareils du réseau pour accéder au mock depuis un téléphone, une tablette ou un conteneur. Les autres appareils utilisent l’adresse de votre Mac sur le réseau local, avec le port du mock.

La première fois, macOS peut demander si Echolot peut trouver des appareils sur votre réseau local et s’y connecter. Autorisez-le, sinon les autres appareils ne peuvent pas joindre le mock. Vous pouvez changer la réponse plus tard dans Réglages Système › Confidentialité et sécurité › Réseau local.

Toute personne sur le réseau peut alors appeler le mock. Désactivez le partage quand vous n’en avez pas besoin.

En ligne de commandeCopy Anchor Link

echolot mock alpenglow.yaml sert un fichier de spec, et echolot mock -w <workspace> <mock> sert un mock d’un espace de travail avec ses réglages et ses routes, avec ou sans spec, pour la CI ou un conteneur. Voir echolot mock. echolot fake génère des données fictives à partir des mêmes modèles, pour des fixtures et des données de départ.

Les agents peuvent démarrer des mocks et lire leurs journaux via le serveur MCP d’Echolot et, quand l’ensemble d’outils Mocks est activé, créer des mocks, ajouter et modifier des routes, générer des données fictives et créer des requêtes à partir de routes. Voir Agents.