JMeter – Parameterization (CSV Data Set Config)

Test Data setup is a common requirement for any non-functional test. Unique and bulk test data helps to simulate the real-time scenario in Performance Testing. Those test data either need to be generated or get it from the server log. Now, the next question is how to use external Test Data for Non-Functional Testing using Apache JMeter. We can also say how to do parameterization in Apache JMeter. Apache JMeter has an element that allows you to use external test data sets in a CSV or txt format. That element is called ‘CSV Data Set Config’.

What is the CSV Data Set Config element?

The ‘CSV Data Set Config’ element is used to read lines from a file and split them into variables. It is well suited to handle large numbers of variables and is also useful for testing with random and unique values.

Figure 01: ‘CSV Data Set Config’ element

How to add and use the ‘CSV Data Set Config’ element?

Follow the below steps:

  1. Select ‘Test Plan’ or ‘Thread Group’ node (where you want to add CSV Data Set Config’ element)
    Note: CSV Data Set Config is a scope-specific element. When you add it under ‘Test Plan’ then its scope is global whereas to add under a thread group restricts its scope to a particular thread group only.
  2. Right-click on the ‘Test Plan’ or ‘Thread Group’ node
  3. Mouse hover ‘Add’
  4. Mouse hover ‘Config Element’
  5. Click ‘CSV Data Set Config’
  6. Provide the path of the .csv file (Test Data file) in the ‘Filename’ field.
    Note: JMeter has a limitation to use test data which is stored in a .csv file format only. .csv file is a comma-separated file in which values are separated by a comma in each row. Each value is treated as a value of a particular variable.
  7. Set the remaining option as per the requirement (a description of each option is available below)

What are the attributes of the ‘CSV Data Set Config’ element?

“CSV Data Set Config” has below attributes:

  1. Name: To provide “CSV Data Set Config” name
  2. Comments: To provide comments (if any)
  3. File Name: Name or relative path of the file to be read. If the file(s) is/are stored in the Apache JMeter bin folder then the only name is enough (with extension) otherwise give the full path along with the file name. Relative file names are resolved with respect to the path of the active test plan. For distributed testing, the CSV file must be stored on the server host system in the correct relative directory to where the JMeter server is started. Absolute file names are also supported but note that they are unlikely to work in remote mode unless the remote server has the same directory structure. If the same physical file is referenced in two different ways – e.g. csvdata.txt and ./csvdata.txt – then these are treated as different files. If the OS does not distinguish between upper and lower case, csvData.TXT would also be opened separately.
  4. File Encoding: The encoding to be used to read the file, if not the platform default
  5. Variable Names (comma-delimited): List of variable names separated by the comma. JMeter supports CSV header lines: if the variable name field is empty, then the first line of the file is read and interpreted as the list of column names. The names must be separated by the delimiter character. They can be quoted using double quotes.
    JMeter allows values to be quoted; this allows the value to contain a delimiter. If “allow quoted data” is enabled, a value may be enclosed in double-quotes. These are removed. To include double-quotes within a quoted field, use two double-quotes. 
    For Example: 1,”2,3″,”4″”5″ will be treated as
    a. 1
    b. 2,3
    c. 4″5
  6. Delimiter: “\t” or “,” can be used as a delimiter. The delimiter to be used to split the records in the file. If there are fewer values on the line than there are variables the remaining variables are not updated – so they will retain their previous value (if any)
  7. Allow quoted data?Whether the CSV file allows values to be quoted? If this option is enabled (True), then the values can be enclosed in “” (double quote) allowing values to contain a delimiter.
  8. Recycle on EOFTo make the file re-read from the beginning on reaching the end of file (EOF). The default value is true. 
  9. Stop thread on EOF: This option will stop the thread if reaches to end of the file (EOF). The default value is false.
    Note: If “Recycle on EOF” is false and “Stop thread on EOF” is false, then on reaching the end of the file, all the variables are set to last line values. If “Recycle on EOF” is false and “Stop thread on EOF” is true, then on reaching the end of file thread will stop.
  10. Sharing Mode: There are 4 sharing mode options.
    1. All Threads: The file will be shared between all the threads. This is a default value.
    2. Current Thread Group: Each file is opened once for each thread group in which the element appears
    3. Current thread – Each file is opened separately for each thread
    4. Edit: all threads sharing the same identifier share the same file. So for example, if you have 4 thread groups, you could use a common id for two or more of the groups to share the file between them. Or you could use the thread number to share the file between the same thread numbers in different thread groups.
      To get in-depth knowledge on the CSV Data Set Config, read the article: Understand Sharing Mode of CSV Data Set Config

Parameterization Example:

Let’s say you have four variables UserID, password, productID, orderID in paramFile.csv. Now refer to the below GIF:

Apache Jmeter - CSV Data Set Config

Additional Points:

Generally, the CSV Data Set Config element is added under the Test Plan to use the parameter value globally. In case you have more than one Thread Group with different CSV files, then you need to either add CSV Data Set Config element under the respective Thread Group or create a set of files, one for each thread. 

By default, the file is only opened once, and each thread will use a different line from the file (when Sharing Mode has All threads value). However, the order in which lines are passed to threads depends on the order in which they execute, which may vary between iterations. Lines are read at the start of each test iteration. The file name and mode are resolved in the first iteration.

In JMeter, you can also set up following parameterization settings:

2 thoughts on “JMeter – Parameterization (CSV Data Set Config)”

  1. Hi,

    If i have 50 user credential, i.e username/password rows in my CSV, then in my thread count , will write 50. And if i just write 5 Thread(users), then will JMeter read only the first 5 users from the CSV?

    Please answer. Thanks!


Leave a Comment