2002-07-13 11:17:49 +08:00
<?xml version="1.0"?>
2003-06-11 23:49:30 +08:00
<document prev= "component_reference.html" next= "glossary.html" date= "$Date$" >
2002-07-13 11:17:49 +08:00
<properties >
<title > User's Manual: Introduction</title>
</properties>
<body >
<section name= "14. Functions" anchor= "functions" >
<p >
JMeter functions are special values that can populate fields of any Sampler or other configuration
element in a test tree. A function looks like this:</p>
<p > <code > ${__functionName(var1,var2,var3)}</code> </p>
<p > Where "__functionName" matches the name of an existing built-in or user-defined function.<br />
Parentheses surround the parameters sent to the function. The actual parameters vary from function
to function. Functions that require no parameters can leave off the parentheses. The function itself
is wrapped in ${}.</p>
<subsection name= "14.1 What can functions do" anchor= "what_can_do" >
<p > There are two kinds of functions: user-defined static values, and built-in functions.<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>
<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. User-defined
2003-06-12 21:39:42 +08:00
functions 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>
</subsection>
<subsection name= "14.2 Where can functions be used?" anchor= "where" >
<p > A user-defined function can be written into any field of any test component. 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 > Built-in functions can be written into any field of non-controller test components. This includes
Samplers, Timers, Listeners, Modifiers, Assertions, and Config Elements.</p>
</subsection>
<subsection name= "14.3 Writing the function string" anchor= "how" >
<p > User-defined functions take the form: <code > ${varName}</code> . In the TestPlan tree element, a two-column table
of user-defined values is kept, matching up variable names with static values. Referencing the
variable in a test element is done by bracketing the variable name with '${' and '}'.</p>
<p > Built-in functions are written in the same manner, but by convention, the names of built-in
parameters begin with "__" 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 left out. A further complication for argument values that themselves contain commas is that the value
2003-06-13 22:51:51 +08:00
should be escaped as necessary. Thus, if you need to include a comma in your parameter value, escape it like so: '\,'. 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>
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>
2002-08-10 03:08:55 +08:00
<subsection name= "14.4 The Function Helper Dialog" anchor= "function_helper" >
<p > The Function Helper dialog is available from JMeter's Tools menu.</p>
2003-06-13 22:51:51 +08:00
<figure 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>
2003-10-09 02:49:41 +08:00
<subsection name= "14.5 Functions" anchor= "functions" >
<component index= "14.5.1" name= "__regexFunction" >
<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>
</ul>
</p> </description>
<properties >
<property name= "First arguement" 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:
& 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>
<component index= "14.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 user. 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> </description>
<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>
2003-10-11 00:12:04 +08:00
<property name= "Second argument" required= "Yes" > 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
multiple places.</property>
</properties>
</component>
<component index= "14.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>
</description>
</component>
<component index= "14.5.4" name= "__intSum" >
<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>
<component index= "14.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 >
Each time it is called it reads the next line from the file.
When the end of the file is reached, it will start reading again from the beginning.
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 >
<property name= "First argument" required= "Yes" > Path to the file name.
(The path can be relative to the JMeter launch directory)
</property>
<property name= "Second argument" required= "No" >
A reference name - refName - for reusing the value created by this function. Stored values are of the form ${refName}.
</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>
</component>
<component index= "14.5.6" name= "__machineName" >
<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>
<component index= "14.5.7" name= "__javaScript" >
<description > <p > The javaScript function executes a piece of JavaScript (not Java!) code and returns its value</p>
</description>
<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>
</ul>
</property>
<property name= "Name of function" required= "Yes" > A reference name for reusing the value
computed by this function.</property>
</properties>
</component>
<component index= "14.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= "Name of function" required= "Yes" > A reference name for reusing the value
computed by this function.</property>
</properties>
</component>
<component index= "14.5.8" name= "__CSVRead" >
<description > <p > The CSVFile function returns a string from a CSV file (c.f. <a href= "#_StringFromFile" > StringFromFile</a> )</p>
<p > NOTE: A single instance of the file is opened and used for all threads.</p> </description>
<properties >
<property name= "File Name" required= "Yes" > The file to read from</property>
<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.
</property>
</properties>
</component>
<component index= "14.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 >
<code >
<pre >
${__property(user.dir)} - return value of user.dir
${__property(user.dir,UDIR)} - return value of user.dir and save in UDIR
${__property(abcd,ABCD,atod)} - return value of property abcd (or "atod" if not defined) and save in ABCD
${__property(abcd,,atod)} - return value of property abcd (or "atod" if not defined) but don't save it
</pre>
</code> </p>
</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>
<component index= "14.5.10" name= "__P" >
<description > <p > This is a simplified property function which is
intended for use with properties defined on the command line.
If the property is not found, the default is returned.
If no default was provided, then returns 1.
</p> For example:<p >
<code >
<pre >
Define the property value:
jmeter -Jgroup1.threads=7 -Jhostname1=www.realhost.edu
Fetch the values:
${__P(group1.threads)} - return the value of group1.threads
${__P(group1.loops)} - return the value of group1.loops
${__P(hostname,www.dummy.org)} - return value of property hostname or www.dummy.org if not defined
</pre>
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!)
</code> </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 "1".</property>
</properties>
</component>
</subsection>
2002-07-13 11:17:49 +08:00
</section>
</body>
</document>
