脚本 API

脚本是在发送请求之前（请求前）或响应到达之后（测试）运行的 JavaScript。它们使用 Postman 的 pm API，因此 Postman 集合中的脚本可以原样运行。本页列出了全部内容。关于如何在 App 中编写脚本并查看结果，参见脚本和测试。

脚本在哪里运行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

脚本在 Echolot 内部的沙盒 JavaScript 引擎（QuickJS）中运行，没有文件系统，没有自己的网络，也没有 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 所说的“当前值”：它们在 App 中持续到窗口关闭，在命令行中持续到命令结束，并且在请求解析时优先于其作用域中已存储的值。它们绝不会写入工作区文件。要保存响应中的值，请使用响应捕获。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。
• URL 中的 {{variables}} 会按请求的环境填入。
• 回调接收 (error, response)；response 与 pm.response 类似。没有回调时返回 promise。
• 该请求没有自己的认证（工作区的认证不适用），也不运行脚本。
• 智能体的 pm.sendRequest 与它的其他发送一样，要经过智能体的批准。

控制运行Copy Anchor Link

pm.cookiesCopy Anchor Link

此次交换的 Cookie：请求发送的和响应设置的。是一个列表，带有 pm.cookies.get(name)、has(name)、toObject()，以及返回 { name, key, value } 的 one(name)。

列表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

有三种方式，都基于 Echolot 自己的 JSON Schema 验证器：

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

旧版 Postman 全局变量Copy 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 的内容绝不会进入工作区文件。