When you start a collection run, all requests are run in the order you see them in the main app. So all requests are executed first, by order of the folder, and then any requests in the root of the collection.
However, you can override this behavior using a built-in function called
postman.setNextRequest(). This function, as the name suggests, allows you to specify which request runs next.
Let's look at a sample collection to understand this function.
Let's assume that we have a collection with four requests. If you run this collection directly, the collection runner runs all four requests in order.
Let's now add
postman.setNextRequest() to Request 1's test script, as shown.
postman.setNextRequest() is a function with one argument, which is the name or ID of the request you want to run next.
In the example, we're setting the next request to Request 4 in the test script for Request 1. So the execution jumps to Request 4 after Request 1 has completed. If we run the same collection now, you'll see that only two requests are run now.
postman.setNextRequest() only works with the collection runner and Newman where the intent is to run a collection, as opposed to sending a single request.
Now that we have a good understanding of how
setNextRequest() works, we can perform advanced actions.
Since you are no longer restricted by the order in which you define your requests, you can jump around your collection, establish conditional logic, or skip unnecessary requests.
This blog post explains how you can write a collection that will generate Spotify playlists for you based on your favorite musical artists.
Remember these two facts as you use this workflow:
postman.setNextRequest()is always executed at the end of the current request. This means that if you put this function before other code blocks anywhere in pre-request or test script, these blocks will still execute.
postman.setNextRequest()has a scope, which is the source of your collection run. If you run a collection, you can jump to any request in the collection (even requests inside folders, using the same syntax). However, if you run a folder, the scope of
postman.setNextRequest()is limited to that folder. So you can jump to any request in this folder, but not ones that are outside of the folder. It includes requests inside other folders, and also root-level requests in the collection. To read more about running collections or folders.
For more information on collection runs, see: