Use a data file to simulate virtual users

When you configure a performance test, you specify a number of virtual users. During the test, each virtual user (VU) runs the selected requests in the specified order in a repeating loop.

By default, each virtual user runs the same requests using the same values. You can customize the behavior of virtual users by importing a CSV or JSON file. Each virtual user can send requests using different values from the imported data file. This enables you to better simulate real-world traffic when testing the performance of your API.

Run a performance test with a data file

Importing a data file enables you to populate variables with imported data when running a performance test. Each virtual user can use data from a different row in the data file, customizing their behavior and better simulating real-world usage of your API.

Before you begin, add variables to the requests in your collection. Then create a data file with the data to use for each variable.

To run a performance test with a data file, do the following:

1. Configure a performance test, specifying the number of Virtual users, the Test duration, and a Load profile.

2. Select a Data file with custom values to use for each virtual user. After you select your data file, a preview of the data file displays.

   The data file must be in CSV or JSON format. Learn more about formatting a data file.

   

3. Postman automatically detects the Data file type. If needed, you can select a different file type (CSV or JSON).

4. Under VU data mapping, select how rows in the data file are mapped to virtual users:

   • Ordered - Each VU uses data from a specific row of the data file. The first VU uses the first data row, the second VU uses the second data row, and the pattern continues until each VU has been assigned a data row. Extra rows aren't used.

   • Randomized - Each VU uses data from a random row of the data file every time the VU runs the collection.

   If you select Ordered and your data file has fewer rows than the number of VUs, some VUs won't receive data during the performance test. You can add more rows to your data file and import the file again, or you can select Randomized.

5. (Optional) For CSV files, Postman automatically detects the data type for each column in the file. If needed, you can use the dropdown menu at the top of a column to select a different data type (String, Boolean, or Number).

   If your CSV file has numbers longer than 16 digits, numbers with preceding zeroes (for example, 000000345), or phone numbers (for example, +12125556709), select the String data type to prevent values from being truncated.

6. Select Continue when you're done configuring the data file.

   You can select the settings icon to reconfigure the data file. You can also select a new data file or select the delete icon to remove the data file.

   

7. Select Run to run the performance test using the data file. Each VU uses the assigned data from the data file to populate variables when running the requests in the collection.

Data file format

Format the CSV file so that the first row has the variable names 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 Unix format. Each row must have the same number of columns.

For CSV files, note the following:

• If the numbers in your data file are longer than 15 digits, you'll need to format them as text in your spreadsheet program, so they're not truncated when exporting to CSV format.

• If your CSV file has numbers longer than 16 digits, numbers with preceding zeroes (for example, 000000345), or phone numbers (for example, +12125556709), you'll need to configure the file in Postman and specify String for the column data type. Learn more about running a performance test with a data file.

Format JSON files as an array of key-value pairs. Each key is the name of a variable, and the value is the data to use within the request.

Variable names are case sensitive, so make sure to use the same case for variables in Postman as in the CSV or JSON file. Variables in data files are resolved as local variables, so you can access them using pm.variables.get("variable_key"). Learn more about using variables in scripts.

Debug errors when using data files

You can view details about errors that occurred during the performance test to help in the debugging process. After the performance test finishes, select the Errors tab. Expand an error class below the graph, then select a request to view the response, headers, and body. Select the data file name to view the variable data that was used for the request.

Data files aren't saved for past performance test runs.