Scripts

A script is a few lines of JavaScript that run around a request. A pre-request script runs before the request is sent and can change it. A post-response script runs when the response arrives and can test it, save values from it, or draw it as a table. Scripts use Postman's pm API, so scripts from Postman collections run here too.

You do not need scripts for simple checks. Tests without code and Captures cover those. Reach for a script when you need logic.

The two kinds of script

Script	Runs	Typical use
Pre-request	Before the request is sent	Set a timestamp, sign the request, add a header, fetch a token
Post-response	After the response arrives	Write tests, save values into variables, choose the next request

Write your first script

1. Open a request and select the Scripts tab.

2. Select Post-response.

3. Type this script:

   pm.test("Status is 200", () => {
     pm.response.to.have.status(200);
   });

4. Select Send.

5. Open the Tests tab of the response. Your test is listed by its name, with a tick or a cross.

The Snippets menu in the Scripts tab inserts ready-made pieces at the cursor, such as Status code is 200, Check a JSON value and Set an environment variable. A dot after Pre-request or Post-response marks a phase that has a script, and the tab itself shows a dot when the request has any script.

Small examples

Read a value from the JSON body and test it:

pm.test("The user is active", () => {
  const user = pm.response.json();
  pm.expect(user.active).to.equal(true);
});

Save a value for later requests. Other requests can then use {{token}}:

const body = pm.response.json();
pm.environment.set("token", body.token);

Set a value before the request goes out (pre-request). The request can use {{now}} in its URL, headers or body:

pm.environment.set("now", Date.now());

Add a header before the request goes out (pre-request):

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

Print something while you work. The output appears in the Console:

console.log("Status was", pm.response.code);

More recipes are in the Script cookbook. Every object and method is listed in the Script API reference.

Where scripts live

Scripts can sit at three levels. Higher levels save you from repeating the same script in every request.

Level	Where to write it	Runs for
Request	The request's Scripts tab	That request
Folder	Folder menu, Auth, scripts and docs, then Scripts	Every request in the folder and its subfolders
Collection	Collection menu, Auth, scripts and docs, then Scripts	Every request in the collection

At folder and collection level the two boxes are named Pre-request script and Post-response script.

The order things run in

When you send a request, ApiWorkbench does this:

1. The collection's pre-request script.
2. Each folder's pre-request script, from the outermost folder inwards.
3. The request's own pre-request script.
4. The request is sent, with the changes the scripts made.
5. The collection's post-response script.
6. Each folder's post-response script, from the outermost folder inwards.
7. The request's own post-response script.
8. The no-code checks in the request's Tests tab.
9. The request's Captures.

All scripts of one phase share one sandbox, so a value that a collection script puts in a variable is there for the request script.

Things that change the flow:

• If a pre-request script throws an error, the request is not sent. The response panel shows Pre-request script failed: followed by the error.
• If a pre-request script calls pm.execution.skipRequest(), the request is not sent and the remaining pre-request scripts do not run.
• If the request gets no response, post-response scripts do not run.
• If a post-response script throws an error outside a pm.test, the response's Tests tab shows Test script failed: followed by the error, and the request counts as failed in the runner.

Where the results go

Output	Where you see it
pm.test results	The response's Tests tab, above the no-code tests
console.log and friends	The Console, under Logs
pm.visualizer.set	A Visualize tab that appears in the response
Variable changes	The variable's current value in its scope; see Variables

Where scripts run

Scripts run when you select Send, in the collection runner and in the command-line runner. They run for HTTP requests.

The load tester does not run scripts. It uses the no-code tests and its own extract rules.

Turn scripts off, or change the timeout

Open Settings:

Setting	What it does	Default
Run scripts	Runs pre-request and post-response scripts on every send. Off: scripts are saved but not run.	On
Script timeout (ms)	How long the scripts of one phase may take before they are stopped. Accepts 100 to 600000.	10000 (10 seconds)

When scripts are off, the Scripts tab says so: "Scripts are turned off in Settings: they are saved but not run."

Limits

Scripts run in a sandbox, separate from the app and from your computer.

• No files. A script cannot read or write files, and cannot attach a file to a request.
• Network only through pm.sendRequest. There is no fetch or XMLHttpRequest.
• Time. A phase that runs longer than the script timeout is stopped with an error.
• Memory. One run may use up to 256 MB.
• Cookies are read-only. pm.cookies reads the cookies for the request's address. Changing the cookie jar from a script is not supported; use the cookie manager.
• Libraries. require() loads the bundled libraries listed in the reference. pm.require (Postman's package library) is not supported.
• Console output. One run keeps up to 1,000 console lines, and a single line is cut at 20,000 characters.
• Variables are text. A value you set is stored as text. Objects are stored as JSON text, so use JSON.parse when you read them back.

Scripts from other people

Read imported scripts before you run them

Importing a Postman collection keeps its scripts exactly as written, and they run when you send a request or run the collection. A script can read your variables, including tokens and passwords, and can send them anywhere with pm.sendRequest.

Before running a collection you did not write, turn Run scripts off in Settings, open the collection, folder and request scripts, and read them. Turn scripts back on when you are satisfied.

Scripts cannot touch your files or start programs, whatever they contain.

Coming from Postman

Scripts written for Postman use the same pm API. Older scripts that use postman.setEnvironmentVariable, tests["name"] = true or responseBody also run. See the Script API reference for what is covered and the Postman migration guide for the wider picture.

Next steps

• Script cookbook: copy-and-paste recipes.
• Script API reference: every pm object and method.
• Collection runner: run requests, scripts and tests in sequence.