Postman Collection Runner: Run and Automate API Test Suites

The Postman Collection Runner lets you execute an entire collection of API requests in sequence, with test assertions, environment variables, and iteration support — all from the Postman GUI. It's the starting point for API test automation before you move to CLI tools like Newman.

Opening the Collection Runner

In Postman:

1. Select your collection in the sidebar
2. Click the Run button (triangle icon) in the top bar, or right-click the collection and choose Run collection
3. The Collection Runner panel opens on the right

Alternatively, press Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (Mac).

Runner Configuration Options

Iterations

Set how many times to run the entire collection. Default is 1. Useful for:

• Load testing (with caution — don't hammer production)
• Data-driven tests when combined with a data file

Delay

Milliseconds to wait between requests. Use this when:

• The API has rate limits
• You need to wait for async operations to complete between calls
• Testing sequential workflows where each step triggers background processing

Data File

Attach a CSV or JSON file to run the collection once per row/item, substituting variables for each iteration.

CSV format:

username,password
alice,pass123
bob,pass456
carol,pass789

JSON format:

[
  {"username": "alice", "password": "pass123"},
  {"username": "bob", "password": "pass456"}
]

In your collection requests, reference these as {{username}} and {{password}}.

Environment

Select which Postman environment to use for the run. Variables defined in the environment are available throughout the collection.

Persist Responses

Save response bodies for all requests. Useful for debugging but increases memory usage — disable for large collections.

Run Order

By default, requests run in the order they appear in the collection. You can:

• Reorder them by dragging before running
• Control flow dynamically with postman.setNextRequest() in pre-request or test scripts

Writing Tests in Requests

Each request can have test scripts that run after the response is received:

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

// Check response body
pm.test("Returns user data", function () {
  const body = pm.response.json();
  pm.expect(body.id).to.be.a('number');
  pm.expect(body.email).to.include('@');
});

// Check response time
pm.test("Response under 500ms", function () {
  pm.expect(pm.response.responseTime).to.be.below(500);
});

These assertions appear in the Runner results with pass/fail status.

Controlling Request Flow

Use postman.setNextRequest() in test scripts to jump to a different request or stop the run:

// Skip to a specific request by name
postman.setNextRequest("Refresh Token");

// Stop the collection run after this request
postman.setNextRequest(null);

This is useful for conditional flows — for example, if a login request fails, stop the run immediately rather than sending authenticated requests that will all fail anyway.

Analyzing Runner Results

After the run completes, the Results panel shows:

• Pass/Fail status for each request
• Response time per request
• Test results — each assertion with actual vs. expected on failure
• Overall statistics — total requests, assertions, failures

Click any request to expand its details: the request sent, response received, and which tests passed or failed.

Exporting Results

From the runner results view:

• Export Results — saves a JSON file with full run data
• Individual request logs can be copied

For richer HTML reports suitable for sharing with stakeholders, use Newman with the htmlextra reporter — see Newman HTML reporter guide.

Saving a Run Configuration

After configuring the runner (environment, iterations, data file), you can save the run configuration. This creates a Monitor or allows re-running with the same settings without reconfiguring each time.

In Postman's web version, you can also schedule monitors directly from the collection runner — but this requires a paid Postman plan.

Limitations of the GUI Runner

The Collection Runner works well for manual verification, but has limitations for automation:

• Not scriptable — you have to click through the UI each time
• No CI integration — can't run automatically on code push
• No programmatic output — results are visual, not machine-parseable
• Single machine — tied to your local Postman installation

For automated execution, export your collection and use Newman in CI/CD pipelines instead.

When to Use Each Tool

Continuous Monitoring

The Collection Runner is a point-in-time tool. For production API monitoring that runs continuously and alerts you to failures, HelpMeTest runs your tests every 5 minutes with email alerts on failure — usage-based pricing starting at $0.003/run, with a 14-day free trial.