JMeter Native Functions (Part 1)
Table of Contents
Intermediate - This article is part of a series.
I decided to leave the literary translation in this case because I think the original idea remains intact. On the contrary, in some places, I’ve added more information that I’ve gathered since this article was published almost a year ago. Here you can see the original version of the post in English
A while back, when I was starting out with JMeter, I thought I should write my own code for all the functions I’d need to develop in my scripts. I found myself developing Beanshell functions for every challenge I faced, because JMeter’s functions weren’t as popular or “good” for basic tasks. But version after version, these functions grew in number and capability, becoming understandable solutions for a wide variety of testing requirements.
These days, I can’t create a JMeter script without using at least a couple of native functions. They’re so popular that they’re also used for job or technical interview questions. Throughout this post I hope to be able to describe some of its most common uses and how to take advantage of it.
What is a JMeter function? #
A JMeter function is an evaluation that returns a value or result. These functions can cover a variety of needs, such as test information, logic, variables, and/or properties, to name a few.
Where can I use JMeter functions? #
JMeter functions can be used in any component of the test plan, which follows the execution order. In other words, the JMeter execution order must go through that component to execute the function.
First, we must group the functions by type of function or functionality. This will give us a better idea of where to use them. I will also provide some examples that will reveal how to use them and complement your learning.
Here are the JMeter functions we will cover in this post:
1.- Information Functions #
Information functions are particularly useful for identifying data about the running thread or group of threads, the IP address of the load generator or its server name, or obtaining the local time in multiple formats. I would say these functions are the law when debugging a script. For example, the log function allows us to send data of any level of detail to the jmeter.log log via a message.
The data returned by most functions is obtained directly from the JMeter context service, which is like an API service containing all the test and thread information. If you want a particular value from a thread or group of threads you can access its information, each of them contains its own context where all its data is stored.
Examples of information functions:
| Function | Example | Expected result |
|---|---|---|
| threadNum | ${__threadNum} | A numeric value for the running thread ID |
| threadGroupName | ${__threadGroupName} | String for the running thread group name |
| samplerName | ${__samplerName} | Name of the running sampler |
| machineIP | ${__machineIP} | IP address of the load generator or computer |
| machineName | ${__machineName} | Name of the load generator or computer |
| time | ${__time} | Displays the local time of the load generator or computer in EPOCH format |
| time | ${__time(dd-MM-YYYY,)} | Displays the local time of the equipment or load generator in dd-MM-YYYY format |
| timeShift | ${__timeShift(dd-MM-YYYY,,P4D,,)} | Based on the local time of the equipment, 4 days are added, in dd-MM-YYYY format |
| timeShift | ${__timeShift(dd-MM-YYYY,,P-6D,,)} | Based on the local time of the equipment, 6 days are subtracted, in dd-MM-YYYY format |
| log | ${__log(Hello World)} | Displays “Hello World” at the INFO level by definition |
| logn | ${__logn(${TESTSTART.MS},ERR)} | Displays the start of the test, at the ERR level |
We also include images of the examples and you can download the file below:
The JMeter script with information function examples requires Java 1.8+, JMeter 5+, and JMeter plugins.
2.- Input File Functions #
When handling large volumes of data, it is always advisable to use static data files. These values can be delivered to JMeter via comma-separated (CSV) files; each line will be read and segmented to save the values in variables. I am not a fan of using CSV or similar files for scripts; I personally prefer to generate my own data randomly.
However, there are times when we have no other option or are limited to using external inputs. However, we should not overuse these solutions because if the input is large, it could take up a lot of our resources, particularly RAM. In contrast, you can access them line by line with the CSVRead functions or the entire file with StringFromFile.
Examples of input file functions:
| Function | Example | Expected result |
|---|---|---|
| StringFromFile | ${__StringFromFile(file.txt,RowAsString,,)} | Reads the file file.txt and saves the first row in the variable RowAsString, incremented by iteration |
| FileToString | ${__FileToString(filex.txt,FileAsString,,)} | Reads the file file.txt and saves its entire contents in the variable FileAsString |
| CSVRead | ${__CSVRead(file.csv,0)} | Returns column 0 of the first row of the file file.csv, incremented by iteration |
| XPath | ${__XPath(file.xml,..//[@id=book]/div/a)} | Returns the value of the Xpath evaluation in the file file.xml |
| StringToFile | ${__StringToFile(file.out,“Hello World”)} | Writes “Hello World” to the file file.out, variables can also be written |
3.- Calculation Functions #
Mathematical calculations or random values are often necessary for our business logic. For example, let’s think about the number of plane or concert tickets we’re going to buy. This requirement could easily be solved by generating a random value between 1 and 10. However, this function has its limitations; I would by no means recommend it for generating a 16-digit credit card number. There are other functions that would do this much more easily and efficiently, such as RandomString.
If you’re dealing with dates, or eventually need to calculate a date in the future, but within a time range, the RandomDate function is the ideal solution. I personally use this function in conjunction with the timeShift function to calculate a date within the range of 10 to 60 days in the future, and it would look something like this.
${__RandomDate(MM/dd/YYYY,${__timeShift(MM/dd/YYYY,,P10D,,)},${__timeShift(MM/dd/YYYY,,P60D,,)},,)}
Additionally, if you need to keep track of a specific number of iterations or requests for a service or product, the counter function could be used within the request involved to keep a sequential count of occurrences or invocations. This variable could grow per thread or group of threads, depending on our needs.
Examples of calculation functions:
| Function | Example | Expected result |
|---|---|---|
| counter | ${__counter(TRUE,C1)} | Execution counter per thread |
| counter | ${__counter(FALSE,C2)} | Execution counter per thread group, optional by definition |
| digest | ${__digest(MD5,Test1234,,,)} | Encryption of the text “Test1234” using MD5 |
| digest | ${__digest(SHA-256,Test1234,mysalt,,)} | Encryption of the text “Test1234” using SHA-256 with a salt |
| intSum | ${__intSum(10,20,IntSum)} | Displays the sum of two integers, also saves the result in the variable IntSum |
| longSum | ${__longSum(65535,65535,LongSum)} | Displays the sum of two integers, also saves the result in the variable LongSum |
| RandomDate | ${__RandomDate(,,2021-01-01,,)} | Randomly generates a date between today and 2021-01-01 |
| RandomFromMultipleVars | ${__RandomFromMultipleVars(Var1|Var2,)} | Choose a random variable and display its result |
| RandomString | ${__RandomString(16,1234567890,)} | Generates a 16-character string, with a random value chosen from the input at each position |
| RandomString | ${__RandomString(16,abcdefghijkl,)} | Generates a 16-character string, with a random value chosen from the input at each position |
| UUID | ${__UUID()} | Generates a random 16-byte or 128-bit UUID |
We also include images of the examples, and you can download the file below:
The JMeter script with calculation function examples requires Java 1.8+, JMeter 5+, and JMeter plugins.