스크립트 API

스크립트는 요청을 보내기 전(요청 전)이나 응답이 도착한 후(테스트)에 실행되는 JavaScript입니다. Postman의 pm API를 사용하므로 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

스크립트는 Echolot 안의 샌드박스 JavaScript 엔진(QuickJS)에서 실행되며, 파일 시스템도, 자체 네트워크도, Node.js 모듈도 없습니다. 밖으로 나가는 유일한 방법은 Echolot을 통해 보내는 pm.sendRequest입니다.

예외를 던지거나 제한을 넘은 스크립트는 스크립트 오류로 보고되며, 실패한 테스트로 집계됩니다.

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은 로컬 값, 데이터 행, 폴더와 요청 변수, 환경, 작업 공간, 전역 변수의 순서로 찾습니다.

// 요청 전: 본문에 서명
const signature = CryptoJS.HmacSHA256(pm.request.body.raw, pm.environment.get("apiSecret")).toString();
pm.request.headers.upsert({ key: "X-Signature", value: signature });

// 테스트: 새 주문의 ID를 다음 요청을 위해 보관
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을 통해 다른 요청을 보냅니다. 프록시, 인증서, 쿠키는 다른 요청과 똑같이 적용됩니다.

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

// 프라미스를 사용할 수도 있습니다
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와 같습니다. 콜백이 없으면 프라미스를 반환합니다.
• 이 요청에는 자체 인증이 없으며(작업 공간의 인증은 적용되지 않습니다) 스크립트도 실행하지 않습니다.
• 에이전트의 pm.sendRequest는 다른 전송과 마찬가지로 에이전트의 승인을 거칩니다.

실행 제어Copy Anchor Link

pm.cookiesCopy Anchor Link

이 교환의 쿠키입니다. 요청이 보낸 쿠키와 응답이 설정한 쿠키입니다. 목록이며 pm.cookies.get(name), has(name), toObject(), { name, key, value }를 반환하는 one(name)이 있습니다.

목록Copy Anchor Link

헤더, 쿼리 매개변수, 쿠키는 Postman 속성 목록입니다.

consoleCopy Anchor Link

console.log, info, warn, error, debug, trace는 요청의 콘솔에 쓰이며, 명령줄에서는 ── console ── 아래에 쓰입니다. 객체는 JSON으로 기록됩니다.

타이머Copy Anchor Link

setTimeout, setInterval, setImmediate는 스크립트가 끝난 후 지연 시간 순서대로 함수를 실행하며, 실제로 기다리지는 않습니다. setInterval은 한 번 실행됩니다. clearTimeout 등은 취소합니다.

JSON 스키마Copy Anchor Link

세 가지 방법이 있으며 모두 Echolot 자체의 JSON 스키마 검증기를 사용합니다.

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 스키마 검사는 스크립트 없이도 동작합니다. 테스트 탭의 JSON Schema 검사입니다.

라이브러리Copy Anchor Link

예전 Postman 전역 객체Copy Anchor Link

예전 컬렉션의 스크립트가 사용하는 것들이며, 동작합니다.

없는 것Copy Anchor Link

• 다른 모듈: 위에 나열되지 않은 것(cheerio, xml2js, moment, Node 자체 모듈)을 require하면 “The module … is not available in Echolot scripts.”라는 예외가 발생합니다.
• 실제 대기: 타이머는 지연 없이 실행되며, fetch나 XMLHttpRequest는 없습니다. pm.sendRequest를 사용하세요.
• 파일과 프로세스: 스크립트는 파일을 읽거나 쓰거나 프로그램을 시작할 수 없습니다.
• pm.visualizer.set은 받아들여지므로 이를 사용하는 스크립트는 실행되지만, Echolot은 시각화를 표시하지 않습니다.
• xml2Json, pm.require와 Postman의 패키지 라이브러리, pm.vault.
• 파일 속의 비밀 값: 스크립트는 비밀 변수를 다른 변수처럼 읽지만, set으로 설정한 값은 작업 공간 파일에 전달되지 않습니다.