Scripting API

Скрипты — это JavaScript, который выполняется перед отправкой запроса (скрипты перед запросом) или после получения ответа (тестовые скрипты). Они используют API pm из Postman, поэтому скрипты из коллекций Postman запускаются без изменений. На этой странице перечислено всё. О том, как писать их в приложении и читать результаты, см. скрипты и тесты.

Где выполняются скриптыCopy Anchor Link

• Скрипты запроса находятся на его вкладке Скрипты и сохраняются как <slug>.pre.js и <slug>.test.js рядом с запросом. Скрипты есть и у папок, и у рабочего пространства (_folder.pre.js, _folder.test.js); см. файлы рабочего пространства.
• Для каждого запроса сначала выполняется скрипт рабочего пространства, затем скрипты папок снаружи внутрь, затем собственный скрипт запроса. Все скрипты одного события работают в одной песочнице.
• У вызовов MCP скриптов нет.
• Скрипты, пришедшие извне Echolot (импорт, Git, другой редактор), выполняются, только когда вы им доверитесь: Доверять скриптам, после того как прочитаете их через Просмотреть скрипты….
• Утилита командной строки тоже запускает скрипты — в echolot run и echolot send.

ПесочницаCopy Anchor Link

Скрипты выполняются в изолированном движке JavaScript (QuickJS) внутри Echolot: без файловой системы, без собственной сети и без модулей Node.js. Единственный выход наружу — pm.sendRequest, который отправляет запрос через Echolot.

Скрипт, который выбрасывает исключение или превышает ограничение, считается ошибкой скрипта, а она засчитывается как непройденный тест.

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

Тесты в скриптах перед запросом тоже учитываются.

pm.expectCopy Anchor Link

pm.expect(value) (или expect(value)) — утверждение в стиле Chai. Сообщения о сбоях читаются так же, как у Chai: expected 401 to equal 200.

Слова-связки, которые улучшают читаемость и ничего не делают: to, be, been, is, that, which, and, has, have, with, at, of, same, but, does, still, also.

Флаги: not (отрицание), deep (сравнение по значению), nested (пути с точками в property), own, any, all, ordered.

Для ответа expect принимает и утверждения Postman об ответе: pm.expect(pm.response).to.have.status(200), .header(name), .jsonBody(…), .body(…), .responseTime(…), а также pm.expect(pm.response).to.be.ok, .success, .json и остальные, перечисленные ниже.

pm.responseCopy Anchor Link

В тестовых скриптах — ответ.

Утверждения об ответе: pm.response.to.have.… и pm.response.to.not.have.…:

pm.response.to.be.…:

pm.requestCopy Anchor Link

Запрос. В скрипте перед запросом то, что вы в нём измените, и будет отправлено.

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

У объекта url есть protocol, host (массив меток), port, path (массив сегментов), query (список), hash, а также getHost(), getPath(), getQueryString(), getPathWithQuery(), getRemote(), update(text), addQueryParams(…), removeQueryParams(…), toString(). URL, который вы не меняете, сохраняет свой точный текст, включая {{variables}}; Echolot подставляет их после скриптов.

ПеременныеCopy Anchor Link

У каждой области есть get(name), has(name), set(name, value), unset(name), clear(), toObject() и replaceIn(text). set превращает объекты в текст JSON.

pm.variables.get ищет в таком порядке: локальные значения, строка данных, переменные папки и запроса, окружение, рабочее пространство, глобальные переменные.

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

Что сохраняет set. Значения, которые задают скрипты, — это «текущие значения» Postman: они живут, пока открыто окно в приложении или выполняется команда в командной строке, и при разрешении запросов важнее сохранённых значений своей области. В файлы рабочего пространства они не записываются никогда. Чтобы сохранить значение из ответа, используйте захват из ответа. Локальные значения из pm.variables.set забываются, когда начинается прогон.

replaceIn(text) подставляет {{variables}} из перечисленных выше областей. Из динамических значений он знает {{$guid}}, {{$randomUUID}}, {{$timestamp}}, {{$isoTimestamp}} и {{$randomInt}}; все остальные {{$…}} остаются как есть, чтобы Echolot подставил их при отправке запроса.

pm.infoCopy Anchor Link

pm.sendRequestCopy Anchor Link

Отправляет из скрипта другой запрос через Echolot: прокси, сертификаты и cookie действуют, как для любого запроса.

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

• Первый аргумент — URL или объект с url, method (по умолчанию GET), header (массив { key, value }, объект или список) и body.
• body — строка, { mode: "raw", raw }, { mode: "urlencoded", urlencoded: [{ key, value }] } или { mode: "graphql", graphql: { query, variables } }. Два последних задают Content-Type, если вы его не указали.
• {{variables}} в URL подставляются с учётом окружения запроса.
• Колбэк получает (error, response); response похож на pm.response. Без колбэка возвращается промис.
• У запроса нет собственной авторизации (авторизация рабочего пространства не применяется), и скрипты он не запускает.
• pm.sendRequest агента проходит через одобрения агента, как другие его отправки.

Управление прогономCopy Anchor Link

pm.cookiesCopy Anchor Link

Cookie этого обмена: те, что отправил запрос, и те, что установил ответ. Это список с pm.cookies.get(name), has(name), toObject() и one(name), который возвращает { name, key, value }.

СпискиCopy Anchor Link

Заголовки, параметры запроса и cookie — это списки свойств Postman:

consoleCopy Anchor Link

console.log, info, warn, error, debug и trace пишут в Консоль запроса, а в командной строке — под ── console ──. Объекты выводятся как JSON.

ТаймерыCopy Anchor Link

setTimeout, setInterval и setImmediate выполняют свои функции после скрипта, в порядке их задержек, не ожидая по-настоящему. setInterval срабатывает один раз. clearTimeout и остальные отменяют.

JSON SchemaCopy Anchor Link

Три способа, все на собственном валидаторе JSON Schema в 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);

Проверка по JSON Schema работает и без скрипта: это проверка JSON Schema на вкладке Тесты.

БиблиотекиCopy Anchor Link

Старые глобальные объекты PostmanCopy Anchor Link

Скрипты из старых коллекций используют их, и они работают:

Чего там нетCopy Anchor Link

• Другие модули: require чего-либо, не перечисленного выше (cheerio, xml2js, moment, собственные модули Node), выбрасывает «The module … is not available in Echolot scripts.»
• Настоящее ожидание: таймеры работают без задержки, а fetch и XMLHttpRequest отсутствуют. Используйте pm.sendRequest.
• Файлы и процессы: скрипты не могут читать и записывать файлы или запускать программы.
• pm.visualizer.set принимается, так что скрипты, которые его используют, работают, но Echolot визуализацию не показывает.
• xml2Json, pm.require и библиотека пакетов Postman, а также pm.vault.
• Секреты в файлах: скрипты читают секретные переменные, как любые другие, но то, что они задают через set, никогда не попадает в файлы рабочего пространства.