API de scripts

Los scripts son JavaScript que se ejecuta antes de enviar una solicitud (previo a la solicitud) o cuando llega su respuesta (de prueba). Usan la API pm de Postman, así que los scripts de las colecciones de Postman se ejecutan tal cual. Esta página lista todo. Para escribirlos en la app y leer sus resultados, consulta scripts y pruebas.

Dónde se ejecutan los scriptsCopy Anchor Link

• Los scripts de una solicitud están en su pestaña Scripts, guardados como <slug>.pre.js y <slug>.test.js junto a la solicitud. Las carpetas y el espacio de trabajo también tienen scripts (_folder.pre.js, _folder.test.js); consulta archivos del espacio de trabajo.
• Para cada solicitud, se ejecuta primero el script del espacio de trabajo, después el de cada carpeta de fuera adentro y, por último, el de la propia solicitud. Todos los scripts de un mismo evento comparten un sandbox.
• Las llamadas MCP no tienen scripts.
• Los scripts que llegaron de fuera de Echolot (una importación, Git, otro editor) se ejecutan solo cuando confías en ellos: Confiar en los scripts, tras leerlos con Revisar scripts….
• La herramienta de línea de comandos también ejecuta scripts, en echolot run y echolot send.

El sandboxCopy Anchor Link

Los scripts se ejecutan en un motor de JavaScript aislado (QuickJS) dentro de Echolot, sin sistema de archivos, sin red propia y sin módulos de Node.js. La única salida es pm.sendRequest, que envía a través de Echolot.

Un script que lanza una excepción, o que supera un límite, se notifica como un error de script, que cuenta como una prueba fallida.

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;
});

Las pruebas de los scripts previos a la solicitud también cuentan.

pm.expectCopy Anchor Link

pm.expect(value) (o expect(value)) es una aserción al estilo de Chai. Los fallos se leen como los de Chai: expected 401 to equal 200.

Palabras de encadenamiento, que se leen bien y no hacen nada: to, be, been, is, that, which, and, has, have, with, at, of, same, but, does, still, also.

Indicadores: not (niega), deep (compara por valor), nested (rutas con puntos en property), own, any, all, ordered.

En una respuesta, expect también admite las aserciones de respuesta de Postman: pm.expect(pm.response).to.have.status(200), .header(name), .jsonBody(…), .body(…), .responseTime(…), y pm.expect(pm.response).to.be.ok, .success, .json y los demás de más abajo.

pm.responseCopy Anchor Link

En los scripts de prueba, la respuesta.

Aserciones de respuesta: pm.response.to.have.… y pm.response.to.not.have.…:

pm.response.to.be.…:

pm.requestCopy Anchor Link

La solicitud. En un script previo a la solicitud, los cambios que le hagas son lo que se envía.

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

El objeto url tiene protocol, host (un array de etiquetas), port, path (un array de segmentos), query (una lista), hash, y getHost(), getPath(), getQueryString(), getPathWithQuery(), getRemote(), update(text), addQueryParams(…), removeQueryParams(…), toString(). Una URL que no cambias conserva su texto exacto, {{variables}} incluidas; Echolot las resuelve después de los scripts.

VariablesCopy Anchor Link

Cada ámbito tiene get(name), has(name), set(name, value), unset(name), clear(), toObject() y replaceIn(text). set convierte los objetos en texto JSON.

pm.variables.get busca en este orden: valores locales, la fila de datos, variables de carpeta y de solicitud, el entorno, el espacio de trabajo, las 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);

Qué conserva set. Los valores que fijan los scripts son los “valores actuales” de Postman: duran lo que dure la ventana de la app, o el comando en la línea de comandos, y prevalecen sobre los valores guardados de su ámbito cuando se resuelven las solicitudes. Nunca se escriben en los archivos del espacio de trabajo. Para guardar un valor de una respuesta, usa una captura de respuesta. Los valores locales de pm.variables.set se olvidan cuando empieza una ejecución.

replaceIn(text) rellena las {{variables}} de los ámbitos anteriores. De los valores dinámicos, conoce {{$guid}}, {{$randomUUID}}, {{$timestamp}}, {{$isoTimestamp}} y {{$randomInt}}; cualquier otro {{$…}} se deja como está, para que Echolot lo resuelva al enviar la solicitud.

pm.infoCopy Anchor Link

pm.sendRequestCopy Anchor Link

Envía otra solicitud desde un script, a través de Echolot: se aplican los proxies, los certificados y las cookies como en cualquier solicitud.

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);
});

• El primer argumento es una URL, o un objeto con url, method (GET por omisión), header (un array de { key, value }, un objeto o una lista) y body.
• body es una cadena, { mode: "raw", raw }, { mode: "urlencoded", urlencoded: [{ key, value }] } o { mode: "graphql", graphql: { query, variables } }. Los dos últimos fijan su Content-Type cuando no lo haces tú.
• Las {{variables}} de la URL se rellenan, con el entorno de la solicitud.
• La función de retorno recibe (error, response); response es como pm.response. Sin función de retorno, devuelve una promesa.
• La solicitud no tiene autenticación propia (no se aplica la del espacio de trabajo) y no ejecuta scripts.
• El pm.sendRequest de un agente pasa por las aprobaciones del agente, como sus otros envíos.

Controlar una ejecuciónCopy Anchor Link

pm.cookiesCopy Anchor Link

Las cookies de este intercambio: las que envió la solicitud y las que fijó la respuesta. Una lista, con pm.cookies.get(name), has(name), toObject() y one(name), que devuelve { name, key, value }.

ListasCopy Anchor Link

Las cabeceras, los parámetros de consulta y las cookies son listas de propiedades de Postman:

consoleCopy Anchor Link

console.log, info, warn, error, debug y trace escriben en la Consola de la solicitud, y en la línea de comandos bajo ── console ──. Los objetos se escriben como JSON.

TemporizadoresCopy Anchor Link

setTimeout, setInterval y setImmediate ejecutan sus funciones después del script, en el orden de sus retrasos, sin esperar de verdad. setInterval se ejecuta una vez. clearTimeout y los demás los cancelan.

JSON SchemaCopy Anchor Link

Tres formas, todas con el validador de JSON Schema propio de 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);

Una comprobación de JSON Schema también funciona sin script: la comprobación JSON Schema de la pestaña Pruebas.

BibliotecasCopy Anchor Link

Los antiguos globales de PostmanCopy Anchor Link

Los scripts de colecciones más antiguas los usan, y funcionan:

Lo que no hayCopy Anchor Link

• Otros módulos: un require de cualquier cosa que no esté en la lista anterior (cheerio, xml2js, moment, los módulos propios de Node) lanza “The module … is not available in Echolot scripts.”
• Esperas reales: los temporizadores se ejecutan sin retraso, y no hay fetch ni XMLHttpRequest. Usa pm.sendRequest.
• Archivos y procesos: los scripts no pueden leer ni escribir archivos ni iniciar programas.
• pm.visualizer.set se acepta, así que los scripts que lo usan se ejecutan, pero Echolot no muestra ninguna visualización.
• xml2Json, pm.require y la biblioteca de paquetes de Postman, y pm.vault.
• Secretos en archivos: los scripts leen las variables secretas como cualquier otra, pero lo que set fija nunca llega a los archivos del espacio de trabajo.