Using CSV and JSON data files in the Postman Collection Runner

Postman’s Collection Runner is a powerful tool. As its name implies, the Collection Runner (CR) lets you run all requests inside a Postman collection one or more times. It also executes tests and generates reports so you can see how your API tests compare to previous runs.

Basic usage
To run a collection, open the Collection Runner window by clicking on the link in the navigation bar. Choose a collection from the drop down menu, and hit Start.

Screen Shot 2016-06-25 at 13.07.25

That's all it takes!

To run a collection multiple times, you need to set the iteration count.
Screen Shot 2016-06-25 at 13.07.52

One feature that gets most people stumped is using data files with the Collection Runner. On this front, we admit that the Postman documentation lacks clarity and I hope that this article helps you understand the feature better.

The Collection Runner let’s you import a CSV or a JSON file and then use the values from the data file inside HTTP requests and scripts. We call these variables data variables. To use them inside the Postman UI, you have to follow the same syntax as environment or global variables. Having the same syntax helps you test individual requests inside Postman using dummy environment values. When you move to the Collection Runner you don't have to change anything.

Data variables in requests
Variables inside the Postman UI are enclosed inside curly braces. For example, in the screenshot below, {{username}} and {{password}} inside URL parameters would be replaced by corresponding values from the data file:

Screen Shot 2016-06-25 at 14.47.47

Data variables in pre-request and test scripts
Inside pre-request and test scripts, the special data dictionary contains values loaded from the data file for a specific iteration. For example data.username or data[‘username’] would let you access the value of the username variable from a data file.

Screen Shot 2016-06-25 at 14.48.35

CSV files
For CSV files to work inside the Collection Runner, the first row needs to consist of variable names that you want to use inside requests. Every subsequent row is used as a data row. Make sure the line endings of the CSV file are in the Unix format. That's a restriction in our current CSV parser. Line endings can be changed in a text editor like Sublime Text.

Download sample CSV file

To see how the CSV file values are mapped to a Postman request, check out this illustration:

CSV-mapping.png.001

JSON files
The JSON file needs to be an array of key/value pairs. The keys are used as variable names while the values are replaced inside requests.

Download sample JSON file

To see how the JSON file values are mapped to a Postman request, check out this illustration:
JSON-mapping.001

Walkthrough
We have created a sample collection for you using our echo.getpostman.com service as an example.

  1. Click on the Import collection button in the collection sidebar.

Screen Shot 2016-06-25 at 15.08.35

  1. Copy and paste the link given below in the Import from a URL input field and press Import.

  1. Once the collection is imported, have a look at the first request.

Screen Shot 2016-06-25 at 15.09.38

The request uses the username variable as a URL parameter.

  1. Open the test script editor. It’ll show you the following snippet:

tests["Body contains username"] = responseBody.has(data.username);
tests["Body contains password"] = responseBody.has(data.password);

The test checks for the presence of the username and password values from the data file in the responseBody variable. If everything works properly, then this test should pass.

  1. Open the Collection Runner window and select the “Walkthrough – Data files” collection.

Download either of the files linked below.

CSV

JSON

  1. Select “Choose files” from the file and load the data file in the collection runner. If the data file was loaded successfully, you can preview the values within the Collection Runner.

Screen Shot 2016-06-25 at 15.10.55

  1. The iteration count can be anything from 1 to 3. If the number of iterations specified is less than the values in the data file, then the last row values are repeated.

  2. Run the collection and observe the result. If everything went well, you should see all tests passing in the Collection Runner result window.

Screen Shot 2016-06-25 at 15.11.32

Conclusion

Testing your API using the Collection Runner and data files would make it more robust by testing for hundreds of variations instead of a couple of use cases. It can also be used for performing basic operations like database initialization, clean up or just for a basic checkup. If you have come up with a creative use case for using data files inside Postman, let us know in the comments and we will feature it on the blog.

UPDATE: Check out the follow up: Looping through a data file in the Postman Collection Runner 🍜