20. Functions and Variables¶

The Regex Function is used to parse the previous response (or the value of a variable) using any regular expression (provided by user). The function returns the template string with variable values filled in.

The __regexFunction can also store values for future use. In the sixth parameter, you can specify a reference name. After this function executes, the same values can be retrieved at later times using the syntax for user-defined values. For instance, if you enter "refName" as the sixth parameter you will be able to use:

• ${refName} to refer to the computed result of the second parameter ("Template for the replacement string") parsed by this function
• ${refName_g0} to refer to the entire match parsed by this function.
• ${refName_g1} to refer to the first group parsed by this function.
• ${refName_g#} to refer to the n^th group parsed by this function.
• ${refName_matchNr} to refer to the number of groups found by this function.

The counter generates a new number each time it is called, starting with 1 and incrementing by +1 each time. The counter can be configured to keep each simulated user's values separate, or to use the same counter for all users. If each user's values is incremented separately, that is like counting the number of iterations through the test plan. A global counter is like counting how many times that request was run.

The counter uses an integer variable to hold the count, which therefore has a maximum of 2,147,483,647.

The counter function instances are completely independent. The global counter - "FALSE" - is separately maintained by each counter instance.

Multiple __counter function calls in the same iteration won't increment the value further.
If you want to have a count that increments for each sample, use the function in a Pre-Processor such as User Parameters.

The thread number function simply returns the number of the thread currently being executed. These numbers are only locally unique with respect to their ThreadGroup, meaning thread #1 in one threadgroup is indistinguishable from thread #1 in another threadgroup, from the point of view of this function.

ctx.getThreadNum()

There are no arguments for this function.

Usage Example:

${__threadNum}

The thread group name function simply returns the name of the thread group being executed.

There are no arguments for this function.

Usage Example:

${__threadGroupName}

The intSum function can be used to compute the sum of two or more integer values.

The longSum function can be used to compute the sum of two or more long values, use this instead of __intSum whenever you know your values will not be in the interval -2147483648 to 2147483647.

The StringFromFile function can be used to read strings from a text file. This is useful for running tests that require lots of variable data. For example when testing a banking application, 100s or 1000s of different account numbers might be required.

See also the CSV Data Set Config test element which may be easier to use. However, that does not currently support multiple input files.

Each time it is called it reads the next line from the file. All threads share the same instance, so different threads will get different lines. When the end of the file is reached, it will start reading again from the beginning, unless the maximum loop count has been reached. If there are multiple references to the function in a test script, each will open the file independently, even if the file names are the same. [If the value is to be used again elsewhere, use different variable names for each function call.]

If an error occurs opening or reading the file, then the function returns the string "**ERR**"

The machineName function returns the local host name. This uses the Java method InetAddress.getLocalHost() and passes it to getHostName()

The machineIP function returns the local IP address. This uses the Java method InetAddress.getLocalHost() and passes it to getHostAddress()

The javaScript function executes a piece of JavaScript (not Java!) code and returns its value

The JMeter Javascript function calls a standalone JavaScript interpreter. Javascript is used as a scripting language, so you can do calculations etc.

The following variables are made available to the script:

• log - the Logger for the function
• ctx - JMeterContext object
• vars - JMeterVariables object
• threadName - String containing the current thread name
• sampler - current Sampler object (if any)
• sampleResult - previous SampleResult object (if any)
• props - JMeterProperties (class java.util.Properties) object

Rhinoscript allows access to static methods via its Packages object. See the Scripting Java documentation. For example one can access the JMeterContextService static methods thus: Java.type("org.apache.jmeter.threads.JMeterContextService").getTotalThreads()

The random function returns a random number that lies between the given min and max values.

The RandomDate function returns a random date that lies between the given start date and end date values.

The RandomString function returns a random String of length using characters in chars to use.

The RandomFromMultipleVars function returns a random value based on the variable values provided by Source Variables.

• Boundary Extractor
• Regular Expression Extractor
• CSS Selector Extractor
• JSON Extractor
• XPath Extractor
• XPath2 Extractor

The UUID function returns a pseudo random type 4 Universally Unique IDentifier (UUID).

The CSVRead function returns a string from a CSV file (c.f. StringFromFile)

NOTE: JMeter supports multiple file names.

In most cases, the newer CSV Data Set Config element is easier to use.

When a filename is first encountered, the file is opened and read into an internal array. If a blank line is detected, this is treated as end of file - this allows trailing comments to be used.

All subsequent references to the same file name use the same internal array. N.B. the filename case is significant to the function, even if the OS doesn't care, so CSVRead(abc.txt,0) and CSVRead(aBc.txt,0) would refer to different internal arrays.

The *ALIAS feature allows the same file to be opened more than once, and also allows for shorter file names.

Each thread has its own internal pointer to its current row in the file array. When a thread first refers to the file it will be allocated the next free row in the array, so each thread will access a different row from all other threads. [Unless there are more threads than there are rows in the array.]

The property function returns the value of a JMeter property. If the property value cannot be found, and no default has been supplied, it returns the property name. When supplying a default value, there is no need to provide a function name - the parameter can be set to null, and it will be ignored.

• ${__property(user.dir)} - return value of user.dir
• ${__property(user.dir,UDIR)} - return value of user.dir and save in UDIR
• ${__property(abcd,ABCD,atod)} - return value of property abcd (or "atod" if not defined) and save in ABCD
• ${__property(abcd,,atod)} - return value of property abcd (or "atod" if not defined) but don't save it

This is a simplified property function which is intended for use with properties defined on the command line. Unlike the __property function, there is no option to save the value in a variable, and if no default value is supplied, it is assumed to be 1. The value of 1 was chosen because it is valid for common test variables such as loops, thread count, ramp up etc.

Define the property value:

jmeter -Jgroup1.threads=7 -Jhostname1=www.realhost.edu

The log function logs a message, and returns its input string

The logn function logs a message, and returns the empty string

The BeanShell function evaluates the script passed to it, and returns the result.

For full details on using BeanShell, please see the BeanShell web-site at http://www.beanshell.org/

A single instance of a function may be called from multiple threads. However the function execute() method is synchronised.

If the property "beanshell.function.init" is defined, it is passed to the Interpreter as the name of a sourced file. This can be used to define common methods and variables. There is a sample init file in the bin directory: BeanShellFunction.bshrc.

The following variables are set before the script is executed:

• log - the Logger for the BeanShell function (*)
• ctx - JMeterContext object
• vars - JMeterVariables object
• props - JMeterProperties (class java.util.Properties) object
• threadName - the threadName (String)
• Sampler - the current Sampler, if any
• SampleResult - the current SampleResult, if any

The __groovy function evaluates Apache Groovy scripts passed to it, and returns the result.

If the property "groovy.utilities" is defined, it will be loaded by the ScriptEngine. This can be used to define common methods and variables. There is a sample init file in the bin directory: utility.groovy.

The following variables are set before the script is executed:

• log - the Logger for the groovy function (*)
• ctx - JMeterContext object
• vars - JMeterVariables object
• props - JMeterProperties (class java.util.Properties) object
• threadName - the threadName (String)
• sampler - the current Sampler, if any
• prev - the previous SampleResult, if any
• OUT - System.out

(*) means that this is set before the init file, if any, is processed. Other variables vary from invocation to invocation.

For instance don't do the following:

${__groovy("${myVar}".substring(0\,2))}

Imagine that the variable myVar changes with each transaction, the Groovy above cannot be cached as the script changes each time.

Instead do the following, which can be cached:

${__groovy(vars.get("myVar").substring(0\,2))}

The split function splits the string passed to it according to the delimiter, and returns the original string. If any delimiters are adjacent, "?" is returned as the value. The split strings are returned in the variables ${VAR_1}, ${VAR_2} etc. The count of variables is returned in ${VAR_n}. A trailing delimiter is treated as a missing variable, and "?" is returned. Also, to allow it to work better with the ForEach controller, __split now deletes the first unused variable in case it was set by a previous split.

${__split(${VAR},VAR,|)}

The XPath function reads an XML file and matches the XPath. Each time the function is called, the next match will be returned. At end of file, it will wrap around to the start. If no nodes matched, then the function will return the empty string, and a warning message will be written to the JMeter log file.

${__XPath(/path/to/build.xml, //target/@name)}

The setProperty function sets the value of a JMeter property. The default return value from the function is the empty string, so the function call can be used anywhere functions are valid.

The original value can be returned by setting the optional 3^rd parameter to "true".

Properties are global to JMeter, so can be used to communicate between threads and thread groups

The time function returns the current time in various formats.

The jexl function returns the result of evaluating a Commons JEXL expression. See links below for more information on JEXL expressions.

The __jexl2 function uses Commons JEXL 2

• JEXL syntax description
• JEXL examples

The jexl function returns the result of evaluating a Commons JEXL expression. See links below for more information on JEXL expressions.

The __jexl3 function uses Commons JEXL 3

• JEXL syntax description
• JEXL examples

The V (variable) function returns the result of evaluating a variable name expression. This can be used to evaluate nested variable references (which are not currently supported).

For example, if one has variables A1,A2 and N=1:

• ${A1} - works OK
• ${A${N}} - does not work (nested variable reference)
• ${__V(A${N})} - works OK. A${N} becomes A1, and the __V function returns the value of A1

The evalVar function returns the result of evaluating an expression stored in a variable.

This allows one to read a string from a file, and process any variable references in it. For example, if the variable "query" contains "select ${column} from ${table}" and "column" and "table" contain "name" and "customers", then ${__evalVar(query)} will evaluate as "select name from customers".

The eval function returns the result of evaluating a string expression.

This allows one to interpolate variable and function references in a string which is stored in a variable. For example, given the following variables:

• name=Smith
• column=age
• table=birthdays
• SQL=select ${column} from ${table} where name='${name}'

This can be used in conjunction with CSV Dataset, for example where the both SQL statements and the values are defined in the data file.

The char function returns the result of evaluating a list of numbers as Unicode characters. See also __unescape(), below.

This allows one to add arbitrary character values into fields.

The unescape function returns the result of evaluating a Java-escaped string. See also __char() above.

This allows one to add characters to fields which are otherwise tricky (or impossible) to define via the GUI.

Function to unescape a string containing HTML entity escapes to a string containing the actual Unicode characters corresponding to the escapes. Supports HTML 4.0 entities.

For example, the string

${__unescapeHtml(<Français>)}

If an entity is unrecognized, it is left alone, and inserted verbatim into the result string. e.g. ${__unescapeHtml(>&zzzz;x)} will return >&zzzz;x.

Uses StringEscapeUtils#unescapeHtml(String) from Commons Lang.

Function which escapes the characters in a String using HTML entities. Supports HTML 4.0 entities.

For example,

${__escapeHtml("bread" & "butter")}

Uses StringEscapeUtils#escapeHtml(String) from Commons Lang.

Function to decode a application/x-www-form-urlencoded string. Note: use UTF-8 as the encoding scheme.

For example, the string

${__urldecode(Word+%22school%22+is+%22%C3%A9cole%22+in+french)}

Uses Java class URLDecoder.

Function to encode a string to a application/x-www-form-urlencoded string.

For example, the string

${__urlencode(Word "school" is "école" in french)}

Uses Java class URLEncoder.

The FileToString function can be used to read an entire file. Each time it is called it reads the entire file.

If an error occurs opening or reading the file, then the function returns the string "**ERR**"

The samplerName function returns the name (i.e. label) of the current sampler.

The function does not work in Test elements that don't have an associated sampler. For example the Test Plan. Configuration elements also don't have an associated sampler. However some Configuration elements are referenced directly by samplers, such as the HTTP Header Manager and Http Cookie Manager, and in this case the functions are resolved in the context of the Http Sampler. Pre-Processors, Post-Processors and Assertions always have an associated Sampler.

Example:

${__samplerName()}

The TestPlanName function returns the name of the current test plan (can be used in Including Plans to know the name of the calling test plan).

Function which escapes the ORO Regexp meta characters, it is the equivalent of \Q \E in Java Regexp Engine.

For example,

${__escapeOroRegexpChars([^"].+?,)}

Uses Perl5Compiler#quotemeta(String) from ORO.

Function which escapes the characters in a String using XML 1.0 entities.

For example,

${__escapeXml("bread" & 'butter')}

Uses StringEscapeUtils#escapeXml10(String) from Commons Lang.

The timeShift function returns a date in the given format with the specified amount of seconds, minutes, hours, days or months added

The digest function returns an encrypted value in the specific hash algorithm with the optional salt, upper case and variable name.

The __dateTimeConvert function converts a date that is in source format to a target format storing the result optionally in the variable name.

The __isPropDefined function returns true if property exists or false if not.

The __isVarDefined function returns true if variable exists or false if not.

The change case function returns a string value which case has been changed following a specific mode. Result can optionally be saved in a JMeter variable.

The __StringToFile function can be used to write a string to a file. Each time it is called it writes a string to file appending or overwriting.

The default return value from the function is the empty string