CSV Data Set Config

CSV Data Set Config is used to read lines from a file, and split them into variables. It is easier to use than the __CSVRead() and _StringFromFile() functions. It is well suited to handling large numbers of variables, and is also useful for testing with “random” and unique values.

Generating unique random values at run-time is expensive in terms of CPU and memory, so just create the data in advance of the test. If necessary, the “random” data from the file can be used in conjunction with a run-time parameter to create different sets of values from each run – e.g. using concatenation – which is much cheaper than generating everything at run-time.

In this post, I will guide you how to read data from CSV using CSV Data Set Config, and show you all feature which this element provides.

1. Using CSV Data Set Config:

I’ll use a basic web test plan for Login as below:

The test plan above is referred from JMeter Cookbook of author Bayo Erinle. And hope that it will not cause any copyright violation 🙂 .

You can download this example here. We need to run this test with the data (username, password) is pre-defined in csv, then read it while running.

Step 1: I will prepare some username and password in the csv file like below:

joel,secr3t
jim,grooVy
sam,sCala
tom,pa$$
patrick,allgood!
hari,c0mmons
acton,letmeein
bayo,express

Where joel, jim, sam, tom, etc. are the username. And secr3t, grooVy, sCala, pa$$, etc. are the password. The sign comma “,” between the values called delimiter. Normally in CSV file we use the comma to separate the values.

Then save the CSV file in the same location with the test plan, and named it users.csv

Step 2: In the test plan, I’ll create a CSV Data Set Config (Test Plan > Add > Config Element > CSV Data Set Config)

Input the name of CSV into Filename: users.csv

Input Variable Names into Variable Names field, each variable is equal to the column in the CSV. For example in my CSV, the first column is used for username, and second is used for the password, so I’ll be named it corresponding: USERNAME,PASSWORD. These variables are also used for referring later.

Please remember that the variables must be separated by a comma (,).

Step 3: Replace the fixed data in Login request by calling the variables reading from CSV file.

In this example, I will:
– replace joel by ${USERNAME}
– replace secr3t by ${PASSWORD}

And don’t forget to change the first Response Assertion from fixed data to the variable ${USERNAME} also. This is just to make sure it can log in successfully.

Step 4: In Thread Group, set Number of Threads to 8 (equals to the number of users in CSV file) then run the test, and look how it work.

You can see, in each request, it uses the different data (USERNAME and PASSWORD) from CSV file to login.

You can run it by yourself with the Test Plan here, and the CSV file here.

2. Configuration in CSV Data Set Config

2.1 Filename: It’s the name of the file to be read.

• If the CSV file is the same location with Test Plan (.jmx) file, then you just input the name of CSV file only. Ex: “users.csv” as above.
• If the CSV file is difference location with test plan file, then you must input absolute path of the file.
  • In Window, it looks like: C:\Desktop\JMeter\users.csv
  • In Mac, Linux, it looks like: /Users/user/Desktop/users.csv
• We also can use the dot “.” to represent the current folder of test plan file.
  For example: We have data folder is the same location of Test Plan file, and under the data folder, we have CSV file “users.csv”, then we can input into the CSV Data Set Config like that: ./data/users.csv
  
  NOTE: The sign “/” can use for both Linux, Mac, and Window
• Actually, the CSV file is also a plain text file, so we can use the extension .txt instead of .csv, it still works well. Just make sure the format inside is the same, don’t change it.

2.2 File encoding: The encoding to be used to read the file, if not the platform default.

So by default, it will use the default encoding of the OS to read the file. Usually, we don’t touch this option. But it will help you in case your data file contains double-bytes characters, for example Vietnamese, Japanese or Chinese, etc. In Window, you must save the file with encoding is UTF-8 or Unicode, to make sure all your data is not broken. But in Window, the default encoding is ANSI, then JMeter uses this encoding to read the file, and it will cause the problem, broken data. Very easy, just input the same encoding of the file into File encoding field in Data Set Config. Refer image below:

2.3 Variable Names: List of variable names (comma-delimited).

Let go back the sample in section 1. Each column in the csv file, we must have a corresponding variable name in CSV Data Set Config

We have 2 columns in users.csv, the first column stores data of Username, and the second data stores data of Password. Then I named the variables in CSV Data Set Config corresponding: USERNAME,PASSWORD.

And these variables will be referred later as ${USERNAME}, ${PASSWORD}.

NOTE: each variable must be separated by a comma “,”. And if there is a redundant column which is not used, but it appears on csv file, then we must create a blank variable for it.

Example: We have csv data with 4 columns Username, Password, Phone, and Gender. But we don’t need to use the data of Phone, so we should input variables like below:

Just leave blank the variable of Phone. If you input:USERNAME,PASSWORD,GENDER so the GENDER will be treated as Phone.

JMeter supports CSV header lines: if the variable name field 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.

At that time, your CSV file looks like:

USERNAME,PASSWORD
joel,secr3t
jim,grooVy
sam,sCala
tom,pa$$
patrick,allgood!
hari,c0mmons
acton,letmeein
bayo,express

JMeter will read the data from the second line, and treat the first line as Variables Name

In the gif above, I just run only 1 user, to prove that the JMeter read data from the second line.

2.4 Delimiter: Delimiter to be used to split the records in the file. Default is comma “,”

In my sample, the delimiter is the comma “,”. In some case, we need to change the delimiter to another sign, such as semicolon “;” or a tab.

For example: You need to include the price in your csv data file. Then you should change the delimiter to another, and set the same delimiter in your file into Delimiter field in JMeter.

Ex 1: Using semicolon “;”

ITEMS;PRICE
laptop;2,345
monitor;1,234
macbook;3,456

Ex 2: Or using tab (\t) (it’s the tab key on the keyboard)

ITEMS    PRICE
laptop   2,345
monitor  1,234
macbook  3,456

2.5 Allow quoted data?: Should the CSV file allow values to be quoted? If enabled, then values can be enclosed in “ – double-quote – allowing values to contain a delimiter. Default is false

Sometimes, the data have space, or it contains your delimiter but you don’t want to change the delimiter, or the value need to break downline. The double-quote data will help you to solve them all. Very easy, just put them into the double-quote. And please note, each of the embedded double-quote characters must be represented by a pair of double-quote characters.

And don’t forget to change this value to true to apply the double quote.

Please see the following data:

I will store them into the csv like this:

1997,Ford,E350,"ac, abs, moon",3000.00
1999,Chevy,"Venture ""Extended Edition""","",4900.00
1999,Chevy,"Venture ""Extended Edition, Very Large""",,5000.00
1996,Jeep,Grand Cherokee,"MUST SELL!
air, moon roof, loaded",4799.00

Set-up in CSV Data Set Config:

And see how it works:

Please refer this sample here, and the csv here. This sample I used the plugins Dummy Sample. If you can not open the test plan file, please install this plugin first: https://jmeter-plugins.org/wiki/DummySampler/

2.6 – 2.7 Recycle on EOF? and Stop thread on EOF?:

EOF = End of File

• Recycle on EOF? Should the file be re-read from the beginning on reaching EOF? (default is true)
• Stop thread on EOF? Should the thread be stopped on EOF, if Recycle is false? (default is false)

2.8 Sharing mode:

• All threads – (the default) the file is shared between all the threads.
  It means it don’t care the requests come from what thread groups, no matter they come from what threads or even come from which loops. Every single request will read ONE line in CSV file. Assume CSV Data Set Config is the same level with all Thread Group.
  
• Current thread group – each file is opened once for each thread group in which the element appears. Mean when new Thread Group is started, it will read the file from the beginning – the first line. Assume CSV Data Set Config is the same level with all Thread Group.
  
• Current thread – each file is opened separately for each thread (users). It means each user start will read the file from the beginning again. Only the loop inside each thread (user) will read the next line.
  
• Edit – It’s the same “All Threads” mode, but this one will share for only the Thread Group with has the same identifier. In the sample below, the Thread Group A and Thread Group B will share the file each other as “All Threads” mode.
  
  Click here for original image.

Referal:
[1] JMeter Cookbook – Bayo Erinle
[2] Apache JMeter – Component Reference