Looping through a Data File in the Postman Collection Runner

 

Update, January 2020: Want to see how the Postman Collection Runner has evolved even further? Read our more recent blog post about Postman product improvements.

---

Postman’s Collection Runner lets you run all the requests inside a collection locally in the Postman app. It also runs API tests and generates reports so that you can measure the performance of your tests.

If you upload a data file to the collection runner, you can:

• Test for hundreds of scenarios
• Initialize a database
• Streamline setup or teardown for testing

Let’s start with the basics.

Run a collection with the Collection Runner

To run a collection in the Postman app, click on the chevron (>) next to the collection’s name to expand the details view. Select the blue Run button to open the Collection Runner in a new window.

Verify the collection and environment if you’re using one, and hit the blue Run button. You’ll see the collection requests running in sequence and the results of your tests if you’ve written any.

Use data variables

What if you want to loop through data from a data file? This would allow you to test for hundreds of scenarios.

In the Postman app, you can import a CSV or JSON file, and use the values from the data file in your requests and scripts. You can do this using data variables with a similar syntax as we do when using environment and global variables.

Using data variables in requests

Text fields in the Postman app, like the authorization section or parameters data editor, rely on string substitution to resolve variables. Therefore, you should use the double curly braces syntax like {{variable-name}} in the text fields.

Using data variables in scripts

The pre-request and test script sections of the Postman app rely on JavaScript (not text). Therefore, you can use Postman’s pm.* API, like the pm.iterationData.get(“variable-name”) method, to access the values loaded from the data file.

Use data files

Using a CSV file

The CSV file should be formatted so that the first row contains the variable names that you want to use inside the requests. After that, every row will be used as a data row. The line endings of the CSV file must be in the UNIX format. Each row should have the same number of columns.

Using a JSON file

The JSON file should be formatted as an array of key-value pairs. The keys will be the name of the variable with the values the data that is used within the request.

---

Try it yourself:

Click the orange Run in Postman button above to import this example collection into your local version of the Postman app.

We will run this collection using a data file about my 4th favorite type of Japanese food: ramen. The data file can be exported from Google Search Trends about the volume of searches for “Ramen” by city. Download one or both of these sample data files, and give it a try.

• CSV file
• JSON file

---