Send some or all of the API requests in a Postman Collection in the order you choose with the Collection Runner. The Collection Runner logs the test results for each request, and it can use scripts to pass data between requests and change the request workflow.
Use collection runs to automate your functional API testing. You can run collections manually, or schedule collection runs in the Postman cloud with the Collection Runner or monitors. You can also integrate collection runs with your CI/CD pipeline using the Postman CLI, Postman's command line tool.
See how an integration test can ensure that all individual components of an API function together seamlessly. To try out this template, select Integration testing.
You can manually run the requests in a collection or a folder.
Select Collections in the sidebar and select the collection or folder you want to run.
You can also run a collection or folder that's linked to an API. Learn more about adding a collection to an API.
Select Run.
You can also select Runner from the Postman footer and drag a collection from Collections or History in the sidebar.
On the Functional tab, select Run manually.
You can also schedule runs and automate runs with the Postman CLI.
If you want your collection to run with an environment, select it using the environment selector at the top right of Postman. You can also select Environments in the sidebar, then select the environment you want to use.
Choose any configuration options:
Iterations - The number of times to run the collection. You can also run collections multiple times with different data sets to build workflows.
Delay - An interval delay in milliseconds between each request.
Data - A data file for the collection run.
Persist responses for a session - Log the response headers and bodies so you can review them after running the collection. For large collections, persisting responses may affect performance.
Request and response details are persisted locally during your current Postman session and aren't saved permanently. Signing out of Postman, signing into another device with the same account, or refreshing your browser will end your session and remove the logged data.
Response and request details are available for the person who started the collection run. Other team members can't view details for collection runs that you start.
Turn off logs during run - Turn off logging to the Postman Console during the collection run. Request and response details such as method, URL, headers, and body won't be logged. Also, all log statements in scripts will be ignored. Selecting this option may improve performance of the Postman app when running large collections.
Advanced settings
By default, your requests run in the sequence they're listed in the collection. If you need to change the order of execution, select and drag a request to its new location in the order. You can also remove an individual request from the run by clearing the checkbox next to its name.
You can alter the flow of execution from your request scripts using
setNextRequest
to create workflows.
When you've completed your configuration, select Run (collection name).
Your Postman plan gives you a limited number of collection runs you can use each month. This limit applies to collections that you run in a workspace using the Run manually option. This limit doesn't apply to scheduled collection runs in the Postman cloud. A collection run with multiple iterations counts as a single run.
A message will display in the Collection Runner when you're approaching your usage limit. Learn more about resource usage in Postman.
When running collections manually, Postman displays the results of your request executions and test results in real time. You can view the source of the collection run, selected environment, number of iterations, total duration, number of tests, and average response time.
To learn more about what happened during the collection run, do any of the following:
Select a request to view details about the request. You can view general information about the request and the request headers and body. You can also view the response headers and body if you selected the Persist responses for a session option when configuring the collection run.
Select the name of a request to open the request in a new tab. You can view any post-response scripts or select Send to send the request again.
Select the Passed, Failed, or Skipped tabs to filter the results by test status. To show all requests, select the All Tests tab. If any tests in a request script fail during a collection run, the whole request fails.
If your collection run included more than one iteration, select an iteration number to jump to the results of a specific iteration.
Select View all runs to view a list of past runs. Learn more about viewing run history.
Select View Summary to view a summary of the collection run, including test results. To return to the full results, select View Results.
You can add scripts and tests to packages in your team's Package Library, and run the contents of packages from the Collection Runner. Learn how to add packages to the Package Library, and import packages into your pre-request and post-response scripts.
After reviewing the results of the collection run, you can run the collection again. For example, you can edit the code for a failed test and run the collection again to check if the test succeeds.
To run the collection again from the run results, do one of the following:
If you changed the selection or order of requests, or any other settings, the custom order and configuration are saved with the run results.
To run the collection again later using your custom configuration, select the Runs tab in the collection to view past runs. Select the view report icon next to a run to open the collection run results. From here you can select Run Again to run the collection again using the same settings.
You can share collection run results with others by exporting the results from the Collection Runner.
The option to export a collection run report is available in the Postman desktop app but not in the Postman web app.
To export a collection run, do the following:
You can import the results of a collection run that was exported to a file. Select Runner from the Postman footer and drag the exported file into the Collection Runner.
Each collection has a Runs tab you can use to view past functional runs, scheduled runs, and performance runs. You can also view details such as test counts and average response times.
The Functional tab has controls to select how many recent collection runs to view. You can filter the displayed runs by user, by run status, and by source (Collection Runner or Postman CLI).
The following are displayed for each collection run:
Hover over an item to show the following controls:
The Scheduled tab shows all the scheduled runs for the current collection. The following are displayed for each scheduled run:
Hover over an item to show the following controls:
The Performance tab shows past performance runs for the collection. You can view metrics for each run, including the number of virtual users (VUs), duration, total number of requests, requests per second, average response time, and error rate.
Select a run to view a graph and full details for the performance run. Learn more about viewing performance metrics.
In addition to running collections manually, you can schedule collections to run automatically at specified times in the Postman cloud. You can also use collection runs with other Postman utilities to build automation into your API projects:
Build on the Collection Runner fundamentals you've learned with the following topics:
Use scripts to build workflows with conditional sequences for running the requests in your collections. To learn more, go to Customize request order in a collection run.
Run your collections on a schedule to automatically test the functionality of your APIs. To learn more, go to Automate collection runs on a schedule.
Use the Collection Runner to test the performance of your API with the same requests, collections, and environments you use for functional API tests. To learn more, go to Simulate user traffic to test your API performance.
Last modified: 2024/09/10
Additional resources
Videos
Blog posts
Case Studies