Skip to content
Tutorials Center
My learning

Topics

Lesson 20 of 37 ยท Parameterization and Correlation

CSV Data Set Config: Feeding Test Data to Threads

Use the CSV Data Set Config element to give every virtual user its own data: file paths, variable names, delimiters, sharing modes, recycle and stop on EOF.

A load test where every virtual user logs in as the same account, searches for the same product and orders the same item is not a realistic test. Caches answer every request, the database sees one row, and locks never collide. To make traffic look like real people you need parameterization: replacing fixed values with data that changes per thread and per iteration.

The most common JMeter tool for this is the CSV Data Set Config element. It reads a text file one line at a time and puts the fields of that line into variables. Note that this track describes JMeter's menus and files exactly, but JMeter itself cannot run on this site. The runnable examples are small Python stand-ins that behave like the element, so you can see the logic.

Adding the element

Right-click the Thread Group (or the Test Plan) and choose Add > Config Element > CSV Data Set Config. Its main fields are:

Field Meaning
Filename Path to the file. Prefer a path relative to the .jmx file, such as data/users.csv, so the test works on other machines.
File encoding Leave empty for the platform default, or enter UTF-8 explicitly.
Variable Names Comma-separated names, one per column, for example username,password.
Ignore first line Tick it if the file has a header row.
Delimiter , by default. Use \t for tab-separated files.
Allow quoted data? Allows fields such as "Smith, Ann" that contain the delimiter.
Recycle on EOF? When the file ends, start again from the first line (default True).
Stop thread on EOF? When the file ends and recycling is off, stop the thread.
Sharing mode Who shares the file pointer: all threads, current thread group, current thread, or an identifier.

A file named data/users.csv:

TEXT
username,password
ann,s3cret1
bo,s3cret2
cy,s3cret3

With Variable Names set to username,password and Ignore first line ticked, you refer to the values as ${username} and ${password} in any sampler, for example in the body of a login request.

How lines are handed out

Each time a thread starts an iteration, the element gives that thread the next line. With the default All threads sharing mode, the file pointer is shared by the whole test: thread 1 gets line 1, thread 2 gets line 2, and so on. When a thread comes back for its second iteration it takes whichever line is next, not "its" line.

Python Stand-in: how threads consume CSV lines

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

With recycling on, the third user is followed by the first again. With recycling off and Stop thread on EOF on, threads quietly stop once the data is used up. That is exactly what you want when each account may be used only once, for example "register 10,000 new customers".

Sharing modes

  • All threads: one pointer for the entire test. Every row is used once before any repeats. This is the right default for unique logins.
  • Current thread group: each thread group has its own pointer, so two groups can both read the file from the top.
  • Current thread: every thread reads the file from the start independently. Use it when each user must walk through the same sequence of values.
  • Identifier: elements with the same name share a pointer, which lets you share across thread groups selectively.

Do not open a CSV file with a different tool while a test is running, and do not give two elements with different Variable Names the same file in "All threads" mode and expect lines to stay paired. Each element advances the pointer independently.

Random and weighted data

CSV Data Set Config reads sequentially. If you need random picks, use one of these approaches:

  1. Shuffle the file before the test (a one-line script).
  2. Use the __CSVRead or __RandomFromMultipleVars functions (see variables and functions).
  3. Repeat popular rows in the file. If 70 percent of searches are for "laptop", put it on 70 of 100 lines.
Python Stand-in: weighted rows by repetition

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Practical tips

  • Create files with enough rows: at least as many as the number of threads times iterations if every row must be unique.
  • Keep test data in the same repository as the .jmx, and keep real production credentials out of it.
  • On distributed tests, the file must exist on every agent, and each agent reads its own copy. Split the data so agents do not reuse the same accounts (see distributed architecture).
  • If a value looks like ${username} in the request, the variable did not load. Check the path, the header setting and the variable names.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which setting makes JMeter skip a header row such as username,password?

    Ignore first line skips the first row, so the header text is not used as data.
  2. 2. With sharing mode All threads, what happens when thread 2 asks for a row after thread 1 took the first one?

    All threads share one file pointer, so each request for a row advances it.
  3. 3. Each account may be used only once. Which combination fits?

    Without recycling, threads stop when the data is exhausted instead of reusing accounts.
  4. 4. How do you refer to the value in the column named username?

    JMeter variables use the ${name} syntax in samplers, headers and assertions.

Summary

  • CSV Data Set Config reads a file line by line into variables used as ${name}.
  • Prefer relative file paths and a header row with Ignore first line.
  • Recycle on EOF and Stop thread on EOF decide what happens when data runs out.
  • The sharing mode decides whether threads share one pointer or each have their own.
  • For random or weighted data, shuffle the file or repeat rows.

Next: Variables and Functions