Postman’s Collection Runner executes requests sequentially by default, which is often the desired behavior for API testing and workflow automation.
Imagine you have a sequence of API calls that need to happen in a specific order. For instance, you might first create a user, then log that user in, and finally retrieve the user’s profile. The Collection Runner is designed to handle exactly this. When you run a collection, Postman iterates through each request in the order they appear within the collection or folder.
Here’s a look at a sample collection and how the Runner would process it:
{
"info": {
"_postman_id": "your-collection-id",
"name": "User Workflow",
"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
},
"item": [
{
"name": "Create User",
"request": {
"method": "POST",
"url": "https://api.example.com/users",
"body": {
"mode": "raw",
"raw": "{\"username\": \"testuser\", \"password\": \"password123\"}"
}
},
"response": []
},
{
"name": "Login User",
"request": {
"method": "POST",
"url": "https://api.example.com/login",
"body": {
"mode": "raw",
"raw": "{\"username\": \"testuser\", \"password\": \"password123\"}"
}
},
"response": []
},
{
"name": "Get User Profile",
"request": {
"method": "GET",
"url": "https://api.example.com/users/me"
},
"response": []
}
]
}
When you click the "Run" button for this collection in Postman, the Collection Runner will:
- Execute "Create User": It sends a POST request to
https://api.example.com/users. - Execute "Login User": After the "Create User" request completes (regardless of success or failure, unless you have specific error handling to stop execution), it sends a POST request to
https://api.example.com/login. - Execute "Get User Profile": After the "Login User" request completes, it sends a GET request to
https://api.example.com/users/me.
This sequential execution is fundamental for scenarios where subsequent requests depend on the output of preceding ones. For example, if the "Create User" request returns a user ID, you would typically save this ID in an environment variable within a Tests script. Then, the "Login User" or "Get User Profile" requests could reference this variable to operate on the specific user created.
// In the Tests tab for "Create User"
pm.test("Status code is 201", function () {
pm.response.to.have.status(201);
});
if (pm.response.code === 201) {
const responseData = pm.response.json();
pm.environment.set("createdUserId", responseData.id); // Save the user ID
pm.environment.set("username", responseData.username); // Save username for login
}
And then in "Login User":
// In the Tests tab for "Login User"
pm.test("Status code is 200", function () {
pm.response.to.have.status(200);
});
if (pm.response.code === 200) {
const responseData = pm.response.json();
pm.environment.set("authToken", responseData.token); // Save the auth token
}
And finally, in "Get User Profile":
// In the Tests tab for "Get User Profile"
pm.test("Status code is 200", function () {
pm.response.to.have.status(200);
});
pm.request.headers.add({
key: "Authorization",
value: "Bearer {{authToken}}" // Use the saved token
});
The Collection Runner’s default sequential execution makes it a powerful tool for orchestrating complex API workflows without needing external scripts or tools. You can control the flow further using the postman.setNextRequest() function within your Tests scripts, which allows you to explicitly define which request runs next, skip requests, or even create loops.
The order of execution is determined by the order of items within the collection or folders. If you have nested folders, Postman will traverse them in order, executing requests within each folder sequentially before moving to the next folder.
One subtle aspect of the Collection Runner’s sequential execution is how it handles the Tests scripts. These scripts run after the response for a request has been received. This means that any environment variable or global variable set within the Tests script of one request is immediately available for the next request in the sequence. This immediate availability is what enables dynamic data flow between requests.
The Collection Runner also allows you to configure iteration counts and delays between requests. When you set an iteration count greater than 1, each request in the collection will be executed that many times sequentially. For example, if you have 3 requests and set iterations to 2, Request 1 runs, then Request 2, then Request 3, and then Request 1 runs again, followed by Request 2, and finally Request 3.
The most surprising thing about the Collection Runner’s sequential execution is that its default behavior is often misunderstood as a simple list traversal. In reality, the ability to dynamically control the next request using postman.setNextRequest() transforms it from a simple sequential runner into a stateful workflow engine capable of complex conditional logic and branching.
Understanding how variables persist and are made available between requests in the sequence is key to mastering dynamic workflows.
The next thing you’ll likely encounter is how to handle conditional execution and error handling within the Collection Runner to build more robust test suites.