A variable is simply a named box that holds a value you want to reuse or change while the test is running.

The problem variables solve

Apache JMeter is a free, open-source tool that sends many requests to a website, API or server at once so you can see how the system behaves under pressure. When you record or build a test, you usually start with fixed values: one username, one product number, one server address. That works for a single request. It breaks the moment you pretend to be a thousand different people.

If a thousand virtual users all log in with the same username, the server may block the account, serve everyone the same cached page, or simply behave unrealistically. Real traffic is varied. Real users have different names, search for different things, and receive different tokens from the server. Variables are how you inject that variety, and how you carry information from one request to the next.

Three jobs a variable does

The basic way to use one

Anywhere JMeter lets you type text, such as a URL path, a header, a form field or a body, you can wrap a variable name in a dollar sign and curly braces. For example, writing ${customerId} tells JMeter: “when you build this request, replace this with whatever the variable named customerId holds right now.” Names are case sensitive, so ${customerId} and ${CustomerId} are two different notepad entries.

JMeter keeps two separate kinds of stored values, and mixing them up is the number one beginner confusion.

A JMeter variable belongs to one thread, one virtual user. A JMeter property belongs to the whole JMeter process and is visible to every thread at once. Properties usually come from configuration files or from the command line when you launch the test. Variables are created and changed while the test runs.

Why the split exists

Load tests run hundreds or thousands of threads in parallel. If every value were global, one thread’s session token would overwrite another’s within milliseconds. Keeping variables private per thread removes that whole category of bug. Properties stay global because things like “which server are we hitting” or “how many users should run” are the same for everybody and need to be decided once.

Under the surface, every thread owns a small private map of names to text values.

When JMeter starts a thread, it hands that thread its own object that behaves like a dictionary: names on the left, values on the right. Developers call it the thread’s variable map. Every element that runs inside that thread, whether it is a sampler, a pre-processor, an extractor or a controller, looks names up in that same dictionary. When your test plan says ${orderId}, JMeter performs a lookup in the running thread’s dictionary and substitutes the answer into the text.

Values are text

The dictionary stores text. Even when you extract the number 42 from a response, JMeter stores the characters “4” and “2”. If you want to do arithmetic you need a function or a script that converts text to a number, calculates, and writes the answer back as text. Advanced scripts can also stash whole objects in the map, but beginners should think of every value as a string.

What happens when a name is missing

If a name does not exist in the dictionary, JMeter does not stop with an error. It leaves the original text, braces and all, in the request. That means your server may receive a literal “${orderId}” and respond with an error. This silent failure is why careful testers always check the request body in a results viewer during a trial run.

Isolation between threads

Because each thread has its own dictionary, thread 1 writing “token = abc” cannot disturb thread 2 holding “token = xyz”. When JMeter starts the test, the values defined at the test plan level are copied into each new thread’s dictionary as starting values. After the copy, each thread is free to overwrite its own version without affecting anyone else.

JMeter offers a toolbox of elements that produce variables, each designed for a particular situation.

How to choose

Ask one question: where does the value come from? If you decide it before the test, use a user defined variable or a property. If a file supplies it, use CSV Data Set Config. If the server hands it to you, use an extractor. If it should be invented fresh each time, use a counter, a random variable or a function. Choosing by origin keeps your plan easy to read and easy to maintain.

The simplest variable source is also the one with the most surprising behaviour, so it deserves a careful look.

What it does

User Defined Variables is a table with two columns: a name and a value. You list your settings once, for example the web server host name, the port, a default pause time, or the base path of the application. Everywhere else in the plan you refer to the names. When you later move the test from a staging server to a pre-production server, you change one cell instead of editing dozens of requests.

The surprising rule about timing

Many newcomers assume a User Defined Variables element runs at the moment the test reaches it, like a sampler. It does not. JMeter processes all User Defined Variables elements at the very start of the test, in the order they appear, regardless of where you placed them in the tree. Placing one halfway down a thread group therefore does not make it “activate” halfway through.

When the value must change mid-test

Because of that start-of-test behaviour, User Defined Variables is the wrong tool for values that need to change while the test runs. For those, use a post-processor, a counter, a function or a small script. A related but different element, the User Parameters pre-processor, assigns values per thread and per iteration at the moment it is reached, which suits “each user gets a different value in this step” scenarios.

Two rules decide whether a variable exists when you need it: where its element sits in the tree, and the fixed order JMeter runs elements in.

Scope rules

A test plan is a tree. Elements apply to the branch beneath their parent. A configuration element placed directly under a thread group affects every sampler in that group. Placed under a single sampler, it affects only that sampler. Placed at test plan level, it affects everything. The same rule applies to extractors: an extractor sitting under one sampler reads only that sampler’s response, while one placed at thread group level tries to read every sampler’s response, which is rarely what you want.

Execution order inside one step

For every sampler, JMeter follows the same sequence, regardless of how you arranged the elements visually.

The CSV Data Set Config element is the workhorse for realistic, varied load.

CSV stands for comma separated values, a plain text file where each line is a record and a delimiter splits the columns. You list the file’s columns as variable names, and JMeter reads one line per thread per iteration, loading each column into the matching variable. Thread one may get “alice” and her password, thread two gets “bob” and his, and so on down the file.

The settings that matter

Sharing mode, explained with a deck of cards

Correlation means taking a value from one response and using it in a later request. Extractors are the tools that do the capturing.

Modern applications constantly hand out one-time values: session tokens, anti-forgery codes, order numbers, cart identifiers. If you record a test and replay it exactly, the old token is stale and the server rejects it. The fix is to capture the fresh token from the earlier response, place it in a variable, and reference that variable in the next request. This habit is called correlation, and it is the single most important variable skill for realistic tests.

The family of extractors

Settings every extractor shares

Each extractor asks for a reference name, which is the variable it will create, a match number that says which hit to keep, and a default value. The match number can mean the first hit, the Nth hit, a random hit, or every hit. The default value is what the variable holds if nothing matched.

When there are many matches

If you ask an extractor for all matches, JMeter creates a family of variables rather than one. Using a reference name of “product” as an example, you receive a count variable that says how many hits were found, plus numbered variables for the first, second, third match and so on. This family is what a ForEach controller later walks through, one value per loop pass.

Sometimes the data must be invented fresh, and JMeter has several ways to do it.

The Counter

A Counter produces a number starting at a value you choose and increasing by a step each time it is used. You can cap it at a maximum, format it with leading zeros, and, importantly, decide whether each virtual user has its own private count or whether all users share one running total. Shared counting gives globally unique numbers such as invoice ids. Private counting gives each user a personal sequence such as “my third item”.

Random Variable

The Random Variable element picks a number between a minimum and a maximum and stores it. It can also keep a per-user seed so that test runs are repeatable. Use it to choose a random page number, a random quantity, or a random index into a list of products.

Functions that generate values inline

Properties make a test configurable from the outside, and a few functions bridge the gap between the two notepads.

Where properties come from

JMeter loads properties from its main configuration file, then from a user-level override file, and finally from options typed on the command line. Later sources win over earlier ones. The command-line option that sets a local property is the dash-J option, and the one that also pushes a property to remote test machines is the dash-G option. Both let one test file run at many sizes without ever being edited.

Reading and writing across the boundary

The property function reads a property and lets you supply a fallback value if it is missing. For example, asking for a property named “users” with a default of 10 means “use whatever was passed in, otherwise ten”. This pattern makes a plan safe to open and run by double-click while still being steerable from automation. A companion function writes a property, which is how one thread group can leave a value that a different thread group reads later.

Variables whose names are themselves variables

A helper function can resolve a name that is built from other variables. If you have variables named for a row and a column, you can assemble the name on the fly and fetch the value it points to. It is powerful for looping through tables, but it is also the point where plans become hard to read, so use it sparingly and comment it well.

When the built-in elements are not enough, a short script can read, calculate and write variables freely.

JSR223 elements run small scripts in a language such as Groovy. Inside the script, JMeter provides a ready-made handle to the current thread’s variable dictionary, so the script can read any variable, change it, create a new one, or remove it. The community recommendation is to prefer Groovy with script caching enabled, because it is compiled once and runs fast, while older scripting options are slower under heavy load.

Good reasons to script

The golden rule of scripting

Script only when no ready-made element can do the job. Built-in elements are clearer to colleagues, easier to debug, and usually faster. A plan that is ninety percent standard elements and ten percent careful scripting ages far better than one that is mostly custom code.

Follow a single value from the moment it is born to the moment it disappears.

A variable has a life story. It is created by some element, it lives in its thread’s dictionary, it is read by later elements, possibly overwritten, and finally it vanishes when the thread ends. The diagram below shows the common path of a login token, the most typical example.

sequenceDiagram
    participant U as Virtual User Thread
    participant D as Thread Variable Map
    participant S as Server
    U->>S: Send login request
    S-->>U: Reply containing a session token
    U->>D: Extractor stores token under a chosen name
    U->>D: Next request looks the name up
    D-->>U: Returns the stored token text
    U->>S: Send request carrying the token
    S-->>U: Reply for the authenticated user
        

The phases of a variable’s life

When one machine cannot generate enough load, several machines share the work, and variables must be planned accordingly.

In distributed mode, one controller machine sends the test plan to several worker machines, often called remote engines or load generators. Each worker runs its own copy of JMeter and its own set of threads. Variables stay private to each thread on each worker, exactly as before. What changes is everything that lives outside JMeter’s memory, especially data files and properties.

flowchart TD
    C["Controller machine: holds the test plan"] --> W1["Worker 1: own threads and own variable maps"]
    C --> W2["Worker 2: own threads and own variable maps"]
    C --> W3["Worker 3: own threads and own variable maps"]
    W1 --> T["System under test"]
    W2 --> T
    W3 --> T
    F1["Data file copy 1"] --> W1
    F2["Data file copy 2"] --> W2
    F3["Data file copy 3"] --> W3
        

What to plan for

Load tests often touch real systems, so passwords and tokens in variables deserve respect.

Test plan files are plain text. It is tempting to type a real password into a User Defined Variables table because it is quick. That file then travels through email, chat, version control and shared drives. Treat any credential inside a plan as if it were published.

You cannot fix what you cannot see, and variables are invisible by default.

Because a missing variable fails silently, every serious tester builds a habit of looking inside the running test. JMeter gives you several windows into the thread’s dictionary, and learning to use them early saves hours of confusion later.

Your inspection toolkit

A reliable debugging routine

Experienced testers keep returning to a handful of proven ways to organise variables.

flowchart LR
    P["Run-wide settings: properties"] --> E["Environment block: user defined variables"]
    D["Test data file"] --> V["Per-user variables"]
    E --> V
    R["Server responses"] --> X["Extractors"]
    X --> V
    V --> Q["Requests built with substituted values"]
    Q --> R
        

These habits look harmless on day one and cause expensive confusion by week three.

A short checklist of habits that separate dependable tests from fragile ones.

The mistakes that cost the most time

Variables show up in every kind of performance test. Here are the situations you will meet most often.

The variable system is flexible, but flexibility has a price.

Choosing between neighbours

Controllers decide what runs and how often, and variables are the information they use to decide.

A controller is a JMeter element that organises samplers into logic: run this group, repeat that group, skip this branch. Many controllers accept variables, which turns a fixed script into a flexible, data-driven one. The test then behaves differently for different users, depending on what the server told them or what their data file contained.

Polling with a variable

Many systems process work in the background. You submit a request, receive a job identifier, and then must ask repeatedly whether the job is done. A while-style loop combined with an extractor that refreshes a status variable models this perfectly. Always add a short timer inside the loop and a sensible upper limit on attempts, or a stuck job will make a virtual user spin forever and flood the server.

Condition text is still just text

Because variables hold text, comparing numbers inside a condition needs attention. The text “10” and the text “9” sort differently from the numbers ten and nine. Use the condition style that treats the expression as a script, or convert deliberately, when you compare quantities rather than words.

Variables are cheap one at a time, but a big test multiplies every small cost by thousands of threads.

The load generator is itself a program with limited memory and processor time. If it becomes the bottleneck, your measurements describe the generator, not the system you meant to test. Variables influence that cost in three ways: how much text they store, how often they are written, and how complex the elements that fill them are.

Where the cost hides

How to verify the generator is healthy

Watch the load generator’s own processor and memory during a trial run. If either stays high while server response times look suspiciously flat, suspect the generator. Reducing stored data, simplifying patterns and removing debug listeners usually restores headroom. When one machine still cannot cope, spread the threads across several machines as described in the distributed chapter.

JMeter quietly provides several useful values so you do not have to invent them.

Without any setup, a running test already has access to a few handy pieces of information. Some are properties that record when the test began, in several formats, which is handy for stamping data with a run date. One is a per-thread variable that reports whether the previous sampler succeeded. Others are available through functions, such as the number of the current thread or the current moment in time.

Recovering from a failed step

Because the previous-sample result is a variable, an If Controller can read it and run recovery logic only when something went wrong, for example re-authenticating after an unexpected rejection. This lets a long scenario survive occasional errors rather than collapsing, while still recording every failure for your report.

Let us build, in sentences rather than code, a realistic test for an online bookstore.

Our goal is to simulate customers who log in, search for a book, add it to a cart and pay. The test must work against any environment and handle one thousand different customers. We will see every kind of variable doing its job.

flowchart TD
    A["Properties from command line"] --> B["Environment block"]
    C["Customer data file"] --> D["Login request"]
    B --> D
    D --> E["Extract token"]
    E --> F["Search request"]
    F --> G["Extract random book id"]
    G --> H["Add to cart request"]
    H --> I["Extract cart id"]
    I --> J["Payment request with unique reference"]
        

Notice the pattern: values flow forward like a relay baton. Properties and files feed the start; extractors keep the baton moving; assertions confirm nobody dropped it. That simple rhythm is the heart of almost every professional JMeter test.

A plan that only its author understands is a liability. A few team habits keep variables readable for years.

The most flexible extractor is also the one that causes the most trouble, so it is worth learning its settings one by one.

A regular expression, often shortened to regex, is a compact description of a text pattern. Instead of saying “find the exact word token”, you can say “find the text that follows the word token, up to the next quotation mark”. The Regular Expression Extractor applies such a pattern to a server response and stores whatever your pattern captured. Parentheses inside the pattern mark the part you want to keep; everything outside the parentheses is only there to locate it.

The settings you will fill in

Greedy versus lazy matching

The biggest source of regex bugs is greediness. A greedy pattern grabs as much text as it possibly can, which means it may run past the end of the value you wanted and swallow half the page. A lazy pattern stops at the first opportunity. When you write a capture group, prefer the lazy form that means “as little as possible until the next marker”. Test the result: if your variable contains far more text than expected, greediness is almost always the reason.

Make patterns resilient

Before you can capture a dynamic value, you must first discover which values are dynamic.

Beginners often record a scenario, replay it, and watch it fail with no clue why. The usual cause is a hidden dynamic value: something the server generated during recording that is different every time. Finding these values is a detective job with a reliable method.

Typical dynamic values

Most variables end up inside an HTTP request, and each part of a request has its own habits.

Cookies

The HTTP Cookie Manager acts like a browser’s cookie jar for each virtual user. Cookies that the server sets are stored automatically and sent back on later requests to the same site, so ordinary session cookies often need no variable at all. Each thread has its own jar, which is exactly what you want. Decide whether the jar should be emptied at the start of every iteration. If you leave it full, a returning user is simulated; if you empty it, every loop pass looks like a brand-new visitor.

Headers

The HTTP Header Manager lets you set headers once and have them apply to every request beneath it. Header values can contain variable names, which is how an authorization token captured at login ends up attached to every later call. Place the header manager at thread group level so it covers all requests, but remember the token must already exist by the time the first request that needs it is built.

Parameters and bodies

Form fields, query parameters and request bodies all accept variable names. For JSON bodies, you are writing text that happens to look like JSON, so a missing or empty variable can quietly produce invalid JSON, for instance an unclosed quotation mark. Check the sent body whenever a request is unexpectedly rejected.

Server defaults

The HTTP Request Defaults element stores the protocol, host name and port once. Combined with variables, one element controls where every request goes, so moving a test between environments needs a single change.

Good variables are only as good as the data behind them, and test data needs its own plan.

A load test is usually limited not by the tool but by the data. Unique accounts, product records and reference numbers must exist in the system before the test starts, and they must still be valid when it ends. Teams that skip this planning step often discover mid-test that they only have two hundred accounts for a thousand users.

Sizing your data

Start with a simple calculation. Count the virtual users, multiply by how many times each will repeat the scenario, and decide whether each repetition may reuse a record. If records must be unique, that product is the number of rows you need. If reuse is acceptable, you only need enough rows to avoid unrealistic hot spots, where thousands of users hammer one record and distort caching.

Preparing and cleaning

Real teams run load tests automatically, and variables are what make a single plan adaptable.

JMeter has a graphical interface for building and debugging plans, but actual load runs should use the command-line mode with no graphics. The graphical window consumes memory and processor time that the load generator needs. In command-line mode, you supply the plan, say where to write results, and pass any properties that steer the run.

flowchart LR
    A["Code change"] --> B["Build pipeline"]
    B --> C["Start JMeter without graphics"]
    P["Environment and size properties"] --> C
    S["Secrets from secret store"] --> C
    C --> R["Result file and summary report"]
    R --> G["Pass or fail gate"]
        

What to parameterise

Pass and fail gates

Pipelines need a clear verdict. You can combine assertions inside the plan, which mark individual requests as failed, with checks on the result summary, such as error percentage or response-time thresholds, to decide whether the build proceeds. Variables again help here: thresholds themselves can be properties, so a team can tighten a limit without editing the plan.

When something goes wrong, match the symptom to its most likely cause, then confirm with a debug element.

A calm method

Resist the urge to change several things at once. Reduce to one user, reproduce the failure, change one item, and rerun. Variable bugs are logical, not mysterious: every one has a spelling, scope, order or data cause. Work through those four in turn and you will find it.

Keep this chapter handy. Each term is explained the way you would explain it to a friend.

Reading is a start; practice makes the ideas stick. Here is a sensible order for building skill.

Once the basics feel comfortable, a handful of subtle behaviours decide whether a large plan stays reliable.

Nested references resolve from the inside out

You can place a variable reference inside another reference or inside a function’s arguments. JMeter resolves the innermost reference first, then works outward. This is how a plan can build a name such as “price for item three” from a counter and then read the variable with that assembled name. It is elegant but fragile, because a single typo in either layer produces a name that does not exist, and the failure is again silent.

Commas inside function arguments

Functions separate their arguments with commas. If a value you pass in itself contains a comma, such as a sentence or a formatted number, JMeter will think you started a new argument. The fix is to escape that comma with a backslash. Forgetting this is a classic cause of functions returning odd results while the plan looks perfectly reasonable.

Setup and teardown groups are separate threads

The special setup and teardown thread groups run in their own threads, before and after the main groups. Because variables belong to a thread, anything stored in a variable inside a setup group is not automatically visible to the main groups. Passing values between them requires a property, which is shared by all threads.

Reusable fragments and scope

When you reuse a block through an include or module controller, the block runs inside the calling thread and sees that thread’s variables. This is convenient, because a shared login step simply writes the token into the caller’s dictionary. It also means a fragment silently depends on names defined elsewhere, so document the names a fragment reads and writes.

A short quick-reference of helpful functions

The name does not exist in that thread at that moment. Check spelling and capitalisation, confirm the element that creates it ran earlier, and make sure it is within scope. If it came from the command line, it is a property and must be read with the property function.

Not directly. Variables belong to one thread. To pass a value across thread groups, write it as a property in one place and read it in another, keeping in mind that all threads see the same property.

A variable is private to one virtual user and changes during the run, while a property is shared by the whole JMeter process and is normally set before the run starts.

Those elements are processed once at the start of the test regardless of where they sit. Use a pre-processor, counter, function or script for values that must change during execution.

Use a CSV Data Set Config with all-threads sharing, disable recycling, and enable stop thread at end of file. When distributing the test, give each machine a different slice of the data.

The pattern or path did not match the actual response. Open the response in a results viewer, compare it character by character with your expression, and watch for different formatting, encoding or response differences between runs.

Yes. Two names that differ only in capital letters are two separate variables, which is a common source of silent failures.

Variables store text. Use a calculation function or a short script to convert the text to a number, do the arithmetic, and write the result back as text.

No. Each thread’s dictionary is discarded when the thread ends, and a new run starts clean. Only files and configuration you provide persist.

It is safe inside the running test, but unsafe inside a saved plan file that others can read. Supply secrets at run time through your pipeline’s secret handling and use dedicated test accounts.

Each worker reads its own data file and keeps its own counters. Split the files, offset counter start values per worker, or use UUID generation so uniqueness does not depend on coordination.

Prefer built-in elements whenever they can do the job. They are faster, clearer to teammates and easier to debug. Reserve short, cached scripts for genuine gaps.

Look at how it is read. A plain dollar-brace name is a variable lookup. A property is read through the property function, often with a default value beside the name. Also check the command that launches the test: anything passed with the dash-J or dash-G options is a property.

They share the same reference name. The extractor that runs later replaces the earlier value. Give each extractor a unique, descriptive name unless you intentionally want the newest value to win.

Use the graphical window to build and debug with a handful of users. For real load, run without graphics, because the interface consumes memory and processor time that the load generator needs for generating traffic.

There is no fixed limit, but readability and memory both suffer when plans accumulate unused or duplicated names. Keep only variables that are referenced, store small values, and prune the rest during regular reviews.

JMeter variables are the memory of your virtual users. They let one test plan imitate thousands of distinct people, carry server-issued values from one request to the next, and keep configuration in a single tidy place. The central ideas are simple: variables are private to one thread, properties are shared by the whole process, values are text, order and scope decide when a name exists, and anything that fails silently should be made to fail loudly. Master those ideas and your load tests will describe the system under test honestly rather than describing your own mistakes.