Functions Usage¶

Since OctoPerf operates JMeter in the background, it is also possible to use JMeter functions. Functions are shortcuts you can use to avoid adding a script block into your virtual user. The same result can be achieved programmatically but they make life easier by handling a lof of common situations.

Note

The function name will be replaced by its output upon runtime in the same way a variable would be. Some functions do not output anything, refer to the function documentation for more details.

Warning

Functions require computation that can in turn make your virtual users slow, make sure to use them sparingly.

Information¶

__threadNum¶

This function outputs the thread (= virtual user) number. The number is between 1 and the max number of running threads. This value is not unique.

Typically In OctoPerf, every runtime group (and load generator in case a runtime group has more than one) will count thread numbers independently.

If you are looking for a unique value per thread, combine this with machineName.

Example

${__threadNum}

__iterationNum¶

This function returns the current iteration number for the virtual user. The iteration number indicates how many times the virtual user was able to execute all its actions starting at 1.

Example

${__iterationNum}

__threadGroupName¶

This function returns the name of the virtual user as specified on the design screen.

Example

${__threadGroupName}

__samplerName¶

This function returns the name of the current sampler. For example it can output the name of the HTTP request being executed.

Warning

This function only works when used from inside a sampler, post/pre processor or assertion.

Example

${__samplerName()}

The output can be saved into a variable in order to be reused later:

Example

${__samplerName(myvar)} ${myvar}

__machineIP¶

This function returns the local machine IP. In OctoPerf, the output will always be 172.17.0.2 since this is the local address of the docker container.

Example

${__machineIP}

__machineName¶

This function returns the local machine name. In OctoPerf, the output will be the local docker container Id, a string of 12 random characters that is unique to each docker container. As such this function can be used to keep track of each individual thread when combined with threadNum and iterationNum

Example

${__machineName}

__TestPlanName¶

This function returns the test plan name. In OctoPerf, the output will always be scenario.jmx since this is how we name all test plans.

Example

${__TestPlanName}

__log¶

This function logs a message and returns its input string.

Attribute	Description	Required
String to be logged	The string you want to log	Yes
Log level	OUT, ERR, DEBUG, INFO (default), WARN or ERROR	No
Throwable text	Creates a Throwable to pass to the logger	No
Comment	Displayed in the string. Useful to identify what is being logged.	No

Example

Simple log message

FunctionOutput

${__log(Message)}

INFO o.a.j.f.LogFunction2: 4Td6qXoBxyeK1U3VyivI 1-1 : Message

Log message using a variable (${myvar} = value)

FunctionOutput

${__log(${myvar},,,myvar=)}

INFO o.a.j.f.LogFunction2: 4Td6qXoBxyeK1U3VyivI 1-1 : myvar= value

__logn¶

This function logs a message but returns an empty string. It works the same way than log but can be used from anywhere since it has no output.

Attribute	Description	Required
String to be logged	The string you want to log	Yes
Log level	OUT, ERR, DEBUG, INFO (default), WARN or ERROR	No
Throwable text	Creates a Throwable to pass to the logger	No

Example

Simple log message

FunctionOutput

${__logn(Message)}

INFO o.a.j.f.LogFunction2: 4Td6qXoBxyeK1U3VyivI 1-1 : Message

Log message using a variable (${myvar} = value)

FunctionOutput

${__logn(myvar=${myvar})}

INFO o.a.j.f.LogFunction2: 4Td6qXoBxyeK1U3VyivI 1-1 : myvar=value

File¶

__StringFromFile¶

This function returns a string from a file. Every time it is called it reads the next line. All virtual users running on the same OctoPerf load generator share access to this file, so they are guaranteed to get a different line, provided there are enough lines.

Attribute	Description	Required
File name	Path to the file, relative to the JMeter folder. If provided through the files menu of OctoPerf, it will be located in `resources/`.	Yes
Variable name	Variable in which the value will be stored for later use.	No
Start sequence number	In case of multiple files specify the starting sequence number.	No
End sequence number	Final sequence number. If omitted there is no limit.	No

Warning

Multiple calls to this function will open the file independently and might result in different values being used. If you need to reuse the value, make sure to save it to a variable.

Example

Read from multiple files

FunctionFile read

${__StringFromFile(resources/file#'.'log,,1,2)}

file1.log, file2.log

Read the same file twice

FunctionFile read

${__StringFromFile(resources/file.log,,,2)}

file.log is read twice

__FileToString¶

This function returns the content of an entire file as a string. Every time it is called it reads the entire file.

Attribute	Description	Required
File name	Path to the file, relative to the JMeter folder. If provided through the files menu of OctoPerf, it will be located in `resources/`.	Yes
File encoding	Default encoding is `iso 8859-1`, use this option to change it for instance to `UTF-8`	No
Variable name	Variable in which the value will be stored for later use.	No

Example

${__FileToString(resources/file.log,UTF-8)}

__XPath¶

This function returns the result of an XPath expression applied on an XML file. Upon each call to the function, the next available match will be returned, at the end of the file it loops back to the start. If there is no match an empty string is returned.

Since this works similarly to the XPath processor, we recommend to use it instead because it is natively integrated in OctoPerf's UI.

Attribute	Description	Required
File name	Path to the file, relative to the JMeter folder. If provided through the files menu of OctoPerf, it will be located in `resources/`.	Yes
XPath	Default encoding is `iso 8859-1`, use this option to change it for instance to `UTF-8`	Yes

Warning

This function will load the entire file in memory in order to apply the XPath expression. On large files this can lead to huge memory consumption.

Example

${__XPath(resources/file.xml, //target/@name)}

__StringToFile¶

This function appends or overwrites a file with a string.

Attribute	Description	Required
File name	Path to the file, relative to the JMeter folder. If provided through the files menu of OctoPerf, it will be located in `resources/`.	Yes
String	The string to write.	Yes
Append?	TRUE to append the string at the end of the file, FALSE to overwrite the content of the file. Defaults to TRUE	No
File encoding	Default encoding is `iso 8859-1`, use this option to change it for instance to `UTF-8`	No

Example

${__StringToFile(resources/file.log,message)}

__CSVRead¶

This function reads columns from a CSV file. Compared to __StringFromFile it allows you to pick the right comma separated values instead of a whole line. Since the CSV variable already does this in a more efficient way, we strongly recommend using it instead.

Attribute	Description	Required
File name	Path to the file, relative to the JMeter folder. If provided through the files menu of OctoPerf, it will be located in `resources/`.	Yes
Column number	Column number starting from 0. Use NEXT to skip to the next line and return an empty string.	Yes

Example

${__CSVRead(path/name.csv,0)} Check out our more advanced example on the CSV variable page for more details.

Time¶

__time¶

This function returns the current time in various formats.

Attribute	Description	Required
Format	The date output format, see DateTimeFormatter documentation for more details.	Yes
Variable name	Variable in which the value will be stored for later use.	No

Some examples with the current date 2021-02-10 13:31:16 :

Time	Result
`${__time()}`	`1612960276007`
`${__time(/1000)}`	`1612960276`
`${__time(y-MM-dd HH:mm:ss)}`	`2021-02-10 13:31:16`
`${__time(YMD)}`	`20210210`
`${__time(Y-M-D--H:M:S)}`	`2021-02-10--14:32:16`

__timeshift¶

The Timeshift function can generate date and times as well but is mostly used to place an offset on a date.

Attribute	Description
Format	The date output format, see DateTimeFormatter documentation for more details.
Date to shift	The date you want to shift using Format set in first attribute. If empty, current date is used instead.
Shift value	Indicates the amount of time to shift. The format is `PnDTnHnMn.nS` it can be preceded by a `-` for negative date shifts. More info can be found in the documentation.
Locale to use for format	The string format of a locale. See the locale documentation for more info. If empty, the function will default to`en_EN`.
Variable name	Variable in which the value will be stored for later use.

Warning

Contrary to what Oracle's documentation may suggest, to use negative date increments for time intervals of an hour or less, it is mandatory to use PT instead of just P. Ex: -PT1H.

Some examples with the current date 2021-02-10 13:31:16 :

Timeshift	Result
`${__timeShift(,,,,)}`	`1612960276007`
`${__timeShift(dd/MM/yyyy,,,,)}`	`10/02/2021`
`${__timeShift(y-MM-dd HH:mm:ss,,,,)}`	`2021-02-10 13:31:16`
`${__timeShift(dd/MM/yyyy,,P1D,,)}`	`11/02/2021`
`${__timeShift(dd-MM-y-HH-mm-ss,,P1DT1H1M,,)}`	`11-02-2021-14-32-16`
`${__timeShift(dd-MM-y-HH-mm-ss,,-PT1H,,)}`	`10-02-2021-12-31-16`
`${__timeShift(y MMM dd HH:mm:ss,,,fr_FR,)}`	`2021 févr. 10 13:31:16`

__dateTimeConvert¶

This function returns a date converted from its source format to a destination format of your choice.

Attribute	Description	Required
Date string	The date string to convert.	Yes
Source format	The Date string format, if omitted it must be an epoch.	No
Target format	The destination format, see DateTimeFormatter documentation for more details.	Yes
Variable name	Variable in which the value will be stored for later use.	No

Example

${__dateTimeConvert(2021-02-10,yyyy-MM-dd,dd/MM/yyyy)} outputs 10/02/2021

Compute¶

__Counter¶

This function returns an incrementing integer. The value is incremented every time a virtual user finishes its iteration. Calling this function several times within the same iteration will yeld the same value.

Depending on your use case, you might have better control on the counter through the Counter variable.

Attribute	Description	Required
Local?	TRUE means the counter is local to the current thread/Virtual user only. FALSE means it will increment with every thread/Virtual user running inside the same OctoPerf container.	Yes
Variable name	Variable in which the value will be stored for later use.	No

Example

${__counter(TRUE,count)}

__digest¶

This function returns an encrypted value based on the hash, salt and other parameters.

Attribute	Description	Required
Algorithm	MD2, MD5, SHA-1, SHA-224, SHA-256, SHA-384 or SHA-512. For more details check StandardNames.	Yes
String to encode	The value that will be encrypted.	Yes
Salt	Salt to be added after the string.	No
Upper Case	Results will be lowercase, use TRUE to uppercase results.	No
Variable name	Variable in which the value will be stored for later use.	No

Example

${__digest(SHA-512,This is a value to encrypt,salt,,)}

__intSum¶

This function returns the sum of two or more integer values.

Attribute	Description	Required
First integer	The first integer to add.	Yes
Second integer	Second integer to add.	Yes
Nth integer	Nth integer to add.	No
Variable name	Variable in which the value will be stored for later use. Must contain at least one non-integer char.	No

Example

${__intSum(14,6,22,myvar)}

__longSum¶

This function returns the sum of two or more long values. Use this when __intSum isn't enough.

Attribute	Description	Required
First integer	The first long to add.	Yes
Second integer	Second long to add.	Yes
Nth integer	Nth long to add.	No
Variable name	Variable in which the value will be stored for later use. Must contain at least one non-integer char.	No

Example

${__longSum(14,6,22,myvar)}

__doubleSum¶

This function returns the sum of two or more floating values.

Attribute	Description	Required
First value	The first double to add.	Yes
Second value	Second double to add.	Yes
Nth value	Nth double to add.	No
Variable name	Variable in which the value will be stored for later use. Must contain at least one non-float char.	No

Example

${__doubleSum(14.2,5.7,22.1,myvar)}

__Random¶

This function returns a random value between min and max.

Attribute	Description	Required
Min	Minimum value.	Yes
Max	Maximum value.	Yes
Variable name	Variable in which the value will be stored for later use.	No

Example

${__Random(0,10, variable)}

__RandomDate¶

This function returns a random date between the start and end date.

Attribute	Description	Required
Format	The date output format, see DateTimeFormatter documentation for more details.	No
Start	Start date, default is now.	No
End	End date.	Yes
Locale	The locale to be used. See locale list for more details. Default is en_EN.	No
Variable name	Variable in which the value will be stored for later use.	No

Example

${__RandomDate(,,2025-12-31)} ${__RandomDate(yyyy MM dd,,31 12 2025,,variable)}

__RandomFromMultipleVars¶

This function returns a random value based on all the variables provided.

Attribute	Description	Required
Source variables	Pipe separated list of variables names.	Yes
Variable name	Variable in which the value will be stored for later use.	No

Example

${__RandomFromMultipleVars(variable1|variable2)}

__RandomString¶

This function returns a random string.

Attribute	Description	Required
Length	Length of the random string.	Yes
Allowed chars	List of allowed characters.	No
Variable name	Variable in which the value will be stored for later use.	No

Example

${__RandomString(6,a12zeczclk, MYVAR)}

__chooseRandom¶

This function returns a random value picked among its arguments. The last argument must be the variable name in which the random value is stored.

Attribute	Description	Required
1^st value	First random candidate.	Yes
2^nd value	Second random candidate.	No
Nth value	Nth random candidate.	No
Variable name	Variable in which the value will be stored for later use.	Yes

Example

${__chooseRandom(red,green,blue,orange,violet,magenta,randomColor)}

__UUID¶

This function returns a random Universally Unique IDentifier.

Example

${__UUID}

__if¶

This function returns two different values depending on the comparison of its two first arguments.

Attribute	Description	Required
Actual value	Value to be compared.	Yes
Expected value	Value to compare with.	Yes
Return if true	Value returned if comparison is ==	Yes
Return if false	Value to return if comparison is !=	Yes
Variable name	Variable in which the result will be stored for later use.	No

Example

${__if(${number}, 5, ok, invalid)}

Properties¶

__isPropDefined¶

This function returns TRUE if the property exists or FALSE if it doesn't.

Example

${__isPropDefined(TESTSTART.MS)}

__property¶

This function returns the value of a property. The shorter __P function can also be used, although it can't be stored into a variable (2^nd attribute is default value instead).

Properties are values shared among all users running inside the same OctoPerf container. This can be used in combination with the runtime properties to control your scripts in real time while the test is running.

Attribute	Description	Required
Name	Name of the property to fetch.	Yes
Variable name	Variable in which the result will be stored for later use.	No
Default value	If the property doesn't exist, return this value instead.	No

Example

${__property(propertyName,myvar)}

${__P(propertyName)}

__setProperty¶

This function returns the value to be set or an empty string. It can be used to update the value of a property.

Attribute	Description	Required
Name	Override or create a property with this name.	Yes
Value	Value to set.	Yes
Return	TRUE if the value should be returned as well, defaults to FALSE.	No

Example

${__setProperty(propertyName,propertyValue)}

__env¶

This function returns the value of an environment variable.

Attribute	Description	Required
Name	Name of the environment variable to fetch.	Yes
Variable name	Variable in which the result will be stored for later use.	No
Default value	If the environment variable doesn't exist, return this value instead.	No

Example

${__env(env_var,myvar)}

Scripting¶

__groovy¶

This function returns the output of a groovy script.

It is sometime required to use a scripting language to deal with unusual behaviors. Although it is possible to write JSR samplers/pre/postprocessors it is sometimes faster to just go for a quick one line script just where it is required.

Attribute	Description	Required
Expression	Groovy expression to evaluate.	Yes
Variable name	Variable in which the result will be stored for later use.	No

Example

It can be as easy as a simple condition for your while/if:

${__groovy(${count}<=2)}

Or you could compute a value:

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

Info

If you make use of groovy, avoid using the ${...} syntax for variables. Otherwise since the result may differ on each execution your script cannot be cached and may result in poor performance.

__javaScript¶

This function returns the output of a JavaScript script.

It is sometime required to use a scripting language to deal with unusual behaviors. Although it is possible to write JSR samplers/pre/postprocessors it is sometimes faster to just go for a quick one line script just where it is required.

Attribute	Description	Required
Expression	JavaScript expression to evaluate.	Yes
Variable name	Variable in which the result will be stored for later use.	No

Example

It can be as easy as a simple condition for your while/if:

${__javaScript(${count}<=2)}

Or you could compute a value:

${__javaScript(${myvar}.slice(7\,15))}

Variables¶

__split¶

This function returns the value of the string passed as a first attribute. It stores the splits of this string in a list of variables.

Attribute	Description	Required
Name	Name of the string to split.	Yes
Variable name	Variable in which the result will be stored for later use. If several splits, _N will be added at the end of the variable name.	Yes
Delimiter	The delimiter. Default is , (comma)	No

Example

If myvar contains this|is|a|list|42, with:

${__split(${myvar},split,|)}

The output variables will be:

* split_n = 5 * split_1 = this * split_2 = is * split_3 = a * split_4 = list * split_5 = 42 * split_6 = null * etc...

__eval¶

This function returns the result of evaluating a string expression. This is especially useful when you need to evaluate the variables and functions from inside a string stored inside a variable.

Example

For example with the following variables:

name = "OctoPerf"
tool = "JMeter"
input = "${name} is ${tool} on steroids"

${__eval(${input})}

Will return: OctoPerf is JMeter on steroids

__evalVar¶

This function returns the result of evaluating a string expression. It works exactly as __eval but the variable syntax markers can be omitted.

Example

${__evalVar(input)}

__V¶

This function returns the result of evaluating a string expression. Since the ${...} syntax used for variables does not allow nested variables this function must be used to tell JMeter to evaluate nested variables. It works exactly as __eval.

Example

${__V(categories_${counter})}

We already have a detailed example of a situation where this can be useful on the while page.

__isVarDefined¶

This function returns TRUE if the variable name exists or FALSE if it doesn't.

Example

${__isVarDefined(myvar)}

__isDefined¶

This function returns 1 if the variable name exists or 0 if it doesn't.

Example

${__isDefined(myvar)}

String¶

__char¶

This function returns the result of evaluating a comma separated list of unicode codes.

The number to be converted to a Unicode character can be:

Decimal number by default,
Hex number, if prefixed by 0x,
Octal, if prefixed by 0.

Example

${__char(13,10)} will return CRLF

${__char(111,99,116,111,112,101,114,102)} will return octoperf

__changeCase¶

This function returns a string with changes to its case.

Attribute	Description	Required
String	String to update.	Yes
Case mode	UPPER, LOWER or CAPITALIZE	Yes
Variable name	Variable in which the result will be stored for later use.	No

Example

${__changeCase(octoperf is JMeter on steroids,UPPER)} will return OCTOPERF IS JMETER ON STEROIDS

${__changeCase(octoperf is JMeter on steroids,LOWER)} will return octoperf is jmeter on steroids

${__changeCase(octoperf is JMeter on steroids,CAPITALIZE)} will return Octoperf Is JMeter On Steroids

__regexFunction¶

This function returns the result of a regex expression applied to the last response. It works similarly to the regex post processor and offer the same configuration options.

__strLen¶

This function returns the length of a string.

Attribute	Description	Required
String	String to evaluate.	Yes
Variable name	Variable in which the result will be stored for later use.	No

Example

${__strLen(${myvar})}

__substring¶

This function returns a subset of a string.

Attribute	Description	Required
String	String to evaluate.	Yes
Begin index	Index of the first char of the substring (starting at 0).	Yes
End index	Index of the last char of the substring.	Yes
Variable name	Variable in which the result will be stored for later use.	No

Example

${__substring("OctoPerf is JMeter on steroids",13,19)} will return JMeter.

__strReplace¶

This function returns a string after replacing a subset of it.

Attribute	Description	Required
String	String to evaluate.	Yes
Substring to replace	The subset that will be replaced. All matches will be replaced from beginning to end.	Yes
Replacement substring	The string to replace with.	Yes
Variable name	Variable in which the result will be stored for later use.	No

Example

${__strReplace("OctoPerf is JMeter on steroids",on,with)} will return OctoPerf is JMeter with steroids.

__strReplaceRegex¶

This function returns a string after replacing a subset of it through a regex.

Attribute	Description	Required
String	String to evaluate.	Yes
Search expression	Regex that defines what to replace.	Yes
Replacement substring	The string to replace with.	Yes
Variable name	Variable in which the result will be stored for later use.	No

Example

${__strReplaceRegex("OctoPerf is JMeter on steroids",' ',-)} will return OctoPerf-is-JMeter-on-steroids.

__MD5¶

This function returns the MD5 hash of a string.

Attribute	Description	Required
String	String to hash.	Yes
Variable name	Variable in which the result will be stored for later use.	No

Example

${__MD5("OctoPerf is JMeter on steroids")} will return fc1ddf979566cc0a07e94ba8a26d7e00.

__unescape¶

This function returns the result of evaluating a Java escaped string. It makes it easier to input special chars than using the UI.

Example

${ __unescape(\r\n)} will return CRLF.

__escapeHtml¶

This function returns a string and escapes the characters using HTML entities.

Example

${__escapeHtml("OctoPerf" & "JMeter")} will return "OctoPerf" & "JMeter".

__unescapeHtml¶

This function returns a string and unescapes the characters using HTML entities.

Example

${__unescapeHtml("OctoPerf" & "JMeter")} will return "OctoPerf" & "JMeter".

__escapeOroRegexpChars¶

This function returns a string where ORO Regexp meta characters are escaped.

Example

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

__escapeXml¶

This function returns a string where characters are escaped using XML 1.0 entities.

Example

${__escapeXml("OctoPerf" & "JMeter")} will return "OctoPerf" & "JMeter".

__urlencode¶

This function returns a string where URL chars have been encoded. Our correlation rules will use this function when encoding is set to Url encode.

Example

${__urlencode(string th@t requires "encoding")} will return string+th%40t+requires+%22encoding%22.

Info

Using this function spaces were encoded as +, if you prefer to have them encoded as %20 you can use another function like: ${__javaScript(encodeURIComponent("${query}"),)}

__urldecode¶

This function returns a string where URL chars have been decoded. Our correlation rules will use this function when encoding is set to Url decode.

Example

${__urldecode(string+th%40t+requires+%22encoding%22)} will return string th@t requires "encoding".

__base64Encode¶

This function returns a string encoded in base64.

Attribute	Description	Required
String	String to encode.	Yes
Variable name	Variable in which the result will be stored for later use.	No

Example

${__base64Encode("OctoPerf is JMeter on steroids")} will return T2N0b1BlcmYgaXMgSk1ldGVyIG9uIHN0ZXJvaWRz.

__base64Decode¶

This function returns a string decoded from a base64 value.

Attribute	Description	Required
String	String to decode.	Yes
Variable name	Variable in which the result will be stored for later use.	No

Example

${__base64Decode("T2N0b1BlcmYgaXMgSk1ldGVyIG9uIHN0ZXJvaWRz")} will return OctoPerf is JMeter on steroids.