It means feeding your test with real-looking, varied data that is stored in a simple file instead of being typed into each request.

Two Words Explained

A parameter is a value that can change, such as a user name, a search word, or a product number. To parameterize a test is to replace a fixed value with a named placeholder, so the real value is filled in when the request is sent. A CSV file is a plain text file in which each line is one record and the pieces of each record are separated by a comma. CSV stands for comma-separated values. Spreadsheet programs can open and save such files, which makes them easy to prepare.

How It Looks in Practice

Suppose your file has three columns and four rows:

The first virtual user takes the first row, the second takes the second row, and so on. Each user logs in with their own name and searches for their own word. The login request does not contain a fixed name any more. It contains a placeholder that JMeter replaces with the value from the user’s row.

Identical data does not merely look unrealistic. It actively spoils your measurements.

The Problems of One Identity

• Caching makes the system look faster than it is. When the same search is repeated, the server may keep the answer in fast memory. Your test measures that cheap memory lookup instead of the real work.
• Sessions clash. Many applications refuse or interfere with multiple simultaneous logins of the same account, or silently log the first one out.
• Locks and conflicts. If a hundred users update the same record at once, the database makes them queue up. That queue is not what real traffic looks like.
• Duplicate rejections. A shop may refuse to create the same order twice, or a sign-up form may refuse a repeated email address.
• Hot spots. One account or one item receives all the traffic, so you test one corner of the system and ignore the rest.

What Varied Data Gives You

Eight small ideas explain nearly everything about the CSV Data Set Config.

The Rule of One Row per Iteration

Remember this sentence: each virtual user takes one new row every time it begins a new iteration. All requests inside the same iteration see the same row. That is why a login and the search that follows can use the same user’s name and word. On the next iteration, the user receives the next unused row.

The element is easy to configure. The quality of your file decides whether the test is meaningful.

Format Rules

• One record per line. Each line is one set of values for one iteration.
• The same number of columns on every line. A short line leaves variables with stale or empty values.
• A consistent delimiter. Use the same separator everywhere, and make sure the values themselves do not contain that character, unless they are wrapped in quotation marks and quoted data is allowed.
• Plain text only. Save as CSV text, not as a spreadsheet document.
• No stray blank lines. Empty lines, especially at the end, can cause confusing behaviour.
• A known encoding. Save as UTF-8 when the data contains accented letters or other non-English characters.
• Optional header line. The first line may hold the column names, which you can use as variable names.

Choosing the Content

Think about which values change between real visitors and which of them matter for the behaviour of the system. Typical columns are credentials, search words, product or category identifiers, customer numbers, addresses, quantities, and coupon codes. Do not parameterize things that never change, such as the name of the website, because that only adds clutter.

How Many Rows

Count carefully. A test that never repeats a row needs at least as many rows as the number of users multiplied by the number of iterations each will run. A test that is allowed to reuse rows needs fewer, but you must make sure reuse does not cause trouble such as one account logged in twice at once. A later chapter shows the arithmetic.

Adding the element takes a few clicks. Choosing its settings takes thought, and the next chapters explain each one.

The file sits outside JMeter. The config element reads it, and the virtual users draw rows from it.

flowchart TD
    F["CSV file on disk: one record per line"] --> C["CSV Data Set Config: reads lines and hands them out"]
    C --> T1["Virtual User 1: gets row 1"]
    C --> T2["Virtual User 2: gets row 2"]
    C --> T3["Virtual User 3: gets row 3"]
    T1 --> V1["Variables: username, password, searchWord"]
    T2 --> V2["Variables: username, password, searchWord"]
    T3 --> V3["Variables: username, password, searchWord"]
    V1 --> S["Samplers: Login, Search, Add to basket"]
    V2 --> S
    V3 --> S
    S --> SYS["System under test"]
    

Reading the Diagram

The file holds the records. The CSV Data Set Config reads lines from it and hands one to each virtual user as that user begins an iteration. Each user stores the values in their own variables. The samplers then send requests with those values filled in, so the system under test sees three different people.

The Main Components

• The file. A passive store of records.
• The config element. The one that opens the file, tracks the position, and hands out rows.
• The virtual users. The ones that ask for rows and keep their own copy as variables.
• The samplers. The elements that read the variables and put the values into requests.

Behind the scenes, there is a single marker moving down the file, and users take turns using it.

sequenceDiagram
    participant U1 as Virtual User 1
    participant U2 as Virtual User 2
    participant C as CSV Data Set Config
    participant F as CSV File
    U1->>C: Start iteration, ask for next row
    C->>F: Read line at pointer position
    F-->>C: Line 1
    C-->>U1: Values of line 1 become variables
    C->>C: Move pointer to line 2
    U2->>C: Start iteration, ask for next row
    C->>F: Read line at pointer position
    F-->>C: Line 2
    C-->>U2: Values of line 2 become variables
    C->>C: Move pointer to line 3
    

What the Diagram Shows

When the first user begins an iteration, it asks the element for a row. The element reads the line at the pointer, gives the values to that user, and moves the pointer forward. When the second user asks, it receives the next line. No two users receive the same line, because the pointer moves with each request. The reading is done carefully, so that two users asking at the same instant still receive different lines.

When the Row Is Taken

A user takes a row at the start of each iteration, not at the moment a request uses the variable. So if a journey has ten requests, all ten use the same row. The next row is taken only when the user begins the next pass.

What Is Stored

The values are stored as variables belonging to that user. Another user cannot see them. This is the reason that two users can use the same variable name and still hold different values at the same moment.

The data is only useful once your requests actually refer to it.

Writing a Placeholder

To use a stored value, write the variable name inside a dollar sign and curly braces wherever a value is expected. JMeter replaces it with the user’s value just before the request is sent. This works in the path, parameters, headers, body, and most other fields. For example, a login request’s username field would hold the placeholder for the variable called username, instead of a fixed name.

Names Must Match Exactly

Variable names are case sensitive. A variable called searchWord is not the same as searchword. If the placeholder name differs even slightly from the name in the CSV Data Set Config, JMeter does not find a value. It sends the placeholder text itself, and the server rejects it.

Where the Placeholder Can Go

Before studying each setting in detail, look at the whole panel and learn its shape.

EOF is short for end of file. The next chapters explain each setting in turn, using small examples and real-life comparisons.

A test that works on your laptop but cannot find its data file on the load generator is a very common surprise.

Absolute and Relative Paths

An absolute path gives the full location of a file from the top of the disk, such as a drive letter and a chain of folders. It works only on a machine that has the same folders. A relative path gives the location starting from a known folder. In JMeter, a relative path is counted from the folder that holds the test plan file. If the data file sits beside the plan, the filename alone is enough.

Distributed Testing and Files

In a distributed test, JMeter does not copy your data file to the worker machines. The controller sends the plan, but each worker opens the data file itself. So the file must exist on every worker, at the path the plan names. If it is missing on one worker, the users on that worker fail to get any data.

A Good Habit

Keep the test plan and its data files together in one folder under version control, and use relative paths. Then anyone who fetches the folder gets everything needed to run the test.

The names you give the columns are the names you will use in every request.

Naming the Columns

In the variable names box, list the names in the same order as the columns, separated by commas. If the file has three columns for user name, password, and search word, you might name them username, password, and searchWord. The first value in each line goes into the first variable, the second into the second, and so on.

Using the File’s Own Header

If you leave the variable names box empty, JMeter treats the first line of the file as the list of names. This is convenient, because the names live together with the data. You do not then need to tick anything to skip that line; it is consumed as the header.

Typing Names and Skipping the Header

If the file has a header line but you also type the variable names in the box, the header would be read as a data row. To avoid this, turn on the option to ignore the first line. This option has an effect only when names are typed in.

Naming Habits

• Use letters, digits, and underscores, with no spaces.
• Choose names that describe the content, such as customerId rather than col2.
• Do not reuse a name already used by another element in the same plan, because one source may overwrite the other.
• Remember that names are case sensitive.

The separator decides where one value ends and the next begins. Get it wrong and the columns slide out of line.

The Delimiter

The default separator is a comma. You can choose another character, such as a semicolon, a vertical bar, or a tab. A tab is written in the box using a special marker for the tab character. Pick a character that never appears inside your values.

When Values Contain the Separator

Suppose a column holds addresses, and an address contains a comma, such as “12 Park Road, Springfield.” If the file uses commas as separators, that address looks like two values. The usual remedy is to wrap such a value in quotation marks. The setting Allow quoted data tells JMeter to treat text inside quotation marks as one value, even if it contains the separator.

Alternative: Choose a Different Separator

Another way to avoid the problem is to pick a separator that does not appear in your data, such as a vertical bar. Then no quotation marks are needed, and the file is simpler to read and to edit.

Some of the strangest data failures come from characters you cannot see.

What Encoding Means

Computers store text as numbers, and an encoding is the table that says which number stands for which character. If the file was saved with one encoding and read with another, letters such as accented vowels turn into strange symbols. The server then receives gibberish and may reject it or return different results.

What to Do

• Save data files as UTF-8, which handles almost every language.
• Set the file encoding box in the panel to match, when your data contains non-English characters.
• For plain English letters and digits, the default is usually fine.

Invisible Troublemakers

How to Find Them

Run one user and open the request in the results viewer. Compare what was sent with what you meant to send. If a value looks right to the eye but the server refuses it, suspect an invisible character, and recreate the file with a plain text editor.

Eventually, the pointer passes the last line. Two settings decide what happens next.

The Two Settings

• Recycle on EOF. When on, the pointer jumps back to the first data line and starts again. When off, the file is considered used up.
• Stop thread on EOF. When on, a user that asks for a row after the data is used up is ended. This setting matters only when recycling is off.

The Combinations

The Marker Value Trap

With recycling off and stopping off, the variables are filled with a special marker, and the user continues. Every request then carries that marker, and the server rejects it. The report shows a sudden wave of failures at the point where the data ran out. If you see requests containing the marker text, you have run out of rows.

The sharing mode decides whether users take turns on one pointer or each have their own.

The Choices

Choosing a Mode

• Unique data per user: use “All threads.”
• Two Thread Groups with their own data files: each file normally has its own config element, and “All threads” keeps each file’s pointer shared by all users of that file.
• Each user must replay the same list of items in order: use “Current thread.”
• Two elements that should step through the same file together: give them the same identifier.

Three questions decide almost every configuration.

flowchart TD
    Q["How should each row be used?"] --> A{"May a row be used more than once?"}
    A -->|"Yes, reuse is harmless"| R["Recycle on EOF: on"]
    A -->|"No, each row only once"| B{"What should a user do when rows run out?"}
    B -->|"End that user"| ST["Recycle off, Stop thread on EOF: on"]
    B -->|"Stop the whole test"| SZ["Recycle off, Stop thread on; size the file so it cannot run out unexpectedly"]
    R --> C{"Must different users get different rows?"}
    ST --> C
    C -->|"Yes"| AT["Sharing mode: All threads"]
    C -->|"No, each user replays the same list"| CT["Sharing mode: Current thread"]
    AT --> D{"Several groups with separate files?"}
    D -->|"Yes"| SEP["One config element per file"]
    D -->|"No"| OK["One config element is enough"]
    

Reading the Diagram

First decide whether a row may be used more than once. If it may, switch recycling on. If it must not, switch recycling off and decide what a user should do when no rows remain. Then decide whether different users must receive different rows. If yes, use the sharing mode for all threads. If every user should replay the same list in the same order, use the current thread mode. Finally, if different Thread Groups have different files, give each file its own config element.

Common Configurations

Where you put the element in the tree decides which samplers can see its variables.

The Scope Rule

A config element applies to samplers in its scope: the samplers beneath its parent. If you place it directly under a Thread Group, all samplers in that group can use its variables. If you place it under a single controller, only samplers inside that controller can. If you place it directly under the Test Plan, every Thread Group can use it.

Where to Put It

Placement and Row Advancement

The element advances the row at the start of each iteration of its parent. If it sits under the Thread Group, a new row is taken each time a user begins a Thread Group iteration. If it sits under a Loop Controller, a new row is taken for every pass of that inner loop. This lets you take a fresh row for each item in a shopping basket, while keeping one login row per user.

Real journeys need several kinds of data at once. Several config elements can work side by side.

Why Use Several Files

• Different lifetimes. Accounts may be used once per user, while search words may be reused freely.
• Different shapes. A file of accounts has two columns, and a file of products has five.
• Different owners. Another team may supply the product list while you maintain the account list.
• Easier maintenance. Replacing one list does not require touching the others.

Rules for Several Elements

• Give each element a clear name, such as “Accounts” and “Products.”
• Use different variable names in each element, so one does not overwrite the other.
• Choose the recycle and sharing settings per file, according to how its data may be used.
• Remember that each element advances its own pointer, independently of the others.

An Important Consequence

Because each pointer moves independently, rows from different files are not paired. User three may receive the third account and the seventh product. If you need a particular account to be linked with a particular product, put both in the same file, as columns of one row.

Simple arithmetic prevents the most embarrassing data failure of all: running out in the middle of the test.

The Basic Rule

When each row may be used only once, the number of rows needed is the number of rows consumed in total. Each virtual user consumes one row per iteration. So:

Rows needed = number of users × iterations per user.

If you have two hundred users and each runs five iterations, you need one thousand rows. If the test runs for a fixed time instead of a fixed number of iterations, estimate how many iterations each user can complete: the test duration divided by the time one iteration takes, including think time.

An Example

Why a Margin

If the system under test becomes faster than expected, users finish iterations sooner and consume more rows. If it is slower, they consume fewer. A margin protects against the first case. Real runs also often include extra rows consumed by warm-up runs and by rerun attempts.

When Reuse Is Fine

Data that is only read, such as search words, can be reused safely. A file of a few hundred varied words may serve a test of any length. But remember that very small lists cause repeated requests, which brings back the caching problem. Aim for enough variety that repeated requests are as rare as they would be in real life.

Credentials are the first thing most tests parameterize, and the one most likely to cause trouble.

Why Unique Accounts Matter

Many applications limit simultaneous sessions for one account, log earlier sessions out, or lock an account after repeated activity. If all users share one account, the test measures a very unusual situation. Using a separate account for each virtual user matches what happens in production, where many people are logged in at once, each with their own identity.

Preparing the Accounts

• Create them in advance. The accounts must exist in the test system before the test starts, with passwords that work.
• Create enough of them. Use the arithmetic from the previous chapter, with a margin.
• Give them realistic state. An account with no history behaves differently from an account with a year of orders. Where behaviour depends on history, prepare data to match.
• Use test-only accounts. Never use real customers’ accounts or passwords.
• Reset between runs. If a run changes an account, such as emptying its credit balance, restore it before the next run.

The Logout Question

If each virtual user logs in on every iteration and the application allows only one session per account, a user who loops must log out before the next iteration, or use a different account. Otherwise the second login may fail or kick out the first one. Decide whether your journey includes a logout step and whether recycling is safe for the accounts.

Choosing the values is as important as choosing the file format. The distribution of requests should resemble real traffic.

Real Traffic Is Uneven

In real life, a few items are very popular and most are rarely viewed. A news site has a handful of headline stories and thousands of old articles. A shop has bestsellers and slow movers. If your test picks every item with equal probability, it is more even than reality. If it always picks the same few, it is more skewed than reality.

Making the Mix Realistic

• Use real data patterns. If you have access to anonymised logs or analytics, build the list from them, so popular items appear more often.
• Repeat popular values. A simple way to weight a list is to include popular values several times in the file.
• Include rare values too. Slow-moving items test the less common paths, such as cache misses and cold database pages.
• Include failure cases deliberately. A few searches with no results, or a few mistyped words, are normal in real life.
• Keep the list long enough. A tiny list leads to repeated requests and unrealistic caching.

The Caching Effect

When a test creates data, the values you feed it often must be unique, valid, and well shaped.

Typical Cases

Uniqueness Across Runs

If the first run registers the user “newuser001,” the second run cannot register it again. You have two choices: clean the test system between runs, or generate fresh values each time. For fresh values, you can build the file with a number or date stamp inside each value, or use built-in functions that produce unique values at run time.

Validity

Data that the application rejects as invalid wastes the test, because the system spends its time producing error messages rather than doing normal work. Check the rules for each field, such as length, characters allowed, and ranges, and prepare the file to follow them. Include a small share of invalid data only if you want to test error handling on purpose.

Some data is consumed by use. A test that forgets this works once and fails on the second run.

Kinds of Data That Change

• One-time codes. Vouchers and invitation codes that work only once.
• Stock levels. Items that sell out, so later orders fail.
• Balances. Accounts that run out of credit.
• Records that move through stages. An order that was paid cannot be paid again.
• Unique fields. Names and emails that cannot be created twice.

Strategies

Record What You Used

Keep a copy of the exact data file used in each important run, stored with the results. When something looks odd later, you can see precisely which rows were used.

Real journeys mix two kinds of data: what you prepared, and what the server invents along the way.

Two Sources, One Request

A login request may need your prepared user name and password from the CSV file, and also a hidden security code that the server placed in the login page. The first comes from the CSV Data Set Config. The second must be caught from the earlier response by an extractor, which is a kind of Post-Processor. The final request uses both kinds of variables, written the same way inside a dollar sign and curly braces.

Name Clashes

Both tools write into the same pool of variables. If an extractor and a CSV column use the same name, the later writer replaces the earlier value. Use clearly different names, such as a prefix for CSV variables, so you always know where a value came from.

Using CSV Values in Checks

You can also use CSV variables inside assertions. For example, after login the page should greet the user by name, and the expected phrase can be built from the user name variable. Each user then checks for their own name, which proves that the right account was really logged in.

The CSV Data Set Config is the most common choice, but not the only one. Knowing the alternatives helps you pick wisely.

Choosing Between Them

• For prepared, valid records, use the CSV Data Set Config.
• For values that only need to be unique, use a counter or a function and avoid a file altogether.
• For random picking from a list, use a plugin that reads randomly, or shuffle the file once before the test.
• For data that already lives in a system you can query, consider exporting it to a file first. A file is simple, fast, and independent of other systems during the test.

For a few users, you can type the file by hand. For thousands, you need a method.

Ways to Build a File

• A spreadsheet program. Fill a column with a series, and combine columns with formulas. Save the result as plain CSV text.
• A small script. A short program written in any language can produce thousands of lines with patterned values such as numbered accounts.
• A database export. If the accounts or products already exist, export the needed columns directly.
• Test data tools. Some tools generate realistic fake names, addresses, and numbers.
• Production-like copies, anonymised. Data derived from real patterns, with personal details removed or changed.

Keeping Data and System in Step

A file of accounts is useful only if the system really has those accounts. The best method is to create the accounts and the file together from the same source, such as one script that registers the accounts in the test system and writes the matching file. Then the two cannot drift apart.

Checks Before Using a File

The element is efficient, but very large files and very busy tests deserve a little care.

Reading Cost

The element reads the file line by line, so even large files do not fill the machine’s memory. The cost per row is small. For most tests, the CSV Data Set Config is not a performance concern at all.

Where Care Is Needed

• Extremely large files. Files with millions of lines take disk space and time to move between machines. Split them if you can.
• Many elements. Dozens of elements, each reading separate files, add some overhead.
• Slow storage. A data file on a slow network drive can delay users. Keep files on the local disk of the load generator.
• Very wide rows. Rows with hundreds of columns create hundreds of variables for each user.
• Large values. Columns that hold big bodies of text enlarge the memory used by each user.

Practical Advice

A data file is part of your test. Treat it with the same care as the plan.

Versioning

Store the test plan and small data files together in version control, so changes are tracked and anyone can recover an earlier version. For very large files, store the script or recipe that creates them, and keep the generated file outside version control, with a clear note about how to rebuild it.

Naming and Documentation

• Give files descriptive names, such as accounts for the checkout test, not just data1.
• Add a short note beside each file: its purpose, its columns, how it was generated, and its limits, such as a count of rows.
• Record the date and the system version it was built for.

Staleness

Data goes stale. Accounts get deleted, products are withdrawn, and rules for valid values change. A file that worked last quarter may produce a wave of failures today. Check data files whenever the system changes, and run a one-user smoke test before every important run.

Ownership

Decide who owns each file. When nobody owns it, nobody updates it, and the test slowly rots. A named owner and a refresh schedule keep data healthy.

A short collection of everyday problems that waste hours.

The Spreadsheet Trap

Spreadsheet programs try to be helpful. They may remove leading zeros from numbers such as a postal code, turn a long account number into a number with an exponent, or change a date into another format. The text in the cell looks right on screen, but the saved file holds something different. Always check the saved file in a plain text editor.

Loops decide how often rows are taken. Understanding this prevents unexpected shortages and repeats.

Loops at the Thread Group

If a Thread Group has two hundred users and each runs five loops, the CSV element, placed under the group, hands out one row per loop, so a thousand rows are consumed. If the loop count is set to run forever, with the test stopped by a duration, the number of rows consumed depends on how fast the system answers, which is why you must estimate with care.

Loop Controllers Inside a Journey

A Loop Controller repeats a set of steps inside one iteration, for example adding five items to a basket. If the CSV element sits under the Thread Group, all five passes of the inner loop use the same row. If the element sits under the Loop Controller, each inner pass takes a fresh row, giving five different products.

Other Controllers

An If Controller that skips a part of the journey also skips any CSV element inside it, so no row is consumed for that pass. A Once Only Controller runs its contents just on the first iteration of each user, which suits a login that happens once. A Transaction Controller groups steps for measuring and does not change how rows advance.

The speed at which a test consumes data depends on how it is shaped in time.

Ramp-Up

Ramp-up is the period during which users are started gradually. During ramp-up, row consumption starts slowly and grows as more users join. Total rows consumed over the full test still follow the arithmetic of users and iterations, but a long ramp-up means early users run more iterations than late ones.

Fixed Duration Tests

When a test runs for a set time, users repeat their loops until the time is up. Faster responses mean more iterations, and more iterations mean more rows. A system that performs better than expected could therefore consume rows faster than planned and run the file dry. Keep a margin.

Think Time

Pauses between steps slow each user down and reduce row consumption. If you shorten pauses to push more load, remember that you also use data faster. Recalculate the rows needed after any change to pauses.

Effects on Throughput and Data

When several machines generate load, data needs special care. Each machine reads its own copy of the file.

The Core Problem

In a distributed test, every worker machine runs the plan with its own virtual users, and every worker has its own row pointer. If all workers read the same file from the top, then worker one’s first user and worker two’s first user both take row one. Two users share one account at the same time, which is just the clash you wanted to avoid.

The Solution: Split the Data

Other Points

• Users multiply. Fifty users in the plan on four workers means two hundred users, which need two hundred rows per iteration.
• The same plan, different data. The plan is identical, and only the data slices differ.
• The file must exist. A missing file on one worker leaves its users without data.
• Keep a map. Record which slice went to which worker, so you can trace a failure to the right row.

When one user fails and another succeeds, the first question is: which row did each one use?

Why Tracing Matters

Many failures depend on the data. An account with a wrong password, a product that is out of stock, a record in a strange state. If your results do not show which row a user used, you cannot connect a failure to its data, and you will spend hours guessing.

Ways to Trace

• Put an identifier in the request. Where the application allows it, include the user name or a row number in a harmless field, such as a custom header or a label.
• Include the key value in sample labels or messages. Failure messages that mention the account name make reports easier to read.
• Save request details for failures only. Configure result files to save the request data when a sample fails, so you can see which values were sent.
• Use the debugging listener on small runs. The View Results Tree shows each request, including the values used.
• Log row numbers sparingly. A small log line when something unusual happens is helpful. A line per request fills the disk.

Watching for Data Problems in Results

Data files often hold credentials and personal details. Handle them with care, even in a test environment.

What Can Go Wrong

• Real personal data in files. Copying production customer records into test files exposes people’s privacy and may break the law.
• Passwords stored in plain text. Data files are plain text and anyone with access can read every password.
• Files in shared repositories. A file committed to a shared repository may be copied or seen by many people.
• Result files that repeat the data. Saved request details copy usernames and passwords into result files and dashboards.
• Leftover files. Old data files forgotten on shared machines.

Good Habits

• Use synthetic test data. Invent names, addresses, and numbers.
• If production-like data is needed, anonymise it thoroughly before it reaches the test environment.
• Use test-only accounts with limited permissions and short-lived passwords.
• Keep data files in access-controlled storage, not in public or widely shared folders.
• Do not save passwords in result files. Review which fields are saved.
• Delete data files and results when the project no longer needs them.
• Use the payment provider’s published test card details, and never real cards.
• Test only systems you own or have written permission to test.

The CSV approach is simple and popular, and it has limits you should know.

Key Trade-Offs

A sensible middle path is to use a CSV file for records that must exist in the system, such as accounts, and functions for values that only need to be unique, such as time stamps.

Experienced testers keep returning to a handful of good habits and a handful of repeated mistakes.

Good Patterns

Anti-Patterns

A short list that separates calm, reliable data-driven tests from endless surprises.

Best Practices

• Plan your data first. Decide which values vary, how many rows you need, and how they will be created.
• Use unique accounts per user and keep a margin of spare accounts.
• Choose realistic variety, including popular and rare values.
• Check every file for column counts, blank lines, stray spaces, and encoding.
• Set end-of-file behaviour on purpose, not by default.
• Use relative paths and keep data beside the plan.
• Split data for distributed runs where uniqueness matters.
• Run a one-user smoke test before every important run.
• Keep data synthetic and files protected.
• Document each file and name an owner.

Common Mistakes

These are teaching illustrations of common situations. They are not descriptions of any particular company’s setup.

A repeatable recipe that works for almost any recorded journey.

Let us plan the data for a small shop test, using invented numbers to teach the method.

The Scenario

A shop wants to test its busiest hour. The plan has three hundred virtual users. Each user logs in, searches for a product, views it, and adds it to the basket. One iteration takes about sixty seconds including pauses. The test will run for forty minutes.

Step 1: Work Out Iterations and Rows

The second line shows a very different need. A test where each user logs in once and then loops through searches needs only a few hundred accounts. A test where every iteration is a fresh login by a new account needs fifteen thousand. The journey design decides the data need.

Step 2: Choose the Files and Settings

Step 3: Place the Elements

The accounts element goes under a Once Only Controller that holds the login, so each user takes one account row at the start. The search words element goes under the Thread Group, so each iteration takes a new search word. Login and search use different variable names, so they never overwrite each other.

Step 4: Check the Result

A smoke test with three users for three iterations shows three different accounts on login and a new search word on each iteration. The log shows no file errors. The team then runs the full test with a gradual ramp-up, confident that data will not run out.

When data does not behave, a fixed path of questions finds the cause fast.

flowchart TD
    S["A request carries a wrong or missing value"] --> A{"Does the request show the placeholder text itself?"}
    A -->|"Yes"| N["Check variable name spelling and case, the names list, and element scope"]
    A -->|"No"| B{"Does it show an end-of-file marker?"}
    B -->|"Yes"| E["Data ran out: add rows, turn on recycling, or stop users at the end"]
    B -->|"No"| C{"Is the value empty or shifted to the wrong column?"}
    C -->|"Yes"| D["Check delimiter, quoted data, blank lines, and column counts"]
    C -->|"No"| F{"Is the value the same for all users?"}
    F -->|"Yes"| G["Check sharing mode, element placement, and whether the variable is overwritten elsewhere"]
    F -->|"No"| H["Check the row itself: is it valid in the system, and is it duplicated?"]
    

Reading the Diagram

Start with what the failing request actually carried. If you see the placeholder text, the variable was not found. If you see the end-of-file marker, the rows ran out. If the value is empty or in the wrong column, the file’s structure is wrong. If every user has the same value, the sharing mode or the placement of the element is the problem. If everything looks fine but the system rejects the value, the row itself is invalid.

Common Symptoms and Causes

Several pairs of ideas look alike and behave differently. Knowing the difference saves hours.

This is a composed story built to teach. It is an illustration, not an account of a real team.

The Situation

A team tested a members’ website with five hundred virtual users and a file of five hundred accounts. In the first week, the test ran well. The team then lengthened the test from ten minutes to an hour, to look for slow leaks. Each user now logged in on every iteration, and users ran about forty iterations each.

The Surprise

Twelve minutes into the new test, the error rate shot up from nearly zero to more than ninety percent, and it stayed there. The server’s graphs looked healthy. The team feared a sudden failure in the application and stopped the test.

The Investigation

The Lesson

The application had not failed. The data had run out, and the test sent nonsense to a healthy server. Two habits would have prevented the confusion: calculating the rows needed before the run, and setting end-of-file behaviour deliberately.

When tests run on their own after each change, data must be ready and correct without a person watching.

Why Pipelines Raise the Stakes

In a pipeline, nobody checks the first minutes of a run. If the data file is missing, stale, or too small, the test may fail in a confusing way, or worse, pass without exercising anything important. Data preparation must be part of the pipeline itself.

Practices for Pipelines

• Prepare data as a pipeline step. A step before the test creates or refreshes accounts and writes the data file.
• Pass paths as properties. The folder with data files is given at start-up, so the same plan works on any build machine.
• Check the data before the run. A short step counts the rows and columns and fails the build if there are not enough.
• Fail loudly when data runs out. Turn stopping on, and add checks that flag requests carrying the end-of-file marker.
• Reset the environment. Restore data to a known state, so a rerun starts from the same place.
• Keep the files with the results. Store the exact data used with the saved results, for later investigation.
• Run a quick smoke test first. One user for a few iterations will reveal most data problems in seconds.

A one-page reminder for the next time you are in a hurry.

Plain-language meanings of the words used in this guide.

Pilots read a checklist before every flight, however experienced they are. A short list protects a test run in the same way.

Before You Press Start

• The values that should vary have been identified and replaced by placeholders.
• Row arithmetic is done for users, iterations, and think time, with a margin.
• Every file was checked for column counts, blank lines, spaces, duplicates, and encoding.
• The data exists in the system. A few rows were tried by hand.
• End-of-file behaviour was chosen on purpose, not left by default.
• Sharing mode and element placement match the intention.
• Paths are relative or come from a property, and files exist on every worker.
• Data is split per worker where uniqueness matters.
• A one-user smoke test passed, and the log shows no file errors.
• Data is synthetic and files are protected. The target is permitted for testing.

After the Run

• Search the results for the end-of-file marker and for placeholder text.
• Look for failures that cluster around particular accounts or rows.
• Save the exact data files together with the results.
• Reset or refresh the data for the next run, and note what changed.

CSV parameterization gives each virtual user their own identity and errands, so a load test looks like a real crowd instead of one person copied many times.