Skip to content
Tutorials Center
My learning

Topics

Lesson 9 of 37 ยท Concepts and Setup

JMeter Variables, Properties and Functions

Learn how JMeter variables (${name}), properties (__P, -J) and built-in functions like __Random, __time and __UUID work, with scope rules, examples and common pitfalls.

Hard-coded values make a plan brittle. JMeter gives you three tools to make plans flexible: variables (per-thread values you write as ${name}), properties (global settings, often set on the command line) and functions (small built-ins that produce values on demand). Knowing which is which, and when each is evaluated, removes a whole class of baffling bugs.

Honesty note. JMeter cannot run here. The syntax shown is the real syntax. The runnable blocks are stand-ins: a tiny ${...} expander that handles variables, __P and a few functions, so you can practice reading expressions. They are not JMeter's evaluator.

Variables

A variable belongs to a thread (each virtual user has its own set). You reference it with ${name} in almost any text field: paths, bodies, headers, assertion patterns.

Ways to create variables:

Source Example
User Defined Variables (plan level) BASE_PATH = /api/v2
CSV Data Set Config columns username, password
Post-processors (extractors) JSON Extractor puts $.token in token
Counter, Random Variable orderNo, rnd
JSR223 code vars.put("name", "value")

Two scope rules matter:

  1. User Defined Variables at plan level are evaluated once at start, before threads run, and the values are shared as initial values. They cannot see per-thread variables.
  2. A variable set by an extractor in one thread is invisible to other threads. That is a feature: each user keeps their own session token.

When a variable does not exist, JMeter leaves the text as is: you will see a literal ${token} in the request, a strong hint that an extractor failed or the name is misspelled.

Properties

Properties are global to the JMeter instance (not per thread). They come from jmeter.properties, user.properties, or the command line:

Terminal
jmeter -n -t plan.jmx -Jusers=50 -Jhost=qa.example.test

Inside the plan, read them with the __P function, which takes a name and an optional default:

  • ${__P(users,10)} gives 50 in the run above, 10 if the property is not set.
  • ${__P(host,staging.example.test)} for the server name.

Put ${__P(users,10)} in the Thread Group's Number of Threads field and you can scale a test without opening the GUI. Remember: -J sets a local property; -G sends a property to remote servers too in distributed tests.

A subtlety: __P reads properties, ${name} reads variables. They do not see each other, unless you copy one into the other, for example in a User Defined Variables element: HOST = ${__P(host,staging.example.test)}, after which ${HOST} works as a variable.

Functions

A function call looks like ${__functionName(arg1,arg2)}. They are evaluated each time the field is used. Frequently used ones:

Function Result
${__Random(1,100,)} Random whole number between 1 and 100; the third argument can name a variable to store it
${__RandomString(8,abcdef0123)} 8 random characters from the given set
${__UUID} A random UUID
${__time(yyyy-MM-dd'T'HH:mm:ss,)} Current time in the pattern; with no pattern gives epoch milliseconds
${__threadNum} Thread number (1 based)
${__counter(FALSE,)} Counter value; first argument TRUE makes it per thread
${__P(name,default)} Property
${__property(name)} Property (no default)
${__V(name)} Evaluate a variable whose name is itself built from variables
${__urlencode(a b)} Percent-encoded text
${__digest(SHA-256,text,,,)} Hash of some text
${__split(a;b;c,parts,;)} Split into parts_1, parts_2 ...
${__groovy(1+2)} Run a Groovy expression (JMeter 5.x ships Groovy support via JSR223)

Use Options > Function Helper Dialog to build and test the call, as noted in the GUI tour. Mind the comma: values with commas inside function arguments must be escaped as \,.

Nested expressions

Expressions can be nested: ${__Random(1,${maxItems},)} generates a number up to the variable maxItems. This is a common way to pick a random product id. Likewise ${__V(item_${idx})} reads item_1, item_2 and so on, which is how you loop through extracted lists (extractors created with "Match No. = -1" produce name_1, name_2, and name_matchNr).

When is a value evaluated?

  • Fields of a sampler: at the moment the sampler runs, in that thread. ${__time()} there gives the time of this request.
  • User Defined Variables: once at start.
  • Thread Group number fields: once, at test start.
  • Setting a variable after you used it does not retroactively change earlier requests.

Stand-in: a mini expander

The block below expands ${var}, ${__P(name,default)}, ${__threadNum}, ${__Random(a,b,)} using a seeded generator. It leaves unknown variables unexpanded, like JMeter.

JS Stand-in: expand ${...} expressions

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

No output.

Look at the third line: the unreplaced ${token} is exactly what you would see in a JMeter request when an extractor failed. Spotting that in the Results Tree is a core debugging skill.

Variables versus properties: quick guide

Variable Property
Scope One thread Whole JMeter instance
Read with ${name} ${__P(name,default)}
Set with Extractors, CSV, vars.put -J, user.properties, props.put
Typical use Session tokens, row data Environment, user counts, durations

To share a value between threads, store it as a property in a setUp Thread Group (props.put("token", ...)) and read it with __P elsewhere.

Common pitfalls

  • Using ${__P(...)} with a variable name and getting the default: they are different stores.
  • Spaces after commas in function arguments become part of the value.
  • A variable named like a function or containing dots is easy to confuse; use plain names with letters, digits and underscores.
  • Unescaped commas in function arguments, such as __RandomString.
  • Forgetting that CSV columns become variables only for threads that read a row.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. How do you read a property named users with a default of 10?

    __P reads properties (for example set with -Jusers=50) and returns the default if the property is not set.
  2. 2. A request body shows the literal text ${token}. What most likely happened?

    JMeter leaves unknown variables unexpanded, which points to a missing extraction or a typo.
  3. 3. Which statement is true about variables and threads?

    Variables are per thread; properties are global to the JMeter instance.
  4. 4. Which command-line option sets a property named host to qa.example.test?

    -J sets a local JMeter property; -G also sends it to remote servers.

Summary

  • Variables (${name}) are per thread; properties (${__P(name,default)}) are global.
  • Functions like __Random, __time, __UUID and __threadNum generate values at use time.
  • -Jname=value passes properties; use them for hosts, user counts and durations.
  • A literal ${name} in a request signals a missing variable.
  • Use setUp Thread Groups and props.put to share a value between threads.

Next: The HTTP Request Sampler