Routes en JavaScript

Les routes créées à la main et une spec répondent avec des réponses que vous écrivez à l’avance. Parfois un mock doit faire plus : se souvenir de la commande qu’un client vient de passer, calculer une réponse, ou échouer au troisième appel. Les Routes en JavaScript sont de petits gestionnaires qui répondent en premier aux requêtes d’un mock. Leurs variables vivent tant que le mock tourne : elles peuvent donc garder un état d’une requête à l’autre. Tout ce qu’une route ne gère pas passe aux routes créées à la main du mock, puis à sa spec.

Écrire des routesCopy Anchor Link

Ouvrez un mock sur la page Mocks et faites défiler jusqu’à la carte Routes en JavaScript. Écrivez les routes dans l’éditeur, puis cliquez sur Enregistrer les routes. Revenir revient à ce qui était enregistré.

Cet exemple, pour un mock de la spec Alpenglow, garde les commandes qu’un client passe et les renvoie par ID :

let orders = []

mock.post("/orders", (req, res) => {
  const order = { id: "ord_" + (orders.length + 1), status: "pending", ...req.json() }
  orders.push(order)
  res.status(201).header("Location", "/v1/orders/" + order.id).json(order)
})

mock.get("/orders/:id", (req, res) => {
  const order = orders.find(o => o.id === req.params.id)
  return order ?? res.status(404).json({ error: "no such order" })
})

Après un enregistrement, la carte liste les routes que le script a enregistrées (Running: POST /orders, GET /orders/:id) ou, en orange, la raison pour laquelle le script ne s’est pas chargé. Les routes sont conservées dans mocks/<name>.js à côté des réglages du mock : elles vont donc dans Git avec l’espace de travail.

Quand les routes s’exécutentCopy Anchor Link

• Les routes en JavaScript répondent en premier, avant les routes créées à la main et la spec. La première route dont la méthode et le chemin correspondent répond.
• Les chemins sont sous le chemin de serveur de la spec, quand le mock sert une spec : écrivez /orders, pas /v1/orders.
• Une route qui ne définit rien et ne renvoie rien transmet la requête aux routes créées à la main et à la spec, qui répondent comme d’habitude. Utilisez-le pour ne gérer que certaines requêtes, par exemple un seul paramètre de requête.
• Le script s’exécute une fois au démarrage du mock. Ses variables de niveau supérieur, et l’objet state, vivent jusqu’à l’arrêt du mock.
• L’enregistrement redémarre les routes, avec un état neuf. Les changements de la spec, des routes créées à la main ou des réglages du mock le conservent.
• Les requêtes sont traitées une par une : l’état reste donc cohérent.

Le journal du mock marque chaque requête qu’une route a traitée avec le nom de la route : placez le pointeur dessus pour voir Traitée par cette route ou Transmise par cette route (aux routes créées à la main ou à la spec). Ce qu’une route écrit avec console.log apparaît dans le journal sous la requête.

L’API des routesCopy Anchor Link

Enregistrez des routes avec mock et une méthode :

Dans un chemin, :name correspond à un segment et le place dans req.params.name ; * correspond au reste.

Un gestionnaire reçoit req et res :

Chaque fonction de res renvoie res : les appels s’enchaînent donc, res.status(201).json(order). Une valeur que le gestionnaire renvoie est envoyée en JSON : return order revient donc à res.json(order). Les gestionnaires peuvent être async.

state (aussi mock.state) est un objet conservé d’une requête à l’autre, pour ce que vous préférez ne pas garder dans une variable à vous :

mock.get("/me", (req, res) => {
  state.calls = (state.calls ?? 0) + 1
  if (state.calls % 3 === 0) return res.status(503).json({ error: "try again" })
  // Nothing set: the routes made by hand or the spec answer this request.
})

LimitesCopy Anchor Link

Les routes s’exécutent dans le même bac à sable que les scripts de requête, pas dans Node : pas de système de fichiers et pas de réseau. Chaque requête peut exécuter du JavaScript pendant 2 secondes, et le script a 2 secondes pour démarrer. Un gestionnaire qui lève une exception répond 500 avec l’erreur, qui apparaît aussi dans le journal.

Faire confiance aux routesCopy Anchor Link

Les routes sont du code qui s’exécute sur votre Mac : elles suivent donc la même règle que les scripts de requête. Les routes que vous écrivez et enregistrez dans Echolot s’exécutent. Celles qui viennent de l’extérieur, par Git, par un import ou parce qu’une autre app a modifié le fichier, ne s’exécutent pas : la carte indique Ces scripts viennent de l’extérieur d’Echolot, et le mock ne démarre pas tant que vous ne les avez pas lues et cliqué sur Faire confiance aux scripts. S’ils changent de nouveau en dehors d’Echolot, Echolot redemande.

Les agents peuvent lire les routes d’un mock, mais jamais les écrire.

En ligne de commandeCopy Anchor Link

echolot mock -w <workspace> <mock> exécute un mock d’un espace de travail avec toutes ses routes ; --routes <file> exécute des routes en JavaScript d’un autre fichier, aussi avec un fichier de spec. Voir echolot mock.