Using CSV and JSON Data Files in the Postman Collection Runner
Don’t forget to register here to attend POST/CON 24, Postman’s biggest API conference ever: April 30 to May 1, 2024 in San Francisco.
Update: If you want to dip deeper into the Postman Collection Runner, check out this newer post about Postman’s 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.
That’s all it takes!
To run a collection multiple times, you need to set the iteration count.
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 environments 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:
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.
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.
To see how the CSV file values are mapped to a Postman request, check out this illustration:
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.
To see how the JSON file values are mapped to a Postman request, check out this illustration:
Walkthrough
2021 Update: We have created an updated collection that relies on the same general workflow and principles shown in the following steps. Check out this collection with documentation for getting started:
https://www.postman.com/postman/workspace/postman-team-collections/collection/1559645-4d04faca-bdc1-47ed-85e0-ce5630b01c83
Please note: The following screenshots won’t match directly, since the UI has been updated since this blog post was first published, and the new collection is using different CSV/JSON files to demo the Collection Runner.
1. Click on the Import collection button in the collection sidebar.
2. Copy and paste the colletion link in the Import from a URL input field and press Import.
3. Once the collection is imported, have a look at the first request.
The request uses the username variable as a URL parameter.
4. 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.
5. Open the Collection Runner window and select the “Walkthrough – Data files” collection.
Download either of the files linked below.
6. 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.
7. 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.
8. Run the collection and observe the result. If everything went well, you should see all tests passing in the Collection Runner result window.
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.
Don’t forget to check out the follow-up post: Looping through a Data File in the Postman Collection Runner.
I have an environment variable called “counter”, which basically increments every time I create an object. How can I use that environment variable so I don’t have to create 10 sets of data in my JSON/CSV to create 10 objects?
I did not get your question exactly. Are you trying to generate data dynamically?
Hi, i’m exactly trying to generate my post and put bodies dynamically through a csv – without succeed. Does postman support that?
Does postman support that?
How to generate data Dynamically ?
This should help: https://learning.postman.com/docs/writing-scripts/script-references/variables-list/
I see what you mean. Suppose the two API, one of them only needs to be executed once, and the other API executes more than one use case of CSV, and I’ll describe the requirements:
1. build multiple subdirectories in a directory
2. each subdirectory runs its own CSV file independently
3., of course, it’s best to be able to run your own CSV files independently of each API
I come from China, using translation software, inappropriate, please forgive me, thank you!
in the tests tab fetch the counter and increment it and set it back to counter
let value= Number(pm.environment.get(‘your_key’));
value=value+1;
m.enviromnement.set(‘your_key’,value);
How to parse the zip compressed package in the Test editor
If there is 10 times the GET request. Can I know which request the best and worst request?
Is there any way to have the variable actually within the URL instead of as a parameter? This works with the Environment variables but I can’t seem to get it to work with the URL itself. IE: http://foo.com/api/{{id}} will not work but http://foo.com/api/?id={{id}} does. any thoughts?
Variables are replaced for the entire URL. Not sure why you are facing the issue Tucker. Can you email a sample collection to us at help@getpostman.com
Appreciate this post. Let me try it out.
Also visit my blog post – brave frontier mod
hello as a matter of fact your ideas regarding How to use CSV and JSON data files in Postman for comprehensive API testing Especially, your awesome post on this page http://www.hnwatcher.com/r/1528840/How-to-use-CSV-and-JSON-data-files-in-Postman-for-comprehensive-API-testing are contemplated as a critical Issue
how to get raw data posted by postman in php file
Is there any way to reset the values of environment variables before running the collection runner?
I know I am a little late to this discussion, but you can use postman.clearEnvironmentVariable(name); to clear any of them out. I created an array of the variable names I needed to clean, and looped through it as part of the test of the final element.
function cleanup(){
var clean = [“x”, “y”, “z”, ];
for(var i = 0; i < clean.length; ++i){
postman.clearEnvironmentVariable(clean[i]);
}
}
cleanup();
The con? Its not terribly dynamic, you have to create the array of variable names yourself. Additionally, I am not certain whether it affects the time displayed for test results, however I would expect Postman to isolate the test time from the actual ReST service timing.
When I’m outside the collection runner, and just want to run my request in the normal UI, would I set up an evironment variable for each “data” variable? That would seem to imply a lot of duplication?
For example in my collection I might have {{url}}/action?id={{id}} and have url and id defined as environment variables. Then defined again in my data variables. Is that the correct approach?
The only approach I’ve gotten to work for having things work in Postman *and* Collection Runner against a data file is to:
1) set up a global variable in the pre-request script:
postman.setGlobalVariable(“expectedunitcost”, 77.175);
2) in my test, compare a value against the data object(or the globals object if the data object is null)
var payload = JSON.parse(responseBody);
tests[“unitPrice is accurate”] = payload.laborPrice.unitPrice === data[“expectedunitcost”] || globals[“expectedunitcost”];
This assumes a value named expectedunitcost exists in your Collection Runner data file.
Thanks Nate, unfortunately that still leads to duplication – you need data variables declared in your pre-request script, and conditional statements throughout your tests, as well as data files for the collection runner.
Ideally within Postman you would be able to specify a data file, just as you can in the collection runner.
I am trying to post an integer value from a .json file. This will be a test POST request, the column should not accept the integer value, and a test will run to verify that.
However in the raw body of the parameterized POST request the only way to call the variable is in double quotes. So, it always tries to post this integer variable as a string since it is in double quotes, causing my tests to fail. Is there some workaround for this?
example json file to be used by the collection
{
“id_value” : 1
}
Example POST request using data variables
{
“id” : “{{id_value}}”
}
Did you get this sorted? I am having the same problem where the variables are of mixed types. Booleans and integers are coming out as strings.
Yeah, you have to include the attribute name in the variable.
So in the data/environment file your variable value would be:
{
“id_value” : “”id”:1″
}
Then in the raw json payload you would call the variable without quotes:
{
{{id_value}}
}
Do you have an example where this worked? Collection Runner and Newman both don’t seem to recognize the double brackets (without quotes) as needing to be replaced and my request literally sends {{id_value}}.
Doesn’t seem to work with nested elements:
{
“parent” : [{child : “{{PARAM}}”}],
}
Data is not subbed out in my POST request
Did you ever find a way around this?
You can work around this by including the attribute names in the variable.
So in the data/environment file your variable value would be:
{
“PARAM” : “”parent” : [{ “child_name” : “child_value” }]”
}
Then in the raw json payload you would call the variable without quotes:
{
{{PARAM}}
}
POSTman will display a syntax error, but this can be ignored.
I am using the env_gk as environmental variable and using that for maintaining the base url.
URL: {env_gk}}/api/v1/{{users}}?includePermissions=true.
users is another global variable which is set like this in pre-request script.
postman.setGlobalVariable(“users”, ‘users/’+data.user);
will it work? the final out come should be users-> users/user_id and user_id will be from data file.
Also is there a way to check how URL resolved?
can i choose DB as data source from postman?
I am trying iteration variable. But it always runs only once.
Have uploaded the data file as csv with two records and a header row. If i specify the iteration value anything greater than 1 , it always executes only once.
It just reads the first record from the file, am i missing anything?
@disqus_SV6ALCBuTj:disqus Can you try upgrading to v4.1.2 of the app? chrome://extensions > Enable ‘developer mode’ > Update.
My Postman app is on that version.
Postman 4.1.2
Under my collections folder i have 3 apis chained. When i give iteration 1 it gets executed once. When i give a number 4 it gets executed twice and if 7 thrice and there on.. Is that how its supposed to work.
Using collection runner and feeding the data file in csv formart.
In my pre-request script i have
postman.setEnvironmentVariable(
“merchantId”, data.merchantId
);
Here is the preview of data
iteration merchantId
1 abc
2 xyz
It gets executed during first iteration , but while second iteration starts, its errors out saying
‘Something is wrong with your test scripts. Please fix them in the editor first.
Message : There was an error during JSON.parse(); Unexpected token E ‘
Is there a way to export/write data to external CSV file ?
Is there a way to set “Authorization” header by using a CSV / JSON file. I do not want to store the credentials, even if encoded in base64 within the collections. I want to have those credentials stored externally.
I’ve tried to set it this way (CSV/JSON) but I got an error. I’ve also tried to use “Preset” and then use “Run”, but when I download the collection, I can see that the credentials are embedded in the file.
Also note that I do not want to store the credentials as an environment variable, because I will export environment variables after the test run.
How could I do such thing?
Thank you in advance for your answer. Stéphane
Then try storing the credentials in globals. Also, you can join our Slack community and ask this to other Postman users to check how they’re doing this. https://www.postman.com/slack-invite
hi,we provide online training & video tutorial for soapui
for free videos refer
http://soapui-tutorial.com/soapui-tutorial/introduction-to-webservices/
var jsonData = JSON.parse(responseBody);
tests[“Your test name”] = jsonData.value === 100;
In value do I have to provide the complete JSON path? When I provide the path, it’s failing test.
I need to test a bunch to servers each with a bunch of URLs. My list of servers and the url list keeps on changing. Is there a way I automate looping through these two data sets?
Hi,
I tried using the tool. I am facing issue with Json String values. Even the demo link run given with sample Json is failing.
My Sample Json looks like this
[
{
“1”:”LEG123″,
“2”:”AMERA”,
“3”:”estSalePrice66,
“4”:”TEST SALE PRICE66″,
“5”:”cdc78d48-2809-42e3-b006-3e799ed226d2″,
“6”:”QAR””
}
]
{
“Type” : “Sale”,
“active” : true,
“Entity” : {
“id” : {{1}},
“code” : {{2}},
“elementType” : “Legal_Entity”
},
“code” : {{3}},
“description” : {{4}},
“currency” : {
“id” : {{5}},
“code” : {{6}}
}
}
But my REST API is getting the string values with single Quotes and giving error. Any hint as what the issue and possible solution
Hi – I have expected results in my imported .csv file that include ®.
The postman .csv data file reader during the reading (and previewing) process for Collection Runner seems to interpret these as � This is causing false fails in my test results. Note that I confirmed my csv file is saving these characters correctly as ®, and I also confirmed that using postman console.log(“SP Complete®”); returns as ®. The problem seems to be in the postman csv reader. Please advise if there is a way around this or a fix coming soon. Thx!
“If the number of iterations specified is less than the values in the data file, then the last row values are repeated.”
Shouldn’t this read, “”If the number of iterations specified is GREATER than the values in the data file, then the last row values are repeated.”
We have to supply data file path for every run in collection Runner. Is there a way to set data file path once and run anytime ?
Another question : ActiveXObject was not supported by Chrome browser, thats why we cannot establish DB connection from Postman(Chrome extension version). Now we got stand alone Windows/Mac App. Is there a way to connect database in recent Windows/Mac App ?
Hi Ravi,
Did you find a way to do this?
Doesnt work me.
the request does not replace {{paramname}} with the json input I am sending.
Even the samples dont run
Hi,
Thanks for this article.
I have imported the demo collection using mentioned link however on run getting “404
Not Found” error.
Tried both csv & json files. in preview its showing correct data.
However on run getting error.
Any suggestion.
Hi,
I have created copy of data file with only 3 parameters url, username, password
url as https://echo.getpostman.com
Request link is also modified to https://echo.getpostman.com/get?username={{username}}&password={{password}}&url={{url}}
Now results are getting passed.
Thanks for getting in touch. I think your best bet would be to join our Slack community and post your question there, here is a link to join: https://www.postman.com/slack-invite. It’s a great resource for all Postman users, you’ll even find our very own devs on there all the time. Let me know how you get on.
Cheers,
Rob
Need to run a collection from console. My collection contains multiple requests where each request has there own json/csv testdata. i’m able to run each of them from runner individually. Is there a way where i can run whole collection with each request having their own testdata file from runner/console.
You can export the collection and run it using wingman.
Hi, thanks for sharing this great article.
Is there anyway to run an individual Post / Get request using a csv file?
This would be useful when testing individual requests before committing them to the collection.
Hello,
I am trying to extract a column with multiple values from excel to an array in postman.
Is there a way I can do this without using Iteration?
Thank you,
Hi Abhinav,
You did great job by providing the postman.
After using the postman, one feature is missing. That is manually disabling the Request which we are not going to use. For example when the feature of project is no more use in that case we need to disable the request service for respective services. If you provide those disable or enable feature in each request it will be great enhancement for Postman.
If you need any help in development, let me know. I will be more interested to work with you.
Thanks & Regards,
Sachin
You show how to use data variables in a GET. What about using data variables in a POST payload? I use the same {{}} syntax and Postman/Runner gets null; I take it because it doesn’t know to go look at the .csv I specified.
Below format when mapped is not working in request paylod
[
{ “data”:
{
“url”: “http://www.twitter.com/a85”,
“user_id”: 1,
“token_id”: 123123123,
“username”: “abhinav”,
“password”: “abc”
}},
{
“data”: {
“url”: “http://www.twitter.com/sobtiankit”,
“user_id”: 2,
“token_id”: 899899,
“username”: “ankit”,
“password”: “def”
}}
]
Working when we convert this JSON file to CSV and import
Hello,
Thanks for post, very helpful.
if csv file have multiple sheet, how it will work ?
While importing the url: “https://www.postman.com/collections/1c6c3d5cfe3b12978a5f”
Postman is throwing an error as format not recognized, please help.
Hello team,
Please let me know how to specify test data file (.json/.csv) in exported postman collection, so that I can run it via command line using newman on my local system.
I would like to run functional test cases (postman_collection.json) via Jenkins CI build as well. So, need to get an idea where & how to mention test data file in exported collection.
Appreciate your quick help. Thanks in advance.
Thanks,
Sukanta
how can i test my api for my backend code ? i need to inter a fils to postman to let it do API’s test ? i don,t know how can i get this fils from by backend or my database ???? i need same help plz even i don’t get documentation wase helpeen me for !
Hi Amani, Please contact our support team at http://www.postman.com/support and they’ll be able to help you.
How to use different sheets csv data in collection runner
Hi Girish, Please contact our support team at http://www.postman.com/support and they’ll be able to help you.
I am running the postman runner using a json object while executing the post man runner the data for the request payload is not taken from the json file but it takes it from the previously executed api request(same API) without runner. What could be the reason ?
While I tried to take the input from a .csv or .json file my “Start Run/Start Test” Option is disabled in Postman tool
Hi, I have a JSON in which contents are escaped. e.g.
{
“tenantId”: “tenant1”,
“Payload”: “{\r\n\t\”descriptor\”: {\r\n\t\t\”contentId\”: \”5id1\”\r\n\t}}”
}
I am trying to run it using runner, where I will post different payloads for different tenants. But while doing so when the postman reads my JSON file it is removing all the escaped characters. How can I avoid it?
Thanks
Hi Ritesh, Please contact our support team at http://www.postman.com/support and they’ll be able to help you.
Thank you for this article!
Can you please update the link to the collection? the current link does not work. Also, I wasn’t able to find this collection on postman-echo.com
Hi Lio, Please use this more recent collection here.
Where Can I find Collection Runner?
How to save .csv , .json file in Data Files?
Hi Amod, You can check out our Learning Center docs for the Collection Runner here.
Is there a character limit on the data when you upload a csv to the Runner? I’m uploading a csv, and it has an id with 21 characters, and it appears to get truncated at 20 characters. Also it seems to round another one of the IDs, treating it as a number instead of as a string.
Is there maybe an incompatibility betwen .csv and the Postman runner?
Hi, If you want to keep very large numbers or numbers with leading zeros as they are, you can specify them as a string in CSV file by wrapping the number in double quotes like this: “9223372036854775807” (a number wrapped in quotes will be parsed as a string instead of a JavaScript Number). If you still have issues, please contact our support team at https://support.postman.com/.
I have a csv with various rows and a collection with various requests but only the first row . request is executed. Any advice please?
Please contact our support team here, and they’ll be glad to help you!
How to pass csv data in postman collection so monitor can pick it..?
Great guide… Confusing to me though.. I’ve listed out the steps that I had to do to make it work.. Hopefully it’ll save some of you some time..
1. Go-to the collection:
https://www.postman.com/postman/workspace/postman-team-collections/collection/1559645-4d04faca-bdc1-47ed-85e0-ce5630b01c83
2. Find>Working with data files: ramen
3. Click the 3 dots next to it>Fork Collection
4. Give it a name and put it in the workspace that you want.
5. Once it’s in your workspace go to it.
6. Right click the 3 dots next “Example request” rename it to “Get usernames”
7. Go to “Tests” and delete everything.
8. Paste this two lines below:
tests[“Body contains username”] = responseBody.has(data.username);
tests[“Body contains password”] = responseBody.has(data.password);
9. By the “Get” dropdown change the URL to this:
https://postman-echo.com/get?username={{username}}&password={{password}}
10. Click “Save” by the blue “Send’ button
11. Go back to Get username and click on the 3 dots again
12. Duplicate
13. Rename Get username Copy to Post username
14. With Post username selected go up and change “Get” to “Post”
15. Save
16. Click back on the folder “Working with data:ramen”
17. Look for the “Run” button up top in the middle.
18. If you can’t see it click on the 3 dots that are on the same row as the “Share” button.
19. Here are the two files that you can used:
CSV: https://www.dropbox.com/s/zrz49c9s5lqx14s/data-article.csv?dl=0
JSON: https://www.dropbox.com/s/o2cguyx4iv053j6/data-article.json?dl=0
20. Go to the right side middle and click on “Select File”
21. Once you run it and you followed my steps you’ll have completed mostly the entire thing..
22. You’ll get a failed on the “Post” request because the url doesn’t exist for that but it works non the less..
I’ve used this and it works really well. What I’m looking for now is the possibility to use variables from CSV in the response. Is this possible with Postman?
Reference:
“PARAM” : “”parent” : [{ “child_name” : “child_value” }]”
Tried the above, I have multiple Child name + Value pairs inside (upto 12 sometimes 15) see eg below; Postman keeps showing error and doesnot allow me to run the collection. What is the modification required?
“”parent” : [{ “child_name” : “child_value”,
“child_name” : “child_value”,
“child_name” : “child_value”,
“child_name” : “child_value”,……..}]”
how to run range of test data of a csv file. For example if csv file has 10 rows (test data), how can I run only rows 5 through 8 using collection runner?
How to remove JSON request tag from the request if value is not available in CSV?
Hi, I have a json file with an array of f.e. 10 objects. I need to call a request (not a test) 10 times in runner. each time with 1 of those objects as body. I need to get whole object from an array in a file as parameter into body of a request like you get some Variable into URL. With every body unique and every time different number of objects in an array.
Please help.
Hi Simon, If you’re still having issues, please contact our support team at https://www.postman.com/support, and they’ll be glad to help you!
I’m not sure if it’s possible, but can you write a test that spans more that one request?
I have to write one that tests the rate limiting on an endpoint, so the scenario would be something in the trend of.
1st request -> expected response 200 code
2nd request -> expected response 200 code
3rd request -> expected response 429 code
Delay
4th request -> expected response 200 code
I thought the collection runner could do this, but the test code window seems on a per request base.
I wanted a solution to import bulk data for below request body:-
“ABC” : [
“*;*;local;wifi”, “*;*;local;wifi”
],
so for above body i’m passing JSON as below:-
“ABC” : [
{{ABC}}
],
And now in excel file saving with .csv i’m passing
ABC
“*;*;local;wifi”
“*;*;local;wifi”
Here but only single data is getting pass in one iteration .. Please help me with this
Please contact our support team at http://www.postman.com/support and they’ll be able to help you.