| <!DOCTYPE html SYSTEM "about:legacy-compat"> |
| <html lang="en"><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-15"><title>Apache JMeter |
| - |
| User's Manual: Functions and Variables</title><meta name="viewport" content="width=device-width, initial-scale=1"><link href="http://fonts.googleapis.com/css?family=Merriweather:400normal" rel="stylesheet" type="text/css"><link rel="stylesheet" type="text/css" href="../css/new-style.css"></head><body role="document"><a href="#content" class="hidden">Main content</a><div class="header"><!-- |
| APACHE LOGO |
| --><div><a href="http://www.apache.org"><img title="Apache Software Foundation" width="290" height="75" src="../images/asf-logo.png" alt="Logo ASF"></a></div><!-- |
| PROJECT LOGO |
| --><div><a href="http://jmeter.apache.org/"><img src="../images/logo.jpg" alt="Apache JMeter"></a></div><div class="twitter"><div><a href="https://twitter.com/share" class="twitter-share-button" data-text="Powerful Load Testing with Apache #JMeter" data-via="ApacheJMeter" data-lang="en-gb" data-size="large">Tweet</a><script> |
| (function(d,s,id){ |
| var js, |
| fjs=d.getElementsByTagName(s)[0], |
| p=/^http:/.test(d.location)?'http':'https'; |
| if (!d.getElementById(id)) { |
| js=d.createElement(s); |
| js.id=id; |
| js.src=p+'://platform.twitter.com/widgets.js'; |
| fjs.parentNode.insertBefore(js,fjs); |
| } |
| })(document, 'script', 'twitter-wjs'); |
| </script></div><div><a href="https://twitter.com/ApacheJMeter" class="twitter-follow-button" data-show-count="false" data-lang="en-gb" data-size="large">Follow</a><script>(function(d,s,id){ |
| var js, |
| fjs=d.getElementsByTagName(s)[0], |
| p=/^http:/.test(d.location)?'http':'https'; |
| if (!d.getElementById(id)) { |
| js=d.createElement(s); |
| js.id=id; |
| js.src=p+'://platform.twitter.com/widgets.js'; |
| fjs.parentNode.insertBefore(js,fjs); |
| } |
| })(document, 'script', 'twitter-wjs'); |
| </script></div></div><div class="banner"><iframe src="http://www.apache.org/ads/bannerbar.html" style="border-width:0;" frameborder="0" scrolling="no"></iframe><div class="clear"></div></div></div><div class="nav"><ul class="menu"><li><div class="menu-title">About</div><ul><li><a href="../index.html">Overview</a></li><li><a href="http://twitter.com/ApacheJMeter">JMeter on Twitter<img src="../images/twitter.png" alt="Icon for JMeter on Twitter"></a></li><li><a href="../issues.html">Issue Tracking</a></li><li><a href="http://projects.apache.org/feeds/rss/jmeter.xml">Subscribe to What's New</a></li><li><a href="http://www.apache.org/licenses/">License</a></li></ul></li></ul><ul class="menu"><li><div class="menu-title">Download</div><ul><li><a href="../download_jmeter.cgi">Download Releases</a></li><li><a href="../nightly.html">Developer (Nightly) Builds</a></li></ul></li></ul><ul class="menu"><li><div class="menu-title">Documentation</div><ul><li><a href="../changes.html">Changes per version</a></li><li><a href="../usermanual/get-started.html">Get Started</a></li><li><a href="../usermanual/index.html">User Manual</a></li><li><a href="../usermanual/best-practices.html">Best Practices</a></li><li><a href="../usermanual/component_reference.html">Component Reference</a></li><li><a href="../usermanual/functions.html">Functions Reference</a></li><li><a href="../api/index.html">Javadocs</a></li><li><a href="../building.html">Building JMeter and Add-Ons</a></li><li><a href="http://wiki.apache.org/jmeter">JMeter Wiki</a></li><li><a href="http://wiki.apache.org/jmeter/JMeterFAQ">FAQ (Wiki)</a></li></ul></li></ul><ul class="menu"><li><div class="menu-title">Tutorials (PDF format)</div><ul><li><a href="../usermanual/jmeter_distributed_testing_step_by_step.pdf">Distributed Testing</a></li><li><a href="../usermanual/jmeter_proxy_step_by_step.pdf">Recording Tests</a></li><li><a href="../usermanual/junitsampler_tutorial.pdf">JUnit Sampler</a></li><li><a href="../usermanual/jmeter_accesslog_sampler_step_by_step.pdf">Access Log Sampler</a></li><li><a href="../extending/jmeter_tutorial.pdf">Extending JMeter</a></li></ul></li></ul><ul class="menu"><li><div class="menu-title">Community</div><ul><li><a href="http://wiki.apache.org/jmeter/JMeterCommitters">Contributors</a></li><li><a href="../mail.html">Mailing Lists</a></li><li><a href="../svnindex.html">SVN Repositories</a></li></ul></li></ul><ul class="menu"><li><div class="menu-title">Foundation</div><ul><li><a href="http://www.apache.org/">ASF</a></li><li><a href="http://www.apache.org/foundation/getinvolved.html">Get Involved in the ASF</a></li><li><a href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li><li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li></ul></li></ul></div><div class="main" id="content"><ul class="pagelinks"><li><a href="component_reference.html">< Prev</a></li><li><a href="../index.html">Index</a></li><li><a href="regular_expressions.html">Next ></a></li></ul><div class="section"><h1 id="functions">19. Functions and Variables<a class="sectionlink" href="#functions" title="Link to here">¶</a></h1> |
| <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><span class="code">${__functionName(var1,var2,var3)}</span></p> |
| |
| <p> |
| Where "__functionName" matches the name of a function. |
| <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> |
| |
| <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> |
| If the comma is not escaped - e.g. <span class="code">${__javaScript(Math.max(2,5))}</span> - you will get an error such as: |
| <pre> |
| ERROR - jmeter.functions.JavaScript: Error processing Javascript: [Math.max(2] |
| org.mozilla.javascript.EvaluatorException: missing ) after argument list (<cmd>#1) |
| </pre> |
| This is because the string "Math.max(2,5)" is treated as being two parameters to the __javascript function:<br> |
| <span class="code">Math.max(2</span> and <span class="code">5)</span><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 UNDEF is not defined as a variable, then the value of ${UNDEF} is ${UNDEF}. |
| </b> |
| Variables, functions (and properties) are all case-sensitive. |
| <b> |
| Versions of JMeter after 2.3.1 trim spaces from variable names before use, so for example |
| ${__Random(1,63, LOTTERY )} will use the variable 'LOTTERY' rather than ' LOTTERY '. |
| </b> |
| </p> |
| <div class="clear"></div><div class="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 __P or __property function. |
| </div><div class="clear"></div> |
| <div class="clear"></div><div class="note"> |
| When using \ before a variable for a windows path for example C:\test\${test}, ensure you escape the \ otherwise JMeter will not interpret the variable, example: |
| C:\\test\\${test}. |
| <br> |
| Alternatively, just use / instead for the path separator - e.g. C:/test/${test} - Windows JVMs will convert the separators as necessary. |
| </div><div class="clear"></div> |
| <p>List of functions, loosely grouped into types.</p> |
| <table> |
| |
| <tr><th>Type of function</th><th>Name</th><th>Comment</th><th>Since</th></tr> |
| |
| <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="#__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="#__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 (Mozilla Rhino)</td><td>1.9</td></tr> |
| <tr><td>Scripting</td><td> <a href="#__jexl">jexl, jexl2</a></td><td>evaluate a Commons Jexl expression</td><td>jexl(2.2), jexl2(2.6)</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="#__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> |
| <div class="subsection"><h2>19.1 What can functions do<a class="sectionlink" href="#what_can_do" title="Link to here">¶</a></h2> |
| <p>There are two kinds of functions: user-defined static values (or variables), and built-in functions.<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 ${Var${N}} does not work. |
| The __V (variable) function (versions after 2.2) can be used to do this: ${__V(Var${N})}. |
| In earlier JMeter versions one can use ${__BeanShell(vars.get("Var${N}")}. |
| </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> |
| <div class="clear"></div><div class="note">Functions are shared between threads. |
| Each occurrence of a function call in a test plan is handled by a separate function instance.</div><div class="clear"></div> |
| </div> |
| |
| <div class="subsection"><h2>19.2 Where can functions and variables be used?<a class="sectionlink" href="#where" title="Link to here">¶</a></h2> |
| <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 split() and regex() and the variable evaluation functions won't work. |
| The threadNum() function won't work (and does not make sense at test plan level). |
| The following functions should work OK on the test plan: |
| <ul> |
| <li>intSum</li> |
| <li>longSum</li> |
| <li>machineName</li> |
| <li>BeanShell</li> |
| <li>javaScript</li> |
| <li>jexl</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 __threadNum 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> |
| <div class="clear"></div><div class="note">When using variable/function references in SQL code (etc), |
| remember to include any necessary quotes for text strings, |
| i.e. use<br> |
| SELECT item from table where name='${VAR}' |
| <br><b>not</b> |
| <br> |
| SELECT item from table where name=${VAR} |
| <br>(unless VAR itself contains the quotes) |
| </div><div class="clear"></div> |
| </div> |
| |
| <div class="subsection"><h2>19.3 How to reference variables and functions<a class="sectionlink" href="#how" title="Link to here">¶</a></h2> |
| <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 |
| functions 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 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: '\,'.</b> |
| 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> |
| 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 SCRIPT variable because the function call is parsed before the variable is replaced with its value. |
| This works well in conjunction with the BSF 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 |
| <span class="code">${__XPath(${__P(xpath.file),${XPATH})}</span> |
| 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> |
| 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> |
| <div class="clear"></div><div class="note"> |
| If a string contains a backslash('\') and also contains a function or variable reference, the backslash will be removed if |
| it appears before '$' or ',' or '\'. |
| This behaviour is necessary to allow for nested functions that include commas or the string ${. |
| Backslashes before '$' or ',' or '\' are not removed if the string does not contain a function or variable reference. |
| </div><div class="clear"></div> |
| <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; |
| the output will be shown in the appropriate Listener. |
| For versions of JMeter later than 2.3, there is a <a href="../usermanual/component_reference.html#Debug_Sampler">Debug Sampler</a> |
| that can be used to display the values of variables etc in the Tree View Listener. |
| </p> |
| <div class="clear"></div><div class="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.</div><div class="clear"></div> |
| </div> |
| |
| <div class="subsection"><h2>19.4 The Function Helper Dialog<a class="sectionlink" href="#function_helper" title="Link to here">¶</a></h2> |
| <p>The Function Helper dialog is available from JMeter's Tools menu.</p> |
| <figure><a href="../images/screenshots/function_helper_dialog.png"><img src="../images/screenshots/function_helper_dialog.png" width="831" height="305" alt="Function Helper Dialog"></a><figcaption>Function Helper Dialog</figcaption></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> |
| </div> |
| |
| <div class="subsection"><h2>19.5 Functions<a class="sectionlink" href="#functions" title="Link to here">¶</a></h2> |
| |
| <div class="component"><h2 id="__regexFunction">__regexFunction<a class="sectionlink" href="#__regexFunction" title="Link to here">¶</a></h2> |
| <div class="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 __regexFunction 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 "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> |
| <li>${refName_matchNr} to refer to the number of groups found by this function.</li> |
| </ul> |
| <div class="clear"></div><div class="note">If using distributed testing, ensure you switch mode (see jmeter.properties) so that it's not a stripping one, see <a href="http://bz.apache.org/bugzilla/show_bug.cgi?id=56376"> |
| Bug |
| 56376</a></div><div class="clear"></div> |
| </p> |
| </div> |
| |
| <div class="properties"><h3 id="__regexFunction_parms1"> |
| Parameters |
| <a class="sectionlink" href="#__regexFunction_parms1" title="Link to here">¶</a></h3><div class="property title"><div class="name title">Attribute</div><div class="description title">Description</div><div class="required title">Required</div></div> |
| <div class="property"><div class="name req-true">First argument</div><div class="description req-true">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: |
| <a href="(.*)">. This will grab the value of the link and store it as the first group (there is |
| only 1 group). Another example: <input type="hidden" name="(.*)" value="(.*)">. 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</div><div class="required req-true">Yes</div></div> |
| <div class="property"><div class="name req-true">Second argument</div><div class="description req-true">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.</div><div class="required req-true">Yes</div></div> |
| <div class="property"><div class="name req-false">Third argument</div><div class="description req-false">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></div><div class="required req-false">No, default=1</div></div> |
| <div class="property"><div class="name req-false">Fourth argument</div><div class="description req-false">If 'ALL' was selected for the above argument |
| value, then this argument will be inserted between each appended copy of the template value.</div><div class="required req-false">No</div></div> |
| <div class="property"><div class="name req-false">Fifth argument</div><div class="description req-false">Default value returned if no match is found</div><div class="required req-false">No</div></div> |
| <div class="property"><div class="name req-false">Sixth argument</div><div class="description req-false">A reference name for reusing the values parsed by this function.<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).</div><div class="required req-false">No</div></div> |
| <div class="property"><div class="name req-false">Seventh argument</div><div class="description req-false">Input variable name. |
| If specified, then the value of the variable is used as the input instead of using the previous sample result. |
| </div><div class="required req-false">No</div></div> |
| </div> |
| <div class="go-top"><a href="#">^</a></div></div> |
| |
| <div class="component"><h2 id="__counter">__counter<a class="sectionlink" href="#__counter" title="Link to here">¶</a></h2> |
| <div class="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 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> |
| <p> |
| <b> |
| Multiple __counter 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 <a href="../usermanual/component_reference.html#User_Parameters">User Parameters</a>. |
| </p> |
| </div> |
| <div class="properties"><h3 id="__counter_parms1"> |
| Parameters |
| <a class="sectionlink" href="#__counter_parms1" title="Link to here">¶</a></h3><div class="property title"><div class="name title">Attribute</div><div class="description title">Description</div><div class="required title">Required</div></div> |
| <div class="property"><div class="name req-true">First argument</div><div class="description req-true">TRUE if you wish each simulated user's counter |
| to be kept independent and separate from the other users. FALSE for a global counter.</div><div class="required req-true">Yes</div></div> |
| |
| <div class="property"><div class="name req-false">Second argument</div><div class="description req-false">A reference name for reusing the value created by this function.<br> |
| Stored values are of the form ${refName}. This allows you to keep one counter and refer to its value in |
| multiple places. [For JMeter 2.1.1 and earlier this parameter was required.]</div><div class="required req-false">No</div></div> |
| </div> |
| <div class="go-top"><a href="#">^</a></div></div> |
| |
| <div class="component"><h2 id="__threadNum">__threadNum<a class="sectionlink" href="#__threadNum" title="Link to here">¶</a></h2> |
| <div class="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> |
| </div> |
| <div class="clear"></div><div class="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. |
| </div><div class="clear"></div> |
| <div class="go-top"><a href="#">^</a></div></div> |
| |
| <div class="component"><h2 id="__intSum">__intSum<a class="sectionlink" href="#__intSum" title="Link to here">¶</a></h2> |
| <div class="description"> |
| <p> |
| The intSum function can be used to compute the sum of two or more integer values. |
| </p> |
| <div class="clear"></div><div class="note"> |
| JMeter Versions 2.3.1 and earlier required the reference name to be present. |
| The reference name is now optional, but it must not be a valid integer. |
| </div><div class="clear"></div> |
| </div> |
| |
| <div class="properties"><h3 id="__intSum_parms1"> |
| Parameters |
| <a class="sectionlink" href="#__intSum_parms1" title="Link to here">¶</a></h3><div class="property title"><div class="name title">Attribute</div><div class="description title">Description</div><div class="required title">Required</div></div> |
| <div class="property"><div class="name req-true">First argument</div><div class="description req-true">The first int value.</div><div class="required req-true">Yes</div></div> |
| <div class="property"><div class="name req-true">Second argument</div><div class="description req-true">The second int value.</div><div class="required req-true">Yes</div></div> |
| <div class="property"><div class="name req-false">nth argument</div><div class="description req-false">The nth int value.</div><div class="required req-false">No</div></div> |
| <div class="property"><div class="name req-false">last argument</div><div class="description req-false">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. |
| </div><div class="required req-false">No</div></div> |
| </div> |
| <div class="go-top"><a href="#">^</a></div></div> |
| |
| <div class="component"><h2 id="__longSum">__longSum<a class="sectionlink" href="#__longSum" title="Link to here">¶</a></h2> |
| <div class="description"><p>The longSum function can be used to compute the sum of two or more long values. |
| </p></div> |
| |
| <div class="properties"><h3 id="__longSum_parms1"> |
| Parameters |
| <a class="sectionlink" href="#__longSum_parms1" title="Link to here">¶</a></h3><div class="property title"><div class="name title">Attribute</div><div class="description title">Description</div><div class="required title">Required</div></div> |
| <div class="property"><div class="name req-true">First argument</div><div class="description req-true">The first long value.</div><div class="required req-true">Yes</div></div> |
| <div class="property"><div class="name req-true">Second argument</div><div class="description req-true">The second long value.</div><div class="required req-true">Yes</div></div> |
| <div class="property"><div class="name req-false">nth argument</div><div class="description req-false">The nth long value.</div><div class="required req-false">No</div></div> |
| <div class="property"><div class="name req-false">last argument</div><div class="description req-false">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. |
| </div><div class="required req-false">No</div></div> |
| </div> |
| <div class="go-top"><a href="#">^</a></div></div> |
| |
| |
| <a name="_StringFromFile"></a> |
| <div class="component"><h2 id="__StringFromFile">__StringFromFile<a class="sectionlink" href="#__StringFromFile" title="Link to here">¶</a></h2> |
| |
| <div class="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> |
| <div class="clear"></div><div class="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 threadNumber as part of the file name |
| will result in unpredictable behaviour. |
| </div><div class="clear"></div> |
| <p>If an error occurs opening or reading the file, then the function returns the string "**ERR**"</p> |
| </div> |
| |
| <div class="properties"><h3 id="__StringFromFile_parms1"> |
| Parameters |
| <a class="sectionlink" href="#__StringFromFile_parms1" title="Link to here">¶</a></h3><div class="property title"><div class="name title">Attribute</div><div class="description title">Description</div><div class="required title">Required</div></div> |
| <div class="property"><div class="name req-true">File Name</div><div class="description req-true">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. |
| </div><div class="required req-true">Yes</div></div> |
| <div class="property"><div class="name req-false">Variable Name</div><div class="description req-false"> |
| A reference name - refName - for reusing the value created by this function. Stored values are of the form ${refName}. |
| Defaults to "StringFromFile_". |
| </div><div class="required req-false">No</div></div> |
| <div class="property"><div class="name req-false">Start sequence number</div><div class="description req-false">Initial Sequence number (if omitted, the End sequence number is treated as a loop count)</div><div class="required req-false">No</div></div> |
| <div class="property"><div class="name req-false">End sequence number</div><div class="description req-false">Final sequence number (if omitted, seqence numbers can increase without limit)</div><div class="required req-false">No</div></div> |
| </div> |
| <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 java.text.DecimalFormat. |
| 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> |
| <p> |
| <span class="code"> |
| # - insert the number, with no leading zeros or spaces<br> |
| 000 - insert the number packed out to 3 digits with leading zeros if necessary |
| <p></p> |
| Examples:<br> |
| pin#'.'dat -> pin1.dat, ... pin9.dat, pin10.dat, ... pin9999.dat<br> |
| pin000'.'dat -> pin001.dat ... pin099.dat ... pin999.dat ... pin9999.dat<br> |
| pin'.'dat# -> pin.dat1, ... pin.dat9 ... pin.dat999 |
| </span><p></p> |
| If more digits are required than there are formatting characters, the number will be |
| expanded as necessary.<br> |
| <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 ".") |
| <br> |
| In other locales (e.g. fr), the decimal point is "," - which means that "#." |
| becomes "nnn,".<br> |
| See the documentation for DecimalFormat for full details.<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 aaccording to the fomatting instructions.<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 "end" times. |
| In this case the filename is not formatted. |
| <span class="code"> |
| <br> |
| ${_StringFromFile(PIN#'.'DAT,,1,2)} - reads PIN1.DAT, PIN2.DAT<br> |
| ${_StringFromFile(PIN.DAT,,,2)} - reads PIN.DAT twice<br> |
| </span> |
| 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. |
| </p> |
| <div class="go-top"><a href="#">^</a></div></div> |
| |
| <div class="component"><h2 id="__machineName">__machineName<a class="sectionlink" href="#__machineName" title="Link to here">¶</a></h2> |
| <div class="description"><p>The machineName function returns the local host name</p></div> |
| |
| <div class="properties"><h3 id="__machineName_parms1"> |
| Parameters |
| <a class="sectionlink" href="#__machineName_parms1" title="Link to here">¶</a></h3><div class="property title"><div class="name title">Attribute</div><div class="description title">Description</div><div class="required title">Required</div></div> |
| <div class="property"><div class="name req-false">Variable Name</div><div class="description req-false">A reference name for reusing the value |
| computed by this function.</div><div class="required req-false">No</div></div> |
| </div> |
| <div class="go-top"><a href="#">^</a></div></div> |
| |
| <div class="component"><h2 id="__machineIP">__machineIP<a class="sectionlink" href="#__machineIP" title="Link to here">¶</a></h2> |
| <div class="description"><p>The machineIP function returns the local IP address</p></div> |
| |
| <div class="properties"><h3 id="__machineIP_parms1"> |
| Parameters |
| <a class="sectionlink" href="#__machineIP_parms1" title="Link to here">¶</a></h3><div class="property title"><div class="name title">Attribute</div><div class="description title">Description</div><div class="required title">Required</div></div> |
| <div class="property"><div class="name req-false">Variable Name</div><div class="description req-false">A reference name for reusing the value |
| computed by this function.</div><div class="required req-false">No</div></div> |
| </div> |
| <div class="go-top"><a href="#">^</a></div></div> |
| |
| <div class="component"><h2 id="__javaScript">__javaScript<a class="sectionlink" href="#__javaScript" title="Link to here">¶</a></h2> |
| <div class="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> |
| For details of the language, 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>log - the logger for the function</li> |
| <li>ctx - JMeterContext object</li> |
| <li>vars - JMeterVariables object</li> |
| <li>threadName - String containing the current thread name (in 2.3.2 it was misspelt as "theadName")</li> |
| <li>sampler - current Sampler object (if any)</li> |
| <li>sampleResult - previous SampleResult object (if any)</li> |
| <li>props - JMeter Properties object</li> |
| </ul> |
| <p> |
| Rhinoscript allows access to static methods via its Packages object. |
| See the <a href="http://www.mozilla.org/rhino/ScriptingJava.html">Scripting Java</a> documentation. |
| For example one can access the JMeterContextService static methods thus: |
| <span class="code">Packages.org.apache.jmeter.threads.JMeterContextService.getTotalThreads()</span> |
| </p> |
| <div class="clear"></div><div class="note"> |
| JMeter is not a browser, and does not interpret the JavaScript in downloaded pages. |
| </div><div class="clear"></div> |
| </div> |
| |
| <div class="properties"><h3 id="__javaScript_parms1"> |
| Parameters |
| <a class="sectionlink" href="#__javaScript_parms1" title="Link to here">¶</a></h3><div class="property title"><div class="name title">Attribute</div><div class="description title">Description</div><div class="required title">Required</div></div> |
| <div class="property"><div class="name req-true">Expression</div><div class="description req-true">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> |
| <li>"${VAR}"=="abcd"</li> |
| </ul> |
| </div><div class="required req-true">Yes</div></div> |
| <div class="property"><div class="name req-false">Variable Name</div><div class="description req-false">A reference name for reusing the value |
| computed by this function.</div><div class="required req-false">No</div></div> |
| </div> |
| <div class="clear"></div><div class="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: |
| <br> |
| ${__javaScript('${sp}'.slice(7\,99999))} |
| <br> |
| the comma after 7 is escaped.</div><div class="clear"></div> |
| <div class="go-top"><a href="#">^</a></div></div> |
| |
| <div class="component"><h2 id="__Random">__Random<a class="sectionlink" href="#__Random" title="Link to here">¶</a></h2> |
| <div class="description"><p>The random function returns a random number that lies between the given min and max values.</p></div> |
| |
| <div class="properties"><h3 id="__Random_parms1"> |
| Parameters |
| <a class="sectionlink" href="#__Random_parms1" title="Link to here">¶</a></h3><div class="property title"><div class="name title">Attribute</div><div class="description title">Description</div><div class="required title">Required</div></div> |
| <div class="property"><div class="name req-true">Minimum value</div><div class="description req-true">A number</div><div class="required req-true">Yes</div></div> |
| <div class="property"><div class="name req-true">Maximum value</div><div class="description req-true">A bigger number</div><div class="required req-true">Yes</div></div> |
| <div class="property"><div class="name req-false">Variable Name</div><div class="description req-false">A reference name for reusing the value |
| computed by this function.</div><div class="required req-false">No</div></div> |
| </div> |
| <div class="go-top"><a href="#">^</a></div></div> |
| |
| <div class="component"><h2 id="__RandomString">__RandomString<a class="sectionlink" href="#__RandomString" title="Link to here">¶</a></h2> |
| <div class="description"><p>The RandomString function returns a random String of length using characters in chars to use.</p></div> |
| |
| <div class="properties"><h3 id="__RandomString_parms1"> |
| Parameters |
| <a class="sectionlink" href="#__RandomString_parms1" title="Link to here">¶</a></h3><div class="property title"><div class="name title">Attribute</div><div class="description title">Description</div><div class="required title">Required</div></div> |
| <div class="property"><div class="name req-true">Length</div><div class="description req-true">A number length of generated String</div><div class="required req-true">Yes</div></div> |
| <div class="property"><div class="name req-false">Characters to use</div><div class="description req-false">Chars used to generate String</div><div class="required req-false">No</div></div> |
| <div class="property"><div class="name req-false">Variable Name</div><div class="description req-false">A reference name for reusing the value |
| computed by this function.</div><div class="required req-false">No</div></div> |
| </div> |
| <div class="go-top"><a href="#">^</a></div></div> |
| |
| <div class="component"><h2 id="__UUID">__UUID<a class="sectionlink" href="#__UUID" title="Link to here">¶</a></h2> |
| <div class="description"> |
| <p>The UUID function returns a pseudo random type 4 Universally Unique IDentifier (UUID).</p> |
| </div> |
| <div class="properties"><h3 id="__UUID_parms1"> |
| Parameters |
| <a class="sectionlink" href="#__UUID_parms1" title="Link to here">¶</a></h3><div class="property title"><div class="name title">Attribute</div><div class="description title">Description</div><div class="required title">Required</div></div> |
| </div> |
| <div class="go-top"><a href="#">^</a></div></div> |
| |
| <div class="component"><h2 id="__CSVRead">__CSVRead<a class="sectionlink" href="#__CSVRead" title="Link to here">¶</a></h2> |
| <div class="description"><p>The CSVRead function returns a string from a CSV file (c.f. <a href="#_StringFromFile">StringFromFile</a>)</p> |
| <p>NOTE: versions up to 1.9.1 only supported a single file. |
| JMeter versions since 1.9.1 support 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 (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, |
| 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> |
| <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> |
| </div> |
| |
| <div class="properties"><h3 id="__CSVRead_parms1"> |
| Parameters |
| <a class="sectionlink" href="#__CSVRead_parms1" title="Link to here">¶</a></h3><div class="property title"><div class="name title">Attribute</div><div class="description title">Description</div><div class="required title">Required</div></div> |
| <div class="property"><div class="name req-true">File Name</div><div class="description req-true">The file (or *ALIAS) to read from</div><div class="required req-true">Yes</div></div> |
| <div class="property"><div class="name req-true">Column number</div><div class="description req-true"> |
| The column number in the file. |
| 0 = first column, 1 = second etc. |
| "next" - go to next line of file. |
| *ALIAS - open a file and assign it to the alias |
| </div><div class="required req-true">Yes</div></div> |
| </div> |
| <p>For example, you could set up some variables as follows: |
| <ul> |
| <li>COL1a ${__CSVRead(random.txt,0)}</li> |
| <li>COL2a ${__CSVRead(random.txt,1)}${__CSVRead(random.txt,next)}</li> |
| <li>COL1b ${__CSVRead(random.txt,0)}</li> |
| <li>COL2b ${__CSVRead(random.txt,1)}${__CSVRead(random.txt,next)}</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> |
| <div class="clear"></div><div class="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>. |
| </div><div class="clear"></div> |
| <div class="go-top"><a href="#">^</a></div></div> |
| |
| <div class="component"><h2 id="__property">__property<a class="sectionlink" href="#__property" title="Link to here">¶</a></h2> |
| <div class="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>${__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> |
| </div> |
| |
| <div class="properties"><h3 id="__property_parms1"> |
| Parameters |
| <a class="sectionlink" href="#__property_parms1" title="Link to here">¶</a></h3><div class="property title"><div class="name title">Attribute</div><div class="description title">Description</div><div class="required title">Required</div></div> |
| <div class="property"><div class="name req-true">Property Name</div><div class="description req-true">The property name to be retrieved.</div><div class="required req-true">Yes</div></div> |
| <div class="property"><div class="name req-false">Variable Name</div><div class="description req-false">A reference name for reusing the value |
| computed by this function.</div><div class="required req-false">No</div></div> |
| <div class="property"><div class="name req-false">Default Value</div><div class="description req-false">The default value for the property.</div><div class="required req-false">No</div></div> |
| </div> |
| <div class="go-top"><a href="#">^</a></div></div> |
| |
| <div class="component"><h2 id="__P">__P<a class="sectionlink" href="#__P" title="Link to here">¶</a></h2> |
| <div class="description"><p>This is a simplified property function which is |
| intended for use with properties defined on the command line. |
| 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. |
| </p>For example:<p> |
| <span class="code"> |
| Define the property value: |
| <br> |
| jmeter -Jgroup1.threads=7 -Jhostname1=www.realhost.edu |
| <br> |
| |
| Fetch the values: |
| <br> |
| ${__P(group1.threads)} - return the value of group1.threads |
| <br> |
| ${__P(group1.loops)} - return the value of group1.loops |
| <br> |
| ${__P(hostname,www.dummy.org)} - return value of property hostname or www.dummy.org if not defined |
| <br> |
| </span> |
| 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!) |
| </p> |
| </div> |
| |
| <div class="properties"><h3 id="__P_parms1"> |
| Parameters |
| <a class="sectionlink" href="#__P_parms1" title="Link to here">¶</a></h3><div class="property title"><div class="name title">Attribute</div><div class="description title">Description</div><div class="required title">Required</div></div> |
| <div class="property"><div class="name req-true">Property Name</div><div class="description req-true">The property name to be retrieved.</div><div class="required req-true">Yes</div></div> |
| <div class="property"><div class="name req-false">Default Value</div><div class="description req-false">The default value for the property. |
| If omitted, the default is set to "1".</div><div class="required req-false">No</div></div> |
| </div> |
| <div class="go-top"><a href="#">^</a></div></div> |
| |
| <div class="component"><h2 id="__log">__log<a class="sectionlink" href="#__log" title="Link to here">¶</a></h2> |
| <div class="description"> |
| <p> |
| The log function logs a message, and returns its input string |
| </p> |
| </div> |
| |
| <div class="properties"><h3 id="__log_parms1"> |
| Parameters |
| <a class="sectionlink" href="#__log_parms1" title="Link to here">¶</a></h3><div class="property title"><div class="name title">Attribute</div><div class="description title">Description</div><div class="required title">Required</div></div> |
| <div class="property"><div class="name req-true">String to be logged</div><div class="description req-true">A string</div><div class="required req-true">Yes</div></div> |
| <div class="property"><div class="name req-false">Log Level</div><div class="description req-false">OUT, ERR, DEBUG, INFO (default), WARN or ERROR</div><div class="required req-false">No</div></div> |
| <div class="property"><div class="name req-false">Throwable text</div><div class="description req-false">If non-empty, creates a Throwable to pass to the logger</div><div class="required req-false">No</div></div> |
| <div class="property"><div class="name req-false">Comment</div><div class="description req-false">If present, it is displayed in the string. |
| Useful for identifying what is being logged.</div><div class="required req-false">No</div></div> |
| </div> |
| <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> |
| <pre> |
| For example: |
| ${__log(Message)} - written to the log file as "...thread Name : Message" |
| ${__log(Message,OUT)} - written to console window |
| ${__log(${VAR},,,VAR=)} - written to log file as "...thread Name VAR=value" |
| </pre> |
| <div class="go-top"><a href="#">^</a></div></div> |
| |
| <div class="component"><h2 id="__logn">__logn<a class="sectionlink" href="#__logn" title="Link to here">¶</a></h2> |
| <div class="description"> |
| <p> |
| The logn function logs a message, and returns the empty string |
| </p> |
| </div> |
| |
| <div class="properties"><h3 id="__logn_parms1"> |
| Parameters |
| <a class="sectionlink" href="#__logn_parms1" title="Link to here">¶</a></h3><div class="property title"><div class="name title">Attribute</div><div class="description title">Description</div><div class="required title">Required</div></div> |
| <div class="property"><div class="name req-true">String to be logged</div><div class="description req-true">A string</div><div class="required req-true">Yes</div></div> |
| <div class="property"><div class="name req-false">Log Level</div><div class="description req-false">OUT, ERR, DEBUG, INFO (default), WARN or ERROR</div><div class="required req-false">No</div></div> |
| <div class="property"><div class="name req-false">Throwable text</div><div class="description req-false">If non-empty, creates a Throwable to pass to the logger</div><div class="required req-false">No</div></div> |
| </div> |
| <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> |
| <pre> |
| For example: |
| ${__logn(VAR1=${VAR1},OUT)} - write the value of the variable to the console window |
| </pre> |
| <div class="go-top"><a href="#">^</a></div></div> |
| |
| <div class="component"><h2 id="__BeanShell">__BeanShell<a class="sectionlink" href="#__BeanShell" title="Link to here">¶</a></h2> |
| <div class="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> |
| <p> |
| 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>props - JMeter Properties object</li> |
| <li>threadName - the threadName (String)</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> |
| </div> |
| |
| <div class="properties"><h3 id="__BeanShell_parms1"> |
| Parameters |
| <a class="sectionlink" href="#__BeanShell_parms1" title="Link to here">¶</a></h3><div class="property title"><div class="name title">Attribute</div><div class="description title">Description</div><div class="required title">Required</div></div> |
| <div class="property"><div class="name req-true">BeanShell script</div><div class="description req-true">A beanshell script (not a file name)</div><div class="required req-true">Yes</div></div> |
| <div class="property"><div class="name req-false">Name of variable</div><div class="description req-false">A reference name for reusing the value |
| computed by this function.</div><div class="required req-false">No</div></div> |
| |
| </div> |
| <p> |
| Example: |
| <pre> |
| ${__BeanShell(123*456)} - returns 56088 |
| ${__BeanShell(source("function.bsh"))} - processes the script in function.bsh |
| </pre> |
| </p> |
| <div class="clear"></div><div class="note"> |
| Remember to include any necessary quotes for text strings and JMeter variables that represent text strings. |
| </div><div class="clear"></div> |
| <div class="go-top"><a href="#">^</a></div></div> |
| |
| <div class="component"><h2 id="__split">__split<a class="sectionlink" href="#__split" title="Link to here">¶</a></h2> |
| <div class="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}. |
| From JMeter 2.1.2 onwards, a trailing delimiter is treated as a missing variable, and "?" is returned. |
| 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. |
| </p> |
| <p></p> |
| Example: |
| <span class="code"> |
| <br> |
| Define VAR="a||c|" in the test plan. |
| <br> |
| ${__split(${VAR},VAR,|)} |
| <br> |
| This will return the contents of VAR, i.e. "a||c|" and set the following variables: |
| <br> |
| VAR_n=4 (3 in JMeter 2.1.1 and earlier) |
| <br> |
| VAR_1=a |
| <br> |
| VAR_2=? |
| <br> |
| VAR_3=c |
| <br> |
| VAR_4=? (null in JMeter 2.1.1 and earlier) |
| <br> |
| VAR_5=null (in JMeter 2.1.2 and later) |
| </span> |
| </div> |
| |
| <div class="properties"><h3 id="__split_parms1"> |
| Parameters |
| <a class="sectionlink" href="#__split_parms1" title="Link to here">¶</a></h3><div class="property title"><div class="name title">Attribute</div><div class="description title">Description</div><div class="required title">Required</div></div> |
| <div class="property"><div class="name req-true">String to split</div><div class="description req-true">A delimited string, e.g. "a|b|c"</div><div class="required req-true">Yes</div></div> |
| <div class="property"><div class="name req-true">Name of variable</div><div class="description req-true">A reference name for reusing the value |
| computed by this function.</div><div class="required req-true">Yes</div></div> |
| <div class="property"><div class="name req-false">Delimiter</div><div class="description req-false">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>. |
| </div><div class="required req-false">No</div></div> |
| |
| </div> |
| <div class="go-top"><a href="#">^</a></div></div> |
| <div class="component"><h2 id="__XPath">__XPath<a class="sectionlink" href="#__XPath" title="Link to here">¶</a></h2> |
| <div class="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. |
| <div class="clear"></div><div class="note">Note that the entire NodeList is held in memory.</div><div class="clear"></div> |
| </p> |
| <p></p> |
| Example: |
| <span class="code"> |
| <br> |
| |
| <br> |
| ${__XPath(/path/to/build.xml, //target/@name)} |
| <br> |
| This will match all targets in build.xml and return the contents of the next name attribute |
| </span> |
| </div> |
| |
| <div class="properties"><h3 id="__XPath_parms1"> |
| Parameters |
| <a class="sectionlink" href="#__XPath_parms1" title="Link to here">¶</a></h3><div class="property title"><div class="name title">Attribute</div><div class="description title">Description</div><div class="required title">Required</div></div> |
| <div class="property"><div class="name req-true">XML file to parse</div><div class="description req-true"> a XML file to parse</div><div class="required req-true">Yes</div></div> |
| <div class="property"><div class="name req-true">XPath</div><div class="description req-true"> a XPath expression to match nodes in the XML file</div><div class="required req-true">Yes</div></div> |
| </div> |
| <div class="go-top"><a href="#">^</a></div></div> |
| |
| <div class="component"><h2 id="__setProperty">__setProperty<a class="sectionlink" href="#__setProperty" title="Link to here">¶</a></h2> |
| <div class="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 3rd parameter to "true".</p> |
| <p>Properties are global to JMeter, |
| so can be used to communicate between threads and thread groups</p> |
| </div> |
| |
| <div class="properties"><h3 id="__setProperty_parms1"> |
| Parameters |
| <a class="sectionlink" href="#__setProperty_parms1" title="Link to here">¶</a></h3><div class="property title"><div class="name title">Attribute</div><div class="description title">Description</div><div class="required title">Required</div></div> |
| <div class="property"><div class="name req-true">Property Name</div><div class="description req-true">The property name to be set.</div><div class="required req-true">Yes</div></div> |
| <div class="property"><div class="name req-true">Property Value</div><div class="description req-true">The value for the property.</div><div class="required req-true">Yes</div></div> |
| <div class="property"><div class="name req-false">True/False</div><div class="description req-false">Should the original value be returned?</div><div class="required req-false">No</div></div> |
| </div> |
| <div class="go-top"><a href="#">^</a></div></div> |
| |
| |
| <div class="component"><h2 id="__time">__time<a class="sectionlink" href="#__time" title="Link to here">¶</a></h2> |
| <div class="description"> |
| <p>The time function returns the current time in various formats.</p> |
| </div> |
| |
| <div class="properties"><h3 id="__time_parms1"> |
| Parameters |
| <a class="sectionlink" href="#__time_parms1" title="Link to here">¶</a></h3><div class="property title"><div class="name title">Attribute</div><div class="description title">Description</div><div class="required title">Required</div></div> |
| <div class="property"><div class="name req-false">Format</div><div class="description req-false"> |
| The format to be passed to SimpleDateFormat. |
| The function supports various shorthand aliases, see below. |
| If ommitted, the function returns the current time in milliseconds since the epoch. |
| </div><div class="required req-false">No</div></div> |
| <div class="property"><div class="name req-false">Name of variable</div><div class="description req-false">The name of the variable to set.</div><div class="required req-false">No</div></div> |
| </div> |
| <p>If the format string is omitted, then the function returns the current time in milliseconds since the epoch. |
| In versions of JMeter after 2.7, if the format matches "/ddd" (where ddd are decimal digits), |
| then the function returns the current time in milliseconds divided by the value of ddd. |
| For example, "/1000" 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>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> |
| <div class="go-top"><a href="#">^</a></div></div> |
| |
| <div class="component"><h2 id="__jexl">__jexl<a class="sectionlink" href="#__jexl" title="Link to here">¶</a></h2> |
| <div class="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 __jexl function uses Commons JEXL 1, and the __jexl2 function uses Commons JEXL 2</p> |
| <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> |
| </div> |
| |
| <div class="properties"><h3 id="__jexl_parms1"> |
| Parameters |
| <a class="sectionlink" href="#__jexl_parms1" title="Link to here">¶</a></h3><div class="property title"><div class="name title">Attribute</div><div class="description title">Description</div><div class="required title">Required</div></div> |
| <div class="property"><div class="name req-true">Expression</div><div class="description req-true"> |
| The expression to be evaluated. For example, 6*(5+2) |
| </div><div class="required req-true">Yes</div></div> |
| <div class="property"><div class="name req-false">Name of variable</div><div class="description req-false">The name of the variable to set.</div><div class="required req-false">No</div></div> |
| </div> |
| <p> |
| The following variables are made available to the script: |
| </p> |
| <ul> |
| <li>log - the logger for the function</li> |
| <li>ctx - JMeterContext object</li> |
| <li>vars - JMeterVariables object</li> |
| <li>props - JMeter Properties object</li> |
| <li>threadName - String containing the current thread name (in 2.3.2 it was misspelt as "theadName")</li> |
| <li>sampler - current Sampler object (if any)</li> |
| <li>sampleResult - previous SampleResult object (if any)</li> |
| <li>OUT - System.out - e.g. OUT.println("message")</li> |
| </ul> |
| <p> |
| Jexl can also create classes and call methods on them, for example: |
| </p> |
| <p> |
| <span class="code"> |
| Systemclass=log.class.forName("java.lang.System");<br> |
| now=Systemclass.currentTimeMillis(); |
| </span> |
| Note that the Jexl documentation on the web-site wrongly suggests that "div" does integer division. |
| In fact "div" and "/" both perform normal division. One can get the same effect |
| as follows: |
| <span class="code"> |
| i= 5 / 2; |
| i.intValue(); // or use i.longValue() |
| </span> |
| </p> |
| <div class="clear"></div><div class="note">Versions of JMeter after 2.3.2 allow the expression to contain multiple statements. |
| JMeter 2.3.2 and earlier only processed the first statement (if there were multiple statements a warning was logged). |
| </div><div class="clear"></div> |
| <div class="go-top"><a href="#">^</a></div></div> |
| |
| <div class="component"><h2 id="__V">__V<a class="sectionlink" href="#__V" title="Link to here">¶</a></h2> |
| <div class="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 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> |
| </div> |
| |
| <div class="properties"><h3 id="__V_parms1"> |
| Parameters |
| <a class="sectionlink" href="#__V_parms1" title="Link to here">¶</a></h3><div class="property title"><div class="name title">Attribute</div><div class="description title">Description</div><div class="required title">Required</div></div> |
| <div class="property"><div class="name req-true">Variable name</div><div class="description req-true"> |
| The variable to be evaluated. |
| </div><div class="required req-true">Yes</div></div> |
| </div> |
| <div class="go-top"><a href="#">^</a></div></div> |
| |
| <div class="component"><h2 id="__evalVar">__evalVar<a class="sectionlink" href="#__evalVar" title="Link to here">¶</a></h2> |
| <div class="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> |
| </div> |
| |
| <div class="properties"><h3 id="__evalVar_parms1"> |
| Parameters |
| <a class="sectionlink" href="#__evalVar_parms1" title="Link to here">¶</a></h3><div class="property title"><div class="name title">Attribute</div><div class="description title">Description</div><div class="required title">Required</div></div> |
| <div class="property"><div class="name req-true">Variable name</div><div class="description req-true"> |
| The variable to be evaluated. |
| </div><div class="required req-true">Yes</div></div> |
| </div> |
| <div class="go-top"><a href="#">^</a></div></div> |
| <div class="component"><h2 id="__eval">__eval<a class="sectionlink" href="#__eval" title="Link to here">¶</a></h2> |
| <div class="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: |
| <ul> |
| <li>name=Smith</li> |
| <li>column=age</li> |
| <li>table=birthdays</li> |
| <li>SQL=select ${column} from ${table} where name='${name}'</li> |
| </ul> |
| then ${__eval(${SQL})} will evaluate as "select age from birthdays where name='Smith'". |
| </p> |
| <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> |
| </div> |
| |
| <div class="properties"><h3 id="__eval_parms1"> |
| Parameters |
| <a class="sectionlink" href="#__eval_parms1" title="Link to here">¶</a></h3><div class="property title"><div class="name title">Attribute</div><div class="description title">Description</div><div class="required title">Required</div></div> |
| <div class="property"><div class="name req-true">Variable name</div><div class="description req-true"> |
| The variable to be evaluated. |
| </div><div class="required req-true">Yes</div></div> |
| </div> |
| <div class="go-top"><a href="#">^</a></div></div> |
| |
| <div class="component"><h2 id="__char">__char<a class="sectionlink" href="#__char" title="Link to here">¶</a></h2> |
| <div class="description"> |
| <p> |
| The char function returns the result of evaluating a list of numbers as Unicode characters. |
| See also __unescape(), below. |
| </p> |
| <p> |
| This allows one to add arbitrary character values into fields. |
| </p> |
| </div> |
| |
| <div class="properties"><h3 id="__char_parms1"> |
| Parameters |
| <a class="sectionlink" href="#__char_parms1" title="Link to here">¶</a></h3><div class="property title"><div class="name title">Attribute</div><div class="description title">Description</div><div class="required title">Required</div></div> |
| <div class="property"><div class="name req-true">Unicode character number (decimal or 0xhex)</div><div class="description req-true"> |
| The decimal number (or hex number, if prefixed by 0x, or octal, if prefixed by 0) to be converted to a Unicode character. |
| </div><div class="required req-true">Yes</div></div> |
| </div> |
| <p>Examples: |
| <br> |
| ${__char(13,10)} = ${__char(0xD,0xA)} = ${__char(015,012)} = CRLF |
| <br> |
| ${__char(165)} = ¥ (yen) |
| </p> |
| <div class="go-top"><a href="#">^</a></div></div> |
| |
| <div class="component"><h2 id="__unescape">__unescape<a class="sectionlink" href="#__unescape" title="Link to here">¶</a></h2> |
| <div class="description"> |
| <p> |
| The unescape function returns the result of evaluating a Java-escaped string. See also __char() above. |
| </p> |
| <p> |
| This allows one to add characters to fields which are otherwise tricky (or impossible) to define via the GUI. |
| </p> |
| </div> |
| |
| <div class="properties"><h3 id="__unescape_parms1"> |
| Parameters |
| <a class="sectionlink" href="#__unescape_parms1" title="Link to here">¶</a></h3><div class="property title"><div class="name title">Attribute</div><div class="description title">Description</div><div class="required title">Required</div></div> |
| <div class="property"><div class="name req-true">String to unescape</div><div class="description req-true"> |
| The string to be unescaped. |
| </div><div class="required req-true">Yes</div></div> |
| </div> |
| <p>Examples: |
| <br> |
| ${__unescape(\r\n)} = CRLF |
| <br> |
| ${__unescape(1\t2)} = 1[tab]2 |
| </p> |
| <div class="go-top"><a href="#">^</a></div></div> |
| |
| <div class="component"><h2 id="__unescapeHtml">__unescapeHtml<a class="sectionlink" href="#__unescapeHtml" title="Link to here">¶</a></h2> |
| <div class="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 <span class="code">"&lt;Fran&ccedil;ais&gt;"</span> |
| will become <span class="code">"<Français>"</span>. |
| </p> |
| <p> |
| If an entity is unrecognized, it is left alone, and inserted verbatim into the result string. |
| e.g. <span class="code">">&zzzz;x"</span> will become <span class="code">">&zzzz;x"</span>. |
| </p> |
| <p> |
| Uses StringEscapeUtils#unescapeHtml(String) from Commons Lang. |
| </p> |
| </div> |
| |
| <div class="properties"><h3 id="__unescapeHtml_parms1"> |
| Parameters |
| <a class="sectionlink" href="#__unescapeHtml_parms1" title="Link to here">¶</a></h3><div class="property title"><div class="name title">Attribute</div><div class="description title">Description</div><div class="required title">Required</div></div> |
| <div class="property"><div class="name req-true">String to unescape</div><div class="description req-true"> |
| The string to be unescaped. |
| </div><div class="required req-true">Yes</div></div> |
| </div> |
| <div class="go-top"><a href="#">^</a></div></div> |
| |
| <div class="component"><h2 id="__escapeHtml">__escapeHtml<a class="sectionlink" href="#__escapeHtml" title="Link to here">¶</a></h2> |
| <div class="description"> |
| <p> |
| Function which escapes the characters in a String using HTML entities. |
| Supports HTML 4.0 entities. |
| </p> |
| <p> |
| For example,<span class="code">"bread" & "butter"</span> |
| becomes: |
| <span class="code">&quot;bread&quot; &amp; &quot;butter&quot;</span>. |
| </p> |
| <p> |
| Uses StringEscapeUtils#escapeHtml(String) from Commons Lang. |
| </p> |
| </div> |
| |
| <div class="properties"><h3 id="__escapeHtml_parms1"> |
| Parameters |
| <a class="sectionlink" href="#__escapeHtml_parms1" title="Link to here">¶</a></h3><div class="property title"><div class="name title">Attribute</div><div class="description title">Description</div><div class="required title">Required</div></div> |
| <div class="property"><div class="name req-true">String to escape</div><div class="description req-true"> |
| The string to be escaped. |
| </div><div class="required req-true">Yes</div></div> |
| </div> |
| <div class="go-top"><a href="#">^</a></div></div> |
| |
| <div class="component"><h2 id="__urldecode">__urldecode<a class="sectionlink" href="#__urldecode" title="Link to here">¶</a></h2> |
| <div class="description"> |
| <p> |
| Function to decode a application/x-www-form-urlencoded string. |
| Note: use UTF-8 as the encoding scheme. |
| </p> |
| <p> |
| For example, the string <span class="code">Word+%22school%22+is+%22%C3%A9cole%22+in+french</span> would get converted to |
| <span class="code">Word "school" is "école" in french</span>. |
| </p> |
| <p> |
| Uses Java class <a href="http://docs.oracle.com/javase/6/docs/api/java/net/URLDecoder.html">URLDecoder</a>. |
| </p> |
| </div> |
| |
| <div class="properties"><h3 id="__urldecode_parms1"> |
| Parameters |
| <a class="sectionlink" href="#__urldecode_parms1" title="Link to here">¶</a></h3><div class="property title"><div class="name title">Attribute</div><div class="description title">Description</div><div class="required title">Required</div></div> |
| <div class="property"><div class="name req-true">String to decode</div><div class="description req-true"> |
| The string with URL encoded chars to decode. |
| </div><div class="required req-true">Yes</div></div> |
| </div> |
| <div class="go-top"><a href="#">^</a></div></div> |
| |
| <div class="component"><h2 id="__urlencode">__urlencode<a class="sectionlink" href="#__urlencode" title="Link to here">¶</a></h2> |
| <div class="description"> |
| <p> |
| Function to encode a string to a application/x-www-form-urlencoded string. |
| </p> |
| <p> |
| For example, the string <span class="code">Word "school" is "école" in french</span> would get converted to |
| <span class="code">Word+%22school%22+is+%22%C3%A9cole%22+in+french</span>. |
| </p> |
| <p> |
| Uses Java class <a href="http://docs.oracle.com/javase/6/docs/api/java/net/URLEncoder.html">URLEncoder</a>. |
| </p> |
| </div> |
| |
| <div class="properties"><h3 id="__urlencode_parms1"> |
| Parameters |
| <a class="sectionlink" href="#__urlencode_parms1" title="Link to here">¶</a></h3><div class="property title"><div class="name title">Attribute</div><div class="description title">Description</div><div class="required title">Required</div></div> |
| <div class="property"><div class="name req-true">String to encode</div><div class="description req-true"> |
| String to encode in URL encoded chars. |
| </div><div class="required req-true">Yes</div></div> |
| </div> |
| <div class="go-top"><a href="#">^</a></div></div> |
| |
| <div class="component"><h2 id="__FileToString">__FileToString<a class="sectionlink" href="#__FileToString" title="Link to here">¶</a></h2> |
| |
| <div class="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 "**ERR**"</p> |
| </div> |
| |
| <div class="properties"><h3 id="__FileToString_parms1"> |
| Parameters |
| <a class="sectionlink" href="#__FileToString_parms1" title="Link to here">¶</a></h3><div class="property title"><div class="name title">Attribute</div><div class="description title">Description</div><div class="required title">Required</div></div> |
| <div class="property"><div class="name req-true">File Name</div><div class="description req-true">Path to the file name. |
| (The path can be relative to the JMeter launch directory) |
| </div><div class="required req-true">Yes</div></div> |
| <div class="property"><div class="name req-false">File encoding if not the platform default</div><div class="description req-false"> |
| The encoding to be used to read the file. If not specified, the platform default is used. |
| </div><div class="required req-false">No</div></div> |
| <div class="property"><div class="name req-false">Variable Name</div><div class="description req-false"> |
| A reference name - refName - for reusing the value created by this function. Stored values are of the form ${refName}. |
| </div><div class="required req-false">No</div></div> |
| </div> |
| <p>The file name, encoding and reference name parameters are resolved every time the function is executed.</p> |
| <div class="go-top"><a href="#">^</a></div></div> |
| |
| <div class="component"><h2 id="__samplerName">__samplerName<a class="sectionlink" href="#__samplerName" title="Link to here">¶</a></h2> |
| |
| <div class="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> |
| </div> |
| |
| <div class="properties"><h3 id="__samplerName_parms1"> |
| Parameters |
| <a class="sectionlink" href="#__samplerName_parms1" title="Link to here">¶</a></h3><div class="property title"><div class="name title">Attribute</div><div class="description title">Description</div><div class="required title">Required</div></div> |
| <div class="property"><div class="name req-false">Variable Name</div><div class="description req-false"> |
| A reference name - refName - for reusing the value created by this function. Stored values are of the form ${refName}. |
| </div><div class="required req-false">No</div></div> |
| </div> |
| <div class="go-top"><a href="#">^</a></div></div> |
| |
| <div class="component"><h2 id="__TestPlanName">__TestPlanName<a class="sectionlink" href="#__TestPlanName" title="Link to here">¶</a></h2> |
| |
| <div class="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> |
| </div> |
| <div class="go-top"><a href="#">^</a></div></div> |
| |
| <div class="component"><h2 id="__escapeOroRegexpChars">__escapeOroRegexpChars<a class="sectionlink" href="#__escapeOroRegexpChars" title="Link to here">¶</a></h2> |
| <div class="description"> |
| <p> |
| Function which escapes the ORO Regexp meta characters, it is the equivalent of \Q \E in Java Regexp Engine. |
| </p> |
| <p> |
| For example,<span class="code">[^"].+?</span> |
| becomes: |
| <span class="code">\[\^\"\]\.\+\?</span>. |
| </p> |
| <p> |
| Uses Perl5Compiler#quotemeta(String) from ORO. |
| </p> |
| </div> |
| |
| <div class="properties"><h3 id="__escapeOroRegexpChars_parms1"> |
| Parameters |
| <a class="sectionlink" href="#__escapeOroRegexpChars_parms1" title="Link to here">¶</a></h3><div class="property title"><div class="name title">Attribute</div><div class="description title">Description</div><div class="required title">Required</div></div> |
| <div class="property"><div class="name req-true">String to escape</div><div class="description req-true"> |
| The string to be escaped. |
| </div><div class="required req-true">Yes</div></div> |
| <div class="property"><div class="name req-false">Variable Name</div><div class="description req-false"> |
| A reference name - refName - for reusing the value created by this function. Stored values are of the form ${refName}. |
| </div><div class="required req-false">No</div></div> |
| </div> |
| <div class="go-top"><a href="#">^</a></div></div> |
| |
| </div> |
| |
| <div class="subsection"><h2>19.6 Pre-defined Variables<a class="sectionlink" href="#predefinedvars" title="Link to here">¶</a></h2> |
| <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>COOKIE_cookiename - contains the cookie value (see <a href="../usermanual/component_reference.html#HTTP_Cookie_Manager">HTTP Cookie Manager</a>)</li> |
| <li>JMeterThread.last_sample_ok - whether or not the last sample was OK - true/false. |
| Note: this is updated after PostProcessors and Assertions have been run. |
| </li> |
| <li>START variables (see next section)</li> |
| </ul> |
| </div> |
| <div class="subsection"><h2>19.6 Pre-defined Properties<a class="sectionlink" href="#predefinedprops" title="Link to here">¶</a></h2> |
| <p> |
| 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. |
| </p> |
| <ul> |
| <li>START.MS - JMeter start time in milliseconds</li> |
| <li>START.YMD - JMeter start time as yyyyMMdd</li> |
| <li>START.HMS - JMeter start time as HHmmss</li> |
| <li>TESTSTART.MS - test start time in milliseconds</li> |
| </ul> |
| <p> |
| Please note that the START variables / properties represent JMeter startup time, not the test start time. |
| They are mainly intended for use in file names etc. |
| </p> |
| </div> |
| </div><ul class="pagelinks"><li><a href="component_reference.html">< Prev</a></li><li><a href="../index.html">Index</a></li><li><a href="regular_expressions.html">Next ></a></li></ul></div><div class="footer"><div class="copyright"> |
| Copyright © |
| 1999 – |
| 2015 |
| , Apache Software Foundation |
| </div><div class="trademarks">Apache, Apache JMeter, JMeter, the Apache |
| feather, and the Apache JMeter logo are |
| trademarks of the |
| Apache Software Foundation. |
| </div></div></body></html> |