Collection Runner

What is the Collection Runner?

The Collection Runner lets you run all requests in a collection (or a folder within one) in sequence, automatically. Instead of clicking "Send" on each request one by one, the runner fires them all and gives you a pass/fail report at the end.

It's how you go from manually testing individual endpoints to running an automated end-to-end test of your entire API workflow.

When to Use It

• Full workflow testing — register → login → create resource → update → delete
• Regression testing — run your full collection after every code change
• Data-driven testing — run the same requests with different input data using a CSV or JSON file
• Smoke testing — quickly verify all endpoints are alive after a deployment

Running a Collection

1. Right-click on your collection in the sidebar
2. Click "Run collection" (or click the ▶ Run button)
3. The Collection Runner panel opens with options:

Setting	Description
Iterations	How many times to run the entire collection
Delay	Milliseconds to wait between requests
Data file	CSV or JSON for data-driven testing
Environment	Which environment to use
Save responses	Store response bodies in the run results

4. Click "Run [Collection Name]"

Reading the Results

After the run, you see a summary with:

• Total requests run
• Tests passed / failed
• Average response time
• Per-request breakdown: status code, response time, test results

Click on any request to see its full response and which specific assertions passed or failed.

Data-Driven Testing

The real power of the runner is running the same requests with different data from a file. This is great for testing:

• Multiple user registrations
• Various edge cases for an endpoint
• A list of IDs to fetch

CSV Format

users.csv

email,password,expectedStatus
user1@test.com,pass123,201
user2@test.com,pass456,201
invalid-email,pass789,400
user1@test.com,pass123,409

JSON Format

users.json

[
  { "email": "user1@test.com", "password": "pass123", "expectedStatus": 201 },
  { "email": "user2@test.com", "password": "pass456", "expectedStatus": 201 },
  { "email": "invalid-email",  "password": "pass789", "expectedStatus": 400 }
]

Using Data Variables in Requests

Reference data file columns the same way you reference environment variables — {{variable_name}}:

Request body:

{
  "email": "{{email}}",
  "password": "{{password}}"
}

In your test script:

const expectedStatus = parseInt(pm.iterationData.get("expectedStatus"));
pm.test(`Status is ${expectedStatus}`, () => {
  pm.response.to.have.status(expectedStatus);
});

pm.iterationData.get() reads from the current row of your data file.

Running with a Data File

1. In the Collection Runner, click "Select File" under Data
2. Choose your CSV or JSON file
3. Postman sets Iterations to match the number of rows automatically
4. Run — each iteration uses the next row of data

Controlling Request Order with setNextRequest

By default, the runner executes requests top to bottom. You can change this with postman.setNextRequest() in a test script:

Login Request → Tests

const json = pm.response.json();

if (pm.response.code === 200) {
  pm.environment.set("TOKEN", json.token);
  postman.setNextRequest("Get User Profile"); // jump to this request next
} else {
  postman.setNextRequest(null); // stop the run on login failure
}

Use postman.setNextRequest(null) to stop the runner early (useful when a critical step fails and later requests would all be meaningless).

Example: Full Auth Workflow

Here's a real-world collection run sequence:

1. Register User
   → Test: status 201, save userId
   → On failure: stop run

2. Login
   → Test: status 200, token in response
   → Script: save TOKEN to environment

3. Get Profile (authenticated)
   → Test: status 200, data matches registered user

4. Update Profile
   → Test: status 200, changes reflected

5. Delete Account
   → Test: status 200 or 204

6. Verify Deleted (try to login)
   → Test: status 401 or 404

Each request in this sequence builds on the previous — the runner handles the whole flow automatically.

Exporting Run Results

After a run, click "Export Results" to save a JSON report. This is useful for:

• Sharing test results with your team
• Storing results in CI/CD artifacts
• Comparing runs over time

Running Collections from the Command Line (Newman)

For CI/CD pipelines, use Newman — the command-line runner for Postman collections:

npm install -g newman

# Export your collection from Postman, then run:
newman run collection.json -e environment.json

Newman exits with a non-zero code on test failure, which CI systems (GitHub Actions, etc.) detect automatically.

.github/workflows/api-tests.yml

- name: Run API tests
  run: newman run collection.json -e staging.environment.json