Before meeting the tool, we must understand the trouble it removes. Fixed data makes tests lie, and functions make them honest.

What is test data?

Test data is every piece of information your virtual users type or send: usernames, passwords, email addresses, search words, order quantities, dates, and reference numbers. When you record a journey in JMeter, the recording captures the exact values you used. Those values become fixed text inside your requests.

What goes wrong with fixed data?

Fixed data causes several kinds of trouble, and each one gives a false picture of how your system behaves.

• Duplicate conflicts. Many applications refuse to create two accounts with the same email or two orders with the same reference. With fixed data, only the first virtual user succeeds, and everyone else gets an error.
• Unrealistic caching. If every user searches for the same word, the server answers from its fast memory after the first request. Your report looks wonderful, but real users, who search for thousands of different words, would see slower pages.
• Lock contention. When thousands of users update the same record, the database makes them wait in a queue. Real life rarely behaves that way, so you measure a problem that real users never meet.
• Stale values. A date recorded on Monday is wrong by Friday. A request for “today’s report” using a fixed date will ask for a day that is long gone.
• No traceability. If every request looks identical, you cannot tell in the server logs which virtual user did what.

The solution: let JMeter make the data

JMeter includes dozens of ready-made functions. A function is a small built-in helper that produces a value when it is needed: a random number, a unique identifier, the current time, the number of the current user, and much more. You place the function inside a request, and every time JMeter sends that request, the function creates a fresh value.

A short, clear definition, followed by how to open it and why it exists.

The simple definition

The Function Helper Dialog is a small window inside the JMeter screen that helps you build function text. You pick a function from a list, type its settings into a small form, and the dialog creates the exact piece of text that JMeter understands. You then paste that text into any field of your test.

Let us unpack the words in that definition:

• Dialog. A small pop-up window that asks you for a few choices, then goes away. It is not part of your test plan and it is never saved inside your test file.
• Function. A named helper that returns a value. Every function name begins with two underscore characters, such as __Random.
• Parameters. The settings you give a function. A random function, for example, needs to know the smallest and largest number it may choose.

How to open it

In the JMeter window, open the Options menu and choose Function Helper Dialog. JMeter also offers a keyboard shortcut for it, which is shown next to the menu entry. The dialog opens on top of your test plan, and you can keep it open while you work on your test.

What you will see

The dialog is simple. It has a list from which you choose a function. Below that, a small table shows the settings that function accepts, with a place for you to type each value. A button builds the finished text and copies it for you. The dialog can also show the documentation of the chosen function, and a field that shows the value the function produced when you tried it. Labels can differ a little between JMeter versions, but the layout and the idea are the same.

Why does it exist?

Function text has a strict shape. One missing bracket, one extra space in the wrong place, or one comma in the wrong spot, and JMeter will treat your text as plain words instead of a function. The helper removes this risk. It builds the text for you, so the shape is always correct.

A little history

Apache JMeter began as a simple Java tool for testing web applications, and it grew into a general load testing tool at the Apache Software Foundation. As tests became larger, testers needed ways to create varied data, so the project added a library of built-in functions. The helper dialog followed, because remembering the exact name and settings of dozens of functions is hard for any human.

Beginners often mix up three ideas that look alike. Separating them now saves hours of confusion later.

Variables

A variable is a named box that holds a value for one virtual user. You read it by writing its name inside ${ }, such as ${username}. Variables are private: each virtual user has its own set. They are created by many elements, such as extractors, data files, and user-defined variable lists.

Properties

A property is a named setting that belongs to the whole JMeter run, shared by every user. Properties usually come from the command line or a settings file, for example the address of the server you want to test. You read them with a function, because the plain ${ } form reads variables, not properties.

Functions

A function is a helper that produces a value at the moment it is used. You write it as ${__name(settings)}. The two underscores at the start tell JMeter, “This is a function, not a variable.”

How they work together

These three ideas are partners. A function can read a property: ${__P(server)} reads the server address from the run settings. A function can store its result in a variable, so you can reuse the same value later: many functions accept a final setting that names a variable to save into. And a function can use variables inside its own settings, which is how functions are nested and combined.

Case matters

Names are case sensitive. A variable called UserName is not the same as username. Function names are also case sensitive, so the __Random function must be typed exactly that way. This is another reason to let the helper dialog write the text for you.

A tool makes more sense when you see the whole machine around it. Here is the cast of characters in a JMeter test and where functions appear.

The cast of characters

The flow in one picture

The diagram below shows how the helper dialog, your test plan, and the function engine connect. The dialog is only a design-time assistant. The real work happens later, when the test runs.

flowchart LR
A["Tester"] --> B["Function Helper Dialog"]
B --> C["Generated function text"]
C --> D["Field in a Sampler"]
D --> E["Test Runs"]
E --> F["Function Engine"]
F --> G["Fresh value in each request"]
G --> H["Web Server"]
    

Read the diagram from left to right. The tester uses the dialog before the test starts. The text then lives quietly inside a field. Only when the test runs does the function engine turn the text into real values, one for each request.

Design time versus run time

This split is the most important idea in the chapter. At design time, you are building the test with the helper dialog. At run time, virtual users are executing it and functions are being worked out. The dialog helps with the first, and the engine handles the second.

Where can functions be used?

Almost anywhere you can type text in a test element: a request path, a parameter value, a header, a request body, an assertion, a timer delay, a name, or the settings of other elements. This broad reach is what makes functions so powerful. One small function placed in one small field can change the whole behaviour of the test.

flowchart TD
TP["Test Plan"] --> TG["Thread Group"]
TG --> S1["HTTP Request - Sign Up"]
TG --> S2["HTTP Request - Search"]
S1 --> F1["Function in email field"]
S1 --> F2["Function in name field"]
S2 --> F3["Function in search word field"]
    

Every function call follows the same shape. Learn this shape once, and every function in JMeter becomes readable.

The shape

A function call is made of five small pieces, written in a fixed order:

Put together, a random number call looks like this in words: dollar, curly, two underscores, the word Random, round bracket, smallest number, comma, largest number, round bracket, curly bracket. In text, it is written ${__Random(1,100)}.

Parameters: required and optional

Each function documents its parameters in a fixed order. Some are required, and some may be left out. Many functions have an optional last parameter that names a variable. If you provide that name, the function stores its result in a variable of that name, so you can reuse the same value later without calling the function again.

Leaving a parameter empty

If you want to skip an optional parameter but still give a later one, you leave the earlier spot empty but keep the comma. The commas hold the positions, just as empty seats in a row still keep the other seats numbered correctly.

Commas inside values

The comma has a special job: it separates parameters. If a value you pass needs to contain a comma itself, such as a text with a comma in it, JMeter would wrongly split it into two parameters. To prevent this, you put a backslash in front of the comma. The backslash tells JMeter, “This comma is part of the value, not a separator.” The helper dialog also warns you about this, so it is a good habit to check any value containing commas.

Nesting functions

A function’s parameter can itself be another function or a variable. This is called nesting. For example, you can ask for a random number between one and the number of items found on a page, where that number is stored in a variable. JMeter works from the inside out: it first resolves the inner pieces, and then uses their values for the outer function.

Spaces

Be careful with spaces. A space inside a parameter is usually treated as part of the value. A stray space after a comma or before a bracket can change the meaning, or break the function. When you use the helper dialog, it avoids stray spaces automatically.

Let us walk through one complete use of the dialog, from opening it to seeing the value land in a real request.

The goal

Suppose you are testing a sign-up page. Each virtual user must enter a different email address, so the server does not reject duplicates. You want JMeter to create a random, unique looking email every time. Here is how the helper dialog gets you there.

Combining a function with fixed text

The email field can contain ordinary words and a function together. For example, you can type the word user, then paste the function text, then type @example.com. Each request then sends something like user, a long unique code, and the fixed domain. JMeter replaces only the function part and leaves the rest alone.

Why use a safe domain?

When you invent email addresses, use a domain reserved for examples, such as example.com, or a domain you own. Never invent addresses at a real company’s domain, since a test might accidentally send real emails to real people.

Testing a function on its own

You do not need a full test plan to experiment. Open the dialog, pick any function, fill the settings, and press the button repeatedly. This is a fast, safe playground for learning what each function returns. Many testers keep the dialog open while they build a plan and use it as a quick lookup for function names and their parameters.

Let us open the hood and watch JMeter turn a piece of function text into a real value, one small step at a time.

Step one: spotting the function

When the test starts, JMeter reads each field of each element and looks for the opening marker, a dollar sign followed by a curly bracket. Anything between the matching curly brackets is a possible variable or function reference. If the name starts with two underscores, JMeter treats it as a function call.

Step two: finding the function

JMeter keeps a catalogue of all functions that it knows about, both those that ship with it and any extra ones you add through plugins. It looks up the function by name in this catalogue. If the name is not found, the text is left unchanged, which is why a misspelled name shows up as raw characters in your requests.

Step three: reading the parameters

JMeter splits the settings at the commas, taking care of escaped commas and nested brackets. If any parameter contains another reference, JMeter works that one out first. This inside-out order is what makes nesting possible.

Step four: running the function

With the parameters ready, JMeter asks the function to produce its value. The function may use the current virtual user’s variables, the run’s properties, the clock, or a random number generator, depending on what it does.

Step five: replacing and sending

JMeter substitutes the value into the field, in place of the function text. The final text goes into the request that is sent to the server. If the function also had a variable name parameter, JMeter stores the value in that variable for later use.

sequenceDiagram
participant VU as Virtual User
participant S as Sampler
participant E as Function Engine
participant F as Function
participant V as Variable Store
participant W as Web Server
VU->>S: Prepare the request
S->>E: Field contains function text
E->>E: Find name and split parameters
E->>F: Ask for a value
F-->>E: Return the value
E->>V: Save value if a variable name was given
E-->>S: Replace text with the value
S->>W: Send the finished request
    

Once or every time?

A very important question is when the function is worked out. For most places, the answer is every time the request is prepared. If the sampler runs a thousand times, the function runs a thousand times, and each run gets a fresh value. That is the whole point of using functions.

There is one famous exception. Some elements are evaluated only once at the start of the test. The most common example is the User Defined Variables element. If you place a random function in such an element, JMeter works it out one time, stores the result, and then every user and every iteration shares that same value. Beginners are often surprised by this, so remember: if you want a new value on every request, place the function directly in the sampler field.

Multiple uses in one request

If you write the same function twice in one request, JMeter works each one out separately. A random function placed in two fields gives two different numbers. If you need the same value in two places, give the function a variable name parameter in the first place, and then use that variable name in the second place.

Every virtual user does it on its own

Each virtual user works out its own functions at its own pace. This is why a thousand users produce a thousand different values at nearly the same moment, without waiting for each other. Functions that need to share a count across users, such as a global counter, are built with care so that two users never receive the same number.

JMeter ships with many functions. Rather than memorising a long list, learn the families. Each family answers one kind of need.

A quick reference of well-known functions

These are the functions you will use most often. They fill your test with variety, so no two users look alike.

The random number function

The __Random function picks a whole number between a smallest and a largest value. Both limits are included. So a call with one and six behaves like rolling a normal die, and a call with one and one hundred behaves like picking a percentage. A third, optional parameter names a variable where the chosen number is also saved.

Typical uses are a random quantity of items, a random page number, a random pause length, or a random pick from a list when combined with the variable helpers shown in a later chapter.

The random string function

The __RandomString function creates random text. You give it the length you want and, optionally, the set of characters it may use. If you leave the set out, it uses a default mix of ordinary characters. A final optional parameter again names a variable for saving the result.

This function suits usernames, search words, product names, comments, and passwords for test accounts. If you give it only digits as the allowed characters, you get a random number as text with a fixed length, which suits phone numbers or reference codes.

The unique identifier function

The __UUID function produces a long random identifier that is, for practical purposes, unique. The chance of two matching values is so small that you can treat each value as one of a kind. It takes no settings at all, which makes it the easiest function to use.

It is an excellent choice for email names, order references, correlation identifiers, and any value that the server requires to be unique.

The counter function

The __counter function gives a number that increases by one each time it is used. Its first parameter decides whether each virtual user has its own counter or whether all users share a single counter. A true setting means each user counts on its own. A false setting means one global count shared by everyone. A second, optional parameter names a variable to save the result.

A common trap with counters

Every time the counter function is read, it counts up. If you write the same counter call in two fields of one request, the first field gets one number and the second field gets the next number. They will not match. If you need the same number in both places, store it in a variable with the optional name parameter and then use the variable twice.

Choosing between random and counter

Time travels in a straight line, and tests that use fixed dates break as the days go by. Time functions keep your test in step with the real clock.

The time function

The __time function reads the clock of the machine running the test. If you give it no settings, it returns the number of milliseconds that have passed since a fixed starting moment in 1970, a number computers love. If you give it a format, it returns a human readable date and time in the shape you describe. A second, optional parameter names a variable to save the result.

Format letters

A format is a small pattern of letters that tells the function how to write the date. Letters stand for parts: a group of four letters for the year, two for the month, two for the day, and similar letters for hours, minutes, and seconds. Because capital and small letters mean different things, the exact casing matters. The helper dialog shows the notes for the format, and it is worth testing a format in the dialog before using it.

The time shift function

The __timeShift function takes a date and moves it forward or backward by an amount. It lets you ask for “tomorrow,” “seven days ago,” or “next month.” You describe the amount in a standard duration notation that begins with the letter P. For example, a one-day amount starts with P, then the number one, then the letter D. You can also supply a locale for language specific names, and a variable name to store the result.

Where time functions shine

• Booking dates. A travel or hotel site refuses dates in the past, so a fixed recorded date fails as soon as it passes. A time shift that adds a few days to today always gives a valid future date.
• Report ranges. A report that asks for “the last seven days” needs a start date that moves along with the calendar.
• Timestamps for tracing. Adding the current time to a request name or header helps you match test requests to server logs.
• Unique names. A time stamp added to a record name helps keep it distinct between test runs.

Mind the clock of the load generator

Time functions read the clock of the machine on which the test runs. If that machine has the wrong time or a different time zone from the server under test, the dates you create might be rejected or may land on the wrong day. When running tests from several machines at once, check that their clocks agree.

Time zones and daylight changes

Dates near midnight and near seasonal clock changes are classic sources of bugs. A test that runs just after midnight on one machine might still be on the previous day on the server. Where it matters, choose dates a day or two away from the edge, so a small clock difference cannot flip the result.

Sometimes a test needs to know which virtual user is speaking, or which machine it is running on. These small functions answer such questions.

The thread number function

The __threadNum function returns the number of the current virtual user within its thread group, counting from one. If a group has a hundred users, they receive numbers one to one hundred. This number is stable for each user for the whole run.

It is useful for picking test accounts, for example by building a username from the word user plus the thread number. Each virtual user then uses its own account, with no clash and no need for a data file.

The machine functions

The __machineName function returns the name of the computer running the test. The __machineIP function returns its network address. When you run a distributed test with several load generators, these let you tag requests with their origin, so that if a problem appears you can see which generator sent it.

The names of plan elements

The __TestPlanName function returns the name of the test plan, and the __samplerName function returns the name of the sampler currently running. Adding these to a header or a request label gives logs that explain themselves. A server log line that carries the sampler name tells you at once which test step produced it.

Putting identity to work

Properties let you change a test without touching the test file. This is the secret of tests that run in many places, with many sizes, from one single plan.

What is a property again?

A property is a named setting that belongs to the whole run. It can come from a settings file that JMeter reads at startup, or from the command line, where you pass it with a short flag in front of the name. Every virtual user sees the same property value.

The __P function

The __P function reads a property. Its first parameter is the property name. Its second parameter is a default value that JMeter uses when the property was not supplied. If you leave out the default, JMeter falls back to a plain number one, which may surprise you, so it is wise to always give a default that makes sense.

The __property function

The __property function is similar but has a different parameter order. It takes the property name, an optional variable name to save the result in, and an optional default. It is handy when you want to copy a property into a variable for reuse across the plan.

The __setProperty function

The __setProperty function writes a property while the test is running. Because properties are shared by every user, a value set by one user becomes visible to all the others. This is a way to pass information between thread groups, for example when a setup group logs in once and shares a token with the main group. By default, this function returns an empty text, so using it inside a request field does not add anything to the request.

Why properties make tests flexible

Suppose your test plan reads the server name, the number of users, and the duration through property functions with sensible defaults. Now the same plan can run on a developer laptop with five users against a test server, or from a build pipeline with five hundred users against a staging server. You change only the command line, and the plan itself stays untouched.

flowchart LR
A["Command line settings"] --> C["JMeter Properties"]
B["Settings file"] --> C
C --> D["Function: read property with default"]
D --> E["Thread Group and Sampler fields"]
E --> F["Same plan, different runs"]
    

Properties in the thread group

Thread group fields, such as the number of users and the ramp-up time, accept functions. They are read once, at the start. This is the classic way to make a plan scale up or down from the command line without opening the graphical screen.

Cautions with shared properties

• Race conditions. If many users write the same property at nearly the same time, the final value depends on who wrote last. Use shared writes sparingly, and prefer to write once from a setup step.
• Types are text. A property is stored as text, even when it looks like a number. Functions and elements that need numbers will convert the text, but a typo such as a stray space can cause an error.
• Names can clash. JMeter has its own properties. Use a clear prefix for your own, such as the name of your project, to avoid overwriting one by accident.

Some of the most clever tricks in JMeter come from functions that work with other variables. They let your test make decisions about which variable to read.

The __V function

Normally you write a variable name directly, such as ${product}. But what if the name itself must be built from pieces, such as the word product, an underscore, and a number held in another variable? The __V function solves this. You give it a name expression, JMeter builds the name, and then it gives you the value of the variable with that name. If the variable does not exist, you will usually see the name text itself instead of a value, which is a handy clue when debugging.

Picking a random item from a captured list

This is the best known use. Suppose an earlier step captured a list of items into numbered variables, and a helper variable stores how many items were found. You ask the random function for a number between one and that count, and you feed the result to the variable helper to read the matching item. In a single field, the three ideas combine: count, random choice, and lookup. Each virtual user ends up with a different item.

The __split function

The __split function takes a text and breaks it into pieces at a separator character. It stores the pieces in numbered variables and also records how many pieces there were. It is useful when a response or a data file gives you several values joined together, such as a list of identifiers separated by commas. After splitting, each identifier has its own variable, ready for use.

The __eval and __evalVar functions

Sometimes a text contains function or variable references that must be worked out after the text has been loaded. The __eval function takes a text and resolves any references inside it. The __evalVar function does the same, but reads the text from a named variable. They are helpful when the reference text comes from a data file or a property, because JMeter would otherwise treat that text as plain words.

Checking whether a variable exists

Some versions provide helpers that test whether a variable or property is defined. They let you build conditions, for example to run an extra step only when an optional value was present. Check the dropdown in the dialog to see which of these your version offers.

Why this matters for realism

Real shoppers do not all click the first product. Using a random lookup spreads the load across the whole catalogue, which stresses different database rows and different cache entries. A test that always opens the first product tends to look better than reality because the same item is already in memory.

Servers are picky about the exact shape of text. These functions reshape, protect, and fingerprint text so it travels safely.

URL encoding and decoding

Web addresses can carry only a limited set of characters. Spaces, ampersands, equals signs, and many symbols must be rewritten into safe codes. The __urlencode function performs this rewriting, and the __urldecode function reverses it. Use encoding when you place a value that may contain symbols into a query part of an address.

Be careful not to encode twice. The HTTP request element has its own option to encode each parameter. If you switch it on and also call the function, the server sees the codes of the codes and cannot read the value.

HTML escaping

The __escapeHtml function turns symbols that have special meaning in web pages into safe codes, and the __unescapeHtml function reverses it. They are useful when a value taken from a page must be compared with text you typed, or sent back in a form of the same style.

Escaping for pattern searches

If you build a search pattern from a value, any symbols in that value could be read as pattern symbols. The __escapeOroRegexpChars function adds protective backslashes in front of such symbols. It is the right tool when you want the pattern engine to treat a value as plain text.

Changing case

The __changeCase function turns text into upper case, lower case, or a capitalised form. Some servers compare emails or codes in a case sensitive way, so having a way to force the case avoids mismatches.

Fingerprints of text

The __digest function builds a short fingerprint of a text using a chosen method, optionally with a salt, which is an extra secret text mixed in. Fingerprints are used by some systems to sign requests or verify that data was not changed. You give the method name, the text, and the optional extras, and you can ask for the result in upper case letters.

Special characters

The __char function turns a number into the character it stands for. This is the clean way to insert characters that are hard to type, such as a line break or a tab, into a request body.

Sometimes the data you need already lives in a file. A list of real looking names, a list of search words, or a long message body. File functions bring that data into your test.

The __StringFromFile function

This function reads one line from a text file each time it is called, and moves on to the next line on the next call. When it reaches the end, it starts again at the top. You give it the file path, and optionally a variable name and the first and last file numbers for a series of files. It is a quick way to hand out one line per request without any extra elements.

The __FileToString function

This function reads a whole file and returns its full text. It is helpful for large request bodies, such as a long message you do not want to paste into a field. You give the path, optionally the text encoding, and optionally a variable to store it in.

The older __CSVRead function

Older plans use a function that reads values from a table file, column by column. It still exists, but JMeter’s own guidance prefers a dedicated element for this job, called the CSV Data Set Config. The element is easier to read, handles sharing between users more clearly, and gives more control over what happens at the end of the file.

When to use a file and when not to

Paths and distributed tests

A file path that works on your laptop might not exist on a load generator in another place. When you run tests from several machines, each machine needs its own copy of the file at the same relative path. A relative path, counted from the folder of the test plan, is much more portable than a full path typed from your own disk.

Sharing between users

When many virtual users read from the same file, each call hands out the next line to whoever asks first. Different users may therefore get different lines in an unpredictable order. If every user must use a specific line, such as their own account, a different design based on the thread number is more reliable.

When no ready-made function does the job, JMeter lets you run a small expression in a scripting language. This is powerful, and it deserves respect.

What scripting functions do

A scripting function takes a short expression, runs it using a scripting language built into the Java platform, and returns the result. The most recommended one today is __groovy. Other choices include __jexl3 and the older __BeanShell. You write the expression in the parameter, and optionally a variable name to store the answer.

When it makes sense

• Calculations. For example, computing a total from several variables.
• Conditions. Choosing between two values based on a variable.
• Text surgery. Cutting, joining, or reshaping text in ways that simple functions cannot.

The price

Scripting functions cost more than the simple ones. Each use asks a scripting engine to read and run text. If the expression is long or runs thousands of times per second, the load generator may spend a surprising amount of effort on it. For heavy logic, JMeter’s guidance is to use a dedicated scripting element with caching turned on, which compiles the script once and reuses it. A short, simple expression in a function is fine, but long logic belongs in a proper script element.

Readability and safety

A script hidden inside a field is easy to overlook. A teammate who reads the plan may not notice that a request depends on a hidden calculation. Keep scripting functions short, add a comment to the element, and never run scripts from sources you do not trust, since a script can do almost anything on the load generator machine.

The older approach

The __BeanShell function was once the standard choice. It is slower and is no longer the recommended path. If you meet it in an older plan, consider moving to the newer scripting function when you next update the plan.

Single functions are useful. Combined functions are where tests start to feel like real traffic. Here are tried and trusted recipes, described in words.

Recipe 1: A unique, believable email

Start with a fixed word such as loadtest. Add the current user’s thread number so you can trace the account back to its user. Add the unique identifier function so repeated runs never clash. End with a safe example domain. The result is unique, traceable, and harmless.

Recipe 2: A valid future booking date

Take today’s date, shift it forward by a random number of days. The shift function accepts the amount as text, so you can build the duration from the letter P, a random number, and the letter D. Each booking lands on a different future date, and no booking ever falls in the past.

Recipe 3: A random product from a captured list

As described in Chapter 13, ask the random function for a number up to the stored count, and give it to the variable helper. Every user opens a different product.

Recipe 4: A request signature

Some systems require a fingerprint built from the request data and a shared secret. Combine the current time, the user’s identity, and the secret into one text, and pass that text to the digest function. Put the secret itself in a property, never in the plan.

Recipe 5: A search term from a file with a random suffix

Read one line from a word list with the file function, and add a random short string to it. You obtain search terms that mostly exist in the data, but never repeat exactly, which keeps caches honest.

Recipe 6: Think time that varies

Real people do not pause for exactly three seconds between clicks. Put a random function inside the delay field of a timer, with a range such as two to six seconds. Pauses now vary naturally, and the load pattern looks more like a crowd than a metronome.

Reading nested functions

When you meet a long nested call, read it from the inside out. Find the innermost brackets, decide what they produce, and replace them in your mind with that result. Then move outward one layer at a time. A long call becomes a short series of small steps.

flowchart TD
A["Outer function call"] --> B["Needs parameter one"]
A --> C["Needs parameter two"]
B --> D["Inner function: thread number"]
C --> E["Inner function: unique identifier"]
D --> F["Value resolved first"]
E --> G["Value resolved first"]
F --> H["Outer function runs with both values"]
G --> H
    

Keep recipes readable

A good rule is to avoid nesting more than three levels deep. If a recipe needs more, split it. Store the first result in a variable with the optional name parameter, then use the variable in the next function. Several small steps with clear names beat one dense call that nobody wants to touch.

Theory becomes useful when it meets practice. These scenarios appear again and again in real projects.

A reusable approach

Test data feels harmless, but functions touch secrets, files, and scripts. A little care keeps your tests safe.

Keep secrets out of the plan

A plan file is plain text. Anyone who opens it can read every value inside. Passwords, keys, and tokens should never be typed into a field directly. Use property functions to bring them in at run time from the command line or from a protected settings file.

Command lines can be seen too

On many systems, other users can see the list of running programs and their arguments. If you pass a secret on the command line, it may be visible to others on the same machine. For sensitive values, use a protected file that only the test user can read, and keep that file outside shared folders and outside version control.

Do not log secrets

Functions that write to the log, and listeners that save requests, can store the values you send. If a request contains a password or a key, it can end up in a result file or a log. Limit what you save, protect the results folder, and delete old results when you are done.

Respect scripting risks

A scripting function can read files, make network calls, and run other programs on the machine. Only use expressions written by you or a trusted teammate. Never paste a script from an unknown source into a function field. Treat a shared plan from outside your team as code that needs review before it runs.

Use synthetic data

Generate made-up names, emails, and numbers rather than copying real customers’ data. Use domains reserved for examples, or domains you control. This keeps real people out of your test traffic and protects you from privacy trouble and accidental emails to real addresses.

Test with permission

Heavy functions generate heavy traffic. Run load tests only against systems you own or have written permission to test. Pointing a large test at a live system without agreement can disrupt real users and may break rules or contracts.

Things will go wrong. The skill is not in avoiding every mistake but in finding the cause quickly. These are the tools to know.

The dialog itself

The Function Helper Dialog is your first debugging tool. Paste a suspicious function into it, or rebuild it from scratch, and watch what it returns. If the dialog gives a sensible answer but the test does not, the problem is probably the position of the function or the timing of its evaluation, not the function text itself.

View Results Tree

This listener shows each request exactly as it was sent, with every function already replaced by its value. If you see a dollar sign and curly brackets in the request, the function was not recognised. If you see the same value in many requests, the function was worked out once instead of each time. The tree is the clearest mirror of what really happened.

Debug Sampler

This sampler sends nothing to the server. It prints the current variables, properties, and system settings into its own result. Place one after a function that saves into a variable, and open its response to confirm that the variable holds the value you expected.

Log functions

JMeter provides functions that write a message to its log file while the test runs, such as __log and __logn. They pass their text through, so you can wrap a function with them and see its value in the log without changing the request. Use them for short checks, and remove them when finished, since heavy logging slows the run.

The log file

JMeter writes warnings and errors to a log file. Errors from badly formed functions, missing files, or failed scripts show up there. Reading the log is also the quickest way to learn about problems that never appear on screen.

A debugging checklist

Numbers worth watching during real runs

• Error rate. A rise in rejections for duplicate data suggests that a function is repeating values.
• Distribution of values. In the server’s logs, check that users really used different values.
• Load generator CPU. Heavy scripting functions can strain the test machine and distort results.
• Log size. Very chatty log functions can fill disks during long runs.

When thousands of virtual users run, even tiny costs add up. Understanding the cost of functions helps you build tests that scale.

Where does the cost come from?

Each function call takes a small amount of processing time on the load generator. A simple one, like a random number, is almost free. A file read touches the disk. A fingerprint calls a cryptographic routine. A script starts an engine to interpret text. Multiply by thousands of users and many requests, and the cost becomes visible.

Why the generator’s health matters

If the load generator is overloaded, it cannot send requests on time or measure responses accurately. Your report will show slow replies that are really caused by a tired test machine, not by the application. A good test keeps the generator comfortably below its limits.

Ways to keep functions cheap

• Prefer simple functions. Use random, counter, time, and thread number first. They are fast.
• Avoid scripting in hot paths. If a function runs on every request, a script in it runs thousands of times.
• Compute once, reuse many times. Save a result into a variable with the optional name, and reuse it instead of calling the function again.
• Avoid reading files on every request. For large data sets, use the dedicated data element, which reads efficiently and shares lines cleanly.
• Limit logging functions. Writing to the log on every request produces large files and slows the run.
• Run without the graphical screen. For real load, use the command line mode and save only the result fields you need.

Scaling out

When one machine cannot generate enough load, JMeter supports distributed testing where a controller drives several generators. Each generator evaluates functions on its own. Thread numbers repeat on each generator, so a plan that builds account names from the thread number will see duplicates across machines unless you also include the machine name or an offset passed through a property. Plan for this early.

Global counters across machines

A global counter is global only within one generator. Two generators each start their own count and will both produce the number one, then the number two. If you need numbers that are unique across the whole fleet, combine the counter with the machine name, or give each generator a different starting offset through a property.

A good craftsperson owns more than one tool. Functions are quick and flexible, but sometimes a dedicated element is cleaner, faster, or easier to read.

How to choose

flowchart TD
A["Need a changing value"] --> B{"Where does the value come from?"}
B -->|"The server gave it in a response"| C["Use an Extractor"]
B -->|"A fixed list of real data"| D["Use CSV Data Set Config"]
B -->|"Simple random, unique, or time value"| E["Use a Function"]
B -->|"A setting for the whole run"| F["Use a Property function"]
B -->|"Complex logic"| G["Use a JSR223 element"]
    

No tool is perfect. Knowing the trade-offs helps you choose with confidence.

The main trade-off: speed of writing versus clarity

A function is the quickest way to add varied data, because you write a single piece of text in a single field. But the same quickness hides the logic. A reader who opens the plan must click through fields to discover where data comes from. Dedicated elements take more clicks to create but show their settings openly. For small plans, functions win. For large, long-lived plans, a mixture works best, with visible elements for the important data and functions for the small details.

Flexibility versus safety

Functions can do many things, from reading files to running scripts. This power is welcome, but it needs discipline. A plan full of clever hidden calculations is hard to review and hard to trust. Keep the clever parts few and well commented.

Simplicity versus realism

A single random number is simple but may repeat. A thoughtful recipe with a counter, a thread number, and a time stamp is more work but never repeats. Choose the level of effort that matches how much uniqueness the application demands.

A short, practical collection of habits that separate calm, reliable tests from frustrating ones.

Best practices

Common mistakes

Small details that cause big surprises

Quotes are just characters. In JMeter functions, quote marks are not special. If you wrap a value in quotes, the quotes become part of the value. This is a frequent surprise for people who come from programming languages, where quotes mark the start and end of text.

Spaces are real. A space after a comma becomes part of the next parameter. A function that expects a number may then see a space and a number, and fail to read it. Write parameters tightly, with no extra spaces, unless a space is truly part of the value.

Empty parameters need their commas. To skip an optional parameter and give a later one, leave the first spot empty but keep its comma. Dropping the comma shifts every later parameter one place to the left, and the function will read the wrong values.

Case matters inside parameters too. Format letters for dates, the names of hashing methods, and the words true and false may each be sensitive to capital and small letters. When a function gives a surprising answer, try the exact spelling shown in the dialog’s help text.

Language and region. Dates and numbers can be written in different ways across languages. A test machine set to one region may produce month names or number marks that a server in another region does not accept. When it matters, set the region on purpose in the function, or choose number-only formats that mean the same everywhere.

Escaping the dollar sign. If you truly need the characters dollar and curly bracket to appear as plain text in a request, for example in a message body that shows sample text, JMeter may still try to read them as a reference. Check the sent request carefully in such cases, and build the text in a way that avoids accidental references.

Design patterns that work

• Generate, save, reuse. Create a value once, store it in a variable, and use the variable wherever the value is needed again.
• Default and override. Read settings with defaults, and override them from the command line when you need a different run.
• Unique plus random. Pair a guaranteed unique part with a random part for data that is unique and natural looking.
• Trace headers. Add identity details to a header on every request, so later investigation takes minutes.

A test plan is read, changed, and run by many people. A few shared habits make functions a team asset rather than a mystery.

Naming and comments

Give elements clear names that tell the story of the journey. Use the comments field to note where a function lives and why it was chosen. A single sentence, such as “Unique email from thread number and identifier,” saves the next person an hour of detective work.

Version control

Store plans in a version control system, just as you do with application code. Since a plan is text, changes can be compared and reviewed. Before saving, remove secrets, and keep run-specific details such as server names in properties.

Command line and pipelines

Run real load from the command line, which saves memory and processing power compared with the graphical screen. Pass properties on the command line to pick the server, the number of users, and the duration. Pipelines can then start the same plan on every build, with small settings for quick checks and larger ones for scheduled runs.

Review checklist

A small cheat sheet

Quick answers to the questions beginners ask most often.

You began with a post office and one thousand birthday cards, and finished with a clear understanding of how JMeter makes test data. Here is what to carry with you.