It is a JMeter element that reads lines from a text file and turns each piece of a line into a variable your test can use.

Starting with the basics

Apache JMeter is a free, open-source tool written in Java that measures how well a system behaves when many users use it at the same time. This is called load testing or performance testing. A JMeter test is arranged as a tree called a Test Plan, and the pieces inside the tree are called test elements. Each virtual user is a thread, a small worker that walks through the tree independently of the others.

A Sampler sends one request, such as an HTTP call, and records the answer. A Config Element supplies settings or data to the samplers around it. A variable is a named value that JMeter swaps into a field at run time. You write a variable by putting its name between a dollar sign and curly brackets. The CSV Data Set Config is a config element whose job is to fill variables with data from a file.

What it really does

You point the element at a text file. Each line of the file is one record, and the values on the line are separated by a chosen character, usually a comma. You give names to the columns. Then, whenever a virtual user starts a new pass, the element reads the next line and stores its values in variables for that user. Samplers can then write those variable names into their fields, and JMeter replaces them with the real values.

Why it matters so much

Almost no real application can be tested honestly with a single set of values. Logins must differ. Search words must vary. Orders need unique references. If the data is wrong, the test is measuring a fantasy: errors from duplicates, or unrealistic speed from caches. A test with careful data behaves like a crowd of different people. A test with careless data behaves like one person cloned a thousand times.

Before learning the element, it helps to see exactly what goes wrong when a test has no varied data.

Four things that go wrong

Why caches fool you

A cache is a fast memory where a system keeps answers it has already worked out, so it can reuse them. When a thousand users search for the same word, the system works the answer out once and then hands back copies. A real crowd searches for thousands of different words, and most of those answers must be worked out from scratch. A test that always asks the same question therefore measures the speed of the cache, not the speed of the system. The report looks wonderful and predicts nothing.

The value of realistic spread

Real data has natural spread. Some products are popular and many are rarely viewed. Some users have large carts and many have small ones. A good test file reflects that spread. It does not need to be perfect, but it should not be absurdly narrow either.

CSV is one of the simplest file formats there is, and a few small details decide whether JMeter reads it correctly.

What CSV means

CSV stands for Comma Separated Values. It is a plain text file where each line is one record and the values on that line are separated by commas. You can open it in any text editor or in a spreadsheet program. The first line often holds the names of the columns, and the lines after it hold the data.

The table above shows how a data file looks when viewed as a grid. In the actual file, each row is a line and the cells are separated by the delimiter. When JMeter reads it, the first row of data fills the variables named username, password, city and product_id for one user, the second row for another user, and so on.

Small details with big effects

The position of the CSV Data Set Config in the tree decides which users and which samplers can see its variables, and how often it reads a new line.

A typical tree

A test starts with the Test Plan and a Thread Group, which controls how many virtual users run and how many times each one repeats. Config elements such as the CSV Data Set Config are normally placed near the top of the Thread Group, so every sampler beneath them can use the variables.

flowchart TD
    A[Test Plan] --> B[Thread Group]
    B --> C[CSV Data Set Config users]
    B --> D[HTTP Request Defaults]
    B --> E[HTTP Cookie Manager]
    B --> F[HTTP Request Login]
    B --> G[HTTP Request Search]
    B --> H[Listener]

Scope in one idea

Scope means which samplers an element affects. An element affects its own level and everything beneath it, like a notice pinned on one floor of a building: everyone on that floor sees it. A CSV element placed under the Thread Group is visible to every sampler in the group. A CSV element placed under one controller is visible only to samplers in that controller.

The order JMeter runs things

For each sample, JMeter applies config elements first, then pre-processors, then timers, then the sampler runs. After the response, post-processors, assertions and listeners follow. The CSV element, as a config element, has its values ready before the sampler fills in its fields. This is why variables from the file can appear in the very first request of a pass.

The screen has a handful of fields. Each one answers a simple question about the file and about what to do with it.

The fields

How to read the Filename field

If the filename is just the name of a file, such as users.csv, JMeter looks for it next to the test plan. This is convenient, because you can keep the plan and its data together in one folder and move them as a pair. An absolute path, which starts from the root of a drive, works but ties the plan to one machine. The filename field also accepts a variable or a property, so the path can be chosen when the test is launched. This lets one plan use a small file for a quick check and a large file for the full run.

The element needs to know what to call each column. There are two ways to tell it, and each has its own rules.

Way one: type the names into the element

In the Variable Names field, you type the names of your columns in the same order they appear in the file, separated by commas. If your file has username, password and city, you type those three names. When you do this, the first line of the file is treated as data unless you also set the Ignore First Line option to true. If your file does have a header row and you forget the option, the header text is used as the first record, and your first virtual user logs in with the literal word “username”.

Way two: let the file’s first line supply the names

If you leave the Variable Names field empty, JMeter reads the first line of the file and uses it as the list of column names. This is neat, because the file describes itself, and you can add a column later without editing the plan. The first record of real data then starts from the second line.

Naming rules that save pain

Behind the scenes, the file is opened once and handed out one line at a time. Seeing the steps explains most surprises.

Step by step

sequenceDiagram
    participant T as Virtual User Thread
    participant C as CSV Data Set Config
    participant F as Data File
    participant S as Sampler
    T->>C: A new pass is starting
    C->>F: Ask for the next line
    F-->>C: One line of text
    C->>C: Split the line into values
    C-->>T: Store values in this user's variables
    T->>S: Run the sampler
    S->>S: Replace variable names with the values

Variables belong to each user

The values are stored in the variable space of the thread that asked. Each virtual user therefore has its own copy of username, password and the rest. User one’s login cannot be changed by user two reading a new line. This is why a hundred threads can each hold a different name at the same instant.

Order is not guaranteed

Threads ask for lines in whatever order they happen to reach the element. Thread seven may arrive before thread three. If you need a particular user to always get a particular line, the plain shared mode does not promise that. Later chapters show how to arrange that when it matters.

The sharing mode decides whether users take lines from one shared pile, from separate piles, or from each other’s piles.

The four choices

flowchart TD
    A[Need data for each user] --> B{Must each user get a different row}
    B -->|Yes| C[All threads]
    B -->|No| D{Should each user walk the whole file}
    D -->|Yes| E[Current thread]
    D -->|No| F{Separate pools per user type}
    F -->|Yes| G[Current thread group or Identifier]
    F -->|No| C

Seeing the difference

Suppose a file has five lines and three users each read two lines. With All threads, the six reads draw lines one to five and then the sixth read needs a recycled first line. Every user gets a different line until the file wraps. With Current thread, every user reads lines one and two, so all three users see exactly the same data. The same file, with the same plan, behaves very differently depending on this single setting.

Two elements, one file

When two CSV elements point to the same file with the same sharing setting, they may end up drawing from a shared position. If they have different variable names, each one then consumes lines that the other would have used, and neither user sees the full set. If you need the same file read twice for two different purposes, use different sharing identifiers, or make a second copy of the file.

Every file ends. What JMeter does at that moment is under your control, and the wrong choice causes some of the most confusing test failures.

The two settings that decide

Two options work together. Recycle on EOF answers the question “when the file ends, should I go back to the first line?” EOF stands for end of file. Stop thread on EOF answers “if I am not recycling, should the user stop?” Stop only has an effect when recycling is off.

flowchart TD
    A[Reached end of file] --> B{Recycle on EOF}
    B -->|True| C[Go back to the first line]
    B -->|False| D{Stop thread on EOF}
    D -->|True| E[This user stops]
    D -->|False| F[Variables get the text EOF marker]

The three outcomes

Choosing on purpose

Reading data is only half the job. The values must land in the right fields of the right requests.

Where variables can go

You can use a variable almost anywhere you can type text in a sampler. Write the variable’s name between a dollar sign and curly brackets, and JMeter replaces it with the value at run time. Common places include the path of an HTTP request, the Parameters table, the Body Data for a JSON or XML request, header values, and assertions that check for expected text.

Combining file data with captured values

Many flows mix two sources of data. The file gives the starting values, such as the username and password. The server then returns changing values, such as a session token, and an extractor, a post-processor that reads a value out of a response, stores them in another variable. The next request uses both: the name from the file and the token from the extractor. Keep the two sets of variable names different so neither overwrites the other.

flowchart LR
    A[CSV file row] --> B[Username and password variables]
    B --> C[Login request]
    C --> D[Server returns token]
    D --> E[Extractor stores token variable]
    E --> F[Next request uses token and city]
    A --> F

When a variable is not found

If you misspell a variable name in a sampler, JMeter does not stop. It leaves the text of the variable reference in place, so the server receives something like a dollar sign and the literal name. The request then fails in a confusing way. If requests seem to contain strange text that looks like a variable, compare the spelling in the sampler with the name in the element, including upper and lower case.

The element reads a new line each time the part of the tree that holds it begins a new pass. So where you place it decides how often the data changes.

Thread Group level

If the element sits directly under the Thread Group, a new line is read at the start of each pass of the whole scenario. Every sampler in that pass sees the same row. This is the right choice when one pass represents one user doing one complete journey, such as logging in, searching and checking out with one set of details.

Inside a Loop Controller

A Loop Controller repeats the elements beneath it a set number of times. If the CSV element sits inside it, a new line is read on every pass of that inner loop. This is right when each repetition should use fresh data, such as adding ten different products to a cart, one per pass.

flowchart TD
    A[Thread Group] --> B[Login request]
    A --> C[Loop Controller 5 passes]
    C --> D[CSV Data Set Config products]
    C --> E[Add To Cart request]
    A --> F[Checkout request]

Comparing the placements

Two files, two jobs

A common design uses two CSV elements. One, at the top of the Thread Group, holds the credentials, one row per user. Another, inside the loop, holds the products, one row per repetition. They have different variable names and different files, so they never collide.

A data file that is too small is one of the most common causes of unreliable tests. A little arithmetic, done early, prevents it.

How many rows do you need?

The number of rows needed depends on how many reads the test will perform. Each read happens once per pass, per user, at the placement of the element. So the formula is the number of users, times the number of passes at that level, times the loop count if the element is inside a loop.

For tests that run for a set time rather than a set count, estimate from the request rate and the duration. If you expect fifty logins per minute for sixty minutes, you need three thousand unique accounts, and more if you want a safety margin.

Creating the data

flowchart LR
    A[Work out rows needed] --> B[Generate or export the data]
    B --> C[Create the accounts in the test system]
    C --> D[Verify a sample by hand]
    D --> E[Save as plain UTF-8 CSV]
    E --> F[Place the file next to the plan]

The data must exist in the system

A file full of usernames is useless if those users do not exist in the system under test. Test accounts must be created ahead of time, with the same passwords as the file, and product ids must refer to products that really exist. A frequent beginner failure is a perfect plan sending a thousand logins to accounts that were never created, producing a thousand errors that look like a broken system.

When one machine cannot generate enough load, JMeter spreads the plan over several machines. This changes how data files behave.

What distributed testing is

In distributed testing, one controller machine commands several load generator machines. Each generator runs a full copy of the plan with its own set of virtual users. The generators then send traffic to the system under test, and send their results back to the controller.

flowchart TD
    C[Controller] --> G1[Load Generator 1 with users part 1]
    C --> G2[Load Generator 2 with users part 2]
    C --> G3[Load Generator 3 with users part 3]
    G1 --> T[System Under Test]
    G2 --> T
    G3 --> T

The file is read on each generator

Each load generator reads the file from its own disk. JMeter does not send the controller’s file to them. If the file is missing on a generator, the test fails there. Relative paths are resolved on each generator, so the file must sit in the same relative place. Absolute paths from your own computer will rarely exist on the generators.

The duplicate trap

If every generator has a copy of the same complete file, every generator starts at line one, and the same line is used by one user on each machine at the same time. With five generators, five users may log in with the same account together. The fix is to split the data: give each generator its own slice of rows, with no overlap, or use a pattern in the data that includes the generator’s identity.

The element itself is light. The trouble comes from the size of the data and from how the file is used.

Cheap to read

JMeter reads the file line by line as needed and does not hold it all in memory. A file with a few lines and a file with a few million lines behave almost identically while the test runs. The cost of reading a line is tiny compared with the cost of sending a request over a network.

Where the cost does appear

Keeping the file local

A data file placed on a slow shared network drive makes every read depend on that drive. Copy the file to the load generator’s own disk before the run. It removes a source of random delays that would otherwise show up as odd pauses in the test.

Think time still matters

Varied data does not replace realistic pacing. A loop that reads a new line and fires a request with no pause still floods the server. Use timers to keep each user’s pace human, so that the load the test creates matches the load you want to study.

A data file often holds usernames and passwords. It deserves the same care as any other sensitive document.

Never use real people’s data

Do not fill test files with real customers’ names, emails, phone numbers or card details. Data protection laws in many countries, including India, the European Union and others, place strict duties on how personal data is stored and used, and a load test file copied onto laptops and shared drives can easily break them. Use made-up people, made-up numbers and test accounts created just for this purpose. Where a test needs data shaped like real data, produce an anonymised version in which every identifying detail has been replaced.

Passwords in plain text

A CSV file stores passwords as plain text. That is acceptable only for throwaway test accounts in a test environment. Never place a real production password in such a file. If the system supports test tokens that expire quickly, prefer them, and generate them just before the run.

Test only what you are allowed to test

Loading a system with thousands of logins from varied accounts can look exactly like a credential-stuffing attack, where criminals try many stolen passwords. Always have written permission, test in an environment you own or have been given, and warn the operators of the system before a run so that security tools and staff do not react as though it were a real attack.

Data problems are quiet. The test runs, the numbers appear, and only careful looking shows that the wrong values were sent.

The debugging toolkit

Common symptoms and their usual causes

A reliable routine

Experienced engineers use a few reliable data designs and avoid a handful of tempting shortcuts.

Patterns that work

Anti-patterns to avoid

These are the habits that experienced performance engineers repeat on every project, and the slips that beginners make again and again.

Best practices checklist

Common mistakes

• Forgetting to set Ignore First Line when a header row is present and names are typed into the element.
• Leaving a blank line at the end of the file, which becomes a record of empty values.
• Assuming that threads receive rows in a fixed order, when the order depends on who arrives first.
• Placing the element below the sampler that needs its variables.
• Running two Thread Groups on the default sharing mode and finding that they steal rows from each other.
• Using the same variable name in the CSV element and in an extractor, so they overwrite each other.
• Saving the data file from a spreadsheet and losing leading zeros or turning long numbers into scientific notation.
• Copying the same complete file to every load generator.

Here is how teams use the CSV Data Set Config in different kinds of systems. These are illustrative patterns that show the kind of scale and care involved, not descriptions of any company’s private tooling.

What these examples share

In every case, the data file is designed with the same care as the plan. The size is calculated, the spread resembles reality, the accounts exist, the privacy rules are respected, and the end-of-file behaviour is chosen on purpose.

The CSV Data Set Config is the everyday workhorse for test data. It has clear edges, and other tools fill the gaps.

Alternatives and complements

Order and randomness

Because the element reads in order, a file sorted by popularity or by name gives a predictable and possibly biased sequence. If the order must not influence the test, shuffle the file before the run. Shuffling a file in advance is simple and removes any hidden pattern, such as all the users from one city coming first.

Static data versus live data

A file is a snapshot. If the system’s real data changes between the day the file was made and the day of the test, rows may become invalid: products withdrawn, accounts locked, prices changed. For long-lived test suites, regenerate the file regularly or pull data from the system itself at the start of the run.

Short, direct answers to the questions people ask most often about the CSV Data Set Config.

The CSV Data Set Config turns a crowd of clones into a crowd of different people. Careful use of it separates believable tests from fantasies.