jMeter - Functions


JMeter Functions and User Variables

  • JMeter functions are special values that can populate fields of any Sampler or other element in a test tree. A function call looks like this:

  • _functionName matches the name of a function. For example ${__threadNum}.

  • If a function parameter contains a comma, then be sure to escape this with "\" as shown below.

    ${__time(EEE\, d MMM yyyy)}
  • Variables are referenced as:


List of Functions

Following table lists a group of functions loosely grouped into types:

Type of functionNameComment
InformationthreadNumget thread number
InformationsamplerNameget the sampler name (label)
InformationmachineIPget the local machine IP address
InformationmachineNameget the local machine name
Informationtimereturn current time in various formats
Informationloglog (or display) a message (and return the value)
Informationlognlog (or display) a message (empty return value)
InputStringFromFileread a line from a file
InputFileToStringread an entire file
InputCSVReadread from CSV delimited file
InputXPathUse an XPath expression to read from a file
Calculationcountergenerate an incrementing number
CalculationintSumadd int numbers
CalculationlongSumadd long numbers
CalculationRandomgenerate a random number
CalculationRandomStringgenerate a random string
CalculationUUIDgenerate a random type 4 UUID
ScriptingBeanShellrun a BeanShell script
ScriptingjavaScriptprocess JavaScript (Mozilla Rhino)
Scriptingjexl, jexl2evaluate a Commons Jexl expression
Propertiespropertyread a property
PropertiesPread a property (shorthand method)
PropertiessetPropertyset a JMeter property
VariablessplitSplit a string into variables
VariablesVevaluate a variable name
Variablesevalevaluate a variable expression
VariablesevalVarevaluate an expression stored in a variable
StringregexFunctionparse previous response using a regular expression
StringescapeOroRegexpCharsquote meta chars used by ORO regular expression
Stringchar generate Unicode char values from a list of numbers
StringunescapeProcess strings containing Java escapes (e.g. \n & \t)
StringunescapeHtmlDecode HTML-encoded strings
StringescapeHtmlEncode strings using HTML encoding
StringTestPlanNameReturn name of current test plan
  • There are two kinds of functions:

    • user-defined static values (or variables)

    • built-in functions

  • User-defined static values allow the user to define variables to be replaced with their static value when a test tree is compiled and submitted to be run.

  • Note that variables cannot currently be nested; i.e ${Var${N}} does not work.

  • The __V (variable) function (versions after 2.2) can be used to do this: ${__V(Var${N})}.

  • This type of replacement is possible without functions, but was less convenient and less intuitive

Where can functions and variables be used?

  • Functions and variables can be written into any field of any test component.

  • The following functions should work OK on the test plan:

    • intSum

    • longSum

    • machineName

    • BeanShell

    • javaScript

    • jexl

    • random

    • time

    • property functions

    • log functions

Functions which are used on the Test Plan have some restrictions. JMeter thread variables will have not been fully set up when the functions are processed, so variable names passed as parameters will not be set up, and variable references will not work, so split() and regex() and the variable evaluation functions won't work. The threadNum() function won't work (and does not make sense at test plan level).

Referencing variables and functions

  • Referencing a variable in a test element is done by bracketing the variable name with '${' and '}'.

  • Functions are referenced in the same manner, but by convention, the names of functions begin with "__" to avoid conflict with user value names.

  • Some functions take arguments to configure them, and these go in parentheses, comma-delimited. If the function takes no arguments, the parentheses can be omitted. For eg:

  • Alternatively, you can define your script as a variable, e.g. on the Test Plan:

    SCRIPT     vars.put("name","value")
  • The script can then be referenced as follows:


The Function Helper Dialog

The Function Helper Dialog is available from JMeter's Options tab. Function Helper Dialog
  • Using the Function Helper, you can select a function from the pull down, and assign values for its arguments. The left column in the table provides a brief description of the argument, and the right column is where you write in the value for that argument. Different functions take different arguments.

  • Once you have done this, click the “Generate" button, and the appropriate string is generated for you to copy-paste into your test plan wherever you like.

Pre-defined Variables

Some variables are defined internally by JMeter. They are:

  • COOKIE_cookiename - contains the cookie value

  • JMeterThread.last_sample_ok - whether or not the last sample was OK - true/false. Note: this is updated after PostProcessors and Assertions have been run.

  • START variables

Pre-defined Properties

Some built-in properties are defined by JMeter. These are listed below. For convenience, the START properties are also copied to variables with the same names.

  • START.MS - JMeter start time in milliseconds

  • START.YMD - JMeter start time as yyyyMMdd

  • START.HMS - JMeter start time as HHmmss

  • TESTSTART.MS - test start time in milliseconds

Please note that the START variables / properties represent JMeter startup time, not the test start time. They are mainly intended for use in file names etc.