eBook > The JMeter Playbook: Build, Scale, and Optimize Performance Tests

CSV Data Set Config

CSV Data Set Config is the most commonly used configuration element for parameterization. It works simply: each virtual user reads the next line from the CSV file on each iteration and stores the value(s) into variable(s).

We chose the Samsung galaxy s6 product in the previous chapter. Now, let’s parameterize it so each user would add different product.

Back to top

Creating a CSV File

Create a file called products.csv in the same directory as your .jmx file:

product
Samsung galaxy s6
Nokia lumia 1520
Nexus 6
Samsung galaxy s7

Tip: Use a header row. JMeter can read the column names from the first line and you won’t have to specify additional variable names in the CSV Data Set Config.

Back to top

Adding the Config Element

Right-click Thread Group → Add → Config Element → CSV Data Set Config.

JMeter Screenshot: CSV Data Set Config configuration panel.

📸 Screenshot: CSV Data Set Config configuration panel.

Settings Explained

SettingDescriptionRecommended Value
FilenamePath to the CSV file (absolute, or relative to the .jmx location)products.csv
File encodingCharacter set. May be necessary for some national characters. UTF-8 (Unicode) is always a good choiceUTF-8
Variable NamesComma-separated names for variables which will be created by the element. If blank, JMeter reads the header row(leave empty if the file has a header)
Ignore first lineSkip the headerTrue (if using header for column names, set to False and leave Variable Names empty)
DelimiterColumn separator,
Allow quoted dataSupport fields like "Smith, Jr."False
Recycle on EOFStart from the beginning when last line of CSV file is reachedTrue
Stop thread on EOFStop the thread when no more lines left in the CSV fileFalse
Sharing modeHow this file is accessed by virtual usersSee below

Sharing Mode

ModeBehaviour
All threadsAll threads in all thread groups share a single file pointer - each thread gets a unique row
Current thread groupSharing is limited to threads within this thread group
Current threadEach thread reads the file independently from the start

For most login scenarios, it makes sense to use All threads so every virtual user reads a new line on each iteration.

Back to top

Using CSV Variables in Requests

Once the CSV Data Set Config is in place, use ${product} anywhere in your samplers:

HTTP Request - POST /login

Method : POST
Path   : /api/login
Body Data:
{
  "product": "${product}",
}

Each thread (virtual user) will pick the next row from the CSV file on every iteration.

Back to top

Multiple CSV Files

You can add multiple CSV Data Set Config elements. For example:

  • users.csv → ${username}, ${password}
  • products.csv → ${productId}, ${productName}

Each file is read independently.

Back to top

Best Practices

  1. Make sure to have enough test data. If you have 100 threads and the file only has 10 rows, the same data will be used by multiple threads. Or the test will end prematurely.
  2. Use relative paths - Keep CSV files next to the .jmx so the test is portable and can be executed on other machines or in CI/CD.
  3. Commit CSV files to version control alongside your test plan.
  4. Use Sharing mode = All threads when each virtual user should have unique data.
Back to top

Summary

  • CSV Data Set Config reads a file line by line and maps columns to variables.
  • Use ${variableName} syntax to reference CSV columns in any sampler field.
  • Choose the right Sharing mode to control whether virtual users get unique or repeated data.

The next step would be learning how JMeter Functions and Variables can be used for tests parameterization.

Back to top