A RetroSearch Logo

Home - News ( United States | United Kingdom | Italy | Germany ) - Football scores

Search Query:

Showing content from https://learning.postman.com/docs/tests-and-scripts/write-scripts/postman-sandbox-api-reference/ below:

Process data and script workflows using Postman JavaScript objects

The Postman JavaScript API functionality enables you to programmatically access and alter request and response data and variables using the pm object. You can also dynamically alter run order to build request workflows for the Collection Runner.

Use variables in scripts

You can access and manipulate variables at each scope in Postman using the pm API.

You can use dynamic variables to generate values when your requests run.

Postman supports a variety of variable scopes. The pm object provides methods for accessing global, collection, and environment variables specifically, and pm.variables methods for accessing variables at different scopes and setting local variables.

Variable scope determines the precedence Postman gives to variables when you reference them, in order of increasing precedence:

The variable with the closest scope overrides any others. For example, if you have a score variable in both the current collection and the active environment, and you call pm.variables.get('score'), Postman returns the current value of the environment variable. When you set a variable value using pm.variables.set, the value is local and only persists for the current request or collection run.





console.log(pm.variables.get('score')); 
console.log(pm.collectionVariables.get('score')); 
console.log(pm.environment.get('score')); 


pm.variables.set('score', 3);
console.log(pm.variables.get('score')); 


console.log(pm.variables.get('score')); 

See the Postman Collection SDK Variables reference for more information.

You can also access variables defined in the individual scopes with pm.environment, pm.collectionVariables, and pm.globals. You can access vault secrets in your Postman Vault with pm.vault.

Postman doesn't support using pm.variables to access and manipulate vault secrets.

You can use variables in your scripts to:

Check if there is a Postman variable in the current scope:

Get the value of the Postman variable with the specified name:

Postman supports getting the value of variables without a scope.

Append a string to the value of the Postman variable using the + operator:

Set a local variable with the specified name and value:

Return the resolved value of a dynamic variable inside a script using the syntax {{$variableName}}:

Return an object containing all variables with their values in the current scope. Based on the order of precedence, this will contain variables from multiple scopes.

Use environment variables in scripts

You need Editor access for the environment to edit environment variables.

You can use the pm.environment method in your scripts to access and manipulate variables in the active (selected) environment:

Get the name of the active environment:

Check if the environment has a variable with the specified name:

Get the variable with the specified name in the active environment:

Append a string to the value of the variable in the active environment using the + operator:

Set the variable with the specified name and value in the active environment:

Return the resolved value of a dynamic variable inside a script using the syntax {{$variableName}}:

Return all variables with their values in the active environment in a single object:

Remove a variable from the active environment, specifying the variable by name:

Clear all variables in the active environment:

Use collection variables in scripts

You need Editor access for the collection to edit collection variables.

Use the pm.collectionVariables methods in your scripts to access and manipulate variables in the collection.

Check if there is a variable in the collection with the specified name:

Return the value of the collection variable with the specified name:

Append a string to the value of the collection variable using the + operator:

Set a collection variable with the specified name and value:

Return the resolved value of a dynamic variable inside a script using the syntax {{$variableName}}:

Return all variables with their values in the collection in an object:

Remove the specified variable from the collection:

Clear all variables from the collection:

Use global variables in scripts

You need the Workspace Editor role to edit its global variables.

Use the pm.globals methods in your scripts to access and manipulate variables at the global scope within the workspace:

Check if there is a global variable with the specified name:

Return the value of the global variable with the specified name:

Append a string to the value of the global variable using the + operator:

Set a global variable with the specified name and value:

Return the resolved value of a dynamic variable inside a script using the syntax {{$variableName}}:

Return all global variables and their values in an object:

Remove the specified global variable:

Clear all global variables in the workspace:

Use data variables in scripts

You can use the pm.iterationData methods in your scripts to access and manipulate variables from data files during a collection run:

Check if a variable with the specified name exists in the current iteration data:

Return a variable from the iteration data with the specified name:

Append a string to the value of the iteration data using the + operator:

Return the iteration data variables in an object:

Convert the iterationData object to JSON format:

Remove the specified variable:

Use vault secrets in scripts

Use the pm.vault methods in your scripts to access or manipulate vault secrets in your Postman Vault. Enable support for vault secrets in scripts from your Postman Vault to use the pm.vault methods. When you send a request or run a collection manually that uses the pm.vault methods, you'll be prompted to grant or deny a collection or the workspace access to your vault secrets using scripts. To keep vault secrets in your Postman Vault secure, make sure to only run scripts you trust.

To use the methods to access your vault secrets linked to external vaults, you must use the Postman desktop app.

The pm.vault methods are supported in pre-request and post-response scripts in HTTP collections and requests. The methods are also supported in scripts when running collections manually with the Collection Runner. Scheduled collection runs, monitors, the Postman CLI, and Newman don't support the pm.vault methods. The pm.vault methods also aren't supported for multi-protocol requests, such as GraphQL and gRPC.

If you're using the Postman web app to access vault secrets from scripts, use the Postman Desktop Agent. Postman recommends you use the latest version of the Postman Desktop Agent to receive recent changes and improvements.

The pm.vault methods run asynchronously in your scripts. Each method also returns a Promise object that represents the completion or failure of the method. Add the await operator before each pm.vault method to wait for the Promise and its resulting value. Note that a method without the await operator may run in your script, but it may not behave as expected. For example:

console.log(await pm.vault.get("secretKey"));
await pm.vault.set("secretKey", "newValue");
await pm.vault.unset("secretKey");
Enable support for vault secrets in scripts

To use the pm.vault methods in scripts to access or manipulate your vault secrets, you must first enable this option from your Postman Vault.

If you try to access or manipulate vault secrets in scripts without enabling support, you'll receive an error in the Postman Console. Also, any code that comes after a pm.vault method won't run when you send the request.

To enable support for vault secrets in scripts, do the following:

  1. Open your Postman Vault.
  2. Select Settings in the upper right of your Postman Vault.
  3. In the Settings tab, turn the toggle on next to Enable support in scripts, then select Enable to confirm.

Once you enable support for vault secrets in scripts, you can use the pm.vault methods in your HTTP collections and requests. When you send a request or run a collection manually that uses the methods, you'll be prompted to grant or deny a collection or the workspace access your vault secrets.

Grant scripts access to your vault secrets

When you send a request or run a collection manually that uses the pm.vault methods in scripts, you'll be prompted to grant or deny a collection or the workspace access to your vault secrets. Postman only allows you to run these scripts from collections or workspaces you've granted access do to so. From your Postman Vault, you can manage the collection or workspace's access to your vault secrets. To keep vault secrets in your Postman Vault secure, make sure to only run scripts you trust.

Make sure you've enabled support for vault secrets in scripts. Otherwise, you won't be prompted to grant or deny a collection or the workspace access to your vault secrets using scripts.

If you create a new HTTP request and send the request before saving it to a collection, the request will be granted to access your vault secrets using scripts. Postman won't prompt you to grant or deny access to your vault secrets if the request isn't saved to a collection.

To grant or deny a collection access to your vault secrets, do the following:

  1. Open your Postman Vault.

  2. Select Collections in the sidebar, then open an HTTP collection or request with a script that accesses or manipulates your vault secrets.

  3. Send the request or run the collection manually.

  4. Select Only this collection.

  5. Choose if you'd like to grant or deny access:

    Postman won't prompt you again for requests in the collection. From your Postman Vault, you can manage the collections you granted or denied access to your vault secrets.

To grant or deny a workspace access to your vault secrets, do the following:

  1. Open your Postman Vault.

  2. Select Collections in the sidebar, then open an HTTP request with a script that accesses or manipulates your vault secrets.

  3. Select Send to send the request.

  4. Select Entire Workspace.

  5. Choose if you'd like to grant or deny access:

    Postman won't prompt you again for collections or requests in the workspace. From your Postman Vault, you can manage the workspace if you granted or denied it access to your vault secrets.

To manage a collection or workspace's access to your vault secrets, do the following:

  1. Open your Postman Vault.

  2. Select Settings in the upper right of your Postman Vault.

  3. Select the Manage Access tab.

  4. Select one of the following next to a collection or workspace:

If you deny the collection or workspace access to your Postman Vault, you'll receive an error in the Postman Console when you send a request at the denied scope. Also, any code that comes after a pm.vault method won't run when you send a request at the denied scope.

Use the pm.vault methods

You can use the pm.vault methods in your scripts to access and manipulate your vault secrets.

Make sure you've enabled support for vault secrets in scripts and granted scripts in the collection or workspace access to your vault secrets using scripts. Otherwise, you'll receive an error in the Postman Console.

To return the value of the vault secret with the specified name:

To append a string to the value of the vault secret using the + operator:

To set a vault secret with the specified name and value:

Postman doesn't support setting the value of vault secrets linked with external vaults.

To remove the specified vault secret:

If you log the value of a vault secret using console.log, the value will be masked in the Postman Console by default. To unmask the value of vault secrets in the console, open your Postman Vault, select Settings, then turn off the toggle next to Mask vault secrets from the Settings tab.

Script with request and response data

You can use pm.request, pm.response, pm.info, and pm.cookies to access request and response data in Postman. You can also send requests using pm.sendRequest.

Script with request data

The pm.request object provides access to the data for the request the script is running within. For a Pre-request, this is the request that's about to run. For a Post-response script, this is the request that has already run.

You can use the pm.request object pre-request scripts to alter various parts of the request configuration before it runs.

The pm.request object provides the following properties and methods:

The request URL:

The list of headers for the current request:

The HTTP request method:

The data in the request body. This object is immutable and can't be modified from scripts:

Add a header with the specified name and value for the current request:

Delete the request header with the specified name:

Insert the specified header name and value (if the header doesn't exist, otherwise the already existing header will update to the new value):

See the Postman Collection SDK Request reference for more information.

Script with response data

The pm.response object provides access to the data returned in the response for the current request in scripts added to the Post-response tab. This object provides the following properties and methods:

The response status code:

The status text string:

The list of response headers:

The time the response took to receive in milliseconds:

The size of the response received:

The response text:

The response JSON, which you can use to drill down into the properties received:

See the Postman Collection SDK Response reference for more information.

Script with request info

The pm.info object provides data related to the request and the script itself, including name, request ID, and iteration count. This object provides the following properties and methods:

The event, which will be either prerequest or test depending on where the script runs within the request:

The value of the current iteration:

The total number of iterations that are scheduled to run:

The saved name of the request running:

A unique GUID that identifies the running request:

Script with request cookies

The pm.cookies object provides access to the list of cookies associated with the request. This object provides the following properties and methods:

Check whether a particular cookie (specified by name) exists for the requested domain:

Get the value of the specified cookie:

Append a string to the value of the specified cookie using the + operator:

Get a copy of all cookies and their values in an object, returning any cookies that are defined for the request domain and path:

See the Postman Collection SDK Cookie List reference for more information.

pm.cookies.jar

You can use pm.cookies.jar to specify a domain for access to request cookies. To enable programmatic access using the pm.cookies.jar methods, first add a domain to the allowlist.

Access the cookie jar object:

Set a cookie using name and value:

Set a cookie using PostmanCookie or a compatible object:

Get a cookie from the cookie jar for a particular URL:

Get all the cookies from the cookie jar for a particular URL, which are available in the callback function:

Remove a cookie for a particular URL:

Clear all cookies from the cookie jar for a particular URL:

Clear and then set a cookie in sequence for a particular URL:

jar.clear(URL:String, callback(error) => {
    jar.set(URL:String, cookieName:String, cookieValue:String, callback(error, cookie)):Function → Object
}):Function → Object

Function calls run asynchronously. Use a callback function to ensure functions run in sequence.

See the Postman Collection SDK Cookie reference for more information.

Send requests from scripts

Use the pm.sendRequest methods to send a request asynchronously from a Pre-request or Post-response script. This enables you to run logic in the background if you are carrying out computation or sending multiple requests at the same time without waiting for each to complete. You can avoid blocking issues by adding a callback function so that your code can respond when Postman receives a response. You can then carry out any more processing you need on the response data.

You can pass the pm.sendRequest method a URL string, or can provide a complete request configuration in JSON including headers, method, body, and more.


pm.sendRequest('https://postman-echo.com/get', (error, response) => {
  if (error) {
    console.log(error);
  } else {
  console.log(response);
  }
});


const postRequest = {
  url: 'https://postman-echo.com/post',
  method: 'POST',
  header: {
    'Content-Type': 'application/json',
    'X-Foo': 'bar'
  },
  body: {
    mode: 'raw',
    raw: JSON.stringify({ key: 'this is json' })
  }
};
pm.sendRequest(postRequest, (error, response) => {
  console.log(error ? error : response.json());
});


pm.sendRequest('https://postman-echo.com/get', (error, response) => {
  if (error) {
    console.log(error);
  }

  pm.test('response should be okay to process', () => {
    pm.expect(error).to.equal(null);
    pm.expect(response).to.have.property('code', 200);
    pm.expect(response).to.have.property('status', 'OK');
  });
});

See the Request definition and Response structure reference docs for more information.

Get the path and name of a request

The pm.execution.location property enables you to get the complete path of a request, including the folder and collection, in array format. For example, for a request named R1 in folder F1 in the C1 collection, the following post-response script code returns ["C1", "F1", "R1"]:

console.log(pm.execution.location);


To get the name of the current element, use the pm.execution.location.current property. For example, if you add the following code to the pre-request script of a folder named F1, it returns F1:

console.log(pm.execution.location.current);


You can use the pm.execution.location and pm.execution.location.current properties in your scripts to understand which items run when a request is sent. This information enables you to implement logic and actions in your scripts tailored to the current location within your API testing or collection structure.

Skip request run from pre-request scripts

The pm.execution.skipRequest method enables you to stop the run of a request from a pre-request script:

pm.execution.skipRequest()

You can use the pm.execution.skipRequest method in the Pre-request tab of a request, collection, or folder. When pm.execution.skipRequest() is encountered, the request isn't sent. Any remaining scripts in the Pre-request tab are skipped, and no tests are run. For example:


if (!pm.environment.get('token')) {
  pm.execution.skipRequest()
}

In the Collection Runner, when pm.execution.skipRequest() is encountered, Postman skips running the current request (including its post-response scripts) and moves to the next request in order. The run results will show no response and no tests found for the request. This same behavior also applies to Postman Flows, Newman, and the Postman CLI.

Using the pm.execution.skipRequest method isn't supported in the Post-response tab of a request, collection, or folder and will have no effect there. You will also get a TypeError: pm.execution.skipRequest isn't a function Console error.

Validate response data with a JSON Schema

The jsonSchema method enables you to write a test assertion that validates the response data with a JSON Schema. Postman uses version 6.12.5 of the Ajv JSON Schema validator to validate response data with a JSON Schema.

To write your test assertion, use the pm.response object and Chai Assertion Library BDD syntax to access the data returned in the response.

The jsonSchema method accepts a JSON Schema as an object in the first argument. It also accepts an object of optional Ajv options in the second argument:

pm.response.<bdd-syntax>.jsonSchema(schema, options);

You can define a JSON Schema in Postman, such as in the Scripts tab of a request. Then you can write a test that validates the properties in your response data against the defined JSON Schema.

In the following example, the JSON Schema requires the response data to contain an alpha property that's a Boolean data type. If the response data is missing this property or it's a different data type, the test fails. This example uses BDD syntax to.have to express the assertion:

const schema = {
  "type": "object",
  "properties": {
    "alpha": {
      "type": "boolean"
    }
  },
  "required": ["alpha"]
};

pm.test('Response is valid', function() {
  pm.response.to.have.jsonSchema(schema);
});
Script workflows

You can use the pm.execution.setNextRequest method for building request workflows when you use the Collection Runner or Newman.

setNextRequest has no effect when you run requests using Send. It only has an effect when you run a collection.

When you run a collection with the Collection Runner or Newman, Postman runs your requests in a default order or an order you specify when you set up the run. However, you can override this run order using pm.execution.setNextRequest to specify which request to run next. For example:

Run the specified request after this one (where requestName is the name of the collection's request, for example "Get customers"):

Run the specified request after this one (where requestId is the request ID returned by pm.info.requestId):

Script Postman visualizations

Use pm.visualizer.set to specify a template to display response data in the Postman Visualizer:

pm.visualizer.set(layout:String, data:Object, options:Object):Function

Example usage:

var template = `<p>{{res.info}}</p>`;
pm.visualizer.set(template, {
    res: pm.response.json()
});
Building response data into Postman visualizations

Use pm.getData to retrieve response data inside a Postman Visualizer template string. For example:

The callback function accepts two parameters:

Example usage:

pm.getData(function (error, data) {
  var value = data.res.info;
});
Writing test assertions

You can use pm.test to write test specifications inside either the Pre-request or Post-response scripts. Tests include a name and assertion:

pm.test(testName:String, specFunction:Function):Function

Postman will output test results as part of the response. The pm.test method returns the pm object, making the call chainable.

The following sample test checks that a response is valid to proceed:

pm.test("response should be okay to process", function () {
  pm.response.to.not.be.error;
  pm.response.to.have.jsonBody('');
  pm.response.to.not.have.jsonBody('error');
});

An optional done callback can be passed to pm.test to test asynchronous functions:

pm.test('async test', function (done) {
  setTimeout(() => {
    pm.expect(pm.response.code).to.equal(200);
    done();
  }, 1500);
});

For example, to get the total number of tests run from a specific location in code:

The pm.expect method enables you to write assertions on your response data, using ChaiJS expect BDD syntax:

You can also use pm.response.to.have.* and pm.response.to.be.* to build your assertions.

See Postman test script examples for more assertions.

Import packages from scripts

You can use the pm.require method to import packages from your team's Package Library or external package registries inside HTTP, gRPC, and GraphQL requests.

The pm.require method accepts the name of the package. Declare the method as a variable if the package has functions or objects you want to call. If the package only has code or instances of the pm object, you don't need to declare the method as a variable:

Use the following format to import a package from the Package Library:

const variableName = pm.require('@team-domain/package-name');

variableName.functionName()

Use the following format to import an external package from a package registry:


const npmVariableName = pm.require('npm:package-name@version-number');

npmVariableName.functionName()


const jsrVariableName = pm.require('jsr:package-name@version-number');

jsrVariableName.functionName()
Use global objects

Postman supports the following JavaScript objects globally in your scripts:

Use external libraries

The require method enables you to use the sandbox built-in library modules. To use a library, call the require method, pass the module name as a parameter, and assign the return object from the method to a variable:

require(moduleName:String):function

The supported libraries available for use in the sandbox include:

The following libraries are deprecated and no longer supported:

The following NodeJS modules are also available:

Postman doesn't support the following in the buffer module: isAscii, isUtf8, resolveObjectURL, transcode, and copyBytesFrom.

Next steps

You can use tests to build Postman into your development projects in a variety of ways using Postman utilities.


RetroSearch is an open source project built by @garambo | Open a GitHub Issue

Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo

HTML: 3.2 | Encoding: UTF-8 | Version: 0.7.4