Skript-API

Skripte sind JavaScript, das läuft, bevor eine Anfrage gesendet wird (Pre-Request), oder nachdem ihre Antwort eingetroffen ist (Test). Sie verwenden die pm-API von Postman, sodass Skripte aus Postman-Sammlungen unverändert laufen. Diese Seite listet sie vollständig auf. Wie du sie in der App schreibst und ihre Ergebnisse liest, steht unter Skripte und Tests.

Wo Skripte laufenCopy Anchor Link

• Die Skripte einer Anfrage stehen in ihrem Tab Skripte und sind neben der Anfrage als <slug>.pre.js und <slug>.test.js gesichert. Auch Ordner und der Arbeitsbereich haben Skripte (_folder.pre.js, _folder.test.js); siehe Arbeitsbereichsdateien.
• Für jede Anfrage läuft zuerst das Skript des Arbeitsbereichs, dann das jedes Ordners von außen nach innen, dann das der Anfrage selbst. Alle Skripte eines Ereignisses teilen sich eine Sandbox.
• MCP-Aufrufe haben keine Skripte.
• Skripte, die von außerhalb von Echolot kamen (Import, Git, ein anderer Editor), laufen erst, wenn du ihnen vertraust: Skripten vertrauen, nachdem du sie mit Skripte prüfen … gelesen hast.
• Auch das Befehlszeilenwerkzeug führt Skripte aus, in echolot run und echolot send.

Die SandboxCopy Anchor Link

Skripte laufen in einer abgeschotteten JavaScript-Engine (QuickJS) in Echolot, ohne Dateisystem, ohne eigenes Netzwerk und ohne Node.js-Module. Der einzige Weg nach draußen ist pm.sendRequest, das über Echolot sendet.

Ein Skript, das eine Ausnahme wirft oder eine Grenze überschreitet, wird als Skriptfehler gemeldet, der als fehlgeschlagener Test zählt.

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

Tests in Pre-Request-Skripten zählen ebenfalls.

pm.expectCopy Anchor Link

pm.expect(value) (oder expect(value)) ist eine Assertion im Stil von Chai. Fehlschläge lesen sich wie bei Chai: expected 401 to equal 200.

Füllwörter, die sich gut lesen und nichts bewirken: to, be, been, is, that, which, and, has, have, with, at, of, same, but, does, still, also.

Flags: not (negiert), deep (vergleicht nach Wert), nested (Pfade mit Punkten in property), own, any, all, ordered.

Bei einer Antwort nimmt expect auch die Antwort-Assertions von Postman an: pm.expect(pm.response).to.have.status(200), .header(name), .jsonBody(…), .body(…), .responseTime(…) und pm.expect(pm.response).to.be.ok, .success, .json und die übrigen weiter unten.

pm.responseCopy Anchor Link

In Test-Skripten die Antwort.

Antwort-Assertions: pm.response.to.have.… und pm.response.to.not.have.…:

pm.response.to.be.…:

pm.requestCopy Anchor Link

Die Anfrage. In einem Pre-Request-Skript wird gesendet, was du an ihr änderst.

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

Das url-Objekt hat protocol, host (ein Array von Labels), port, path (ein Array von Segmenten), query (eine Liste), hash und getHost(), getPath(), getQueryString(), getPathWithQuery(), getRemote(), update(text), addQueryParams(…), removeQueryParams(…), toString(). Eine URL, die du nicht änderst, behält ihren genauen Text, einschließlich {{variables}}; Echolot löst sie nach den Skripten auf.

VariablenCopy Anchor Link

Jeder Bereich hat get(name), has(name), set(name, value), unset(name), clear(), toObject() und replaceIn(text). set wandelt Objekte in JSON-Text um.

pm.variables.get sucht in dieser Reihenfolge: lokale Werte, die Datenzeile, Ordner- und Anfragevariablen, die Umgebung, der Arbeitsbereich, globale Variablen.

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

Was set behält. Werte, die Skripte setzen, sind die „aktuellen Werte“ von Postman: Sie halten für das Fenster in der App oder für den Befehl in der Befehlszeile und haben Vorrang vor den gesicherten Werten ihres Bereichs, wenn Anfragen aufgelöst werden. Sie werden nie in die Dateien des Arbeitsbereichs geschrieben. Um einen Wert aus einer Antwort zu sichern, verwende eine Erfassung aus Antworten. Lokale Werte aus pm.variables.set werden vergessen, wenn ein Durchlauf beginnt.

replaceIn(text) füllt {{variables}} aus den obigen Bereichen. Von den dynamischen Werten kennt es {{$guid}}, {{$randomUUID}}, {{$timestamp}}, {{$isoTimestamp}} und {{$randomInt}}; jedes andere {{$…}} bleibt, wie es ist, damit Echolot es beim Senden der Anfrage auflöst.

pm.infoCopy Anchor Link

pm.sendRequestCopy Anchor Link

Sendet aus einem Skript eine weitere Anfrage über Echolot: Proxys, Zertifikate und Cookies gelten wie bei jeder Anfrage.

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

• Das erste Argument ist eine URL oder ein Objekt mit url, method (Standard GET), header (ein Array aus { key, value }, ein Objekt oder eine Liste) und body.
• body ist ein String, { mode: "raw", raw }, { mode: "urlencoded", urlencoded: [{ key, value }] } oder { mode: "graphql", graphql: { query, variables } }. Die letzten beiden setzen ihren Content-Type, wenn du es nicht tust.
• {{variables}} in der URL werden ausgefüllt, mit der Umgebung der Anfrage.
• Der Callback bekommt (error, response); response gleicht pm.response. Ohne Callback gibt die Funktion ein Promise zurück.
• Die Anfrage hat keine eigene Auth (die Auth des Arbeitsbereichs gilt nicht) und führt keine Skripte aus.
• Das pm.sendRequest eines Agenten läuft über die Genehmigungen des Agenten, wie seine anderen Sendungen.

Einen Durchlauf steuernCopy Anchor Link

pm.cookiesCopy Anchor Link

Die Cookies dieses Austauschs: die, die die Anfrage gesendet hat, und die, die die Antwort gesetzt hat. Eine Liste, mit pm.cookies.get(name), has(name), toObject() und one(name), das { name, key, value } zurückgibt.

ListenCopy Anchor Link

Header, Query-Parameter und Cookies sind Property-Listen von Postman:

consoleCopy Anchor Link

console.log, info, warn, error, debug und trace schreiben in die Konsole der Anfrage und in der Befehlszeile unter ── console ──. Objekte werden als JSON geschrieben.

TimerCopy Anchor Link

setTimeout, setInterval und setImmediate führen ihre Funktionen nach dem Skript aus, in der Reihenfolge ihrer Verzögerungen, ohne wirklich zu warten. setInterval läuft einmal. clearTimeout und die anderen brechen ab.

JSON SchemaCopy Anchor Link

Drei Wege, alle mit dem eigenen JSON-Schema-Validator von 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);

Eine JSON-Schema-Prüfung funktioniert auch ohne Skript: die Prüfung JSON Schema im Tab Tests.

BibliothekenCopy Anchor Link

Die alten Postman-GlobalsCopy Anchor Link

Skripte aus älteren Sammlungen verwenden diese, und sie funktionieren:

Was nicht dabei istCopy Anchor Link

• Andere Module: require von allem, was oben nicht aufgeführt ist (cheerio, xml2js, moment, die eigenen Module von Node), wirft „The module … is not available in Echolot scripts.“
• Echtes Warten: Timer laufen ohne Verzögerung, und es gibt kein fetch und kein XMLHttpRequest. Verwende pm.sendRequest.
• Dateien und Prozesse: Skripte können keine Dateien lesen oder schreiben und keine Programme starten.
• pm.visualizer.set wird angenommen, sodass Skripte, die es verwenden, laufen, aber Echolot zeigt keine Visualisierung.
• xml2Json, pm.require und die Paketbibliothek von Postman sowie pm.vault.
• Secrets in Dateien: Skripte lesen geheime Variablen wie alle anderen, aber was sie mit set setzen, erreicht nie die Dateien des Arbeitsbereichs.