# Using CSV and JSON Data Files in the Postman Collection Runner

> ***Update:** This post has been updated over time to reflect changes in the Postman app. While the screenshots and UI labels may differ from the current interface, the core concepts around using CSV and JSON files to drive collection runs remain the same. For the most up-to-date guidance on running collections with imported data, refer to the [Postman Docs](https://learning.postman.com/docs/collections/running-collections/working-with-data-files/).*

 [Postman’s Collection Runner](https://blog.postman.com/looping-through-a-data-file-in-the-postman-collection-runner/) is a powerful tool. As its name implies, the Collection Runner (CR) lets you run all requests inside a [Postman Collection](https://learning.postman.com/docs/postman/collections/creating-collections/) one or more times. It also executes [tests](https://learning.postman.com/docs/writing-scripts/test-scripts/) and generates reports so you can see how your [API](https://www.postman.com/what-is-an-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. Select a collection from the dropdown menu and click **Start**. [![Screen Shot 2016-06-25 at 13.07.25](https://blog.postman.com/wp-content/uploads/2016/06/Screen-Shot-2016-06-25-at-13.07.25.png)](https://blog.postman.com/wp-content/uploads/2016/06/Screen-Shot-2016-06-25-at-13.07.25.png) 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](https://blog.postman.com/wp-content/uploads/2016/06/Screen-Shot-2016-06-25-at-13.07.52-1024x719.png)](https://blog.postman.com/wp-content/uploads/2016/06/Screen-Shot-2016-06-25-at-13.07.52.png) One feature that gets most people stumped is using data files with the Collection Runner. The Collection Runner lets 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](https://learning.postman.com/docs/sending-requests/managing-environments/) or global [variables](https://learning.postman.com/docs/sending-requests/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 in 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](https://blog.postman.com/wp-content/uploads/2016/06/Screen-Shot-2016-06-25-at-14.47.47-1024x347.png)](https://blog.postman.com/wp-content/uploads/2016/06/Screen-Shot-2016-06-25-at-14.47.47.png)## **Data variables in pre-request and test scripts**

 Inside pre-request and [test scripts](https://learning.postman.com/docs/postman/scripts/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](https://blog.postman.com/wp-content/uploads/2016/06/Screen-Shot-2016-06-25-at-14.48.35-1024x413.png)](https://blog.postman.com/wp-content/uploads/2016/06/Screen-Shot-2016-06-25-at-14.48.35.png) **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](https://www.dropbox.com/s/zrz49c9s5lqx14s/data-article.csv?dl=0) To see how the CSV file values are mapped to a Postman request, check out this illustration: [![CSV-mapping.png.001](https://blog.postman.com/wp-content/uploads/2016/06/CSV-mapping.png.001-1024x768.png)](https://blog.postman.com/wp-content/uploads/2016/06/CSV-mapping.png.001.png) **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](https://www.dropbox.com/s/o2cguyx4iv053j6/data-article.json?dl=0) To see how the JSON file values are mapped to a Postman request, check out this illustration: [![JSON-mapping.001](https://blog.postman.com/wp-content/uploads/2016/06/JSON-mapping.001-1024x768.png)](https://blog.postman.com/wp-content/uploads/2016/06/JSON-mapping.001.png)## **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](https://www.postman.com/postman/workspace/postman-team-collections/collection/1559645-4d04faca-bdc1-47ed-85e0-ce5630b01c83?ctx=documentation) with documentation for getting started: https://www.postman.com/postman/workspace/postman-team-collections/collection/1559645-4d04faca-bdc1-47ed-85e0-ce5630b01c83 1. Click on the **Import collection** button in the collection sidebar. [![Screen Shot 2016-06-25 at 15.08.35](https://blog.postman.com/wp-content/uploads/2016/06/Screen-Shot-2016-06-25-at-15.08.35-1024x610.png)](https://blog.postman.com/wp-content/uploads/2016/06/Screen-Shot-2016-06-25-at-15.08.35.png) 2. Copy and paste the collection 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. [![Screen Shot 2016-06-25 at 15.09.38](https://blog.postman.com/wp-content/uploads/2016/06/Screen-Shot-2016-06-25-at-15.09.38-1024x559.png)](https://blog.postman.com/wp-content/uploads/2016/06/Screen-Shot-2016-06-25-at-15.09.38.png) 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. [CSV](https://www.dropbox.com/s/zrz49c9s5lqx14s/data-article.csv?dl=0) [JSON](https://www.dropbox.com/s/o2cguyx4iv053j6/data-article.json?dl=0) 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. [![Screen Shot 2016-06-25 at 15.10.55](https://blog.postman.com/wp-content/uploads/2016/06/Screen-Shot-2016-06-25-at-15.10.55-1024x840.png)](https://blog.postman.com/wp-content/uploads/2016/06/Screen-Shot-2016-06-25-at-15.10.55.png) 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. [![Screen Shot 2016-06-25 at 15.11.32](https://blog.postman.com/wp-content/uploads/2016/06/Screen-Shot-2016-06-25-at-15.11.32-1024x723.png)](https://blog.postman.com/wp-content/uploads/2016/06/Screen-Shot-2016-06-25-at-15.11.32.png) **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, cleanup, 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. **Don't forget to check out the follow-up post: [Looping through a Data File in the Postman Collection Runner.](https://blog.postman.com/2018/04/11/looping-through-a-data-file-in-the-postman-collection-runner/)**