Using CSV and JSON data files in the Postman Collection Runner

Posted on 28 Oct, 2014Author abhinav

Postman s Collection Runner is a powerful tool. As its name implies, the Collectio
n 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 i
n 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 Collectio
n Runner. On this front, we admit that the Postman documentation lacks clarity a
nd 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 value
s from the data file inside HTTP requests and scripts. We call these variables d
ata variables. To use them inside the Postman UI, you have to follow the same sy
ntax as environment or global variables. Having the same syntax helps you test i
ndividual 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, i
n the screenshot below, {{username}} and {{password}} inside URL parameters woul
d 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 o
r data[ username ] would let you access the value of the username variable from a da
ta 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 consi
st 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 Uni
x format. That's a restriction in our current CSV parser. Line endings can be ch
anged 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 i
llustration:
CSV-mapping.png.001
JSON files
The JSON file needs to be an array of key/value pairs. The keys are used as vari
able 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 servic
e as an example.
Click on the Import collection button in the collection sidebar.
Screen Shot 2016-06-25 at 15.08.35
Copy and paste the link given below in the Import from a URL input field and pre
ss Import.
https://www.getpostman.com/collections/1c6c3d5cfe3b12978a5f
1
https://www.getpostman.com/collections/1c6c3d5cfe3b12978a5f
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.
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 da
ta file in the responseBody variable. If everything works properly, then this te
st should pass.
Open the Collection Runner window and select the Walkthrough Data files collection
.
Download either of the files linked below.
CSV
JSON
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
The iteration count can be anything from 1 to 3. If the number of iterations spe
cified is less than the values in the data file, then the last row values are re
peated.
Run the collection and observe the result. If everything went well, you should s
ee all tests passing in the Collection Runner result window.
Screen Shot 2016-06-25 at 15.11.32