API de script

Les scripts sont du JavaScript qui s’exécute avant l’envoi d’une requête (pré-requête) ou après l’arrivée de sa réponse (test). Ils utilisent l’API pm de Postman : les scripts des collections Postman s’exécutent donc tels quels. Cette page liste tout. Pour les écrire dans l’app et lire leurs résultats, voir scripts et tests.

Où les scripts s’exécutentCopy Anchor Link

• Les scripts d’une requête sont dans son onglet Scripts, enregistrés sous <slug>.pre.js et <slug>.test.js à côté de la requête. Les dossiers et l’espace de travail ont aussi des scripts (_folder.pre.js, _folder.test.js) ; voir fichiers de l’espace de travail.
• Pour chaque requête, le script de l’espace de travail s’exécute en premier, puis celui de chaque dossier de l’extérieur vers l’intérieur, puis celui de la requête. Tous les scripts d’un même événement partagent un seul bac à sable.
• Les appels MCP n’ont pas de scripts.
• Les scripts venus de l’extérieur d’Echolot (un import, Git, un autre éditeur) ne s’exécutent qu’une fois que vous leur faites confiance : Faire confiance aux scripts, après les avoir lus avec Examiner les scripts….
• L’outil en ligne de commande exécute aussi les scripts, dans echolot run et echolot send.

Le bac à sableCopy Anchor Link

Les scripts s’exécutent dans un moteur JavaScript isolé (QuickJS) à l’intérieur d’Echolot, sans système de fichiers, sans réseau propre et sans modules Node.js. La seule issue est pm.sendRequest, qui envoie via Echolot.

Un script qui lève une exception, ou qui dépasse une limite, est signalé comme une erreur de script, qui compte comme un test en échec.

pm.testCopy Anchor Link

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

pm.test("Has products", () => {
  const body = pm.response.json();
  pm.expect(body.items).to.be.an("array").that.is.not.empty;
});

Les tests des scripts de pré-requête comptent aussi.

pm.expectCopy Anchor Link

pm.expect(value) (ou expect(value)) est une assertion à la Chai. Les échecs se lisent comme ceux de Chai : expected 401 to equal 200.

Les mots de liaison se lisent bien et ne font rien : to, be, been, is, that, which, and, has, have, with, at, of, same, but, does, still, also.

Les indicateurs : not (inverse), deep (compare par valeur), nested (chemins à points dans property), own, any, all, ordered.

Sur une réponse, expect accepte aussi les assertions de réponse de Postman : pm.expect(pm.response).to.have.status(200), .header(name), .jsonBody(…), .body(…), .responseTime(…), et pm.expect(pm.response).to.be.ok, .success, .json et les autres ci-dessous.

pm.responseCopy Anchor Link

Dans les scripts de test, la réponse.

Assertions de réponse : pm.response.to.have.… et pm.response.to.not.have.… :

pm.response.to.be.… :

pm.requestCopy Anchor Link

La requête. Dans un script de pré-requête, les changements qu’on lui apporte sont ce qui est envoyé.

pm.request.headers.upsert({ key: "X-Request-Id", value: pm.variables.replaceIn("{{$guid}}") });
pm.request.url.addQueryParams("per_page=50");

L’objet url a protocol, host (un tableau de libellés), port, path (un tableau de segments), query (une liste), hash, et getHost(), getPath(), getQueryString(), getPathWithQuery(), getRemote(), update(text), addQueryParams(…), removeQueryParams(…), toString(). Une URL que vous ne changez pas garde son texte exact, {{variables}} comprises ; Echolot les résout après les scripts.

VariablesCopy Anchor Link

Chaque portée a get(name), has(name), set(name, value), unset(name), clear(), toObject() et replaceIn(text). set transforme les objets en texte JSON.

pm.variables.get cherche dans cet ordre : les valeurs locales, la ligne de données, les variables du dossier et de la requête, l’environnement, l’espace de travail, les variables globales.

// Pre-request: sign the body
const signature = CryptoJS.HmacSHA256(pm.request.body.raw, pm.environment.get("apiSecret")).toString();
pm.request.headers.upsert({ key: "X-Signature", value: signature });

// Test: keep the new order's ID for the next requests
pm.collectionVariables.set("orderId", pm.response.json().id);

Ce que set conserve. Les valeurs que les scripts définissent sont les « valeurs courantes » de Postman : elles durent le temps de la fenêtre dans l’app, ou de la commande en ligne de commande, et l’emportent sur les valeurs enregistrées de leur portée quand les requêtes sont résolues. Elles ne sont jamais écrites dans les fichiers de l’espace de travail. Pour enregistrer une valeur d’une réponse, utilisez une capture de réponse. Les valeurs locales de pm.variables.set sont oubliées au démarrage d’une exécution.

replaceIn(text) remplit les {{variables}} à partir des portées ci-dessus. Parmi les valeurs dynamiques, il connaît {{$guid}}, {{$randomUUID}}, {{$timestamp}}, {{$isoTimestamp}} et {{$randomInt}} ; toute autre {{$…}} est laissée telle quelle, pour qu’Echolot la résolve à l’envoi de la requête.

pm.infoCopy Anchor Link

pm.sendRequestCopy Anchor Link

Envoie une autre requête depuis un script, via Echolot : les proxys, les certificats et les cookies s’appliquent comme pour n’importe quelle requête.

pm.sendRequest("https://demo.echolot.dev/v1/categories", (error, response) => {
  if (error) { console.error(error); return; }
  pm.collectionVariables.set("firstCategory", response.json().items[0].id);
});

// or with a promise
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: pm.environment.get("password") }) }
}).then(response => {
  pm.environment.set("token", response.json().access_token);
});

• Le premier argument est une URL, ou un objet avec url, method (GET par défaut), header (un tableau de { key, value }, un objet, ou une liste) et body.
• body est une chaîne, { mode: "raw", raw }, { mode: "urlencoded", urlencoded: [{ key, value }] } ou { mode: "graphql", graphql: { query, variables } }. Les deux derniers définissent leur Content-Type si vous ne le faites pas.
• Les {{variables}} de l’URL sont remplies, avec l’environnement de la requête.
• Le rappel reçoit (error, response) ; response ressemble à pm.response. Sans rappel, elle renvoie une promesse.
• La requête n’a pas d’auth propre (l’auth de l’espace de travail ne s’applique pas) et n’exécute aucun script.
• Le pm.sendRequest d’un agent passe par les approbations de l’agent, comme ses autres envois.

Contrôler une exécutionCopy Anchor Link

pm.cookiesCopy Anchor Link

Les cookies de cet échange : ceux que la requête a envoyés et ceux que la réponse a définis. Une liste, avec pm.cookies.get(name), has(name), toObject(), et one(name) qui renvoie { name, key, value }.

ListesCopy Anchor Link

Les en-têtes, les paramètres de requête et les cookies sont des listes de propriétés Postman :

consoleCopy Anchor Link

console.log, info, warn, error, debug et trace écrivent dans la Console de la requête, et en ligne de commande sous ── console ──. Les objets sont écrits en JSON.

MinuteriesCopy Anchor Link

setTimeout, setInterval et setImmediate exécutent leurs fonctions après le script, dans l’ordre de leurs délais, sans attendre réellement. setInterval s’exécute une fois. clearTimeout et les autres annulent.

JSON SchemaCopy Anchor Link

Trois façons, toutes sur le validateur JSON Schema propre à Echolot :

const schema = {
  type: "object",
  required: ["sku", "price"],
  properties: { sku: { type: "string" }, price: { type: "object" } }
};

// Chai
pm.expect(pm.response.json()).to.have.jsonSchema(schema);

// ajv
const Ajv = require("ajv");
const validate = new Ajv().compile(schema);
pm.test("Matches the schema", () => pm.expect(validate(pm.response.json()), JSON.stringify(validate.errors)).to.be.true);

// tv4
pm.test("Matches the schema", () => pm.expect(tv4.validate(pm.response.json(), schema)).to.be.true);

Une vérification JSON Schema fonctionne aussi sans script : la vérification JSON Schema de l’onglet Tests.

BibliothèquesCopy Anchor Link

Les anciens globaux PostmanCopy Anchor Link

Les scripts d’anciennes collections les utilisent, et ils fonctionnent :

Ce qui n’y est pasCopy Anchor Link

• Les autres modules : require de tout ce qui n’est pas listé ci-dessus (cheerio, xml2js, moment, les modules propres à Node) lève l’exception « The module … is not available in Echolot scripts. »
• L’attente réelle : les minuteries s’exécutent sans délai, et il n’y a ni fetch ni XMLHttpRequest. Utilisez pm.sendRequest.
• Les fichiers et les processus : les scripts ne peuvent ni lire ni écrire de fichiers, ni lancer de programmes.
• pm.visualizer.set est accepté : les scripts qui l’utilisent s’exécutent donc, mais Echolot n’affiche aucune visualisation.
• xml2Json, pm.require et la bibliothèque de paquets de Postman, et pm.vault.
• Les secrets dans les fichiers : les scripts lisent les variables secrètes comme n’importe quelle autre, mais ce qu’ils définissent avec set n’atteint jamais les fichiers de l’espace de travail.