Test your API using the Collection Runner

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.

Configure a collection run

You can manually run the requests in a collection or a folder.

1. 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.

2. Select Run.

   

   You can also select Runner from the Postman footer. Drag a collection from the sidebar into the Collection Runner. Or select start with a template to create a new collection with example tests you can run.

3. On the Functional tab, select Run manually.

   You can also schedule runs and automate runs with the Postman CLI.

4. 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.

5. 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

     • Stop run if an error occurs - By default, the collection run stops if an exception is encountered within a script or if there's a problem sending a request. Clear this checkbox if you want the collection run to continue after an error occurs.
     • Keep variable values - Persist the variables used in the run, so that any variables updated by the run will remain changed after it completes. If you don't persist variables, changes aren't saved after the run completes. Note that persisting variables in the collection run will update the current value and not the initial value of variables.
     • Run collection without using stored cookies - If your requests use cookies, you can optionally deactivate them for a collection run.
     • Save cookies after collection run - Save the cookies used in this session to the cookie manager. Any values changed by requests during the run will remain after it completes.

6. 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.

7. 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.

Debug run results

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.

Run the collection again

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:

• Select Run Again to run the collection again using the same settings.
• Select + New Run to configure a new run for the collection. Make changes to any settings, and then select Run (collection name) to run the collection again.
• Select Automate Run to automate runs for the collection. You can schedule a run, run using the Postman CLI, or integrate runs with your CI/CD pipeline.

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.

Export collection runs

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:

1. Open the collection run in the Collection Runner. You can also access the collection run using History in the sidebar if you don't have the run open.
2. Select Export Results at the top right to download the run.
3. Choose a location to save your downloaded collection run, then select Save.

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.

View run history

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.

View past runs

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:

• A checkbox for each run and an option to select all runs. Select one or more collection runs and select Delete to remove them.
• The start time of the collection run.
• The run source, duration, all tests, passed tests, failed tests, skipped tests, and the average response time. Select any of these items to sort the table by that item. Select again to change the sort order.

Hover over an item to show the following controls:

• View Report - Select to open the full results for the collection run. Learn more about debugging run results.
• Share - Select to share the results with another team member. This provides a link you can give to other team members so they can view details of this run. Note that this doesn't work in personal workspaces.

View scheduled runs

The Scheduled tab shows all the scheduled runs for the current collection. The following are displayed for each scheduled run:

• The upcoming run's scheduled time
• The name of the scheduled run
• The environment associated with the scheduled run (if any)

Hover over an item to show the following controls:

• View - Select to open a page detailing the scheduled collection run's latest results.
• The more actions icon - Select to pause, resume, edit, or delete the schedule.

View performance runs

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.

Automate collection runs

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:

• Use the Postman CLI command-line interface to run collections and build them into your development pipeline, responding to test outcomes to support your API performance.
• You can also use Newman to run collections from the command line.
• Adding a monitor to your collection lets you schedule collection runs and stay informed of any issues.
• You can also set up a collection webhook to trigger a collection run at a specific time with your own custom payload.

Next steps

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.