Scripts et tests

Les tests vous disent si une réponse est celle que vous attendez. Echolot propose deux façons de les écrire : des vérifications que vous configurez dans l’onglet Tests d’une requête, sans code, et des scripts en JavaScript qui s’exécutent avant l’envoi d’une requête et après sa réponse. Les deux s’exécutent après chaque envoi, dans l’Exécution et en ligne de commande.

Vérifications dans l’onglet TestsCopy Anchor Link

1. Ouvrez une requête, par exemple Catalog › List products dans l’espace de travail Alpenglow.
2. Choisissez l’onglet Tests.
3. Choisissez Ajouter un test et indiquez ce qu’il faut vérifier.
4. Choisissez une comparaison dans le menu à côté et saisissez la valeur attendue.
5. Envoyez la requête. Chaque vérification affiche une coche verte ou une croix rouge, et une vérification en échec en donne la raison en dessous.

Les vérifications sont enregistrées avec la requête et s’exécutent sur chaque réponse à partir de là. La case au début d’une ligne désactive une vérification sans la retirer ; le bouton moins la retire. Le badge de l’onglet Tests compte les vérifications, et le bas de l’onglet indique combien ont réussi, comme 4 réussis ou 1 sur 4 en échec.

La valeur attendue est un modèle : les {{variables}} y fonctionnent. Catalog › Get product vérifie que $.sku est égal à {{productId}}.

Ce que vous pouvez vérifierCopy Anchor Link

Une nouvelle vérification commence avec une valeur raisonnable : État égal à 200, Temps de réponse (ms) inférieur à 1000, Erreurs GraphQL égal à 0, Erreur MCP égal à false, État gRPC égal à OK, et JSON Schema avec {"type": "object"}.

Comment les valeurs se comparentCopy Anchor Link

• est égal à compare les nombres comme des nombres : 200 est égal à 200.0, et ignore les espaces autour de la valeur.
• fait partie de prend une liste séparée par des virgules : 200, 201, 204.
• correspond à la regex réussit quand l’expression régulière correspond n’importe où dans la valeur.
• est de type prend object, array, string, number, integer, boolean ou null.
• Les comparaisons de nombres exigent des nombres des deux côtés ; tout autre cas échoue avec un message qui l’indique.

Valeurs JSONCopy Anchor Link

Le chemin est un JSONPath de clés et d’indices, commençant par $ : $.items[0].sku, $.data.search.totalCount. Un indice négatif compte depuis la fin : $.items[-1]. Ajoutez .length pour compter les éléments d’un tableau ou les clés d’un objet : $.items.length est supérieur à 0. Echolot ne lit que la partie du corps située sur le chemin vers la valeur : les vérifications JSON fonctionnent donc sur des corps de n’importe quelle taille.

Corps avec contient ou ne contient pas fonctionne aussi sur des corps de n’importe quelle taille. Les autres comparaisons du corps, ainsi que JSON Schema et Erreurs GraphQL, lisent le corps entier et s’arrêtent à 50 Mo.

Vérifications pour les autres types de requêteCopy Anchor Link

• GraphQL : les serveurs répondent aux erreurs avec l’état 200 ; ajoutez donc Erreurs GraphQL égal à 0 pour les détecter. Utilisez contient pour vérifier qu’un message précis revient.
• Appels MCP : Erreur MCP égal à false réussit quand l’appel a abouti. Elle échoue sur un résultat marqué comme erreur et sur une erreur JSON-RPC, et le message montre ce que le serveur a dit. Schéma de sortie de l’outil compare le résultat d’un outil au schéma que l’outil déclare ; elle échoue quand l’outil n’en déclare aucun. Voir Requêtes MCP.
• gRPC : État gRPC accepte des noms comme OK et NOT_FOUND ou des codes de 0 à 16 ; 5, not_found et NOT_FOUND sont le même état. Une vérification en échec affiche le message d’état. Voir gRPC.
• Spec OpenAPI : le dossier de la requête (ou un dossier au-dessus) doit être lié à une spec, et la requête doit suivre l’une de ses opérations. La vérification valide alors le corps par rapport au schéma que la spec documente pour l’état reçu. Un état que la spec documente sans corps JSON réussit ; un état non documenté échoue. Voir Specs.

Ajouter des vérifications depuis une réponseCopy Anchor Link

Vous n’avez pas à taper chaque vérification :

• Générer à partir de la réponse… dans l’onglet Tests propose des vérifications d’après la dernière réponse. Les vérifications valables pour toute bonne réponse, comme l’état, le type de contenu et la forme du corps sous forme de JSON Schema, sont déjà cochées. Les valeurs qui changent d’un appel à l’autre, et le temps, sont proposés mais non cochés. Choisissez le schéma déduit pour lire un schéma proposé. Choisissez Ajouter 1 test (ou Ajouter N tests) pour garder ceux qui sont cochés. Envoyez d’abord la requête : le bouton a besoin d’une réponse.
• Dans le Corps de la réponse, en vue Arbre JSON, faites un clic droit sur une valeur et choisissez Ajouter une vérification : cela ajoute une vérification Valeur JSON que le chemin est égal à cette valeur.
• Dans les En-têtes de la réponse, faites un clic droit sur un en-tête et choisissez Ajouter une vérification : cela ajoute une vérification En-tête que l’en-tête est égal à cette valeur.

RésultatsCopy Anchor Link

L’onglet Tests du volet de réponse liste chaque vérification avec son résultat et la valeur trouvée (got 200), puis chaque test des scripts. La page Tests de la barre latérale (Affichage › Tests, ⌥⌘T) liste toutes les requêtes qui ont des vérifications, avec leur état dans la dernière réponse ; cliquez sur l’une d’elles pour ouvrir la requête.

ScriptsCopy Anchor Link

Les scripts sont du JavaScript avec l’API pm.* de Postman : la plupart des scripts Postman s’exécutent donc sans modification. Une requête peut en avoir deux :

• Un script de pré-requête s’exécute avant l’envoi de la requête. Il peut modifier la requête, définir des variables ou ignorer la requête.
• Un script de test s’exécute à l’arrivée de la réponse. Il vérifie la réponse avec pm.test et peut garder des valeurs pour les requêtes suivantes.

1. Ouvrez une requête et choisissez l’onglet Scripts.
2. Choisissez Pré-requête ou Tests en haut. Un point après le nom, comme Tests •, signale un script qui contient du code.
3. Écrivez le script. L’éditeur colore le JavaScript et complète les chemins pm. pendant la saisie. Extraits ajoute un script prêt à l’emploi pour les cas courants.
4. Envoyez la requête.

Par exemple, un script de test pour Catalog › List products :

pm.test("Status code is 200", () => {
  pm.response.to.have.status(200);
});

pm.test("Returns tents", () => {
  const body = pm.response.json();
  pm.expect(body.items.length).to.be.above(0);
});

Et un script de pré-requête qui ajoute un en-tête à chaque requête pour laquelle il s’exécute :

pm.request.headers.add({ key: "X-Request-Id", value: pm.variables.replaceIn("{{$guid}}") });

Chaque pm.test apparaît dans l’onglet Tests de la réponse sous Scripts, après les vérifications de l’onglet Tests. Un script qui lève une exception s’affiche comme Erreur de script avec son message. Ce que les scripts écrivent avec console.log, console.info, console.warn et console.error apparaît dans l’onglet Console de la réponse, marqué pre ou test ; l’onglet est présent dès que des scripts se sont exécutés.

ExtraitsCopy Anchor Link

Scripts sur les dossiers et l’espace de travailCopy Anchor Link

Un dossier et l’espace de travail peuvent aussi avoir des scripts, pour chaque requête qu’ils contiennent. Ouvrez-les depuis le menu contextuel du dossier dans la barre latérale (Réglages du dossier…) ou depuis Réglages de l’espace de travail…, dans l’onglet Scripts.

Pour chaque requête, Echolot exécute d’abord le script de l’espace de travail, puis celui de chaque dossier de l’extérieur vers l’intérieur, puis celui de la requête elle-même. Le même ordre vaut pour les scripts de pré-requête et de test. Seules les requêtes enregistrées exécutent des scripts.

Les appels MCP n’ont pas d’onglet Scripts et n’exécutent aucun script. Tous les autres types de requête en ont un.

L’API pm en un coup d’œilCopy Anchor Link

La liste complète se trouve dans la référence de l’API de scripts.

require fournit lodash, ajv, tv4, crypto-js, uuid, atob et btoa. _ (lodash), tv4, btoa, atob et setTimeout sont aussi disponibles sans lui. Les anciens globaux de Postman (postman.setEnvironmentVariable, tests[...], environment, globals, data, iteration) fonctionnent toujours. Tout autre module échoue avec « The module … is not available in Echolot scripts. »

Variables définies par les scriptsCopy Anchor Link

Ce qu’écrivent pm.environment.set, pm.collectionVariables.set et pm.globals.set est une valeur actuelle : elle vit aussi longtemps que la fenêtre, remplace la valeur enregistrée de cette portée quand les requêtes sont résolues, et n’est jamais écrite dans les fichiers de l’espace de travail. Un jeton qu’un script enregistre atteint donc les requêtes suivantes sans finir dans Git. Pour garder dans l’espace de travail une valeur issue d’une réponse, utilisez plutôt une capture.

pm.variables.set définit une valeur pour l’exécution en cours seulement : une exécution démarre sans les valeurs définies de cette façon par les scripts.

Envoyer une autre requêteCopy Anchor Link

pm.sendRequest envoie une requête depuis un script, par exemple pour aller chercher d’abord un jeton. Elle accepte une URL ou un objet avec url, method, header et body, et soit un callback, soit la promesse qu’elle renvoie :

pm.sendRequest({
  url: pm.variables.replaceIn("{{baseURL}}/auth/token"),
  method: "POST",
  header: { "Content-Type": "application/json" },
  body: { mode: "raw", raw: JSON.stringify({ email: "heidi@alpenglow.ch", password: "alpenglow" }) },
}, (error, response) => {
  if (!error) pm.environment.set("token", response.json().access_token);
});

La requête part comme n’importe quel autre envoi d’Echolot, avec le même proxy et les mêmes certificats, mais sans l’authentification de l’espace de travail ni du dossier. Les scripts attendent les réponses jusqu’à 30 secondes.

Ignorer des requêtes et choisir la suivanteCopy Anchor Link

pm.execution.skipRequest() dans un script de pré-requête empêche l’envoi de la requête ; le volet de réponse et l’Exécution indiquent qu’elle a été ignorée. pm.execution.setNextRequest("Get order") dans une exécution saute ensuite à cette requête, et setNextRequest(null) met fin à l’exécution. Voir l’Exécution.

Scripts venant de l’extérieur d’EcholotCopy Anchor Link

Les scripts sont du code : Echolot n’exécute donc que ceux auxquels vous faites confiance sur ce Mac. Les scripts que vous écrivez dans Echolot sont approuvés dès que vous les enregistrez. Les scripts qui arrivent autrement, par un import, par Git ou par une modification dans un autre éditeur, attendent :

• L’onglet Scripts affiche Ces scripts viennent de l’extérieur d’Echolot, avec Faire confiance aux scripts.
• L’envoi de la requête s’arrête avec Examiner les scripts…. Cela ouvre Exécuter ces scripts ?, avec chaque script qui ne s’est pas encore exécuté et sa provenance (la requête, un dossier ou l’espace de travail). Lisez-les, puis choisissez Faire confiance et envoyer, ou Annuler.

La confiance est conservée sur ce Mac, par espace de travail, pour le code exact : quand le script change hors d’Echolot, la question est reposée. La confiance ne voyage jamais avec l’espace de travail : un espace de travail partagé ne peut donc pas approuver ses propres scripts.

L’outil en ligne de commande exécute tous les scripts de l’espace de travail que vous lui donnez. echolot mcp serve n’exécute que les scripts que l’espace de travail avait à son démarrage.

Le bac à sable et ses limitesCopy Anchor Link

Les scripts s’exécutent dans un bac à sable JavaScript à l’intérieur d’Echolot. Ils n’ont ni système de fichiers, ni réseau propre, ni accès au Mac : les seules issues sont pm.sendRequest, console et les variables. Chaque envoi démarre un nouveau bac à sable.

Un script qui dure trop longtemps échoue avec « the script took longer than 5 s » ; un script qui utilise trop de mémoire échoue avec « the script used more memory than allowed ». Les scripts peuvent toujours lire les variables de l’espace de travail, secrets compris, et les envoyer avec pm.sendRequest : c’est pourquoi les scripts venant de l’extérieur attendent votre confiance.

DépannageCopy Anchor Link

• Générer à partir de la réponse… est grisé : envoyez d’abord la requête. Cela fonctionne pour les requêtes HTTP et GraphQL.
• « aucune spec OpenAPI n’est liée au dossier de cette requête » : liez le dossier à une spec, ou retirez la vérification Spec OpenAPI.
• « “…” n’est pas un JSONPath que cette version comprend » : utilisez uniquement des clés et des indices, comme $.items[0].sku.
• Un script ne s’exécute pas : vérifiez que la requête est enregistrée, que ce n’est pas un appel MCP, et que le script n’attend pas votre confiance.