mirror of https://github.com/apache/jmeter.git
1542 lines
77 KiB
XML
1542 lines
77 KiB
XML
<?xml version="1.0"?>
|
|
<!--
|
|
Licensed to the Apache Software Foundation (ASF) under one or more
|
|
contributor license agreements. See the NOTICE file distributed with
|
|
this work for additional information regarding copyright ownership.
|
|
The ASF licenses this file to You under the Apache License, Version 2.0
|
|
(the "License"); you may not use this file except in compliance with
|
|
the License. You may obtain a copy of the License at
|
|
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
Unless required by applicable law or agreed to in writing, software
|
|
distributed under the License is distributed on an "AS IS" BASIS,
|
|
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
See the License for the specific language governing permissions and
|
|
limitations under the License.
|
|
-->
|
|
|
|
<!DOCTYPE document
|
|
[
|
|
<!ENTITY sect-num '21'>
|
|
<!ENTITY ccedil "ç" >
|
|
<!ENTITY eacute "é" >
|
|
<!ENTITY hellip "…" >
|
|
<!ENTITY nbsp " " >
|
|
<!ENTITY yen "¥" >
|
|
]>
|
|
|
|
<document prev="properties_reference.html" next="regular_expressions.html" id="$Id$">
|
|
|
|
<properties>
|
|
<title>User's Manual: Functions and Variables</title>
|
|
</properties>
|
|
|
|
<body>
|
|
|
|
<!--
|
|
Because this is an XML document, all tags must be properly closed, including ones
|
|
which are passed unchanged into the HTML output, e.g. <br/>, not just <br>.
|
|
|
|
Unfortunately Java does not currently allow for this - it outputs the trailing > -
|
|
which messes up the Help display.
|
|
To avoid these artefacts, use the form <br></br>, which Java does seem to handle OK.
|
|
|
|
-->
|
|
|
|
<section name="§-num;. Functions and Variables" anchor="functions">
|
|
<p>
|
|
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:</p>
|
|
|
|
<p><code>${__functionName(var1,var2,var3)}</code></p>
|
|
|
|
<p>
|
|
Where "__functionName" matches the name of a function.
|
|
<br></br>
|
|
Parentheses surround the parameters sent to the function, for example <code>${__time(YMD)}</code>
|
|
The actual parameters vary from function to function.
|
|
Functions that require no parameters can leave off the parentheses, for example <code>${__threadNum}</code>.
|
|
</p>
|
|
|
|
<p>
|
|
If a function parameter contains a comma, then be sure to escape this with "<code>\</code>", otherwise JMeter will treat it as a parameter delimiter.
|
|
For example:
|
|
<source>
|
|
${__time(EEE\, d MMM yyyy)}
|
|
</source>
|
|
If the comma is not escaped - e.g. <code>${__javaScript(Math.max(2,5))}</code> - you will get an error such as:
|
|
<source>
|
|
ERROR - jmeter.functions.JavaScript: Error processing Javascript: [Math.max(2]
|
|
org.mozilla.javascript.EvaluatorException: missing ) after argument list (<cmd>#1)
|
|
</source>
|
|
This is because the string "<code>Math.max(2,5)</code>" is treated as being two parameters to the __javascript function:<br/>
|
|
<code>Math.max(2</code> and <code>5)</code><br/>
|
|
Other error messages are possible.
|
|
</p>
|
|
<p>Variables are referenced as follows:
|
|
<pre>
|
|
${VARIABLE}
|
|
</pre>
|
|
</p>
|
|
<p>
|
|
<b>
|
|
If an undefined function or variable is referenced, JMeter does not report/log an error - the reference is returned unchanged.
|
|
For example if <code>UNDEF</code> is not defined as a variable, then the value of <code>${UNDEF}</code> is <code>${UNDEF}</code>.
|
|
</b>
|
|
Variables, functions (and properties) are all case-sensitive.
|
|
<b>
|
|
JMeter trims spaces from variable names before use, so for example
|
|
<code>${__Random(1,63, LOTTERY )}</code> will use the variable '<code>LOTTERY</code>' rather than '<code> LOTTERY </code>'.
|
|
</b>
|
|
</p>
|
|
<note>
|
|
Properties are not the same as variables.
|
|
Variables are local to a thread; properties are common to all threads,
|
|
and need to be referenced using the <code>__P</code> or <code>__property</code> function.
|
|
</note>
|
|
<note>
|
|
When using <code>\</code> before a variable for a windows path for example <code>C:\test\${test}</code>, ensure you escape the <code>\</code>
|
|
otherwise JMeter will not interpret the variable, example:
|
|
<code>C:\\test\\${test}</code>.
|
|
<br></br>
|
|
Alternatively, just use <code>/</code> instead for the path separator - e.g. <code>C:/test/${test}</code> - Windows JVMs will convert the separators as necessary.
|
|
</note>
|
|
<p>List of functions, loosely grouped into types.</p>
|
|
<table border="1">
|
|
|
|
<tr><th>Type of function</th><th>Name</th><th>Comment</th><th>Since</th></tr>
|
|
<!-- N.B. the leading space is needed to ensure the content is processed -->
|
|
<tr><td>Information</td><td> <a href="#__threadNum">threadNum</a></td><td>get thread number</td><td>1.X</td></tr>
|
|
<tr><td>Information</td><td> <a href="#__samplerName">samplerName</a></td><td>get the sampler name (label)</td><td>2.5</td></tr>
|
|
<tr><td>Information</td><td> <a href="#__machineIP">machineIP</a></td><td>get the local machine IP address</td><td>2.6</td></tr>
|
|
<tr><td>Information</td><td> <a href="#__machineName">machineName</a></td><td>get the local machine name</td><td>1.X</td></tr>
|
|
<tr><td>Information</td><td> <a href="#__time">time</a></td><td>return current time in various formats</td><td>2.2</td></tr>
|
|
<tr><td>Information</td><td> <a href="#__log">log</a></td><td>log (or display) a message (and return the value)</td><td>2.2</td></tr>
|
|
<tr><td>Information</td><td> <a href="#__logn">logn</a></td><td>log (or display) a message (empty return value)</td><td>2.2</td></tr>
|
|
<tr><td>Input</td><td> <a href="#__StringFromFile">StringFromFile</a></td><td>read a line from a file</td><td>1.9</td></tr>
|
|
<tr><td>Input</td><td> <a href="#__FileToString">FileToString</a></td><td>read an entire file</td><td>2.4</td></tr>
|
|
<tr><td>Input</td><td> <a href="#__CSVRead">CSVRead</a></td><td>read from CSV delimited file</td><td>1.9</td></tr>
|
|
<tr><td>Input</td><td> <a href="#__XPath">XPath</a></td><td>Use an XPath expression to read from a file</td><td>2.0.3</td></tr>
|
|
<tr><td>Calculation</td><td> <a href="#__counter">counter</a></td><td>generate an incrementing number</td><td>1.X</td></tr>
|
|
<tr><td>Calculation</td><td> <a href="#__intSum">intSum</a></td><td>add int numbers</td><td>1.8.1</td></tr>
|
|
<tr><td>Calculation</td><td> <a href="#__longSum">longSum</a></td><td>add long numbers</td><td>2.3.2</td></tr>
|
|
<tr><td>Calculation</td><td> <a href="#__Random">Random</a></td><td>generate a random number</td><td>1.9</td></tr>
|
|
<tr><td>Calculation</td><td> <a href="#__RandomFromMultipleVars">RandomFromMultipleVars</a></td><td>extracts an element from the values of a set of variables separated by <code>|</code></td><td>3.1</td></tr>
|
|
<tr><td>Calculation</td><td> <a href="#__RandomString">RandomString</a></td><td>generate a random string</td><td>2.6</td></tr>
|
|
<tr><td>Calculation</td><td> <a href="#__UUID">UUID</a></td><td>generate a random type 4 UUID</td><td>2.9</td></tr>
|
|
<tr><td>Scripting</td><td> <a href="#__groovy">groovy</a></td><td>run a Groovy script</td><td>3.1</td></tr>
|
|
<tr><td>Scripting</td><td> <a href="#__BeanShell">BeanShell</a></td><td>run a BeanShell script</td><td>1.X</td></tr>
|
|
<tr><td>Scripting</td><td> <a href="#__javaScript">javaScript</a></td><td>process JavaScript (Nashorn)</td><td>1.9</td></tr>
|
|
<tr><td>Scripting</td><td> <a href="#__jexl2">jexl2</a></td><td>evaluate a Commons Jexl2 expression</td><td>jexl2(2.1.1)</td></tr>
|
|
<tr><td>Scripting</td><td> <a href="#__jexl3">jexl3</a></td><td>evaluate a Commons Jexl3 expression</td><td>jexl3 (3.0)</td></tr>
|
|
<tr><td>Properties</td><td> <a href="#__property">property</a> </td><td>read a property</td><td>2.0</td></tr>
|
|
<tr><td>Properties</td><td> <a href="#__P">P</a></td><td>read a property (shorthand method)</td><td>2.0</td></tr>
|
|
<tr><td>Properties</td><td> <a href="#__setProperty">setProperty</a></td><td>set a JMeter property</td><td>2.1</td></tr>
|
|
<tr><td>Variables</td><td> <a href="#__split">split</a></td><td>Split a string into variables</td><td>2.0.2</td></tr>
|
|
<tr><td>Variables</td><td> <a href="#__V">V</a></td><td>evaluate a variable name</td><td>2.3RC3</td></tr>
|
|
<tr><td>Variables</td><td> <a href="#__eval">eval</a></td><td>evaluate a variable expression</td><td>2.3.1</td></tr>
|
|
<tr><td>Variables</td><td> <a href="#__evalVar">evalVar</a></td><td>evaluate an expression stored in a variable</td><td>2.3.1</td></tr>
|
|
<tr><td>String</td><td> <a href="#__regexFunction">regexFunction</a></td><td>parse previous response using a regular expression</td><td>1.X</td></tr>
|
|
<tr><td>String</td><td> <a href="#__escapeOroRegexpChars">escapeOroRegexpChars</a></td><td>quote meta chars used by ORO regular expression</td><td>2.9</td></tr>
|
|
<tr><td>String</td><td> <a href="#__char">char</a></td><td>generate Unicode char values from a list of numbers</td><td>2.3.3</td></tr>
|
|
<tr><td>String</td><td> <a href="#__unescape">unescape</a></td><td>Process strings containing Java escapes (e.g. \n & \t)</td><td>2.3.3</td></tr>
|
|
<tr><td>String</td><td> <a href="#__unescapeHtml">unescapeHtml</a></td><td>Decode HTML-encoded strings</td><td>2.3.3</td></tr>
|
|
<tr><td>String</td><td> <a href="#__escapeHtml">escapeHtml</a></td><td>Encode strings using HTML encoding</td><td>2.3.3</td></tr>
|
|
<tr><td>String</td><td> <a href="#__escapeXml">escapeXml</a></td><td>Encode strings using XMl encoding</td><td>3.2</td></tr>
|
|
<tr><td>String</td><td> <a href="#__urldecode">urldecode</a></td><td>Decode a application/x-www-form-urlencoded string</td><td>2.10</td></tr>
|
|
<tr><td>String</td><td> <a href="#__urlencode">urlencode</a></td><td>Encode a string to a application/x-www-form-urlencoded string</td><td>2.10</td></tr>
|
|
<tr><td>String</td><td> <a href="#__TestPlanName">TestPlanName</a></td><td>Return name of current test plan</td><td>2.6</td></tr>
|
|
</table>
|
|
<p></p>
|
|
<subsection name="§-num;.1 What can functions do" anchor="what_can_do">
|
|
<p>There are two kinds of functions: user-defined static values (or variables), and built-in functions.<br></br>
|
|
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. This replacement happens once at the beginning of the test
|
|
run. This could be used to replace the DOMAIN field of all HTTP requests, for example - making it a simple
|
|
matter to change a test to target a different server with the same test.
|
|
</p>
|
|
<p>
|
|
Note that variables cannot currently be nested; i.e. <code>${Var${N}}</code> does not work.
|
|
The <code>__V</code> (variable) function can be used to do this: <code>${__V(Var${N})}</code>.
|
|
You can also use <code>${__BeanShell(vars.get("Var${N}")}</code>.
|
|
</p>
|
|
<p>This type of replacement is possible without functions, but was less convenient and less intuitive.
|
|
It required users to create default config elements that would fill in blank values of Samplers.
|
|
Variables allow one to replace only part of any given value, not just filling in blank values.</p>
|
|
<p>
|
|
With built-in functions users can compute new values at run-time based on previous response data, which
|
|
thread the function is in, the time, and many other sources. These values are generated fresh for every
|
|
request throughout the course of the test. </p>
|
|
<note>Functions are shared between threads.
|
|
Each occurrence of a function call in a test plan is handled by a separate function instance.</note>
|
|
</subsection>
|
|
|
|
<subsection name="§-num;.2 Where can functions and variables be used?" anchor="where">
|
|
<p>
|
|
Functions and variables can be written into any field of any test component (apart from the TestPlan - see below).
|
|
Some fields do not allow random strings
|
|
because they are expecting numbers, and thus will not accept a function. However, most fields will allow
|
|
functions.
|
|
</p>
|
|
<p>
|
|
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 <code>split()</code> and <code>regex()</code> and the variable evaluation functions won't work.
|
|
The <code>threadNum()</code> function won't work (and does not make sense at test plan level).
|
|
The following functions should work OK on the test plan:
|
|
<ul>
|
|
<li>intSum</li>
|
|
<li>longSum</li>
|
|
<li>machineName</li>
|
|
<li>BeanShell</li>
|
|
<li>groovy</li>
|
|
<li>javaScript</li>
|
|
<li>jexl2/jexl3</li>
|
|
<li>random</li>
|
|
<li>time</li>
|
|
<li>property functions</li>
|
|
<li>log functions</li>
|
|
</ul>
|
|
</p>
|
|
<p>
|
|
Configuration elements are processed by a separate thread.
|
|
Therefore functions such as <code>__threadNum</code> do not work properly in elements such as User Defined Variables.
|
|
Also note that variables defined in a UDV element are not available until the element has been processed.
|
|
</p>
|
|
<note>When using variable/function references in SQL code (etc.),
|
|
remember to include any necessary quotes for text strings,
|
|
i.e. use
|
|
<source>
|
|
SELECT item from table where name='${VAR}'
|
|
</source>
|
|
<b>not</b>
|
|
<source>
|
|
SELECT item from table where name=${VAR}
|
|
</source>
|
|
(unless <code>VAR</code> itself contains the quotes)
|
|
</note>
|
|
</subsection>
|
|
|
|
<subsection name="§-num;.3 How to reference variables and functions" anchor="how">
|
|
<p>Referencing a variable in a test element is done by bracketing the variable name with '<code>${</code>' and '<code>}</code>'.</p>
|
|
<p>Functions are referenced in the same manner, but by convention, the names of
|
|
functions begin with "<code>__</code>" to avoid conflict with user value names<sup>*</sup>. 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.</p>
|
|
|
|
<p><b>Argument values that themselves contain commas should be escaped as necessary.
|
|
If you need to include a comma in your parameter value, escape it like so: '<code>\,</code>'.</b>
|
|
This applies for example to the scripting functions - Javascript, Beanshell, Jexl, groovy - where it is necessary to escape any commas
|
|
that may be needed in script method calls - e.g.
|
|
</p>
|
|
<pre>
|
|
${__BeanShell(vars.put("name"\,"value"))}
|
|
</pre>
|
|
<p>
|
|
Alternatively, you can define your script as a variable, e.g. on the Test Plan:
|
|
<pre>SCRIPT vars.put("name","value")</pre>
|
|
The script can then be referenced as follows:
|
|
<pre>${__BeanShell(${SCRIPT})}</pre>
|
|
There is no need to escape commas in the <code>SCRIPT</code> variable because the function call is parsed before the variable is replaced with its value.
|
|
This works well in conjunction with the JSR223 or BeanShell Samplers, as these can be used to test Javascript, Jexl and BeanShell scripts.
|
|
</p>
|
|
<p>
|
|
Functions can reference variables and other functions, for example
|
|
<code>${__XPath(${__P(xpath.file),${XPATH})}</code>
|
|
will use the property "<code>xpath.file</code>" as the file name
|
|
and the contents of the variable <code>XPATH</code> as the expression to search for.
|
|
</p>
|
|
<p>
|
|
JMeter provides a tool to help you construct
|
|
function calls for various built-in functions, which you can then copy-paste.
|
|
It will not automatically escape values for you, since functions can be parameters to other functions, and you should only escape values you intend as literal.
|
|
</p>
|
|
<note>
|
|
If a string contains a backslash('<code>\</code>') and also contains a function or variable reference, the backslash will be removed if
|
|
it appears before '<code>$</code>' or '<code>,</code>' or '<code>\</code>'.
|
|
This behaviour is necessary to allow for nested functions that include commas or the string <code>${</code>.
|
|
Backslashes before '<code>$</code>' or '<code>,</code>' or '<code>\</code>' are not removed if the string does not contain a function or variable reference.
|
|
</note>
|
|
<p>
|
|
<b>The value of a variable or function can be reported</b> using the <a href="#__logn"><code>__logn()</code></a> function.
|
|
The <code>__logn()</code> function reference can be used anywhere in the test plan after the variable has been defined.
|
|
Alternatively, the Java Request sampler can be used to create a sample containing variable references;
|
|
the output will be shown in the appropriate Listener.
|
|
Note there is a <complink name="Debug Sampler"/>
|
|
that can be used to display the values of variables etc. in the Tree View Listener.
|
|
</p>
|
|
<note><sup>*</sup>If you define a user-defined static variable with the same name as a built-in function, your static
|
|
variable will override the built-in function.</note>
|
|
</subsection>
|
|
|
|
<subsection name="§-num;.4 The Function Helper Dialog" anchor="function_helper">
|
|
<p>The Function Helper dialog is available from JMeter's Tools menu.</p>
|
|
<figure width="831" height="305" image="function_helper_dialog.png">Function Helper Dialog</figure>
|
|
<p>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.</p>
|
|
<p>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.</p>
|
|
</subsection>
|
|
|
|
<subsection name="§-num;.5 Functions" anchor="functions">
|
|
|
|
<component index="§-num;.5.1" name="__regexFunction">
|
|
<description><p>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.</p>
|
|
<p>The <code>__regexFunction</code> 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 "<code>refName</code>" as the sixth
|
|
parameter you will be able to use:
|
|
<ul>
|
|
<li><code>${refName}</code> to refer to the computed result of the second parameter ("Template for the
|
|
replacement string") parsed by this function</li>
|
|
<li><code>${refName_g0}</code> to refer to the entire match parsed by this function.</li>
|
|
<li><code>${refName_g1}</code> to refer to the first group parsed by this function.</li>
|
|
<li><code>${refName_g#}</code> to refer to the n<sup>th</sup> group parsed by this function.</li>
|
|
<li><code>${refName_matchNr}</code> to refer to the number of groups found by this function.</li>
|
|
</ul>
|
|
<note>If using distributed testing, ensure you switch mode (see <code>jmeter.properties</code>) so that it's not a stripping one, see <bugzilla>56376</bugzilla></note>
|
|
</p>
|
|
</description>
|
|
|
|
<properties>
|
|
<property name="First argument" required="Yes">The first argument is the regular expression
|
|
to be applied to the response data. It will grab all matches. Any parts of this expression
|
|
that you wish to use in your template string, be sure to surround in parentheses. Example:
|
|
<code><a href="(.*)"></code>. This will grab the value of the link and store it as the first group (there is
|
|
only 1 group). Another example: <code><input type="hidden" name="(.*)" value="(.*)"></code>. This will
|
|
grab the name as the first group, and the value as the second group. These values can be used
|
|
in your template string</property>
|
|
<property name="Second argument" required="Yes">This is the template string that will replace
|
|
the function at run-time. To refer to a group captured in the regular expression, use the syntax:
|
|
<code>$[group_number]$</code>. I.e.: <code>$1$</code>, or <code>$2$</code>. Your template can be any string.</property>
|
|
<property name="Third argument" required="No, default=1">The third argument tells JMeter which match
|
|
to use. Your regular expression might find numerous matches. You have four choices:
|
|
<ul><li>An integer - Tells JMeter to use that match. '<code>1</code>' for the first found match, '<code>2</code>' for the
|
|
second, and so on</li>
|
|
<li><code>RAND</code> - Tells JMeter to choose a match at random.</li>
|
|
<li><code>ALL</code> - Tells JMeter to use all matches, and create a template string for each one and then
|
|
append them all together. This option is little used.</li>
|
|
<li>A float number between 0 and 1 - tells JMeter to find the X<sup>th</sup> match using the formula:
|
|
(number_of_matches_found * float_number) rounded to nearest integer.</li>
|
|
</ul></property>
|
|
<property name="Fourth argument" required="No">If '<code>ALL</code>' was selected for the above argument
|
|
value, then this argument will be inserted between each appended copy of the template value.</property>
|
|
<property name="Fifth argument" required="No">Default value returned if no match is found</property>
|
|
<property name="Sixth argument" required="No">A reference name for reusing the values parsed by this function.<br></br>
|
|
Stored values are <code>${refName}</code> (the replacement template string) and <code>${refName_g#}</code> where "<code>#</code>" is the
|
|
group number from the regular expression ("<code>0</code>" can be used to refer to the entire match).</property>
|
|
<property name="Seventh argument" required="No">Input variable name.
|
|
If specified, then the value of the variable is used as the input instead of using the previous sample result.
|
|
</property>
|
|
</properties>
|
|
</component>
|
|
|
|
<component index="§-num;.5.2" name="__counter">
|
|
<description><p>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.
|
|
</p>
|
|
<p>The counter uses an integer variable to hold the count, which therefore has a maximum of 2,147,483,647.</p>
|
|
<p>The counter function instances are completely independent.
|
|
The global counter - "<code>FALSE</code>" - is separately maintained by each counter instance.
|
|
</p>
|
|
<p>
|
|
<b>
|
|
Multiple <code>__counter</code> function calls in the same iteration won't increment the value further.
|
|
</b>
|
|
<br/>
|
|
If you want to have a count that increments for each sample, use the function in a Pre-Processor such as <complink name="User Parameters"/>.
|
|
</p>
|
|
</description>
|
|
<properties>
|
|
<property name="First argument" required="Yes"><code>TRUE</code> if you wish each simulated user's counter
|
|
to be kept independent and separate from the other users. <code>FALSE</code> for a global counter.</property>
|
|
|
|
<property name="Second argument" required="No">A reference name for reusing the value created by this function.<br></br>
|
|
Stored values are of the form <code>${refName}</code>. This allows you to keep one counter and refer to its value in
|
|
multiple places.</property>
|
|
</properties>
|
|
</component>
|
|
|
|
<component index="§-num;.5.3" name="__threadNum">
|
|
<description><p>The thread number function simply returns the number of the thread currently
|
|
being executed. These numbers are independent of ThreadGroup, meaning thread #1 in one threadgroup
|
|
is indistinguishable from thread #1 in another threadgroup, from the point of view of this function.</p>
|
|
|
|
<p>There are no arguments for this function.</p>
|
|
<p>Usage Example:
|
|
<source>${__threadNum}</source> returns a number between 1 and the max number of running threads configured in the containing Thread Group
|
|
</p>
|
|
</description>
|
|
<note>
|
|
This function does not work in any Configuration elements (e.g. User Defined Variables) as these are run from a separate thread.
|
|
Nor does it make sense to use it on the Test Plan.
|
|
</note>
|
|
</component>
|
|
|
|
<component index="§-num;.5.4a" name="__intSum">
|
|
<description>
|
|
<p>
|
|
The intSum function can be used to compute the sum of two or more integer values.
|
|
</p>
|
|
<note>
|
|
The reference name is optional, but it must not be a valid integer.
|
|
</note>
|
|
</description>
|
|
|
|
<properties>
|
|
<property name="First argument" required="Yes">The first int value.</property>
|
|
<property name="Second argument" required="Yes">The second int value.</property>
|
|
<property name="nth argument" required="No">The n<sup>th</sup> int value.</property>
|
|
<property name="last argument" required="No">A reference name for reusing the value computed by this function.
|
|
If specified, the reference name must contain at least one non-numeric character otherwise it will
|
|
be treated as another int value to be added.
|
|
</property>
|
|
</properties>
|
|
|
|
<p>Examples:
|
|
<source>${__intSum(2,5,MYVAR)}</source> will return 7 (2+5) and store the result in MYVAR variable. So <code>${MYVAR}</code> will be equal to 7. <br/>
|
|
<source>${__intSum(2,5,7)}</source> will return 14 (2+5+7) and store the result in MYVAR variable. <br/>
|
|
<source>${__intSum(1,2,5,${MYVAR})}</source> will return 16 if MYVAR value is equal to 8, 1+2+5+${MYVAR})<br/>
|
|
</p>
|
|
</component>
|
|
|
|
<component index="§-num;.5.4b" name="__longSum">
|
|
<description><p>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.
|
|
</p></description>
|
|
|
|
<properties>
|
|
<property name="First argument" required="Yes">The first long value.</property>
|
|
<property name="Second argument" required="Yes">The second long value.</property>
|
|
<property name="nth argument" required="No">The n<sup>th</sup> long value.</property>
|
|
<property name="last argument" required="No">A reference name for reusing the value computed by this function.
|
|
If specified, the reference name must contain at least one non-numeric character otherwise it will
|
|
be treated as another long value to be added.
|
|
</property>
|
|
</properties>
|
|
|
|
<p>Examples:
|
|
<source>${__longSum(2,5,MYVAR)}</source> will return 7 (2+5) and store the result in MYVAR variable. So <code>${MYVAR}</code> will be equal to 7. <br/>
|
|
<source>${__longSum(2,5,7)}</source> will return 14 (2+5+7) and store the result in MYVAR variable. <br/>
|
|
<source>${__longSum(1,2,5,${MYVAR})}</source> will return 16 if MYVAR value is equal to 8, 1+2+5+${MYVAR})<br/>
|
|
</p>
|
|
</component>
|
|
|
|
<!-- Alternate spelling -->
|
|
<a name="_StringFromFile"/>
|
|
<component index="§-num;.5.5" name="__StringFromFile">
|
|
|
|
<description>
|
|
<p>
|
|
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.
|
|
</p>
|
|
<p>
|
|
See also the
|
|
<a href="component_reference.html#CSV_Data_Set_Config">CSV Data Set Config test element</a>
|
|
which may be easier to use. However, that does not currently support multiple input files.
|
|
</p>
|
|
|
|
<p>
|
|
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.]
|
|
</p>
|
|
<note>
|
|
Function instances are shared between threads, and the file is (re-)opened by whatever thread
|
|
happens to need the next line of input, so using the <code>threadNumber</code> as part of the file name
|
|
will result in unpredictable behaviour.
|
|
</note>
|
|
<p>If an error occurs opening or reading the file, then the function returns the string "<code>**ERR**</code>"</p>
|
|
</description>
|
|
|
|
<properties>
|
|
<property name="File Name" required="Yes">Path to the file name.
|
|
(The path can be relative to the JMeter launch directory)
|
|
If using optional sequence numbers, the path name should be suitable for passing to DecimalFormat.
|
|
See below for examples.
|
|
</property>
|
|
<property name="Variable Name" required="No">
|
|
A reference name - <code>refName</code> - for reusing the value created by this function. Stored values are of the form <code>${refName}</code>.
|
|
Defaults to "<code>StringFromFile_</code>".
|
|
</property>
|
|
<property name="Start sequence number" required="No">Initial Sequence number (if omitted, the End sequence number is treated as a loop count)</property>
|
|
<property name="End sequence number" required="No">Final sequence number (if omitted, sequence numbers can increase without limit)</property>
|
|
</properties>
|
|
<p>The file name parameter is resolved when the file is opened or re-opened.</p>
|
|
<p>The reference name parameter (if supplied) is resolved every time the function is executed.</p>
|
|
<p><b>Using sequence numbers:</b></p>
|
|
<p>When using the optional sequence numbers, the path name is used as the format string for <code>java.text.DecimalFormat</code>.
|
|
The current sequence number is passed in as the only parameter.
|
|
If the optional start number is not specified, the path name is used as is.
|
|
Useful formatting sequences are:
|
|
</p>
|
|
<dl>
|
|
<dt><code>#</code></dt><dd>insert the number, with no leading zeros or spaces</dd>
|
|
<dt><code>000</code></dt><dd>insert the number packed out to three digits with leading zeros if necessary</dd>
|
|
</dl>
|
|
<example title="Usage of format strings" anchor="string-from-file-format-examples">
|
|
Here are a few format strings and the corresponding sequences they will generate.
|
|
<dl>
|
|
<dt><code>pin#'.'dat</code></dt><dd>Will generate the digits without leading zeros and treat the dot literally like<br />
|
|
<code>pin1.dat</code>, …, <code>pin9.dat</code>, <code>pin10.dat</code>, …, <code>pin9999.dat</code></dd>
|
|
<dt><code>pin000'.'dat</code></dt><dd>Will generate leading zeros while keeping the dot. When the numbers start having more digits
|
|
then those three digits that this format suggests, the sequence will use more digits as can be seen in<br />
|
|
<code>pin001.dat</code>, … <code>pin099.dat</code>, …, <code>pin999.dat</code>, …, <code>pin9999.dat</code></dd>
|
|
<dt><code>pin'.'dat#</code></dt><dd>Will append digits without leading zeros while keeping the dot and generate<br />
|
|
<code>pin.dat1</code>, …, <code>pin.dat9</code>, …, <code>pin.dat999</code></dd>
|
|
</dl>
|
|
</example>
|
|
<p>
|
|
If more digits are required than there are formatting characters, the number will be
|
|
expanded as necessary.<br></br>
|
|
<b>To prevent a formatting character from being interpreted,
|
|
enclose it in single quotes. Note that "<code>.</code>" is a formatting character,
|
|
and must be enclosed in single quotes</b>
|
|
(though <code>#.</code> and <code>000.</code> work as expected in locales where the decimal point is also "<code>.</code>")
|
|
<br></br>
|
|
In other locales (e.g. <code>fr</code>), the decimal point is "<code>,</code>" - which means that "<code>#.</code>"
|
|
becomes "<code>nnn,</code>".<br></br>
|
|
See the documentation for <code>DecimalFormat</code> for full details.<br></br>
|
|
If the path name does not contain any special formatting characters,
|
|
the current sequence number will be appended to the name, otherwise
|
|
the number will be inserted according to the formatting instructions.<br></br>
|
|
If the start sequence number is omitted, and the end sequence number is specified,
|
|
the sequence number is interpreted as a loop count, and the file will be used at most "<code>end</code>" times.
|
|
In this case the filename is not formatted.
|
|
<br></br>
|
|
<code>${_StringFromFile(PIN#'.'DAT,,1,2)}</code> - reads <code>PIN1.DAT</code>, <code>PIN2.DAT</code><br></br>
|
|
<code>${_StringFromFile(PIN.DAT,,,2)}</code> - reads <code>PIN.DAT</code> twice<br></br>
|
|
Note that the "<code>.</code>" in <code>PIN.DAT</code> above should <u>not</u> be quoted.
|
|
In this case the start number is omitted, so the file name is used exactly as is.
|
|
</p>
|
|
</component>
|
|
|
|
<component index="§-num;.5.6a" name="__machineName">
|
|
<description><p>The machineName function returns the local host name. This uses the Java method <code>InetAddress.getLocalHost()</code> and passes it to <code>getHostName()</code></p></description>
|
|
|
|
<properties>
|
|
<property name="Variable Name" required="No">A reference name for reusing the value
|
|
computed by this function.</property>
|
|
</properties>
|
|
<p>Examples:
|
|
<source>${__machineName()}</source> will return the host name of the machine<br/>
|
|
<source>${__machineName}</source> will return the host name of the machine<br/>
|
|
</p>
|
|
</component>
|
|
|
|
<component index="§-num;.5.6b" name="__machineIP">
|
|
<description><p>The machineIP function returns the local IP address. This uses the Java method <code>InetAddress.getLocalHost()</code> and passes it to <code>getHostAddress()</code></p></description>
|
|
|
|
<properties>
|
|
<property name="Variable Name" required="No">A reference name for reusing the value
|
|
computed by this function.</property>
|
|
</properties>
|
|
|
|
<p>Examples:
|
|
<source>${__machineIP()}</source> will return the IP address of the machine<br/>
|
|
<source>${__machineIP}</source> will return the IP address of the machine<br/>
|
|
</p>
|
|
</component>
|
|
|
|
<component index="§-num;.5.7" name="__javaScript">
|
|
<description>
|
|
<p>
|
|
The javaScript function executes a piece of JavaScript (not Java!) code and returns its value
|
|
</p>
|
|
<p>
|
|
The JMeter Javascript function calls a standalone JavaScript interpreter.
|
|
Javascript is used as a scripting language, so you can do calculations etc.</p>
|
|
<p>
|
|
<note>javaScript is not the best scripting language for performances in JMeter. If your plan requires a high number of threads
|
|
it is advised to use <code>__jexl3</code> or <code>__groovy</code> functions.
|
|
</note>
|
|
|
|
For Nashorn Engine, please see <a href="https://docs.oracle.com/javase/8/docs/technotes/guides/scripting/nashorn/">Java Platform, Standard Edition Nashorn User's Guide</a>.<br/>
|
|
For Rhino engine, please see <a href="http://www.mozilla.org/rhino/overview.html">Mozilla Rhino Overview</a>
|
|
</p>
|
|
<p>
|
|
The following variables are made available to the script:
|
|
</p>
|
|
<ul>
|
|
<li><code>log</code> - the <a href="https://www.slf4j.org/api/org/slf4j/Logger.html">Logger</a> for the function</li>
|
|
<li><code>ctx</code> - <a href="../api/org/apache/jmeter/threads/JMeterContext.html">JMeterContext</a> object</li>
|
|
<li><code>vars</code> - <a href="../api/org/apache/jmeter/threads/JMeterVariables.html">JMeterVariables</a> object</li>
|
|
<li><code>threadName</code> - String containing the current thread name</li>
|
|
<li><code>sampler</code> - current <a href="../api/org/apache/jmeter/samplers/Sampler.html">Sampler</a> object (if any)</li>
|
|
<li><code>sampleResult</code> - previous <a href="../api/org/apache/jmeter/samplers/SampleResult.html">SampleResult</a> object (if any)</li>
|
|
<li><code>props</code> - JMeterProperties (class <a href="https://docs.oracle.com/javase/8/docs/api/java/util/Properties.html"><code>java.util.Properties</code></a>) object</li>
|
|
</ul>
|
|
<p>
|
|
Rhinoscript allows access to static methods via its Packages object.
|
|
See the <a href="https://wiki.openjdk.java.net/display/Nashorn/Rhino+Migration+Guide">Scripting Java</a> documentation.
|
|
For example one can access the JMeterContextService static methods thus:
|
|
<code>Java.type("org.apache.jmeter.threads.JMeterContextService").getTotalThreads()</code>
|
|
</p>
|
|
<note>
|
|
JMeter is not a browser, and does not interpret the JavaScript in downloaded pages.
|
|
</note>
|
|
</description>
|
|
|
|
<properties>
|
|
<property name="Expression" required="Yes">The JavaScript expression to be executed. For example:
|
|
<ul>
|
|
<li><code>new Date()</code> - return the current date and time</li>
|
|
<li><code>Math.floor(Math.random()*(${maxRandom}+1))</code>
|
|
- a random number between <code>0</code> and the variable <code>maxRandom</code></li>
|
|
<li><code>${minRandom}+Math.floor(Math.random()*(${maxRandom}-${minRandom}+1))</code>
|
|
- a random number between the variables <code>minRandom</code> and <code>maxRandom</code></li>
|
|
<li><code>"${VAR}"=="abcd"</code></li>
|
|
</ul>
|
|
</property>
|
|
<property name="Variable Name" required="No">A reference name for reusing the value
|
|
computed by this function.</property>
|
|
</properties>
|
|
<note>Remember to include any necessary quotes for text strings and JMeter variables. Also, if
|
|
the expression has commas, please make sure to escape them. For example in:
|
|
<source>
|
|
${__javaScript('${sp}'.slice(7\,99999))}
|
|
</source>
|
|
the comma after <code>7</code> is escaped.</note>
|
|
|
|
<p>Examples:
|
|
<source>${__javaScript(new Date())}</source> will return <code>Sat Jan 09 2016 16:22:15 GMT+0100 (CET)</code><br/>
|
|
<source>${__javaScript(new Date(),MYDATE)}</source> will return <code>Sat Jan 09 2016 16:22:15 GMT+0100 (CET)</code> and store it under variable <code>MYDATE</code><br/>
|
|
<source>${__javaScript(Math.floor(Math.random()*(${maxRandom}+1)),MYRESULT)}</source> will use maxRandom variable, return a random value between 0 and maxRandom and store it in MYRESULT
|
|
<source>${__javaScript(${minRandom}+Math.floor(Math.random()*(${maxRandom}-${minRandom}+1)),MYRESULT)}</source> will use <code>maxRandom</code> and <code>minRandom</code> variables, return a random value between <code>maxRandom</code> and <code>minRandom</code> and store it under variable <code>MYRESULT</code>
|
|
<source>${__javaScript("${VAR}"=="abcd",MYRESULT)}</source> will compare the value of <code>VAR</code> variable with <code>abcd</code>, return <code>true</code> or <code>false</code> and store the result in MYRESULT
|
|
</p>
|
|
|
|
</component>
|
|
|
|
<component index="§-num;.5.8" name="__Random">
|
|
<description><p>The random function returns a random number that lies between the given min and max values.</p></description>
|
|
|
|
<properties>
|
|
<property name="Minimum value" required="Yes">A number</property>
|
|
<property name="Maximum value" required="Yes">A bigger number</property>
|
|
<property name="Variable Name" required="No">A reference name for reusing the value
|
|
computed by this function.</property>
|
|
</properties>
|
|
|
|
<p>Examples:
|
|
<source>${__Random(0,10)}</source> will return a random number between 0 and 10<br/>
|
|
<source>${__Random(0,10, MYVAR)}</source> will return a random number between 0 and 10 and store it in <code>MYVAR</code>. <code>${MYVAR}</code> will contain the random number<br/>
|
|
</p>
|
|
</component>
|
|
|
|
<component index="§-num;.5.8" name="__RandomString">
|
|
<description><p>The RandomString function returns a random String of length using characters in chars to use.</p></description>
|
|
|
|
<properties>
|
|
<property name="Length" required="Yes">A number length of generated String</property>
|
|
<property name="Characters to use" required="No">Chars used to generate String</property>
|
|
<property name="Variable Name" required="No">A reference name for reusing the value
|
|
computed by this function.</property>
|
|
</properties>
|
|
<p>Examples:
|
|
<source>${__RandomString(5)}</source> will return a random string of 5 characters which can be readable or not<br/>
|
|
<source>${__RandomString(10,abcdefg)}</source> will return a random string of 10 characters picked from <code>abcdefg</code> set, like <code>cdbgdbeebd</code> or <code>adbfeggfad</code>, …<br/>
|
|
<source>${__RandomString(6,a12zeczclk, MYVAR)}</source> will return a random string of 6 characters picked from <code>a12zeczclk</code> set and store the result in <code>MYVAR</code>, <code>MYVAR</code> will contain
|
|
string like <code>2z22ak</code> or <code>z11kce</code>, …<br/>
|
|
</p>
|
|
</component>
|
|
|
|
<component index="§-num;.5.8" name="__RandomFromMultipleVars">
|
|
<description><p>The RandomFromMultipleVars function returns a random value based on the variable values provided by <code>Source Variables</code>.</p>
|
|
The variables can be simple or multi-valued as they can be generated by the following extractors:
|
|
<ul>
|
|
<li><a href="component_reference.html#Regular_Expression_Extractor">Regular Expression Extractor</a></li>
|
|
<li><a href="component_reference.html#CSS/JQuery_Extractor">CSS/JQuery Extractor</a></li>
|
|
<li><a href="component_reference.html#JSON_Extractor">JSON Extractor</a></li>
|
|
<li><a href="component_reference.html#XPath_Assertion">XPath Assertion</a></li>
|
|
</ul>
|
|
|
|
Multi-value vars are the ones that are extracted when you set <code>-1</code> for <code>Match Numbers</code>.
|
|
This leads to creation of match number variable called <code>varName_matchNr</code> and for each value to the creation of variable <code>varName_n</code> where n = 1, 2, 3 etc.
|
|
|
|
</description>
|
|
|
|
<properties>
|
|
<property name="Source Variables" required="Yes">Variable names separated by <code>|</code> that contain the values that will be used as input for random computation</property>
|
|
<property name="Variable Name" required="No">A reference name for reusing the value
|
|
computed by this function.</property>
|
|
</properties>
|
|
<p>Examples:
|
|
<source>${__RandomFromMultipleVars(val)}</source> will return a random string based on content of variable val taking into account wether they are multi-value or not<br/>
|
|
<source>${__RandomFromMultipleVars(val1|val2)}</source> will return a random string based on content of variables val1 and val2 taking into account wether they are multi-value or not<br/>
|
|
<source>${__RandomFromMultipleVars(val1|val2, MYVAR)}</source> will return a random string based on content of variables val1 and val2 taking into account wether they are multi-value or not and store the result in <code>MYVAR</code><br/>
|
|
</p>
|
|
</component>
|
|
|
|
|
|
<component index="§-num;.5.8" name="__UUID">
|
|
<description>
|
|
<p>The UUID function returns a pseudo random type 4 Universally Unique IDentifier (UUID).</p>
|
|
</description>
|
|
<properties>
|
|
</properties>
|
|
<p>Examples:
|
|
<source>${UUID()}</source> will return UUIDs with this format : <code>c69e0dd1-ac6b-4f2b-8d59-5d4e8743eecd</code> <br/>
|
|
</p>
|
|
</component>
|
|
|
|
<component index="§-num;.5.8" name="__CSVRead">
|
|
<description><p>The CSVRead function returns a string from a CSV file (c.f. <a href="#_StringFromFile">StringFromFile</a>)</p>
|
|
<p>NOTE: JMeter supports multiple file names.
|
|
</p>
|
|
<p><b>In most cases, the newer
|
|
<a href="component_reference.html#CSV_Data_Set_Config">CSV Data Set Config element</a>
|
|
is easier to use.</b></p>
|
|
<p>
|
|
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.
|
|
</p>
|
|
<p>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 <code>CSVRead(abc.txt,0)</code> and <code>CSVRead(aBc.txt,0)</code> would refer to different internal arrays.
|
|
</p>
|
|
<p>
|
|
The <code>*ALIAS</code> feature allows the same file to be opened more than once,
|
|
and also allows for shorter file names.
|
|
</p>
|
|
<p>
|
|
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.]
|
|
</p>
|
|
<note>The function splits the line at every comma by default.
|
|
If you want to enter columns containing commas, then you will need
|
|
to change the delimiter to a character that does not appear in any
|
|
column data, by setting the property: <code>csvread.delimiter</code>
|
|
</note>
|
|
</description>
|
|
|
|
<properties>
|
|
<property name="File Name" required="Yes">The file (or <code>*ALIAS</code>) to read from</property>
|
|
<property name="Column number" required="Yes">
|
|
The column number in the file.
|
|
<code>0</code> = first column, <code>1</code> = second etc.
|
|
"<code>next</code>" - go to next line of file.
|
|
<code>*ALIAS</code> - open a file and assign it to the alias
|
|
</property>
|
|
</properties>
|
|
<p>For example, you could set up some variables as follows:
|
|
<ul>
|
|
<li>COL1a <code>${__CSVRead(random.txt,0)}</code></li>
|
|
<li>COL2a <code>${__CSVRead(random.txt,1)}${__CSVRead(random.txt,next)}</code></li>
|
|
<li>COL1b <code>${__CSVRead(random.txt,0)}</code></li>
|
|
<li>COL2b <code>${__CSVRead(random.txt,1)}${__CSVRead(random.txt,next)}</code></li>
|
|
</ul>
|
|
This would read two columns from one line, and two columns from the next available line.
|
|
If all the variables are defined on the same User Parameters Pre-Processor, then the lines
|
|
will be consecutive. Otherwise, a different thread may grab the next line.
|
|
</p>
|
|
<note>
|
|
The function is not suitable for use with large files, as the entire file is stored in memory.
|
|
For larger files, use <a href="component_reference.html#CSV_Data_Set_Config">CSV Data Set Config element</a>
|
|
or <a href="#__StringFromFile">StringFromFile</a>.
|
|
</note>
|
|
</component>
|
|
|
|
<component index="§-num;.5.9" name="__property">
|
|
<description><p>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.
|
|
</p>For example:<p>
|
|
<ul>
|
|
<li><code>${__property(user.dir)}</code> - return value of <code>user.dir</code></li>
|
|
<li><code>${__property(user.dir,UDIR)}</code> - return value of <code>user.dir</code> and save in <code>UDIR</code></li>
|
|
<li><code>${__property(abcd,ABCD,atod)}</code> - return value of property <code>abcd</code> (or "<code>atod</code>" if not defined) and save in <code>ABCD</code></li>
|
|
<li><code>${__property(abcd,,atod)}</code> - return value of property <code>abcd</code> (or "<code>atod</code>" if not defined) but don't save it</li>
|
|
</ul>
|
|
</p>
|
|
</description>
|
|
|
|
<properties>
|
|
<property name="Property Name" required="Yes">The property name to be retrieved.</property>
|
|
<property name="Variable Name" required="No">A reference name for reusing the value
|
|
computed by this function.</property>
|
|
<property name="Default Value" required="No">The default value for the property.</property>
|
|
</properties>
|
|
</component>
|
|
|
|
<component index="§-num;.5.10" name="__P">
|
|
<description><p>This is a simplified property function which is
|
|
intended for use with properties defined on the command line.
|
|
Unlike the <code>__property</code> 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.
|
|
</p>For example:<p>
|
|
<code>
|
|
Define the property value:
|
|
<source>
|
|
jmeter -Jgroup1.threads=7 -Jhostname1=www.realhost.edu
|
|
</source>
|
|
|
|
Fetch the values:
|
|
<br></br>
|
|
<code>${__P(group1.threads)}</code> - return the value of <code>group1.threads</code>
|
|
<br></br>
|
|
<code>${__P(group1.loops)}</code> - return the value of <code>group1.loops</code>
|
|
<br></br>
|
|
<code>${__P(hostname,www.dummy.org)}</code> - return value of property <code>hostname</code> or <code>www.dummy.org</code> if not defined
|
|
<br></br>
|
|
</code>
|
|
In the examples above, the first function call would return <code>7</code>,
|
|
the second would return <code>1</code> and the last would return <code>www.dummy.org</code>
|
|
(unless those properties were defined elsewhere!)
|
|
</p>
|
|
</description>
|
|
|
|
<properties>
|
|
<property name="Property Name" required="Yes">The property name to be retrieved.</property>
|
|
<property name="Default Value" required="No">The default value for the property.
|
|
If omitted, the default is set to "<code>1</code>".</property>
|
|
</properties>
|
|
</component>
|
|
|
|
<component index="§-num;.5.11" name="__log">
|
|
<description>
|
|
<p>
|
|
The log function logs a message, and returns its input string
|
|
</p>
|
|
</description>
|
|
|
|
<properties>
|
|
<property name="String to be logged" required="Yes">A string</property>
|
|
<property name="Log Level" required="No"><code>OUT</code>, <code>ERR</code>, <code>DEBUG</code>, <code>INFO</code> (default), <code>WARN</code> or <code>ERROR</code></property>
|
|
<property name="Throwable text" required="No">If non-empty, creates a Throwable to pass to the logger</property>
|
|
<property name="Comment" required="No">If present, it is displayed in the string.
|
|
Useful for identifying what is being logged.</property>
|
|
</properties>
|
|
<p>The <code>OUT</code> and <code>ERR</code> log level names are used to direct the output to <code>System.out</code> and <code>System.err</code> respectively.
|
|
In this case, the output is always printed - it does not depend on the current log setting.
|
|
</p>
|
|
For example:
|
|
<dl>
|
|
<dt><code>${__log(Message)}</code></dt><dd>written to the log file as "<code> … thread Name : Message</code>"</dd>
|
|
<dt><code>${__log(Message,OUT)}</code></dt><dd>written to console window</dd>
|
|
<dt><code>${__log(${VAR},,,VAR=)}</code></dt><dd>written to log file as "<code> … thread Name VAR=value</code>"</dd>
|
|
</dl>
|
|
</component>
|
|
|
|
<component index="§-num;.5.12" name="__logn">
|
|
<description>
|
|
<p>
|
|
The logn function logs a message, and returns the empty string
|
|
</p>
|
|
</description>
|
|
|
|
<properties>
|
|
<property name="String to be logged" required="Yes">A string</property>
|
|
<property name="Log Level" required="No"><code>OUT</code>, <code>ERR</code>, <code>DEBUG</code>, <code>INFO</code> (default), <code>WARN</code> or <code>ERROR</code></property>
|
|
<property name="Throwable text" required="No">If non-empty, creates a Throwable to pass to the logger</property>
|
|
</properties>
|
|
<p>The <code>OUT</code> and <code>ERR</code> log level names are used to direct the output to <code>System.out</code> and <code>System.err</code> respectively.
|
|
In this case, the output is always printed - it does not depend on the current log setting.
|
|
</p>
|
|
For example:
|
|
<dl>
|
|
<dt><code>${__logn(VAR1=${VAR1},OUT)}</code></dt><dd>write the value of the variable to the console window</dd>
|
|
</dl>
|
|
</component>
|
|
|
|
<component index="§-num;.5.13" name="__BeanShell">
|
|
<description>
|
|
<p>
|
|
The BeanShell function evaluates the script passed to it, and returns the result.
|
|
</p>
|
|
<p>
|
|
<b>For full details on using BeanShell, please see the BeanShell web-site at <a href="http://www.beanshell.org/">http://www.beanshell.org/</a>
|
|
</b>
|
|
</p>
|
|
<note>
|
|
Note that a different Interpreter is used for each independent occurrence of the function
|
|
in a test script, but the same Interpreter is used for subsequent invocations.
|
|
This means that variables persist across calls to the function.
|
|
</note>
|
|
<p>
|
|
A single instance of a function may be called from multiple threads.
|
|
However the function <code>execute()</code> method is synchronised.
|
|
</p>
|
|
<p>
|
|
If the property "<code>beanshell.function.init</code>" 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: <code>BeanShellFunction.bshrc</code>.
|
|
</p>
|
|
<p>
|
|
The following variables are set before the script is executed:
|
|
<ul>
|
|
<li><code>log</code> - the <a href="https://www.slf4j.org/api/org/slf4j/Logger.html">Logger</a> for the BeanShell function (*)</li>
|
|
<li><code>ctx</code> - <a href="../api/org/apache/jmeter/threads/JMeterContext.html">JMeterContext</a> object</li>
|
|
<li><code>vars</code> - <a href="../api/org/apache/jmeter/threads/JMeterVariables.html">JMeterVariables</a> object</li>
|
|
<li><code>props</code> - JMeterProperties (class <a href="https://docs.oracle.com/javase/8/docs/api/java/util/Properties.html"><code>java.util.Properties</code></a>) object</li>
|
|
<li><code>threadName</code> - the threadName (String)</li>
|
|
<li><code>Sampler</code> - the current <a href="../api/org/apache/jmeter/samplers/Sampler.html">Sampler</a>, if any</li>
|
|
<li><code>SampleResult</code> - the current <a href="../api/org/apache/jmeter/samplers/SampleResult.html">SampleResult</a>, if any</li>
|
|
</ul>
|
|
(*) means that this is set before the init file, if any, is processed.
|
|
Other variables vary from invocation to invocation.
|
|
</p>
|
|
</description>
|
|
|
|
<properties>
|
|
<property name="BeanShell script" required="Yes">A beanshell script (not a file name)</property>
|
|
<property name="Name of variable" required="No">A reference name for reusing the value
|
|
computed by this function.</property>
|
|
|
|
</properties>
|
|
<p>
|
|
Example:
|
|
<dl>
|
|
<dt><code>${__BeanShell(123*456)}</code></dt><dd>returns <code>56088</code></dd>
|
|
<dt><code>${__BeanShell(source("function.bsh"))}</code></dt><dd>processes the script in <code>function.bsh</code></dd>
|
|
</dl>
|
|
</p>
|
|
<note>
|
|
Remember to include any necessary quotes for text strings and JMeter variables that represent text strings.
|
|
</note>
|
|
</component>
|
|
|
|
<component index="§-num;.5.13" name="__groovy">
|
|
<description>
|
|
<p>
|
|
The <code>__groovy</code> function evaluates <a href="http://groovy-lang.org/" >Apache Groovy</a> scripts passed to it, and returns the result.
|
|
</p>
|
|
<p>
|
|
If the property "<code>groovy.utilities</code>" 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 <code>bin</code> directory: <code>utility.groovy</code>.
|
|
</p>
|
|
<p>
|
|
The following variables are set before the script is executed:
|
|
</p>
|
|
<ul>
|
|
<li><code>log</code> - the <a href="https://www.slf4j.org/api/org/slf4j/Logger.html">Logger</a> for the groovy function (*)</li>
|
|
<li><code>ctx</code> - <a href="../api/org/apache/jmeter/threads/JMeterContext.html">JMeterContext</a> object</li>
|
|
<li><code>vars</code> - <a href="../api/org/apache/jmeter/threads/JMeterVariables.html">JMeterVariables</a> object</li>
|
|
<li><code>props</code> - JMeterProperties (class <a href="https://docs.oracle.com/javase/8/docs/api/java/util/Properties.html"><code>java.util.Properties</code></a>) object</li>
|
|
<li><code>threadName</code> - the threadName (String)</li>
|
|
<li><code>sampler</code> - the current <a href="../api/org/apache/jmeter/samplers/Sampler.html">Sampler</a>, if any</li>
|
|
<li><code>prev</code> - the previous <a href="../api/org/apache/jmeter/samplers/SampleResult.html">SampleResult</a>, if any</li>
|
|
<li><code>OUT</code> - System.out</li>
|
|
</ul>
|
|
<p>
|
|
(*) means that this is set before the init file, if any, is processed.
|
|
Other variables vary from invocation to invocation.
|
|
</p>
|
|
</description>
|
|
|
|
<properties>
|
|
<property name="Expression to evaluate" required="Yes">A groovy script (not a file name)
|
|
<note>Argument values that themselves contain commas should be escaped as necessary.
|
|
If you need to include a comma in your parameter value, escape it like this: '<code>\,</code>'</note>
|
|
</property>
|
|
<property name="Name of variable" required="No">A reference name for reusing the value
|
|
computed by this function.</property>
|
|
|
|
</properties>
|
|
<p>
|
|
Example:
|
|
<dl>
|
|
<dt><code>${__groovy(123*456)}</code></dt><dd>returns <code>56088</code></dd>
|
|
<dt><code>${__groovy("${var}".substring(0\,2))}</code></dt><dd>If var's value is <code>JMeter</code>, it will return <code>JM</code> as it runs <code>String.substring(0,2)</code>. Note
|
|
that <code>,</code> has been escaped to <code>\,</code> </dd>
|
|
</dl>
|
|
</p>
|
|
<note>
|
|
Remember to include any necessary quotes for text strings and JMeter variables that represent text strings.
|
|
</note>
|
|
</component>
|
|
|
|
|
|
<component index="§-num;.5.14" name="__split">
|
|
<description>
|
|
<p>
|
|
The split function splits the string passed to it according to the delimiter,
|
|
and returns the original string. If any delimiters are adjacent, "<code>?</code>" is returned as the value.
|
|
The split strings are returned in the variables <code>${VAR_1}</code>, <code>${VAR_2}</code> etc.
|
|
The count of variables is returned in <code>${VAR_n}</code>.
|
|
A trailing delimiter is treated as a missing variable, and "<code>?</code>" is returned.
|
|
Also, to allow it to work better with the ForEach controller,
|
|
<code>__split</code> now deletes the first unused variable in case it was set by a previous split.
|
|
</p>
|
|
<p/>
|
|
Example:
|
|
<br></br>
|
|
Define <code>VAR</code>="<code>a||c|</code>" in the test plan.
|
|
<br></br>
|
|
<code>${__split(${VAR},VAR,|)}</code>
|
|
<br></br>
|
|
This will return the contents of <code>VAR</code>, i.e. "<code>a||c|</code>" and set the following variables:
|
|
<br></br>
|
|
<code>VAR_n</code>=<code>4</code>
|
|
<br></br>
|
|
<code>VAR_1</code>=<code>a</code>
|
|
<br></br>
|
|
<code>VAR_2</code>=<code>?</code>
|
|
<br></br>
|
|
<code>VAR_3</code>=<code>c</code>
|
|
<br></br>
|
|
<code>VAR_4</code>=<code>?</code>
|
|
<br></br>
|
|
<code>VAR_5</code>=<code>null</code>
|
|
</description>
|
|
|
|
<properties>
|
|
<property name="String to split" required="Yes">A delimited string, e.g. "<code>a|b|c</code>"</property>
|
|
<property name="Name of variable" required="Yes">A reference name for reusing the value
|
|
computed by this function.</property>
|
|
<property name="Delimiter" required="No">The delimiter character, e.g. <code>|</code>.
|
|
If omitted, <code>,</code> is used. Note that <code>,</code> would need to be specified as <code>\,</code>.
|
|
</property>
|
|
|
|
</properties>
|
|
</component>
|
|
<component index="§-num;.5.15" name="__XPath">
|
|
<description>
|
|
<p>
|
|
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.
|
|
<note>Note that the entire NodeList is held in memory.</note>
|
|
</p>
|
|
<p/>
|
|
Example:
|
|
<source>${__XPath(/path/to/build.xml, //target/@name)}</source>
|
|
This will match all targets in <code>build.xml</code> and return the contents of the next name attribute
|
|
</description>
|
|
|
|
<properties>
|
|
<property name="XML file to parse" required="Yes"> a XML file to parse</property>
|
|
<property name="XPath" required="Yes"> a XPath expression to match nodes in the XML file</property>
|
|
</properties>
|
|
</component>
|
|
|
|
<component index="§-num;.5.16" name="__setProperty">
|
|
<description>
|
|
<p>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.</p>
|
|
<p>The original value can be returned by setting the optional 3<sup>rd</sup> parameter to "<code>true</code>".</p>
|
|
<p>Properties are global to JMeter,
|
|
so can be used to communicate between threads and thread groups</p>
|
|
</description>
|
|
|
|
<properties>
|
|
<property name="Property Name" required="Yes">The property name to be set.</property>
|
|
<property name="Property Value" required="Yes">The value for the property.</property>
|
|
<property name="True/False" required="No">Should the original value be returned?</property>
|
|
</properties>
|
|
</component>
|
|
|
|
|
|
<component index="§-num;.5.17" name="__time">
|
|
<description>
|
|
<p>The time function returns the current time in various formats.</p>
|
|
</description>
|
|
|
|
<properties>
|
|
<property name="Format" required="No">
|
|
The format to be passed to SimpleDateFormat.
|
|
The function supports various shorthand aliases, see below.
|
|
If omitted, the function returns the current time in milliseconds since the epoch.
|
|
</property>
|
|
<property name="Name of variable" required="No">The name of the variable to set.</property>
|
|
</properties>
|
|
<p>If the format string is omitted, then the function returns the current time in milliseconds since the epoch.
|
|
If the format matches "<code>/ddd</code>" (where <code>ddd</code> are decimal digits),
|
|
then the function returns the current time in milliseconds divided by the value of <code>ddd</code>.
|
|
For example, "<code>/1000</code>" returns the current time in seconds since the epoch.
|
|
Otherwise, the current time is passed to SimpleDateFormat.
|
|
The following shorthand aliases are provided:
|
|
</p>
|
|
<ul>
|
|
<li><code>YMD</code> = <code>yyyyMMdd</code></li>
|
|
<li><code>HMS</code> = <code>HHmmss</code></li>
|
|
<li><code>YMDHMS</code> = <code>yyyyMMdd-HHmmss</code></li>
|
|
<li><code>USER1</code> = whatever is in the Jmeter property <code>time.USER1</code></li>
|
|
<li><code>USER2</code> = whatever is in the Jmeter property <code>time.USER2</code></li>
|
|
</ul>
|
|
<p>The defaults can be changed by setting the appropriate JMeter property, e.g.
|
|
<code>time.YMD=yyMMdd</code>
|
|
</p>
|
|
</component>
|
|
|
|
<component index="§-num;.5.18" name="__jexl2">
|
|
<description>
|
|
<p>The jexl function returns the result of evaluating a
|
|
<a href="http://commons.apache.org/jexl">Commons JEXL expression</a>.
|
|
See links below for more information on JEXL expressions.
|
|
</p>
|
|
<p>The <code>__jexl2</code> function uses Commons JEXL 2</p>
|
|
<ul>
|
|
<li><a href="http://commons.apache.org/proper/commons-jexl/reference/syntax.html">JEXL syntax description</a></li>
|
|
<li><a href="http://commons.apache.org/proper/commons-jexl/reference/examples.html#Example_Expressions">JEXL examples</a></li>
|
|
</ul>
|
|
</description>
|
|
|
|
<properties>
|
|
<property name="Expression" required="Yes">
|
|
The expression to be evaluated. For example, <code>6*(5+2)</code>
|
|
</property>
|
|
<property name="Name of variable" required="No">The name of the variable to set.</property>
|
|
</properties>
|
|
<p>
|
|
The following variables are made available to the script:
|
|
</p>
|
|
<ul>
|
|
<li><code>log</code> - the <a href="https://www.slf4j.org/api/org/slf4j/Logger.html">Logger</a> for the function</li>
|
|
<li><code>ctx</code> - <a href="../api/org/apache/jmeter/threads/JMeterContext.html">JMeterContext</a> object</li>
|
|
<li><code>vars</code> - <a href="../api/org/apache/jmeter/threads/JMeterVariables.html">JMeterVariables</a> object</li>
|
|
<li><code>props</code> - JMeterProperties (class <a href="https://docs.oracle.com/javase/8/docs/api/java/util/Properties.html"><code>java.util.Properties</code></a>) object</li>
|
|
<li><code>threadName</code> - String containing the current thread name</li>
|
|
<li><code>sampler</code> - current <a href="../api/org/apache/jmeter/samplers/Sampler.html">Sampler</a> object (if any)</li>
|
|
<li><code>sampleResult</code> - previous <a href="../api/org/apache/jmeter/samplers/SampleResult.html">SampleResult</a> object (if any)</li>
|
|
<li><code>OUT</code> - System.out - e.g. <code>OUT.println("message")</code></li>
|
|
</ul>
|
|
<p>
|
|
Jexl can also create classes and call methods on them, for example:
|
|
</p>
|
|
<p>
|
|
<source>
|
|
Systemclass=log.class.forName("java.lang.System");
|
|
now=Systemclass.currentTimeMillis();
|
|
</source>
|
|
Note that the Jexl documentation on the web-site wrongly suggests that "<code>div</code>" does integer division.
|
|
In fact "<code>div</code>" and "<code>/</code>" both perform normal division. One can get the same effect
|
|
as follows:
|
|
<source>
|
|
i= 5 / 2;
|
|
i.intValue(); // or use i.longValue()
|
|
</source>
|
|
</p>
|
|
<note>JMeter allows the expression to contain multiple statements.</note>
|
|
</component>
|
|
|
|
<component index="§-num;.5.19" name="__jexl3" >
|
|
<description>
|
|
<p>The jexl function returns the result of evaluating a
|
|
<a href="http://commons.apache.org/proper/commons-jexl/">Commons JEXL expression</a>.
|
|
See links below for more information on JEXL expressions.
|
|
</p>
|
|
<p>The <code>__jexl3</code> function uses Commons JEXL 3</p>
|
|
<ul>
|
|
<li><a href="http://commons.apache.org/proper/commons-jexl/reference/syntax.html">JEXL syntax description</a></li>
|
|
<li><a href="http://commons.apache.org/proper/commons-jexl/reference/examples.html#Example_Expressions">JEXL examples</a></li>
|
|
</ul>
|
|
</description>
|
|
|
|
<properties>
|
|
<property name="Expression" required="Yes">
|
|
The expression to be evaluated. For example, <code>6*(5+2)</code>
|
|
</property>
|
|
<property name="Name of variable" required="No">The name of the variable to set.</property>
|
|
</properties>
|
|
<p>
|
|
The following variables are made available to the script:
|
|
</p>
|
|
<ul>
|
|
<li><code>log</code> - the <a href="https://www.slf4j.org/api/org/slf4j/Logger.html">Logger</a> for the function</li>
|
|
<li><code>ctx</code> - <a href="../api/org/apache/jmeter/threads/JMeterContext.html">JMeterContext</a> object</li>
|
|
<li><code>vars</code> - <a href="../api/org/apache/jmeter/threads/JMeterVariables.html">JMeterVariables</a> object</li>
|
|
<li><code>props</code> - JMeterProperties (class <a href="https://docs.oracle.com/javase/8/docs/api/java/util/Properties.html"><code>java.util.Properties</code></a>) object</li>
|
|
<li><code>threadName</code> - String containing the current thread name</li>
|
|
<li><code>sampler</code> - current <a href="../api/org/apache/jmeter/samplers/Sampler.html">Sampler</a> object (if any)</li>
|
|
<li><code>sampleResult</code> - previous <a href="../api/org/apache/jmeter/samplers/SampleResult.html">SampleResult</a> object (if any)</li>
|
|
<li><code>OUT</code> - System.out - e.g. <code>OUT.println("message")</code></li>
|
|
</ul>
|
|
<p>
|
|
Jexl can also create classes and call methods on them, for example:
|
|
</p>
|
|
<p>
|
|
<source>
|
|
Systemclass=log.class.forName("java.lang.System");
|
|
now=Systemclass.currentTimeMillis();
|
|
</source>
|
|
Note that the Jexl documentation on the web-site wrongly suggests that "<code>div</code>" does integer division.
|
|
In fact "<code>div</code>" and "<code>/</code>" both perform normal division. One can get the same effect
|
|
as follows:
|
|
<source>
|
|
i= 5 / 2;
|
|
i.intValue(); // or use i.longValue()
|
|
</source>
|
|
</p>
|
|
<note>JMeter allows the expression to contain multiple statements.</note>
|
|
</component>
|
|
|
|
<component index="§-num;.5.20" name="__V">
|
|
<description>
|
|
<p>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).
|
|
</p>
|
|
<p>For example, if one has variables <code>A1</code>,<code>A2</code> and <code>N</code>=<code>1</code>:</p>
|
|
<ul>
|
|
<li><code>${A1}</code> - works OK</li>
|
|
<li><code>${A${N}}</code> - does not work (nested variable reference)</li>
|
|
<li><code>${__V(A${N})}</code> - works OK. <code>A${N}</code> becomes <code>A1</code>, and the <code>__V</code> function returns the value of <code>A1</code></li>
|
|
</ul>
|
|
</description>
|
|
|
|
<properties>
|
|
<property name="Variable name" required="Yes">
|
|
The variable to be evaluated.
|
|
</property>
|
|
</properties>
|
|
</component>
|
|
|
|
<component index="§-num;.5.21" name="__evalVar">
|
|
<description>
|
|
<p>The evalVar function returns the result of evaluating an expression stored in a variable.
|
|
</p>
|
|
<p>
|
|
This allows one to read a string from a file, and process any variable references in it.
|
|
For example, if the variable "<code>query</code>" contains "<code>select ${column} from ${table}</code>"
|
|
and "<code>column</code>" and "<code>table</code>" contain "<code>name</code>" and "<code>customers</code>", then <code>${__evalVar(query)}</code>
|
|
will evaluate as "<code>select name from customers</code>".
|
|
</p>
|
|
</description>
|
|
|
|
<properties>
|
|
<property name="Variable name" required="Yes">
|
|
The variable to be evaluated.
|
|
</property>
|
|
</properties>
|
|
</component>
|
|
<component index="§-num;.5.22" name="__eval">
|
|
<description>
|
|
<p>The eval function returns the result of evaluating a string expression.
|
|
</p>
|
|
<p>
|
|
This allows one to interpolate variable and function references in a string
|
|
which is stored in a variable. For example, given the following variables:
|
|
</p>
|
|
<ul>
|
|
<li><code>name</code>=<code>Smith</code></li>
|
|
<li><code>column</code>=<code>age</code></li>
|
|
<li><code>table</code>=<code>birthdays</code></li>
|
|
<li><code>SQL</code>=<code>select ${column} from ${table} where name='${name}'</code></li>
|
|
</ul>
|
|
then <code>${__eval(${SQL})}</code> will evaluate as "<code>select age from birthdays where name='Smith'</code>".
|
|
|
|
<p>
|
|
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.
|
|
</p>
|
|
</description>
|
|
|
|
<properties>
|
|
<property name="Variable name" required="Yes">
|
|
The variable to be evaluated.
|
|
</property>
|
|
</properties>
|
|
</component>
|
|
|
|
<component index="§-num;.5.23" name="__char">
|
|
<description>
|
|
<p>
|
|
The char function returns the result of evaluating a list of numbers as Unicode characters.
|
|
See also <code>__unescape()</code>, below.
|
|
</p>
|
|
<p>
|
|
This allows one to add arbitrary character values into fields.
|
|
</p>
|
|
</description>
|
|
|
|
<properties>
|
|
<property name="Unicode character number (decimal or 0xhex)" required="Yes">
|
|
The decimal number (or hex number, if prefixed by <code>0x</code>, or octal, if prefixed by <code>0</code>) to be converted to a Unicode character.
|
|
</property>
|
|
</properties>
|
|
<p>Examples:
|
|
<br/>
|
|
<code>${__char(13,10)}</code> = <code>${__char(0xD,0xA)}</code> = <code>${__char(015,012)}</code> = <code>CRLF</code>
|
|
<br/>
|
|
<code>${__char(165)}</code> = <code>¥</code> (yen)
|
|
</p>
|
|
</component>
|
|
|
|
<component index="§-num;.5.24" name="__unescape">
|
|
<description>
|
|
<p>
|
|
The unescape function returns the result of evaluating a Java-escaped string. See also <code>__char()</code> above.
|
|
</p>
|
|
<p>
|
|
This allows one to add characters to fields which are otherwise tricky (or impossible) to define via the GUI.
|
|
</p>
|
|
</description>
|
|
|
|
<properties>
|
|
<property name="String to unescape" required="Yes">
|
|
The string to be unescaped.
|
|
</property>
|
|
</properties>
|
|
<p>Examples:
|
|
<br/>
|
|
<code>${__unescape(\r\n)}</code> = <code>CRLF</code>
|
|
<br/>
|
|
<code>${__unescape(1\t2)}</code> = <code>1</code>[tab]<code>2</code>
|
|
</p>
|
|
</component>
|
|
|
|
<component index="§-num;.5.25" name="__unescapeHtml">
|
|
<description>
|
|
<p>
|
|
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.
|
|
</p>
|
|
<p>
|
|
For example, the string <code>"&lt;Fran&ccedil;ais&gt;"</code>
|
|
will become <code>"<Français>"</code>.
|
|
</p>
|
|
<p>
|
|
If an entity is unrecognized, it is left alone, and inserted verbatim into the result string.
|
|
e.g. <code>"&gt;&zzzz;x"</code> will become <code>">&zzzz;x"</code>.
|
|
</p>
|
|
<p>
|
|
Uses <code>StringEscapeUtils#unescapeHtml(String)</code> from Commons Lang.
|
|
</p>
|
|
</description>
|
|
|
|
<properties>
|
|
<property name="String to unescape" required="Yes">
|
|
The string to be unescaped.
|
|
</property>
|
|
</properties>
|
|
</component>
|
|
|
|
<component index="§-num;.5.26" name="__escapeHtml">
|
|
<description>
|
|
<p>
|
|
Function which escapes the characters in a String using HTML entities.
|
|
Supports HTML 4.0 entities.
|
|
</p>
|
|
<p>
|
|
For example,<code>"bread" & "butter"</code>
|
|
becomes:
|
|
<code>&quot;bread&quot; &amp; &quot;butter&quot;</code>.
|
|
</p>
|
|
<p>
|
|
Uses <code>StringEscapeUtils#escapeHtml(String)</code> from Commons Lang.
|
|
</p>
|
|
</description>
|
|
|
|
<properties>
|
|
<property name="String to escape" required="Yes">
|
|
The string to be escaped.
|
|
</property>
|
|
</properties>
|
|
</component>
|
|
|
|
<component index="§-num;.5.27" name="__urldecode">
|
|
<description>
|
|
<p>
|
|
Function to decode a <code>application/x-www-form-urlencoded</code> string.
|
|
Note: use UTF-8 as the encoding scheme.
|
|
</p>
|
|
<p>
|
|
For example, the string <code>Word+%22school%22+is+%22%C3%A9cole%22+in+french</code> would get converted to
|
|
<code>Word "school" is "école" in french</code>.
|
|
</p>
|
|
<p>
|
|
Uses Java class <a href="http://docs.oracle.com/javase/7/docs/api/java/net/URLDecoder.html">URLDecoder</a>.
|
|
</p>
|
|
</description>
|
|
|
|
<properties>
|
|
<property name="String to decode" required="Yes">
|
|
The string with URL encoded chars to decode.
|
|
</property>
|
|
</properties>
|
|
</component>
|
|
|
|
<component index="§-num;.5.28" name="__urlencode">
|
|
<description>
|
|
<p>
|
|
Function to encode a string to a <code>application/x-www-form-urlencoded</code> string.
|
|
</p>
|
|
<p>
|
|
For example, the string <code>Word "school" is "école" in french</code> would get converted to
|
|
<code>Word+%22school%22+is+%22%C3%A9cole%22+in+french</code>.
|
|
</p>
|
|
<p>
|
|
Uses Java class <a href="http://docs.oracle.com/javase/7/docs/api/java/net/URLEncoder.html">URLEncoder</a>.
|
|
</p>
|
|
</description>
|
|
|
|
<properties>
|
|
<property name="String to encode" required="Yes">
|
|
String to encode in URL encoded chars.
|
|
</property>
|
|
</properties>
|
|
</component>
|
|
|
|
<component index="§-num;.5.29" name="__FileToString">
|
|
|
|
<description>
|
|
<p>
|
|
The FileToString function can be used to read an entire file.
|
|
Each time it is called it reads the entire file.
|
|
</p>
|
|
<p>If an error occurs opening or reading the file, then the function returns the string "<code>**ERR**</code>"</p>
|
|
</description>
|
|
|
|
<properties>
|
|
<property name="File Name" required="Yes">Path to the file name.
|
|
(The path can be relative to the JMeter launch directory)
|
|
</property>
|
|
<property name="File encoding if not the platform default" required="No">
|
|
The encoding to be used to read the file. If not specified, the platform default is used.
|
|
</property>
|
|
<property name="Variable Name" required="No">
|
|
A reference name - <code>refName</code> - for reusing the value created by this function. Stored values are of the form <code>${refName}</code>.
|
|
</property>
|
|
</properties>
|
|
<p>The file name, encoding and reference name parameters are resolved every time the function is executed.</p>
|
|
</component>
|
|
|
|
<component index="§-num;.5.30" name="__samplerName">
|
|
|
|
<description>
|
|
<p>
|
|
The samplerName function returns the name (i.e. label) of the current sampler.
|
|
</p>
|
|
<p>
|
|
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.
|
|
</p>
|
|
</description>
|
|
|
|
<properties>
|
|
<property name="Variable Name" required="No">
|
|
A reference name - <code>refName</code> - for reusing the value created by this function. Stored values are of the form <code>${refName}</code>.
|
|
</property>
|
|
</properties>
|
|
</component>
|
|
|
|
<component index="§-num;.5.31" name="__TestPlanName">
|
|
|
|
<description>
|
|
<p>
|
|
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).
|
|
</p>
|
|
</description>
|
|
|
|
<p>Example:
|
|
<source>${__TestPlanName}</source> will return the file name of your test plan, for example if plan is in a file named Demo.jmx, it will return "<code>Demo.jmx</code><br/>
|
|
</p>
|
|
</component>
|
|
|
|
<component index="§-num;.5.32" name="__escapeOroRegexpChars">
|
|
<description>
|
|
<p>
|
|
Function which escapes the ORO Regexp meta characters, it is the equivalent of <code>\Q</code> <code>\E</code> in Java Regexp Engine.
|
|
</p>
|
|
<p>
|
|
For example,<code>[^"].+?</code>
|
|
becomes:
|
|
<code>\[\^\"\]\.\+\?</code>.
|
|
</p>
|
|
<p>
|
|
Uses Perl5Compiler#quotemeta(String) from ORO.
|
|
</p>
|
|
</description>
|
|
|
|
<properties>
|
|
<property name="String to escape" required="Yes">
|
|
The string to be escaped.
|
|
</property>
|
|
<property name="Variable Name" required="No">
|
|
A reference name - <code>refName</code> - for reusing the value created by this function. Stored values are of the form <code>${refName}</code>.
|
|
</property>
|
|
</properties>
|
|
</component>
|
|
|
|
<component index="§-num;.5.33" name="__escapeXml">
|
|
<description>
|
|
<p>
|
|
Function which escapes the characters in a String using XML 1.0 entities.
|
|
</p>
|
|
<p>
|
|
For example,<code>"bread" & 'butter'</code>
|
|
becomes:
|
|
<code>&quot;bread&quot; &amp; &apos;butter&apos;</code>.
|
|
</p>
|
|
<p>
|
|
Uses <code>StringEscapeUtils#escapeXml10(String)</code> from Commons Lang.
|
|
</p>
|
|
</description>
|
|
|
|
<properties>
|
|
<property name="String to escape" required="Yes">
|
|
The string to be escaped.
|
|
</property>
|
|
</properties>
|
|
</component>
|
|
|
|
</subsection>
|
|
|
|
<subsection name="§-num;.6 Pre-defined Variables" anchor="predefinedvars">
|
|
<p>
|
|
Most variables are set by calling functions or by test elements such as User Defined Variables;
|
|
in which case the user has full control over the variable name that is used.
|
|
However some variables are defined internally by JMeter. These are listed below.
|
|
</p>
|
|
<ul>
|
|
<li><code>COOKIE_cookiename</code> - contains the cookie value (see <complink name="HTTP Cookie Manager" />)</li>
|
|
<li><code>JMeterThread.last_sample_ok</code> - whether or not the last sample was OK - <code>true</code>/<code>false</code>.
|
|
Note: this is updated after PostProcessors and Assertions have been run.
|
|
</li>
|
|
<li><code>START</code> variables (see next section)</li>
|
|
</ul>
|
|
</subsection>
|
|
<subsection name="§-num;.6 Pre-defined Properties" anchor="predefinedprops">
|
|
<p>
|
|
The set of JMeter properties is initialised from the system properties defined when JMeter starts;
|
|
additional JMeter properties are defined in <code>jmeter.properties</code>, <code>user.properties</code> or on the command line.
|
|
</p>
|
|
<p>
|
|
Some built-in properties are defined by JMeter. These are listed below.
|
|
For convenience, the <code>START</code> properties are also copied to variables with the same names.
|
|
</p>
|
|
<ul>
|
|
<li><code>START.MS</code> - JMeter start time in milliseconds</li>
|
|
<li><code>START.YMD</code> - JMeter start time as <code>yyyyMMdd</code></li>
|
|
<li><code>START.HMS</code> - JMeter start time as <code>HHmmss</code></li>
|
|
<li><code>TESTSTART.MS</code> - test start time in milliseconds</li>
|
|
</ul>
|
|
<p>
|
|
Please note that the <code>START</code> variables / properties represent JMeter startup time, not the test start time.
|
|
They are mainly intended for use in file names etc.
|
|
</p>
|
|
</subsection>
|
|
</section>
|
|
|
|
</body>
|
|
</document>
|