JMeter Tutorial: How to Use JMeter Functions

One often-overlooked feature of JMeter is its built-in library of functions. You can simplify your JMeter test plan by using functions to get parameters like the timestamp or thread name, perform complex calculations, add BeanShell or Javascript code, or read from data files without having to code from scratch.

A long time ago when I first started to use JMeter, I thought that I had to code most of the functions that I needed for developing my scripts. I used to find myself using BeanShell scripting for almost every challenge I faced because the JMeter functions were fairly rudimentary and only applicable to simple tasks. However, release by release, these functions grew in number and capacity, becoming more comprehensive solutions for a wide variety of test requirements.

Nowadays, I can’t create a JMeter script without at least one JMeter function. They are so popular that most of the screening JMeter assessment questions involve them. In this blog post,  I will describe some of the most common usages and how to take advantage of them.

What is a JMeter function?

A JMeter function is an evaluation that returns a value. Functions can span a wide variety of types including information functions, scripting functions, and property functions to name a few.

Where can I use JMeter functions?

We can use JMeter Functions under any component of the test plan that follows the execution order. In other words, the JMeter execution order needs to pass through that component to execute the function.

Firstly, we can group the functions by the type of function or functionality. That will give us a better idea of where to use them. I’ll also provide you some JMeter scripts that will show you how to handle those functions to complement your learning.

We can classify the JMeter functions into 7 groups:

  1. Information             Returns test environment information
  2. File Input                  Manipulation of input files
  3. Calculation               Generation of random data or numeric manipulation
  4. Scripting                   Use of JMeter supported languages to code
  5. Properties                Global variables manipulation
  6. Variables                  Local variables manipulation
  7. Strings                      Formatting or conversion of strings

Here are all the JMeter functions on the official Apache JMeter site:

1. Information functions

Information functions become really helpful to identify the thread’s data, the load generator’s IP address or name, and the local time in multiple formats. I would say that these functions are most handy when we are debugging a script. For example, the log function enables you to output breaking point messages in the different log levels.

The data value returned from most of those functions is directly obtained from the JMeter Context Service, which is an API service that holds the information of the test and thread groups. If you want to retrieve particular information from a particular thread, each one holds its own JMeter Context where they store its local data.

Here is a sample JMeter script using the information functions, and it should yield this response data for each:

JMeter Scripts require Java 1.8+, JMeter 5+ and JMeter plugins.

2. File Input functions

When dealing with large amounts of data, it is always recommended to use static data files as input for your scripts. Those values can be passed to JMeter by using the standard CSV input format row by row or storing the complete file in a variable. I’m not a big fan of using external files for supporting my scripts. I prefer to generate my own data sequentially and use a random variable to access it.

Nevertheless, sometimes we can’t take the previous option and importing external data is our only choice. For instance, I wouldn’t recommend that you to save entire files to variables because it will consume a considerable amount of memory. Instead, try accessing them row by row with StringFromFile or CSVRead functions.

3. Calculation functions

Math calculations or random numeric variables are often necessary when designing scripts. For example, let's think about the number of passengers or tickets to buy for an event. This requirement could be easily resolved with a random value between 1 to 10 using the random function. However, this function has its own limitations, such as not being able to generate larger numbers like a 16-digit credit card. Instead, the random string function becomes a lot more useful because it’s more efficient in the way it generates large strings or numbers.

If you are dealing with a particular date or eventually need to pick it among a range, the function random date is the best solution. I personally use that function along with timeShift to pick a date between today and in a range of 60 days ahead, like this:

      ${__RandomDate(MM/dd/YYYY,,${__timeShift(MM/dd/YYYY,,P60D,,)},,)}

Additionally, the counter function is a must if you are doing anything with sequential counting. This variable could be increased by global iteration or by local iteration for each thread.

Here’s a sample JMeter script example using the calculation functions. Below is
the response data from the script.

JMeter Scripts require Java 1.8+, JMeter 5+ and JMeter plugins.

4. Scripting functions

This is probably the most controversial set of JMeter functions because many deem them to be too open and might lead to an infinite set of possibilities. We can’t dig that deep, because the number of ways to use them is countless, but I’d like to show some beneficial use-cases of these functions paired with IF and WHILE controllers.

The scripting language options are Beanshell, Groovy, JavaScript or JEXL. We can select our weapon of choice in order to deal with complex or simple logic. However, as a scripting function, we may probably only use a couple of lines maximum. Why? Because if you want to use any more than that, it’s best to use a pre or post-processor.

Beanshell

Beanshell is a Java interpreter created 20 years ago and the last known update was released in 2003. Obviously, it is obsolete but still functional. I learned JMeter paired with Beanshell from 2012 until 2017 when the Groovy probe was much faster than Beanshell, especially if the compilation code was cached. For over 6 years, I used Beanshell scripting to deal with almost every script’s logic difficulty, using it mostly as a pre- or post-processor and sometimes as a sampler.

Groovy

As strange as it sounds, Groovy was released in the same year that Beanshell was released, in 2003. Since then Groovy has become the most popular JMeter scripting language. Some of its most important advantages are:

  • It’s an object-oriented language
  • It compiles to bytecode directly, as quickly as Java code
  • It caches the compiled code
  • It is constantly maintained and updated

Today, there is no room for comparison between Groovy and Beanshell because Beanshell hasn’t been updated for 16 years. However, as a result, the only scenario where I would recommend using Beanshell would be on legacy JMeter scripts that can’t be migrated to newer JMeter versions. Groovy is also faster and there is no need to migrate because Groovy recognizes Beanshell syntax.

JavaScript

JavaScript or ECMAScript is another interpreted language that can be used in JMeter. Basically, the IF and WHILE controllers judge the boolean evaluation that will let the thread continue or exit the loop. Even though it’s a great language, the JSR223 sampler only supports caching for Groovy which makes JavaScript less efficient. In my opinion, it is best used for small evaluations but not for complex tasks.

JEXL

JEXL stands for Java Expression Language. It’s the most limited scripting language but that is exactly what makes it so popular: its simplicity. Small and fast code that evaluates an expression in a boolean is probably is the most common usage for Jexl in JMeter, though it can also be used in sampler payloads or HTTP parameters.

All the scripting languages have access to certain JMeter resources. The following table describes the Resource/Language relation:

Popular uses:

If you are dealing with IF or WHILE controllers, those controllers require an expression statement based on boolean value to decide either continue or dismiss, therefore the best language options for that boolean task are JavaScript and JEXL, some common expression would be:

Here is a sample JMeter script example using the scripting functions. Below is
the response data from the script.

JMeter Scripts require Java 1.8+, JMeter 5+ and JMeter plugins.

5. Properties functions

Properties are like variables but in a global environment. It means all the threads are able to access or update them, most of those JMeter property values are set from the .properties files located in the bin folder. Please note that if you update some values, you will need to restart JMeter to take effect.

I wouldn't recommend modifying any parameter unless you know exactly what you are doing, because it might affect the expected JMeter behavior and by consequence your results. Despite this potential danger, the advantage of using parameters is pretty extensive, and one of the most common usages is setting up the number of threads, ramp up or test duration of the JMeter scripts. This is actually how Flood.io overrides those parameters in your script.

You might take advantage of those parameters locally using the JMeter CLI.

jmeter.sh -n -t TestPlan.jmx -Jthreads=100 -Jrampup=100 -Jduration=600 -l TestPlan.jtl

Another great example is to set objects globally, not just strings. We are able to set arrays, matrices, queues, lists and any kind of data structure that you might need to support your script tasks. I posted a long time ago a Grafana article on LinkedIn, where I was using an array to collect multiple InfluxDB rows to be pushed in just a single HTTP request.

Here’s a sample JMeter script example using the property functions. Below is
the response data from the script.

JMeter Scripts require Java 1.8+, JMeter 5+ and JMeter plugins.

6. Variables functions

The variables in JMeter are local variables, it means that they are created and destroyed on each thread iteration. Most of the data that we use under a thread execution (like correlations) are stored in variables that will be gone once the thread ends and a new iteration is started. If there is any value that you need to save, it might be saved as property, even though the property values will be gone when the test is stopped, unless you save it into a file.

Here’s a sample JMeter script example using the functions of the variables. Below is
the response data from the script.

JMeter Scripts require Java 1.8+, JMeter 5+ and JMeter plugins.

7. Strings functions

At some point in your scripting, you might need to transform or convert strings. The most common usage is to either URL encode/decode or  HTML escape/unescape.Both functions are really handy when dealing with Web pages and posting parameters. Even though the String functions are meant for conversion, we have two functions that are probably not related at all. One of which is the regexFunction which is a regular expression extractor identical to the post-processor, and the dateTimeConvert which transforms different time formats to match the desired one.

Here’s a sample JMeter script example using the strings functions. Below is
the response data from the script.

JMeter Scripts require Java 1.8+, JMeter 5+ and JMeter plugins.

Putting it all together

If you have heard about these JMeter functions but haven’t had a chance to learn them. I would strongly recommend taking a close look at them.  These functions will definitely increase your JMeter ability and aid in tackling even the most complex of load testing use cases. These functions would enable you to generate more accurate scripts and by consequence better results. We would encourage you to sign up for a free trial which will include 5 free node hours to use for executing your JMeter scripts in the cloud.

Start load testing now

It only takes 30 seconds to create an account, and get access to our free-tier to begin load testing without any risk.

Keep reading: related stories
Return to the Flood Blog