Reuse scripts in Postman

You can add commonly used scripts and tests to packages in your team's Package Library, and reuse them in your personal, private, and team workspaces. Import packages into pre-request scripts and post-response scripts in your team's HTTP requests, collections, and folders. This enables you to maintain scripts and tests in a central location and share them with your team.

About the Package Library

Use the Package Library to store commonly used scripts and tests as packages in your Postman team. This means you can maintain scripts and tests in one location, and reuse them in your personal, private, and team workspaces. Your Postman teammates can also access and import packages from the Package Library, enabling you to share scripts and tests directly in Postman. The Package Library supports JavaScript code.

The number of packages your team can store in the Package Library depends on your Postman plan. Learn more about resource usage in Postman.

Import packages into the Pre-request and Post-response tabs in your team's HTTP requests, collections, and folders. The contents of packages will run when you run the requests they're imported in. Learn more about the execution order of scripts.

The contents of packages will also run when you run HTTP requests, collections, and folders from the Collection Runner (manual, scheduled, and performance tests), Monitors, and Flows. If you're on a Professional or Enterprise team, the contents of packages will run when you run HTTP requests, collections, and folders from the Postman CLI.

Add a package

You can create a package from scratch in the Package Library, and you can add existing code to a new package or an existing package. You can only open the Package Library from personal, private, and team workspaces. To use a package, write code in a package, then import the package in your pre-request and post-response scripts.

You are the owner of the packages you create. Packages remain in your team's Package Library when a package's owner leaves the team or is removed from the team.

Add a new package

To add a new package, do the following:

  1. Open an HTTP request, collection, or folder, then select the Scripts tab.

  2. Select either the Pre-request or Post-response tabs.

  3. Open the pane to the right of the code editor, and select Open package library.

    Open Package Library

  4. Select Pin collection icon New Package.

  5. Enter the following:

    • Name - The name of the package. This is used in the import statement that adds the package to your pre-request or post-response scripts.

      Package names must be lowercase alphanumeric characters, starting with a lowercase alphabetical letter, and contain only dashes, underscores, and no spaces.

      You can't use the name of a package that already exists or a package that was deleted. Also you can't change the name of a package later.

    • Summary - The summary of the package so your teammates understand what it does.

    • Code - Enter code in the package. Learn how to write code in a package.

    Create a new package

  6. Select Create.

Add existing code to a package

To add existing code to a package, do the following:

  1. Open an HTTP request, collection, or folder, then select the Scripts tab.

  2. Select either the Pre-request or Post-response tabs.

  3. Write code you want to add to a package. Learn how to write code in a package.

  4. You can add existing code to a package in the following ways:

    • Add code to an existing package - Highlight the code, open the pane to the right of the code editor, select Pin collection icon Add to package > Add to existing package, then select an existing package or select Find more packages. If you chose to find a different existing package, search for the existing package name, then select Select.

    • Add code to a new package - Highlight the code, open the pane to the right of the code editor, then select Pin collection icon Add to package > New package.

    Add code to a package

    You can also highlight the code, right-click in the code editor, then select Save to Package Library. Select New Package to add the code to a new package, or select Existing Package to add the code to an existing package. If you're adding the code to an existing package, search for the existing package name, then select Select.

    Right-click to add code to a package

  5. Update the package Name, Summary, and Code as needed.

    You can't use the name of a package that already exists or a package that was deleted. Also you can't change the name of a package later.

  6. Select Save icon Save.

Write code in a package

Add JavaScript code, functions, and objects to packages in your team's Package Library. You can also use the Postman JavaScript API functionality, enabling you to use the pm object to access and alter request and response data, write test assertions, and more. The contents of packages run in the order they're listed. After you write code in a package, import a package into an HTTP request, collection, or folder.

You can't use the previous style of writing Postman tests in packages in the Package Library.

Export your functions and objects using the module.exports object property, enabling you to call them from the Pre-request and Post-response tabs. The name you export must match the name of the function declaration or object in your package.

function functionName {
    return result
}

module.exports = {
    functionName
}

You can learn how to document JavaScript functions in your packages.

If your package only includes JavaScript code or pm object instances, and no callable functions or objects, you don't need to export anything.

The following example is a package named postman_logger:

  • The package has a function named logger that accepts a parameter named data, and prints an argument to the Postman Console. The function is exported using module.exports, enabling you to call the function in the Pre-request and Post-response tabs of HTTP requests, collections, and folders.
  • The package also uses the pm object to run the test method. The function inside the test checks whether an API returns a 200 response code. The test result displays in the Test Results tab in the response area of HTTP requests.
// package name: postman_logger
function logger (data) {
    console.log(`Logging information to the console, ${data}`)
}

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

module.exports = {
    logger
}

Add documentation to a package

Postman supports JSDoc for documenting JavaScript functions in your packages. Documentation added to your functions using JSDoc will display in a popup window when you call each function from the Pre-request and Post-response tabs. You can use the official JSDoc documentation to learn how to add documentation to your packages.

The following example has documentation for the logger function using JSDoc. The documentation explains what the function does, and defines what the data parameter is used for and that it accepts a string data type.

/**
 * This function prints a string to the Postman Console.
 * @param {string} data - The text to print to the Postman Console.
 */
function logger (data) {
    console.log(`Logging information to the console, ${data}`)
}

module.exports = {
    logger
}

Import a package

Once you write code in a package, you can import a package into the Pre-request and Post-response tabs of HTTP collections, requests, and folders. This enables you to access the scripts and tests in your packages, and call specific functions and objects. The contents of packages will only run from personal, private, and team workspaces.

You can't import a package into the contents of another package in the Package Library.

Open the pane to the right of the code editor, and select the Find & use packages dropdown list. You can search for and select packages to import them into the code editor.

Find and use packages

Packages are imported into the code editor using the pm.require method. Your team domain and the package name are included as the argument in the following format: @team-domain/package-name. This also declares a JavaScript variable that you can use to call functions and objects in your packages. By default, the variable identifier is based on the package name.

If you change your team domain in your team profile, you must also change the team domain in each occurrence of the pm.require method. You can manually update the team domain, or re-import each package.

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

variableName.functionName()

If your package only includes JavaScript code or pm object instances, and no callable functions or objects, you only need to import it in your pre-request and post-response scripts. You don't need to also declare it as a JavaScript variable.

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

The following example imports a package named postman_logger into the Post-response tab of an HTTP request:

  • The package is declared as a variable named postmanLogger, and the variable is used to call the logger function that's in the package. The function accepts one parameter, and the argument passed to the function is the string The test passed, which is printed to the Postman Console.
  • The package also uses the pm object to run the test method. The test result is displayed in the Test Results tab in the response area.
// team domain: postman
// package name: postman_logger
const postmanLogger = pm.require('@postman/postman_logger');

postmanLogger.logger("The test passed")

// output in the Postman Console: Logging information to the console, The test passed

Edit a package

All team members can view and edit packages in your Postman team.

To edit a package, do the following:

  1. Open an HTTP request, collection, or folder, then select the Scripts tab.
  2. Select either the Pre-request or Post-response tabs.
  3. Open the pane to the right of the code editor, and select Open package library.
  4. Search for and select a package you'd like to edit.
  5. Edit the Summary and Code for the package as needed.
  6. Select Save icon Save.

Delete a package

You must be a Team or Super Admin or the package's owner, to delete a package from your team's Package Library. To find a package's owner, open the Package Library, then view the team member associated with a package.

You can't reuse the name of a package deleted from your Package Library.

To delete a package, do the following:

  1. Open an HTTP request, collection, or folder, then select the Scripts tab.
  2. Select either the Pre-request or Post-response tabs.
  3. Open the pane to the right of the code editor, and select Open package library.
  4. Search for and select a package you'd like to delete.
  5. Select the more actions icon More actions icon, then select Delete.
  6. To confirm your selection, select Yes, I understand.

Use external libraries in packages

You can use external library modules in packages. Learn about supported external library modules and how to use them.

You must use the require method to use the following external library modules in packages:

Last modified: 2024/08/24

Postmanaut dancing. Illustration.