2002-07-13 11:17:49 +08:00
<?xml version="1.0"?>
2004-02-14 09:20:53 +08:00
<!--
2007-01-08 03:27:31 +08:00
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
2004-02-14 09:20:53 +08:00
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.
-->
2006-03-25 07:37:21 +08:00
2006-03-09 06:28:34 +08:00
< !DOCTYPE document
[
<!ENTITY sect-num '19'>
]>
2006-03-25 07:37:21 +08:00
2006-03-09 06:28:34 +08:00
<document prev= "component_reference.html" next= "regular_expressions.html" date= "2004/06/12" >
2002-07-13 11:17:49 +08:00
<properties >
2007-03-02 23:14:15 +08:00
<title > User's Manual: Functions and Variables</title>
2002-07-13 11:17:49 +08:00
</properties>
<body >
2006-03-25 07:37:21 +08:00
<!--
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.
-->
2007-06-03 20:08:50 +08:00
<section name= "§-num;. Functions and Variables" anchor= "functions" >
2002-07-13 11:17:49 +08:00
<p >
2007-06-03 20:08:50 +08:00
JMeter functions are special values that can populate fields of any Sampler or other
2006-05-02 06:08:46 +08:00
element in a test tree. A function call looks like this:</p>
2002-07-13 11:17:49 +08:00
<p > <code > ${__functionName(var1,var2,var3)}</code> </p>
2006-05-02 06:08:46 +08:00
<p >
Where "__functionName" matches the name of a function.
<br > </br>
Parentheses surround the parameters sent to the function, for example ${__time(YMD)}
The actual parameters vary from function to function.
Functions that require no parameters can leave off the parentheses, for example ${__threadNum}.
</p>
2007-06-03 20:08:50 +08:00
<p >
If a function parameter contains a comma, then be sure to escape this with "\", otherwise JMeter will treat it as a parameter delimiter.
For example:
<pre >
${__time(EEE\, d MMM yyyy)}
</pre>
</p>
<p > Variables are referenced as follows:
<pre >
${VARIABLE}
</pre>
</p>
2007-09-06 20:00:38 +08:00
<note >
Properties are not the same as variables.
Variables are local to a thread; properties are common to all threads.
</note>
2004-10-06 22:43:57 +08:00
<p > List of functions:</p>
2007-10-19 03:05:07 +08:00
<table border= "1" >
<tr > <th > Name</th> <th > Comment</th> </tr>
<!-- N.B. the leading space is needed to ensure the content is processed -->
<tr > <td > <a href= "#__regexFunction" > regexFunction</a> </td> <td > parse previous response using a regular expression</td> </tr>
<tr > <td > <a href= "#__counter" > counter</a> </td> <td > generate an incrementing number</td> </tr>
<tr > <td > <a href= "#__threadNum" > threadNum</a> </td> <td > get thread number</td> </tr>
2007-11-28 02:13:56 +08:00
<tr > <td > <a href= "#__intSum" > intSum</a> </td> <td > add int numbers</td> </tr>
<tr > <td > <a href= "#__longSum" > longSum</a> </td> <td > add long numbers</td> </tr>
2007-10-19 03:05:07 +08:00
<tr > <td > <a href= "#__StringFromFile" > StringFromFile</a> </td> <td > read a line from a file</td> </tr>
<tr > <td > <a href= "#__machineName" > machineName</a> </td> <td > get the local machine name</td> </tr>
<tr > <td > <a href= "#__javaScript" > javaScript</a> </td> <td > process JavaScript (Mozilla Rhino)</td> </tr>
<tr > <td > <a href= "#__Random" > Random</a> </td> <td > generate a random number</td> </tr>
<tr > <td > <a href= "#__CSVRead" > CSVRead</a> </td> <td > read from CSV delimited file</td> </tr>
<tr > <td > <a href= "#__property" > property</a> </td> <td > read a property</td> </tr>
<tr > <td > <a href= "#__P" > P</a> </td> <td > read a property (shorthand method)</td> </tr>
<tr > <td > <a href= "#__setProperty" > setProperty</a> </td> <td > set a JMeter property</td> </tr>
<tr > <td > <a href= "#__log" > log</a> </td> <td > log (or display) a message (and return the value)</td> </tr>
<tr > <td > <a href= "#__logn" > logn</a> </td> <td > log (or display) a message (empty return value)</td> </tr>
<tr > <td > <a href= "#__BeanShell" > BeanShell</a> </td> <td > run a BeanShell script</td> </tr>
<tr > <td > <a href= "#__split" > split</a> </td> <td > Split a string into variables</td> </tr>
<tr > <td > <a href= "#__XPath" > XPath</a> </td> <td > Use an XPath expression to read from a file</td> </tr>
<tr > <td > <a href= "#__time" > time</a> </td> <td > return current time in various formats</td> </tr>
<tr > <td > <a href= "#__jexl" > jexl</a> </td> <td > evaluate a Commons Jexl expression</td> </tr>
<tr > <td > <a href= "#__V" > V</a> </td> <td > evaluate a variable name</td> </tr>
<tr > <td > <a href= "#__eval" > eval</a> </td> <td > evaluate a variable expression</td> </tr>
<tr > <td > <a href= "#__evalVar" > evalVar</a> </td> <td > evaluate an expression stored in a variable</td> </tr>
</table>
<p > </p>
2006-03-09 06:28:34 +08:00
<subsection name= "§-num;.1 What can functions do" anchor= "what_can_do" >
2006-05-02 06:08:46 +08:00
<p > There are two kinds of functions: user-defined static values (or variables), and built-in functions.<br > </br>
2003-06-12 21:39:42 +08:00
User-defined static values allow the user to define variables to be replaced with their static value when
2002-07-13 11:17:49 +08:00
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>
2007-03-02 23:14:15 +08:00
<p >
Note that variables cannot currently be nested; i.e ${Var${N}} does not work.
2007-04-29 00:29:09 +08:00
The __V (variable) function (versions after 2.2) can be used to do this: ${__V(Var${N})}.
2007-03-02 23:14:15 +08:00
In earlier JMeter versions one can use ${__BeanShell(vars.get("Var${N}")}.
</p>
2002-07-13 11:17:49 +08:00
<p > This type of replacement is possible without functions, but was less convenient and less intuitive.
2007-06-03 20:08:50 +08:00
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>
2002-07-13 11:17:49 +08:00
<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>
2006-03-26 06:05:33 +08:00
<note > Functions are shared between threads.
Each occurrence of a function call in a test plan is handled by a separate function instance.</note>
2002-07-13 11:17:49 +08:00
</subsection>
2007-10-19 03:05:07 +08:00
<subsection name= "§-num;.2 Where can functions and variables be used?" anchor= "where" >
2007-06-03 20:08:50 +08:00
<p >
Functions and variables can be written into any field of any test component. Some fields do not allow random strings
2002-07-13 11:17:49 +08:00
because they are expecting numbers, and thus will not accept a function. However, most fields will allow
2007-06-03 20:08:50 +08:00
functions.
</p>
<p >
Configuration elements are processed by a separate thread.
Therefore functions such as __threadNum do not work properly in elements such as User Defined Variables.
</p>
2005-03-18 23:27:20 +08:00
<note > When using variable/function references in SQL code (etc),
remember to include any necessary quotes for text strings,
i.e. use<br > </br>
SELECT item from table where name='${VAR}'
<br > </br> <b > not</b>
<br > </br>
SELECT item from table where name=${VAR}
<br > </br> (unless VAR itself contains the quotes)
</note>
2002-07-13 11:17:49 +08:00
</subsection>
2007-10-19 03:05:07 +08:00
<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 '${' and '}'.</p>
<p > Functions are referenced in the same manner, but by convention, the names of
2006-09-18 07:02:36 +08:00
functions begin with "__" to avoid conflict with user value names<sup > *</sup> . Some functions take arguments to
2002-07-13 11:17:49 +08:00
configure them, and these go in parentheses, comma-delimited. If the function takes no arguments, the parentheses can
2007-10-19 03:05:07 +08:00
be omitted.</p>
2007-03-15 09:03:26 +08:00
<p > 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: '\,'.
This applies for example to the scripting functions - Javascript, Beanshell, Jexl - 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 >
2007-10-19 03:05:07 +08:00
Functions can reference variables and other functions, for example
<code > ${__XPath(${__P(xpath.file),${XPATH})}</code>
will use the property "xpath.file" as the file name
and the contents of the variable XPATH as the expression to search for.
</p>
<p >
2007-03-15 09:03:26 +08:00
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>
2007-10-19 03:05:07 +08:00
<p >
<b > The value of a variable or function can be reported</b> using the <a href= "#__logn" > __logn()</a> function.
The __logn() 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;
2007-10-20 08:12:18 +08:00
the output will be shown in the appropriate Listener.
2007-10-19 03:05:07 +08:00
For versions of JMeter later than 2.3, there is a <complink name= "Debug Sampler" />
that can be used to display the values of variables etc in the Tree View Listener.
</p>
2002-07-13 11:17:49 +08:00
<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>
2006-03-09 06:28:34 +08:00
<subsection name= "§-num;.4 The Function Helper Dialog" anchor= "function_helper" >
2002-08-10 03:08:55 +08:00
<p > The Function Helper dialog is available from JMeter's Tools menu.</p>
2007-11-24 10:32:03 +08:00
<figure width= "667" height= "326" image= "function_helper_dialog.png" > Function Helper Dialog</figure>
2002-08-10 03:08:55 +08:00
<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>
2006-03-09 06:28:34 +08:00
<subsection name= "§-num;.5 Functions" anchor= "functions" >
2003-10-09 02:49:41 +08:00
2006-03-09 06:28:34 +08:00
<component index= "§-num;.5.1" name= "__regexFunction" >
2003-10-09 02:49:41 +08:00
<description > <p > The Regex Function is used to parse the previous response using any regular
expression (provided by user). The function returns the template string with variable values filled
in.</p>
<p > The __regexFunction stores values for future use. In the sixth parameter, you can specify
a reference name. After this function executes, the same values can be retrieved at later times
using the syntax for user-defined values. For instance, if you enter "refName" as the sixth
parameter you will be able to use:
<ul >
<li > ${refName} to refer to the computed result of the second parameter ("Template for the
replacement string") parsed by this function</li>
<li > ${refName_g0} to refer to the entire match parsed by this function.</li>
<li > ${refName_g1} to refer to the first group parsed by this function.</li>
<li > ${refName_g#} to refer to the n<sup > th</sup> group parsed by this function.</li>
2004-10-06 22:43:57 +08:00
<li > ${refName_matchNr} to refer to the number of groups found by this function.</li>
2003-10-09 02:49:41 +08:00
</ul>
2004-10-06 22:43:57 +08:00
</p>
</description>
2003-10-09 02:49:41 +08:00
<properties >
2004-06-20 09:23:41 +08:00
<property name= "First argument" required= "Yes" > The first argument is the regular expression
2003-10-09 02:49:41 +08:00
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:
& lt;a href="(.*)"& gt;. This will grab the value of the link and store it as the first group (there is
only 1 group). Another example: & lt;input type="hidden" name="(.*)" value="(.*)"& gt;. 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:
$[group_number]$. Ie: $1$, or $2$. Your template can be any string.</property>
<property name= "Third argument" required= "Yes" > 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. '1' for the first found match, '2' for the
second, and so on</li>
<li > RAND - Tells JMeter to choose a match at random.</li>
<li > ALL - 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 Xth match using the formula:
(number_of_matches_found * float_number) rounded to nearest integer.</li>
</ul> </property>
<property name= "Fourth argument" required= "No" > If 'ALL' 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 ${refName} (the replacement template string) and ${refName_g#} where "#" is the
group number from the regular expression ("0" can be used to refer to the entire match).</property>
</properties>
</component>
2006-03-09 06:28:34 +08:00
<component index= "§-num;.5.2" name= "__counter" >
2003-10-09 02:49:41 +08:00
<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
2006-03-26 06:05:33 +08:00
separate, or to use the same counter for all users. If each user's values is incremented separately,
2003-10-09 02:49:41 +08:00
that is like counting the number of iterations through the test plan. A global counter is like
2006-03-26 06:05:33 +08:00
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 now completely independent.
[JMeter 2.1.1 and earlier used a fixed thread variable to keep track of the per-user count,
so multiple counter functions operated on the same value.]
The global counter - "FALSE" - is separately maintained by each counter instance.
</p>
</description>
2003-10-09 02:49:41 +08:00
<properties >
<property name= "First argument" required= "Yes" > TRUE if you wish each simulated user's counter
to be kept independent and separate from the other users. FALSE for a global counter.</property>
2006-03-26 06:05:33 +08:00
<property name= "Second argument" required= "No" > A reference name for reusing the value created by this function.<br > </br>
2003-10-09 02:49:41 +08:00
Stored values are of the form ${refName}. This allows you to keep one counter and refer to its value in
2006-03-26 06:05:33 +08:00
multiple places. [For JMeter 2.1.1 and earlier this parameter was required.]</property>
2003-10-09 02:49:41 +08:00
</properties>
</component>
2006-03-09 06:28:34 +08:00
<component index= "§-num;.5.3" name= "__threadNum" >
2003-10-09 02:49:41 +08:00
<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>
</description>
2007-06-03 20:08:50 +08:00
<note >
This function does not work in any Configuration elements (e.g. User Defined Variables) as these are run from a separate thread.
</note>
2003-10-09 02:49:41 +08:00
</component>
2007-11-28 02:13:56 +08:00
<component index= "§-num;.5.4a" name= "__intSum" >
2003-10-09 02:49:41 +08:00
<description > <p > The intsum function can be used to compute the sum of two or more integer values.
</p> </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 nth int value.</property>
<property name= "last argument" required= "Yes" > A reference name for reusing the value
computed by this function.</property>
</properties>
</component>
2007-11-28 02:13:56 +08:00
<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.
</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 nth long value.</property>
<property name= "last argument" required= "Yes" > A reference name for reusing the value
computed by this function.</property>
</properties>
</component>
2004-10-06 22:43:57 +08:00
<!-- Alternate spelling -->
2006-05-01 22:45:53 +08:00
<a name= "_StringFromFile" />
<component index= "§-num;.5.5" name= "__StringFromFile" >
2004-10-06 22:43:57 +08:00
2003-10-09 02:49:41 +08:00
<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>
2005-09-26 06:50:48 +08:00
<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>
2003-10-09 02:49:41 +08:00
<p >
Each time it is called it reads the next line from the file.
2004-10-06 22:43:57 +08:00
When the end of the file is reached, it will start reading again from the beginning,
unless the maximum loop count has been reached.
2003-10-09 02:49:41 +08:00
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>
<p > If an error occurs opening or reading the file, then the function returns the string "**ERR**"</p>
</description>
<properties >
2004-02-06 20:29:00 +08:00
<property name= "File Name" required= "Yes" > Path to the file name.
2003-10-09 02:49:41 +08:00
(The path can be relative to the JMeter launch directory)
2004-02-06 20:29:00 +08:00
If using optional sequence numbers, the path name should be suitable for passing to DecimalFormat.
See below for examples.
2003-10-09 02:49:41 +08:00
</property>
2004-02-06 20:29:00 +08:00
<property name= "Variable Name" required= "No" >
2003-10-09 02:49:41 +08:00
A reference name - refName - for reusing the value created by this function. Stored values are of the form ${refName}.
</property>
2004-10-06 22:43:57 +08:00
<property name= "Start sequence number" required= "No" > Initial Sequence number (if omitted, the End sequence number is treated as a loop count)</property>
2004-02-06 20:29:00 +08:00
<property name= "End sequence number" required= "No" > Final sequence number (if omitted, seqence numbers can increase without limit)</property>
2003-10-09 02:49:41 +08:00
</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>
2004-02-06 20:29:00 +08:00
<p > <b > Using sequence numbers:</b> </p>
<p > When using the optional sequence numbers, the path name is used as the format string for java.text.DecimalFormat.
The current sequence number is passed in as the only parameter.
2004-10-06 22:43:57 +08:00
If the optional start number is not specified, the path name is used as is.
2004-02-06 20:29:00 +08:00
Useful formatting sequences are:
2004-06-13 01:11:46 +08:00
</p>
<p >
<code >
2006-03-25 07:37:21 +08:00
# - insert the number, with no leading zeros or spaces<br > </br>
2005-09-07 07:40:33 +08:00
000 - insert the number packed out to 3 digits with leading zeros if necessary
2004-06-13 01:11:46 +08:00
<p />
2006-03-25 07:37:21 +08:00
Examples:<br > </br>
pin#'.'dat -> pin1.dat, ... pin9.dat, pin10.dat, ... pin9999.dat<br > </br>
pin000'.'dat -> pin001.dat ... pin099.dat ... pin999.dat ... pin9999.dat<br > </br>
2005-09-07 07:40:33 +08:00
pin'.'dat# -> pin.dat1, ... pin.dat9 ... pin.dat999
2004-06-13 01:11:46 +08:00
</code> <p />
2004-02-06 20:29:00 +08:00
If more digits are required than there are formatting characters, the number will be
2006-03-25 07:37:21 +08:00
expanded as necessary.<br > </br>
2005-09-07 07:40:33 +08:00
<b > To prevent a formatting character from being interpreted,
enclose it in single quotes. Note that "." is a formatting character,
and must be enclosed in single quotes</b>
(though #. and 000. work as expected in locales where the decimal point is also ".")
2006-03-25 07:37:21 +08:00
<br > </br>
2005-09-07 07:40:33 +08:00
In other locales (e.g. fr), the decimal point is "," - which means that "#."
2006-03-25 07:37:21 +08:00
becomes "nnn,".<br > </br>
See the documentation for DecimalFormat for full details.<br > </br>
2004-02-06 20:29:00 +08:00
If the path name does not contain any special formatting characters,
2004-10-06 22:43:57 +08:00
the current sequence number will be appended to the name, otherwise
2006-03-25 07:37:21 +08:00
the number will be inserted aaccording to the fomatting instructions.<br > </br>
2004-10-06 22:43:57 +08:00
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 "end" times.
In this case the filename is not formatted.
<code >
2006-03-25 07:37:21 +08:00
<br > </br>
${_StringFromFile(PIN#'.'DAT,,1,2)} - reads PIN1.DAT, PIN2.DAT<br > </br>
${_StringFromFile(PIN.DAT,,,2)} - reads PIN.DAT twice<br > </br>
2004-10-06 22:43:57 +08:00
</code>
2005-09-07 07:40:33 +08:00
Note that the "." in PIN.DAT above should <u > not</u> be quoted.
In this case the start number is omitted, so the file name is used exactly as is.
2004-02-06 20:29:00 +08:00
</p>
2003-10-09 02:49:41 +08:00
</component>
2006-03-09 06:28:34 +08:00
<component index= "§-num;.5.6" name= "__machineName" >
2003-10-09 02:49:41 +08:00
<description > <p > The machineName function returns the local host name</p> </description>
<properties >
<property name= "Name of function" required= "Yes" > A reference name for reusing the value
computed by this function.</property>
</properties>
</component>
2006-03-09 06:28:34 +08:00
<component index= "§-num;.5.7" name= "__javaScript" >
2006-04-08 21:42:03 +08:00
<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>
2007-09-06 20:00:38 +08:00
<p >
For details of the language, please see <a href= "http://www.mozilla.org/rhino/overview.html" > Mozilla Rhino Overview</a>
</p>
2007-11-10 03:39:07 +08:00
<p >
Versions of JMeter after 2.3 make the following variables available to the script:
</p>
<ul >
<li > ctx - JMeterContext object</li>
<li > vars - JMeterVariables object</li>
<li > threadName - String</li>
<li > sampler - current Sampler object (if any)</li>
<li > sampleResult - previous SampleResult object (if any)</li>
</ul>
2006-04-08 21:42:03 +08:00
<note >
JMeter is not a browser, and does not interpret the JavaScript in downloaded pages.
</note>
</description>
2003-10-09 02:49:41 +08:00
<properties >
<property name= "Expression" required= "Yes" > The JavaScript expression to be executed. For example:
<ul >
<li > new Date() - return the current date and time</li>
<li > Math.floor(Math.random()*(${maxRandom}+1))
- a random number between 0 and the variable maxRandom</li>
<li > ${minRandom}+Math.floor(Math.random()*(${maxRandom}-${minRandom}+1))
- a random number between the variables minRandom and maxRandom</li>
2005-09-04 07:57:52 +08:00
<li > "${VAR}"=="abcd"</li>
2003-10-09 02:49:41 +08:00
</ul>
</property>
2005-09-04 07:57:52 +08:00
<property name= "Name of function" required= "No" > A reference name for reusing the value
2003-10-09 02:49:41 +08:00
computed by this function.</property>
</properties>
2005-11-17 23:59:09 +08:00
<note > Remember to include any necessary quotes for text strings and JMeter variables. Also, if
2006-04-08 21:42:03 +08:00
the expression has commas, please make sure to escape them. For example in:
<br > </br>
${__javaScript('${sp}'.slice(7\,99999))}
<br > </br>
the comma after 7 is escaped.</note>
2003-10-09 02:49:41 +08:00
</component>
2006-03-09 06:28:34 +08:00
<component index= "§-num;.5.8" name= "__Random" >
2003-10-09 02:49:41 +08:00
<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= "Name of function" required= "Yes" > A reference name for reusing the value
computed by this function.</property>
</properties>
</component>
2006-03-09 06:28:34 +08:00
<component index= "§-num;.5.8" name= "__CSVRead" >
2003-10-09 02:49:41 +08:00
<description > <p > The CSVFile function returns a string from a CSV file (c.f. <a href= "#_StringFromFile" > StringFromFile</a> )</p>
2004-02-01 04:04:49 +08:00
<p > NOTE: versions up to 1.9.1 only supported a single file.
JMeter versions since 1.9.1 support multiple file names.
</p>
2005-09-26 06:50:48 +08:00
<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>
2004-02-01 04:04:49 +08:00
<p >
When a filename is first encountered, the file is opened and read into an internal
2004-02-12 17:31:11 +08:00
array. If a blank line is detected, this is treated as end of file - this allows
trailing comments to be used (N.B. this feature was introduced in versions after 1.9.1)
</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,
2004-02-01 04:04:49 +08:00
so CSVRead(abc.txt,0) and CSVRead(aBc.txt,0) would refer to different internal arrays.
</p>
<p >
The *ALIAS 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>
2007-01-19 09:33:30 +08:00
<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: csvread.delimiter
</p>
2004-02-01 04:04:49 +08:00
</description>
2003-10-09 02:49:41 +08:00
<properties >
2004-02-01 04:04:49 +08:00
<property name= "File Name" required= "Yes" > The file (or *ALIAS) to read from</property>
2003-10-09 02:49:41 +08:00
<property name= "Column number" required= "Yes" >
The column number in the file.
0 = first column, 1 = second etc.
"next" - go to next line of file.
2004-02-01 04:04:49 +08:00
*ALIAS - open a file and assign it to the alias
2003-10-09 02:49:41 +08:00
</property>
</properties>
</component>
2006-03-09 06:28:34 +08:00
<component index= "§-num;.5.9" name= "__property" >
2003-10-09 02:49:41 +08:00
<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 >
2004-06-13 01:11:46 +08:00
<ul >
<li > ${__property(user.dir)} - return value of user.dir</li>
<li > ${__property(user.dir,UDIR)} - return value of user.dir and save in UDIR</li>
<li > ${__property(abcd,ABCD,atod)} - return value of property abcd (or "atod" if not defined) and save in ABCD</li>
<li > ${__property(abcd,,atod)} - return value of property abcd (or "atod" if not defined) but don't save it</li>
</ul>
</p>
2003-10-09 02:49:41 +08:00
</description>
<properties >
<property name= "Property Name" required= "Yes" > The property name to be retrieved.</property>
<property name= "Name of function" 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>
2006-03-09 06:28:34 +08:00
<component index= "§-num;.5.10" name= "__P" >
2003-10-09 02:49:41 +08:00
<description > <p > This is a simplified property function which is
intended for use with properties defined on the command line.
2004-06-13 01:11:46 +08:00
Unlike the __property function, there is no option to save the value in a variable,
and if no default value is supplied, it is assumed to be 1.
The value of 1 was chosen because it is valid for common test variables such
as loops, thread count, ramp up etc.
2003-10-09 02:49:41 +08:00
</p> For example:<p >
<code >
Define the property value:
2006-03-25 07:37:21 +08:00
<br > </br>
2003-10-09 02:49:41 +08:00
jmeter -Jgroup1.threads=7 -Jhostname1=www.realhost.edu
2006-03-25 07:37:21 +08:00
<br > </br>
2003-10-09 02:49:41 +08:00
Fetch the values:
2006-03-25 07:37:21 +08:00
<br > </br>
2003-10-09 02:49:41 +08:00
${__P(group1.threads)} - return the value of group1.threads
2006-03-25 07:37:21 +08:00
<br > </br>
2003-10-09 02:49:41 +08:00
${__P(group1.loops)} - return the value of group1.loops
2006-03-25 07:37:21 +08:00
<br > </br>
2003-10-09 02:49:41 +08:00
${__P(hostname,www.dummy.org)} - return value of property hostname or www.dummy.org if not defined
2006-03-25 07:37:21 +08:00
<br > </br>
2004-06-13 01:11:46 +08:00
</code>
2003-10-09 02:49:41 +08:00
In the examples above, the first function call would return 7,
the second would return 1 and the last would return www.dummy.org
(unless those properties were defined elsewhere!)
2004-06-13 01:11:46 +08:00
</p>
2003-10-09 02:49:41 +08:00
</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 "1".</property>
</properties>
</component>
2006-03-09 06:28:34 +08:00
<component index= "§-num;.5.11" name= "__log" >
2004-02-01 04:04:49 +08:00
<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>
2004-06-20 09:23:41 +08:00
<property name= "Log Level" required= "No" > OUT, ERR, DEBUG, INFO (default), WARN or ERROR</property>
2004-02-01 04:04:49 +08:00
<property name= "Throwable text" required= "No" > If non-empty, creates a Throwable to pass to the logger</property>
</properties>
2004-06-20 09:23:41 +08:00
<p > The OUT and ERR log level names are used to direct the output to System.out and System.err respectively.
In this case, the output is always printed - it does not depend on the current log setting.
</p>
2007-10-19 03:05:07 +08:00
<pre >
For example:
${__log(Message)} - written to the log file
${__log(Message,OUT)} - written to console window
</pre>
2004-02-01 04:04:49 +08:00
</component>
2006-03-09 06:28:34 +08:00
<component index= "§-num;.5.12" name= "__logn" >
2004-02-01 04:04:49 +08:00
<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>
2004-06-20 09:23:41 +08:00
<property name= "Log Level" required= "No" > OUT, ERR, DEBUG, INFO (default), WARN or ERROR</property>
2004-02-01 04:04:49 +08:00
<property name= "Throwable text" required= "No" > If non-empty, creates a Throwable to pass to the logger</property>
</properties>
2004-06-20 09:23:41 +08:00
<p > The OUT and ERR log level names are used to direct the output to System.out and System.err respectively.
In this case, the output is always printed - it does not depend on the current log setting.
</p>
2007-10-19 03:05:07 +08:00
<pre >
For example:
${__logn(VAR1=${VAR1},OUT)} - write the value of the variable to the console window
</pre>
2004-02-01 04:04:49 +08:00
</component>
2006-03-09 06:28:34 +08:00
<component index= "§-num;.5.13" name= "__BeanShell" >
2004-02-01 04:04:49 +08:00
<description >
<p >
The BeanShell function evaluates the script passed to it, and returns the result.
2004-10-06 22:43:57 +08:00
</p>
<p >
2005-09-04 07:57:52 +08:00
<b > Please note that the BeanShell jar file is not included with JMeter; it needs to be separately downloaded.
2006-03-25 07:37:21 +08:00
<br > </br>
2007-09-06 20:00:38 +08:00
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>
2005-09-04 07:57:52 +08:00
</p>
<p >
2004-10-06 22:43:57 +08:00
Note that a different Interpreter is used for each independent occurence 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.
</p>
<p >
A single instance of a function may be called from multiple threads.
However the function execute() method is synchronised.
</p>
<p >
If the property "beanshell.function.init" is defined, it is passed to the Interpreter
as the name of a sourced file. This can be used to define common methods and variables. There is a
sample init file in the bin directory: BeanShellFunction.bshrc.
</p>
<p >
The following variables are set before the script is executed:
<ul >
<li > log - the logger for the BeanShell function (*)</li>
<li > ctx - the current JMeter context variable</li>
<li > vars - the current JMeter variables</li>
<li > threadName - the threadName</li>
<li > Sampler the current Sampler, if any</li>
<li > SampleResult - the current SampleResult, 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>
2004-02-01 04:04:49 +08:00
</description>
<properties >
2004-10-06 22:43:57 +08:00
<property name= "BeanShell script" required= "Yes" > A beanshell script (not a file name)</property>
2004-02-01 04:04:49 +08:00
<property name= "Name of variable" required= "No" > A reference name for reusing the value
computed by this function.</property>
2004-10-06 22:43:57 +08:00
</properties>
<p >
Example:
<pre >
${__BeanShell(123*456)} - returns 56088
${__BeanShell(source("function.bsh"))} - processes the script in function.bsh
</pre>
</p>
2005-09-04 07:57:52 +08:00
<note > Remember to include any necessary quotes for text strings and JMeter variables</note>
2004-10-06 22:43:57 +08:00
</component>
2006-03-09 06:28:34 +08:00
<component index= "§-num;.5.14" name= "__split" >
2004-10-06 22:43:57 +08:00
<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, "?" is returned as the value.
The split strings are returned in the variables ${VAR_1}, ${VAR_2} etc.
The count of variables is returned in ${VAR_n}.
2005-10-24 01:33:21 +08:00
From JMeter 2.1.2 onwards, a trailing delimiter is treated as a missing variable, and "?" is returned.
2006-03-24 03:54:27 +08:00
Also, to allow it to work better with the ForEach controller,
__split now deletes the first unused variable in case it was set by a previous split.
2004-10-06 22:43:57 +08:00
</p>
<p />
Example:
<code >
2006-03-25 07:37:21 +08:00
<br > </br>
2006-03-23 04:44:23 +08:00
Define VAR="a||c|" in the test plan.
2006-03-25 07:37:21 +08:00
<br > </br>
2006-03-23 04:44:23 +08:00
${__split(${VAR},VAR),|}
2006-03-25 07:37:21 +08:00
<br > </br>
2006-03-23 04:44:23 +08:00
This will return the contents of VAR, i.e. "a||c|" and set the following variables:
2006-03-25 07:37:21 +08:00
<br > </br>
2005-10-24 01:33:21 +08:00
VAR_n=4 (3 in JMeter 2.1.1 and earlier)
2006-03-25 07:37:21 +08:00
<br > </br>
2004-10-06 22:43:57 +08:00
VAR_1=a
2006-03-25 07:37:21 +08:00
<br > </br>
2004-10-06 22:43:57 +08:00
VAR_2=?
2006-03-25 07:37:21 +08:00
<br > </br>
2004-10-06 22:43:57 +08:00
VAR_3=c
2006-03-25 07:37:21 +08:00
<br > </br>
2005-10-24 01:33:21 +08:00
VAR_4=? (null in JMeter 2.1.1 and earlier)
2006-03-25 07:37:21 +08:00
<br > </br>
2006-03-24 03:54:27 +08:00
VAR_5=null (in JMeter 2.1.2 and later)
2004-10-06 22:43:57 +08:00
</code>
</description>
<properties >
<property name= "String to split" required= "Yes" > A delimited string, e.g. "a|b|c"</property>
<property name= "Name of variable" required= "Yes" > A reference name for reusing the value
computed by this function.</property>
2006-03-23 04:44:23 +08:00
<property name= "Delimiter" required= "No" > The delimiter character, e.g. <b > |</b> .
If omitted, <b > ,</b> is used. Note that <b > ,</b> would need to be specified as <b > \,</b> .
2004-10-06 22:43:57 +08:00
</property>
2004-02-01 04:04:49 +08:00
</properties>
</component>
2006-03-09 06:28:34 +08:00
<component index= "§-num;.5.15" name= "__XPath" >
2005-03-18 23:27:20 +08:00
<description >
<p >
2007-10-19 03:05:07 +08:00
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.
<note > Note that the entire file is held in memory, so this function should not be used for very large files.</note>
2005-03-18 23:27:20 +08:00
</p>
<p />
Example:
<code >
2006-03-25 07:37:21 +08:00
<br > </br>
2005-03-18 23:27:20 +08:00
2006-03-25 07:37:21 +08:00
<br > </br>
2005-03-18 23:27:20 +08:00
${__XPath(/path/to/build.xml, //target/@name)}
2006-03-25 07:37:21 +08:00
<br > </br>
2007-10-19 03:05:07 +08:00
This will match all targets in build.xml and return the contents of the next name attribute
2005-03-18 23:27:20 +08:00
</code>
</description>
2004-02-01 04:04:49 +08:00
2005-03-18 23:27:20 +08:00
<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>
2005-05-02 20:35:22 +08:00
2006-03-09 06:28:34 +08:00
<component index= "§-num;.5.16" name= "__setProperty" >
2005-05-02 20:35:22 +08:00
<description >
<p > The setProperty function sets the value of a JMeter property.
2005-10-18 01:31:05 +08:00
The default return value from the function is the empty string,
2005-05-02 20:35:22 +08:00
so the function call can be used anywhere functions are valid.</p>
2005-10-18 01:31:05 +08:00
<p > The original value can be returned by setting the optional 3rd parameter to "true".</p>
2005-05-02 20:35:22 +08:00
<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>
2006-05-02 02:42:19 +08:00
<property name= "True/False" required= "No" > Should the original value be returned?</property>
2005-05-02 20:35:22 +08:00
</properties>
</component>
2006-05-02 02:42:19 +08:00
<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.
</property>
<property name= "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.
Otherwise, the current time is passed to SimpleDateFormat.
The following shorthand aliases are provided:
</p>
<ul >
<li > YMD = yyyyMMdd</li>
<li > HMS = HHmmss</li>
<li > YMDHMS = yyyyMMdd-HHmmss</li>
<li > USER1 = whatever is in the Jmeter property time.USER1</li>
<li > USER2 = whatever is in the Jmeter property time.USER2</li>
</ul>
<p > The defaults can be changed by setting the appropriate JMeter property, e.g.
time.YMD=yyMMdd
</p>
</component>
2006-06-01 02:37:18 +08:00
<component index= "§-num;.5.18" name= "__jexl" >
<description >
<p > The jexl function returns the result of evaluating a
2007-11-10 03:39:07 +08:00
<a href= "http://jakarta.apache.org/commons/jexl" > Commons JEXL expression</a> .
See links below for more information on JEXL expressions.
2006-06-01 02:37:18 +08:00
</p>
2007-11-10 03:39:07 +08:00
<ul >
<li > <a href= "http://commons.apache.org/jexl/reference/syntax.html" > JEXL syntax description</a> </li>
<li > <a href= "http://commons.apache.org/jexl/reference/examples.html#Example_Expressions" > JEXL examples</a> </li>
</ul>
2006-06-01 02:37:18 +08:00
</description>
<properties >
<property name= "Expression" required= "Yes" >
The expression to be evaluated.
</property>
</properties>
2007-11-10 03:39:07 +08:00
<p >
JMeter 2.3 (and later versions) make the following variables available to the script:
</p>
<ul >
<li > ctx - JMeterContext object</li>
<li > vars - JMeterVariables object</li>
<li > threadName - String</li>
<li > sampler - current Sampler object (if any)</li>
<li > sampleResult - previous SampleResult object (if any)</li>
</ul>
2006-06-01 02:37:18 +08:00
</component>
2007-03-02 23:14:15 +08:00
<component index= "§-num;.5.19" name= "__V" >
<description >
<p > The V (variable) function returns the result of evaluating a variable name expression.
2007-03-02 23:26:11 +08:00
This can be used to evaluate nested variable references (which are not currently supported).
2007-03-02 23:14:15 +08:00
</p>
2007-03-02 23:26:11 +08:00
<p > For example, if one has variables A1,A2 and N=1:</p>
<ul >
<li > ${A1} - works OK</li>
<li > ${A${N}} - does not work (nested variable reference)</li>
<li > ${__V(A${N})} - works OK. A${N} becomes A1, and the __V function returns the value of A1</li>
</ul>
2007-03-02 23:14:15 +08:00
</description>
<properties >
<property name= "Variable name" required= "Yes" >
The variable to be evaluated.
</property>
</properties>
</component>
2006-05-02 02:42:19 +08:00
2007-09-26 22:03:31 +08:00
<component index= "§-num;.5.20" name= "__evalVar" >
<description >
<p > The eval 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 "query" contains "select ${column} from ${table}"
and "column" and "table" contain "name" and "customers", then ${__evalVar(query)}
will evaluate as "select name from customers".
</p>
</description>
<properties >
<property name= "Variable name" required= "Yes" >
The variable to be evaluated.
</property>
</properties>
</component>
<component index= "§-num;.5.21" name= "__eval" >
<description >
<p > The eval function returns the result of evaluating an expression.
</p>
<p >
This allows one to interpolate variable and function references in a string.
For example, if "column" and "table" contain "name" and "customers",
then ${__eval(select ${column} from ${table})}
will evaluate as "select name from customers".
</p>
</description>
<properties >
<property name= "Variable name" required= "Yes" >
The variable to be evaluated.
</property>
</properties>
</component>
2003-10-09 02:49:41 +08:00
</subsection>
2006-05-02 06:08:46 +08:00
<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 > cookiename - contains the cookie value</li>
<li > JMeterThread.last_sample_ok - whether or not the last sample was OK - true/false</li>
2007-09-06 20:00:38 +08:00
<li > START variables (see next section)</li>
2006-05-02 06:08:46 +08:00
</ul>
</subsection>
<subsection name= "§-num;.6 Pre-defined Properties" anchor= "predefinedprops" >
<p >
2007-09-06 20:00:38 +08:00
The set of JMeter properties is initialised from the system properties defined when JMeter starts;
additional JMeter properties are defined in jmeter.properties, user.properties or on the command line.
</p>
<p >
Some built-in properties are defined by JMeter. These are listed below.
For convenience, the START properties are also copied to variables with the same names.
2006-05-02 06:08:46 +08:00
</p>
<ul >
<li > START.MS - start time in milliseconds</li>
<li > START.YMD - start time as yyyyMMdd</li>
<li > START.HMS - start time as HHmmss</li>
</ul>
</subsection>
2002-07-13 11:17:49 +08:00
</section>
</body>
2004-10-06 22:43:57 +08:00
</document>
