We begin with the problem they solve, because the element only makes sense once the problem is clear.

The copy-and-paste problem

A realistic test plan repeats the same facts again and again. The address of the server appears in every web request. The name of an environment appears in headers and paths. A waiting time may be used in many timers. If each of these is typed directly into each element, the plan becomes brittle. Switching from a development server to a test server means editing dozens of fields, and missing even one produces a test that quietly hits the wrong system.

The solution in one sentence

The User Defined Variables element holds a table of names and values. Anywhere else in the plan, you refer to a value by its name, and JMeter substitutes the real value when the test runs. Change the table once and every reference follows.

What happens without it

Without named values, teams tend to fall into one of two poor habits. Some copy the same address into every request, so every environment change becomes a hunt through the plan. Others keep several nearly identical copies of the whole plan, one per environment, and the copies slowly drift apart until nobody knows which one is correct. Both habits waste time and produce results nobody fully trusts. A single table of named values removes the need for either.

Why it matters for quality

Named values make a plan easier to read, because a request pointed at a name such as the shop address says what it means. They make a plan easier to move between environments. They also make reviews safer, because a colleague can check one table instead of scanning every request.

A handful of terms appear throughout this guide, and learning them now makes everything easier.

There are many ways to give a value to a JMeter plan, and each suits a different job.

flowchart LR
  A[Command line properties] --> V[Variables used in requests]
  B[User Defined Variables] --> V
  C[CSV data file] --> V
  D[Counter and Random elements] --> V
  E[Extractors from responses] --> V
  F[Scripts] --> V
  V --> R[Samplers, timers and assertions]
        

The behaviour looks simple until you see when the values are really worked out.

Evaluated once, at the start

JMeter’s documentation states that every User Defined Variables element in a plan is processed at the start of the test, no matter where it sits in the tree. The values are worked out one time, before the virtual users begin their real work. This is why the element is a good home for constants, and why it is a poor home for anything that is meant to change.

Each thread receives its own copy

When threads start, each one receives its own set of variables, seeded with the values the element produced. From that moment on, a thread may change its own variables, for instance when an extractor stores a token, without affecting any other thread. The starting values are shared in origin but the working copies are private.

Order inside the table

Within one element, rows are processed from top to bottom, so a later row may refer to an earlier one. Across several elements, they are processed in the order they appear in the plan. If the same name is defined twice, the later definition wins. This gives you a simple, predictable way to build a value from smaller parts.

sequenceDiagram
  participant S as JMeter Start-up
  participant U as User Defined Variables
  participant T1 as Thread 1
  participant T2 as Thread 2
  S->>U: Process all elements top to bottom
  U-->>S: Names and evaluated values
  S->>T1: Give private copy
  S->>T2: Give private copy
  T1->>T1: Extractor stores token in own copy
  T2->>T2: Extractor stores different token in own copy
        

Creating the element takes a minute, and doing it carefully saves hours later.

A short review before saving

Before you save the plan, read the table once from top to bottom. Check that every name is spelled the way the rest of the plan spells it, that no value has a stray space at either end, that each row refers only to rows above it, and that the description column says what each value is for. This two-minute review catches most of the errors that otherwise cost an hour of confused debugging later.

A variable is only useful once something refers to it, and a few functions make those references much more powerful.

Where references are allowed

Almost every text field in a plan accepts references: server names, ports, paths, parameter values, headers, timer delays, assertion patterns and more. A few fields that are evaluated before threads exist, notably some thread group settings, are better served by properties, a point covered in detail later.

There are two places to define variables, and beginners often wonder whether they differ.

They behave alike

The test plan itself has a built-in table of user defined variables. The separate config element offers the same kind of table. Both are processed at the start, and both supply initial values to every thread. The practical differences are about organisation, not behaviour.

A practical recommendation

Use separate, well-named elements near the top of the plan, grouped by purpose: one for the target system, one for timings, one for feature switches. It keeps each table short and gives each a place for comments. Reserve the plan-level table for a very small plan, or avoid relying on it entirely so that all your settings live in the same kind of place.

Most JMeter elements affect only what lies beneath them. This one does not, and that surprises nearly everyone.

The usual rule of scope

Timers, assertions and many config elements apply only to the samplers in their scope, meaning the siblings and children at or below their position. It is natural to assume that a variable table placed inside one thread group applies only to that group.

How this element differs

The documentation is explicit that all User Defined Variables elements in a plan are processed at the start regardless of position. A table inside thread group A therefore defines variables for thread group B as well, because the variables are created before any thread group begins. Position affects only the processing order and the human reading of the plan.

The single most common mistake with this element is expecting a value to change when it was only ever evaluated once.

What goes wrong

Because values are worked out once at the start, putting a function that produces a different answer each time, such as the current time, a random number or a unique identifier, into a user defined variable freezes the first answer. Every use of the variable afterwards, by every thread and every iteration, receives the same frozen value. The documentation specifically warns that only the result of the first function call is saved.

The consequences are subtle

All virtual users appear to share one timestamp. All orders carry the same reference number. All searches use the same random keyword, so server caches answer instantly. The test runs, the numbers look fine, and nothing signals that the data variety you intended never existed.

The most valuable pattern in practice joins this element to properties, so that one plan serves many environments.

The idea

Instead of typing a literal value into the table, write the property function with a default. The variable then takes the property’s value when one is supplied from the outside, and falls back to the default otherwise. A plan opened in the graphical interface just works with its defaults, while the command line supplies different values for different runs without anyone editing the plan.

Why the default matters so much

The default is not a throwaway detail. It is what runs whenever someone opens the plan and presses start without supplying anything, which happens constantly during development and review. A good default is safe, small and local: a development address, a handful of users and a short duration. A bad default is a trap waiting for a tired colleague. Treat the choice of default as part of the design, and write down what each default represents.

flowchart LR
  A[Command line property] --> B{Property supplied?}
  B -- Yes --> C[Variable takes supplied value]
  B -- No --> D[Variable takes default]
  C --> E[Requests use the variable]
  D --> E
        

Understanding the privacy of variables explains many puzzling results.

Private by design

Because each thread works on its own copy, a token captured by one user stays with that user. This is exactly what you want for personal values such as session identifiers, and it is why thousands of users can run the same plan without stepping on each other.

Sharing needs a different tool

Sometimes a value found by one thread must reach others, for example an administrator token fetched once for the entire test. Variables cannot do this. Properties are global and can carry such a value, usually written by a script in a setup thread group. Choose carefully, because writing personal data into a shared property makes every user overwrite everyone else.

Because values are built in sequence, order becomes a design tool, and also a source of confusing overrides.

Building values from parts

A row may refer to any row above it, in the same table or in an earlier element. This lets you assemble a long value from small, meaningful pieces. A protocol, a host and a port can each be defined once, and a base address built from them in a following row. Later requests then refer to the base address alone. If the host ever changes, one row changes and the base address follows automatically.

What happens when names collide

If two rows define the same name, the later one wins. That is convenient when you intend it, such as a plan-wide default overridden by a more specific definition, but harmful when it happens by accident. A copy-and-pasted table that reuses a name from another table silently replaces the earlier value.

Collisions with run-time sources

Names can also collide with variables created while the test runs. An extractor that stores a value under the same name as a defined constant replaces the constant for that thread from that moment. A data-file element that uses the same name does likewise. Sometimes this is the point, as when a default is replaced by a real value, but unintended collisions are a classic source of mysterious behaviour.

This element is perfect for constants and wrong for almost everything else, so it helps to know its neighbours.

A short decision table turns the menu of options into a confident choice.

A worked example of choosing

Suppose you need five different pieces of information in one plan: the shop address, a customer account, a unique order number, a delivery slot chosen by the server and the duration of the test. The shop address is a constant, so it belongs in the table, ideally read from a property. The customer account differs per user, so it comes from a data file. The order number must be unique each time, so a counter supplies it. The delivery slot is decided by the server, so an extractor captures it from a response. The duration shapes the whole test, so a property feeds the thread group. Five needs, five different sources, and each one is the natural fit.

Three questions to ask

First, when is the value known: before the test, at launch, or only during the run? Second, who needs it: every user alike, or each user differently? Third, should it change between uses, or stay put? The answers almost always point to exactly one element, and asking them every time prevents the dynamic-function trap described earlier.

Most teams use this element mainly to make one plan run against many environments.

The single-table pattern

A small table at the top of the plan defines protocol, host, port and base path, each reading from a property with a development default. The command line or a property file supplies the real values for test, staging and other environments. It is simple, clear and good enough for most projects.

The labelled-environment pattern

For plans that must switch between several complete sets of settings, define each environment’s values under names that include the environment label, then pick the active set using the variable function with a label supplied as a property. One launch property chooses the environment, and every setting follows.

flowchart TD
  A[Launch with environment label] --> B[Variable selects named settings]
  B --> C[Development values]
  B --> D[Test values]
  B --> E[Staging values]
  C --> F[Requests use chosen values]
  D --> F
  E --> F
        

Documenting each environment

Whichever pattern you choose, keep a short written record of what each environment is: its purpose, who owns it, how closely it resembles production and what data it holds. Results from a small, weak environment must never be compared directly with results from a large, production-like one. Writing the environment’s character next to its settings stops people from drawing the wrong conclusion months later.

The property-file pattern

Keep one property file per environment in version control and name the file on the command line. The plan reads properties as before, and switching environment means pointing at a different file. Review of environment changes happens through ordinary code review.

Users naturally want to control the number of users and the duration through variables, but timing makes that awkward.

The timing problem

Thread group settings, such as the number of threads, the ramp-up time and the duration, are read when the group itself is being set up. Variables, in contrast, live inside threads and are created as threads begin. The group’s own configuration therefore comes before the thing that would supply the variable, which makes variables an unreliable source for these particular fields.

The reliable alternative

The property function is evaluated without needing a thread, so it works well in these fields. A thread count field can read a property with a default, and the same plan runs with ten users in the graphical interface and with a thousand from the command line. This is the standard, dependable pattern.

A plan with fifty undocumented variables is a puzzle. A few habits turn it into a readable map.

User defined variables have no types, which affects how you use numbers and switches.

Text in, text out

Every value in the table is text. A number is the characters of that number, and a switch such as true or false is the word. This is fine wherever a field simply expects text, and also in numeric fields, where JMeter converts the text to a number when it uses it. Problems appear when you try to calculate with them, because there is no arithmetic inside the table.

Calculating when you need to

JMeter provides functions for simple arithmetic, such as adding numbers or evaluating an expression, and script elements for anything more elaborate. Remember that a calculation inside the table is also evaluated only once. If the calculation should use values that change during the run, perform it in an element that runs at that time.

When a value is wrong, the quickest fix starts with seeing exactly what JMeter thinks it is.

Names are resolved wherever they appear, including in the labels of requests, with consequences for your reports.

Labels are text too

A sampler’s name accepts references like any other field. That can be handy, for example to include the environment label in the name, but it can also explode the number of distinct labels in a report. If a name includes a value that differs for every request, such as a unique identifier or a timestamp, each request gets its own row in the statistics, and the report becomes unreadable and heavy.

Keep labels stable

Reports group results by label, so labels should describe the kind of request, not the individual instance. Use stable, descriptive names such as the business action. If you need to see parameters, record them in a separate field or in saved response data for failures, rather than in the name.

When several machines generate load, properties and variables need extra attention.

The plan travels, properties may not

The controller sends the test plan to each worker, so the variable table and its references arrive intact. But properties supplied on the controller’s command line as local settings are not automatically known to workers. A variable defined from a property would then fall back to its default on the workers, with no error, and different machines could test different configurations without anyone noticing.

Global properties solve this

JMeter offers a way to define global properties that are sent to the workers when the test starts. Use it for every value that must match across machines, or place identical property files on each worker. Always confirm, with a short run, that every worker used the same resolved values.

flowchart LR
  C[Controller] -->|plan with variable table| W1[Worker 1]
  C -->|plan with variable table| W2[Worker 2]
  C -->|global properties| W1
  C -->|global properties| W2
  W1 --> R1[Resolved values on worker 1]
  W2 --> R2[Resolved values on worker 2]
  R1 --> M[Values must match]
  R2 --> M
        

The element behaves identically in both modes, but your way of working should differ.

Same behaviour, different purpose

Evaluation happens inside the engine, so variables resolve identically whether the plan runs in the graphical interface or from the command line. Use the interface to define, name and debug variables with one or a few users. Use the command line to run real load with properties supplying the values for each environment.

Edits during a run do not take effect

Because values are processed at the start, changing a table while a test is running does not alter the running threads. Stop the test, edit, and start again. This matters most in the interface, where it is tempting to adjust a value in the middle of a run and expect an immediate effect.

A table of named values is convenient, and convenience tempts people to store things that should never sit in a plan file.

These patterns appear again and again in tidy, trustworthy plans.

Besides the scope surprise and the frozen function, these mistakes look harmless and quietly spoil results.

An honest look at benefits and costs shows when the element is the right answer.

A short order of operations avoids the stumbles described in this guide.

Named values help every kind of sampler, not only web ones.

Stories show how the element helps, and how it can mislead, in everyday projects.

At the start of the test, for every such element in the plan regardless of its position. Values are then copied into each thread’s private variable set.

Because a changing function placed in the table is evaluated only once. Put the function directly in the request field, or use a counter, random variable or data file.

No. All such elements are processed at the start, so position affects only order and readability, not scope.

A variable is private to one thread. A property is global to the whole test. Use properties for settings shared by everyone, and variables for values that belong to a single user.

It is unreliable because thread group settings are read before threads and their variables exist. Use the property function with a default instead.

Define the variable using the property function with a default, then supply the property at launch. If it is not supplied, the default applies.

The reference usually stays as literal text, and JMeter logs a warning. Inspect resolved requests to catch this.

Yes, if the other row is above it, in the same table or an earlier element. Rows are processed from top to bottom.

Editing the table during a run does not affect running threads. Stop, edit and restart. Individual threads can still change their own variables through extractors or scripts.

The table travels with the plan, but properties set locally on the controller do not reach workers. Use global properties or matching property files on every worker.

No. Plans are plain text. Supply secrets at run time through properties from a secret store and keep plan defaults harmless.

They behave the same. Separate, named elements are easier to organise and document, so many teams prefer them. Choose one habit and keep to it.

Names that include per-request values create a separate label for every request. Use stable labels that describe the type of request.

Add a debug sampler and view its output in a results viewer in a one-user run. It lists variables and properties with their current values. Disable it before real load.

The User Defined Variables element does one job very well: it gives names to values you know before the test begins, so you can change them in one place. Its behaviour is simple but easy to misjudge. Values are worked out once at the start, regardless of position, and then copied into each thread’s private variables. That makes the element perfect for constants and environment settings, especially when joined to properties with safe defaults, and wrong for anything that must vary, such as unique identifiers, random numbers, per-user data or values the server decides. Choose the element whose timing and scope match the value, keep secrets out of plans, make sure properties reach every worker, and inspect resolved requests before trusting any run.