Google Git
Sign in
apache / jmeter-site / df0a8c7f08a94a14c6956202cd5027cdc45c9588 / . / usermanual / component_reference.html
blob: c318927b72a2391a6b59fb238148f261556e7728 [file] [log] [blame]
<!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: Component Reference</title>
<meta name="viewport" content="width=device-width, initial-scale=1">
<link href="https://fonts.googleapis.com/css?family=Merriweather:400normal" rel="stylesheet" type="text/css">
<link href="https://maxcdn.bootstrapcdn.com/font-awesome/4.6.1/css/font-awesome.min.css" rel="stylesheet" type="text/css">
<link rel="stylesheet" type="text/css" href="../css/new-style.css">
<link rel="apple-touch-icon-precomposed" href="../images/apple-touch-icon.png">
<link rel="icon" href="../images/favicon.png">
<meta name="msapplication-TileColor" content="#ffffff">
<meta name="msapplication-TileImage" content="../images/mstile-144x144.png">
<meta name="theme-color" content="#ffffff">
</head>
<body role="document">
<a href="#content" class="hidden">Main content</a>
<div class="header">
<!--
APACHE LOGO
-->
<div>
<a href="https://www.apache.org"><img title="Apache Software Foundation" class="asf-logo logo" src="../images/asf-logo.svg" alt="Logo ASF"></a>
</div>
<!--
PROJECT LOGO
-->
<div>
<a href="https://jmeter.apache.org/"><img class="logo" src="../images/logo.svg" alt="Apache JMeter"></a>
</div>
<div class="banner">
<a href="https://www.apache.org/events/current-event.html"><img src="https://www.apache.org/events/current-event-234x60.png" alt="Current Apache event teaser"></a>
<div class="clear"></div>
</div>
</div>
<div class="nav">
<ul class="menu">
<li onClick="return true">
<div class="menu-title">About</div>
<ul>
<li>
<a href="../index.html">Overview</a>
</li>
<li>
<a href="https://www.apache.org/licenses/">License</a>
</li>
</ul>
</li>
</ul>
<ul class="menu">
<li onClick="return true">
<div class="menu-title">Download</div>
<ul>
<li>
<a href="../download_jmeter.cgi">Download Releases</a>
</li>
<li>
<a href="../changes.html">Release Notes</a>
</li>
</ul>
</li>
</ul>
<ul class="menu">
<li onClick="return true">
<div class="menu-title">Documentation</div>
<ul>
<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="../usermanual/properties_reference.html">Properties Reference</a>
</li>
<li>
<a href="../changes_history.html">Change History</a>
</li>
<li>
<a href="../api/index.html">Javadocs</a>
</li>
<li>
<a href="https://cwiki.apache.org/confluence/display/JMETER/Home">JMeter Wiki</a>
</li>
<li>
<a href="https://cwiki.apache.org/confluence/display/JMETER/JMeterFAQ">FAQ (Wiki)</a>
</li>
</ul>
</li>
</ul>
<ul class="menu">
<li onClick="return true">
<div class="menu-title">Tutorials</div>
<ul>
<li>
<a href="../usermanual/jmeter_distributed_testing_step_by_step.html">Distributed Testing</a>
</li>
<li>
<a href="../usermanual/jmeter_proxy_step_by_step.html">Recording Tests</a>
</li>
<li>
<a href="../usermanual/junitsampler_tutorial.html">JUnit Sampler</a>
</li>
<li>
<a href="../usermanual/jmeter_accesslog_sampler_step_by_step.html">Access Log Sampler</a>
</li>
<li>
<a href="../usermanual/jmeter_tutorial.html">Extending JMeter</a>
</li>
</ul>
</li>
</ul>
<ul class="menu">
<li onClick="return true">
<div class="menu-title">Community</div>
<ul>
<li>
<a href="../issues.html">Issue Tracking</a>
</li>
<li>
<a href="https://www.apache.org/security/">Security</a>
</li>
<li>
<a href="../mail.html">Mailing Lists</a>
</li>
<li>
<a href="../svnindex.html">Source Repositories</a>
</li>
<li>
<a href="../building.html">Building and Contributing</a>
</li>
<li>
<a href="https://projects.apache.org/project.html?jmeter">Project info at Apache</a>
</li>
<li>
<a href="https://cwiki.apache.org/confluence/display/JMETER/JMeterCommitters">Contributors</a>
</li>
</ul>
</li>
</ul>
<ul class="menu">
<li onClick="return true">
<div class="menu-title">Foundation</div>
<ul>
<li>
<a href="https://www.apache.org/">The Apache Software Foundation (ASF)</a>
</li>
<li>
<a href="https://www.apache.org/foundation/getinvolved.html">Get Involved in the ASF</a>
</li>
<li>
<a href="https://www.apache.org/foundation/sponsorship.html">Sponsorship</a>
</li>
<li>
<a href="https://www.apache.org/foundation/thanks.html">Thanks</a>
</li>
</ul>
</li>
</ul>
</div>
<div class="main" id="content">
<div class="social-media">
<ul class="social-media-links">
<li class="twitter">
<a href="https://twitter.com/ApacheJMeter" title="Follow us on Twitter"><i class="fa fa-twitter" aria-hidden="true"></i>Twitter</a>
</li>
<li class="github">
<a href="https://github.com/apache/jmeter" title="Fork us on github"><i class="fa fa-github" aria-hidden="true"></i>github</a>
</li>
</ul>
</div>
<ul class="pagelinks">
<li>
<a href="boss.html">&lt; Prev</a>
</li>
<li>
<a href="../index.html">Index</a>
</li>
<li>
<a href="properties_reference.html">Next &gt;</a>
</li>
</ul>
<ul class="section-index">
<li>
<a href="#introduction">18 Introduction</a>
<ul></ul>
</li>
<li>
<a href="#samplers">18.1 Samplers</a>
<ul>
<li>
<a href="#FTP_Request">FTP Request</a>
</li>
<li>
<a href="#HTTP_Request">HTTP Request</a>
</li>
<li>
<a href="#JDBC_Request">JDBC Request</a>
</li>
<li>
<a href="#Java_Request">Java Request</a>
</li>
<li>
<a href="#LDAP_Request">LDAP Request</a>
</li>
<li>
<a href="#LDAP_Extended_Request">LDAP Extended Request</a>
</li>
<li>
<a href="#Access_Log_Sampler">Access Log Sampler</a>
</li>
<li>
<a href="#BeanShell_Sampler">BeanShell Sampler</a>
</li>
<li>
<a href="#JSR223_Sampler">JSR223 Sampler</a>
</li>
<li>
<a href="#TCP_Sampler">TCP Sampler</a>
</li>
<li>
<a href="#JMS_Publisher">JMS Publisher</a>
</li>
<li>
<a href="#JMS_Subscriber">JMS Subscriber</a>
</li>
<li>
<a href="#JMS_Point-to-Point">JMS Point-to-Point</a>
</li>
<li>
<a href="#JUnit_Request">JUnit Request</a>
</li>
<li>
<a href="#Mail_Reader_Sampler">Mail Reader Sampler</a>
</li>
<li>
<a href="#Flow_Control_Action">Flow Control Action
(was:
Test Action
)
</a>
</li>
<li>
<a href="#SMTP_Sampler">SMTP Sampler</a>
</li>
<li>
<a href="#OS_Process_Sampler">OS Process Sampler</a>
</li>
<li>
<a href="#MongoDB_Script_(DEPRECATED)">MongoDB Script (DEPRECATED)</a>
</li>
<li>
<a href="#Bolt_Request">Bolt Request</a>
</li>
</ul>
</li>
<li>
<a href="#logic_controllers">18.2 Logic Controllers</a>
<ul>
<li>
<a href="#Simple_Controller">Simple Controller</a>
</li>
<li>
<a href="#Loop_Controller">Loop Controller</a>
</li>
<li>
<a href="#Once_Only_Controller">Once Only Controller</a>
</li>
<li>
<a href="#Interleave_Controller">Interleave Controller</a>
</li>
<li>
<a href="#Random_Controller">Random Controller</a>
</li>
<li>
<a href="#Random_Order_Controller">Random Order Controller</a>
</li>
<li>
<a href="#Throughput_Controller">Throughput Controller</a>
</li>
<li>
<a href="#Runtime_Controller">Runtime Controller</a>
</li>
<li>
<a href="#If_Controller">If Controller</a>
</li>
<li>
<a href="#While_Controller">While Controller</a>
</li>
<li>
<a href="#Switch_Controller">Switch Controller</a>
</li>
<li>
<a href="#ForEach_Controller">ForEach Controller</a>
</li>
<li>
<a href="#Module_Controller">Module Controller</a>
</li>
<li>
<a href="#Include_Controller">Include Controller</a>
</li>
<li>
<a href="#Transaction_Controller">Transaction Controller</a>
</li>
<li>
<a href="#Recording_Controller">Recording Controller</a>
</li>
<li>
<a href="#Critical_Section_Controller">Critical Section Controller</a>
</li>
</ul>
</li>
<li>
<a href="#listeners">18.3 Listeners</a>
<ul>
<li>
<a href="#Sample_Result_Save_Configuration">Sample Result Save Configuration</a>
</li>
<li>
<a href="#Graph_Results">Graph Results</a>
</li>
<li>
<a href="#Assertion_Results">Assertion Results</a>
</li>
<li>
<a href="#View_Results_Tree">View Results Tree</a>
</li>
<li>
<a href="#Aggregate_Report">Aggregate Report</a>
</li>
<li>
<a href="#View_Results_in_Table">View Results in Table</a>
</li>
<li>
<a href="#Simple_Data_Writer">Simple Data Writer</a>
</li>
<li>
<a href="#Aggregate_Graph">Aggregate Graph</a>
</li>
<li>
<a href="#Response_Time_Graph">Response Time Graph</a>
</li>
<li>
<a href="#Mailer_Visualizer">Mailer Visualizer</a>
</li>
<li>
<a href="#BeanShell_Listener">BeanShell Listener</a>
</li>
<li>
<a href="#Summary_Report">Summary Report</a>
</li>
<li>
<a href="#Save_Responses_to_a_file">Save Responses to a file</a>
</li>
<li>
<a href="#JSR223_Listener">JSR223 Listener</a>
</li>
<li>
<a href="#Generate_Summary_Results">Generate Summary Results</a>
</li>
<li>
<a href="#Comparison_Assertion_Visualizer">Comparison Assertion Visualizer</a>
</li>
<li>
<a href="#Backend_Listener">Backend Listener</a>
</li>
</ul>
</li>
<li>
<a href="#config_elements">18.4 Configuration Elements</a>
<ul>
<li>
<a href="#CSV_Data_Set_Config">CSV Data Set Config</a>
</li>
<li>
<a href="#FTP_Request_Defaults">FTP Request Defaults</a>
</li>
<li>
<a href="#DNS_Cache_Manager">DNS Cache Manager</a>
</li>
<li>
<a href="#HTTP_Authorization_Manager">HTTP Authorization Manager</a>
</li>
<li>
<a href="#HTTP_Cache_Manager">HTTP Cache Manager</a>
</li>
<li>
<a href="#HTTP_Cookie_Manager">HTTP Cookie Manager</a>
</li>
<li>
<a href="#HTTP_Request_Defaults">HTTP Request Defaults</a>
</li>
<li>
<a href="#HTTP_Header_Manager">HTTP Header Manager</a>
</li>
<li>
<a href="#Java_Request_Defaults">Java Request Defaults</a>
</li>
<li>
<a href="#JDBC_Connection_Configuration">JDBC Connection Configuration</a>
</li>
<li>
<a href="#Keystore_Configuration">Keystore Configuration</a>
</li>
<li>
<a href="#Login_Config_Element">Login Config Element</a>
</li>
<li>
<a href="#LDAP_Request_Defaults">LDAP Request Defaults</a>
</li>
<li>
<a href="#LDAP_Extended_Request_Defaults">LDAP Extended Request Defaults</a>
</li>
<li>
<a href="#TCP_Sampler_Config">TCP Sampler Config</a>
</li>
<li>
<a href="#User_Defined_Variables">User Defined Variables</a>
</li>
<li>
<a href="#Random_Variable">Random Variable</a>
</li>
<li>
<a href="#Counter">Counter</a>
</li>
<li>
<a href="#Simple_Config_Element">Simple Config Element</a>
</li>
<li>
<a href="#MongoDB_Source_Config_(DEPRECATED)">MongoDB Source Config (DEPRECATED)</a>
</li>
<li>
<a href="#Bolt_Connection_Configuration">Bolt Connection Configuration</a>
</li>
</ul>
</li>
<li>
<a href="#assertions">18.5 Assertions</a>
<ul>
<li>
<a href="#Response_Assertion">Response Assertion</a>
</li>
<li>
<a href="#Duration_Assertion">Duration Assertion</a>
</li>
<li>
<a href="#Size_Assertion">Size Assertion</a>
</li>
<li>
<a href="#XML_Assertion">XML Assertion</a>
</li>
<li>
<a href="#BeanShell_Assertion">BeanShell Assertion</a>
</li>
<li>
<a href="#MD5Hex_Assertion">MD5Hex Assertion</a>
</li>
<li>
<a href="#HTML_Assertion">HTML Assertion</a>
</li>
<li>
<a href="#XPath_Assertion">XPath Assertion</a>
</li>
<li>
<a href="#XPath2_Assertion">XPath2 Assertion</a>
</li>
<li>
<a href="#XML_Schema_Assertion">XML Schema Assertion</a>
</li>
<li>
<a href="#JSR223_Assertion">JSR223 Assertion</a>
</li>
<li>
<a href="#Compare_Assertion">Compare Assertion</a>
</li>
<li>
<a href="#SMIME_Assertion">SMIME Assertion</a>
</li>
<li>
<a href="#JSON_Assertion">JSON Assertion</a>
</li>
<li>
<a href="#JSON_JMESPath_Assertion">JSON JMESPath Assertion</a>
</li>
</ul>
</li>
<li>
<a href="#timers">18.6 Timers</a>
<ul>
<li>
<a href="#Constant_Timer">Constant Timer</a>
</li>
<li>
<a href="#Gaussian_Random_Timer">Gaussian Random Timer</a>
</li>
<li>
<a href="#Uniform_Random_Timer">Uniform Random Timer</a>
</li>
<li>
<a href="#Constant_Throughput_Timer">Constant Throughput Timer</a>
</li>
<li>
<a href="#Precise_Throughput_Timer">Precise Throughput Timer</a>
</li>
<li>
<a href="#Synchronizing_Timer">Synchronizing Timer</a>
</li>
<li>
<a href="#BeanShell_Timer">BeanShell Timer</a>
</li>
<li>
<a href="#JSR223_Timer">JSR223 Timer</a>
</li>
<li>
<a href="#Poisson_Random_Timer">Poisson Random Timer</a>
</li>
</ul>
</li>
<li>
<a href="#preprocessors">18.7 Pre Processors</a>
<ul>
<li>
<a href="#HTML_Link_Parser">HTML Link Parser</a>
</li>
<li>
<a href="#HTTP_URL_Re-writing_Modifier">HTTP URL Re-writing Modifier</a>
</li>
<li>
<a href="#User_Parameters">User Parameters</a>
</li>
<li>
<a href="#BeanShell_PreProcessor">BeanShell PreProcessor</a>
</li>
<li>
<a href="#JSR223_PreProcessor">JSR223 PreProcessor</a>
</li>
<li>
<a href="#JDBC_PreProcessor">JDBC PreProcessor</a>
</li>
<li>
<a href="#RegEx_User_Parameters">RegEx User Parameters</a>
</li>
<li>
<a href="#Sample_Timeout">Sample Timeout</a>
</li>
</ul>
</li>
<li>
<a href="#postprocessors">18.8 Post-Processors</a>
<ul>
<li>
<a href="#Regular_Expression_Extractor">Regular Expression Extractor</a>
</li>
<li>
<a href="#CSS_Selector_Extractor">CSS Selector Extractor
(was:
CSS/JQuery Extractor
)
</a>
</li>
<li>
<a href="#XPath2_Extractor">XPath2 Extractor</a>
</li>
<li>
<a href="#XPath_Extractor">XPath Extractor</a>
</li>
<li>
<a href="#JSON_JMESPath_Extractor">JSON JMESPath Extractor</a>
</li>
<li>
<a href="#Result_Status_Action_Handler">Result Status Action Handler</a>
</li>
<li>
<a href="#BeanShell_PostProcessor">BeanShell PostProcessor</a>
</li>
<li>
<a href="#JSR223_PostProcessor">JSR223 PostProcessor</a>
</li>
<li>
<a href="#JDBC_PostProcessor">JDBC PostProcessor</a>
</li>
<li>
<a href="#JSON_Extractor">JSON Extractor</a>
</li>
<li>
<a href="#Boundary_Extractor">Boundary Extractor</a>
</li>
</ul>
</li>
<li>
<a href="#Miscellaneous_Features">18.9 Miscellaneous Features</a>
<ul>
<li>
<a href="#Test_Plan">Test Plan</a>
</li>
<li>
<a href="#Thread_Group">Thread Group</a>
</li>
<li>
<a href="#WorkBench">WorkBench</a>
</li>
<li>
<a href="#SSL_Manager">SSL Manager</a>
</li>
<li>
<a href="#HTTP(S)_Test_Script_Recorder">HTTP(S) Test Script Recorder
(was:
HTTP Proxy Server
)
</a>
</li>
<li>
<a href="#HTTP_Mirror_Server">HTTP Mirror Server</a>
</li>
<li>
<a href="#Property_Display">Property Display</a>
</li>
<li>
<a href="#Debug_Sampler">Debug Sampler</a>
</li>
<li>
<a href="#Debug_PostProcessor">Debug PostProcessor</a>
</li>
<li>
<a href="#Test_Fragment">Test Fragment</a>
</li>
<li>
<a href="#setUp_Thread_Group">setUp Thread Group</a>
</li>
<li>
<a href="#tearDown_Thread_Group">tearDown Thread Group</a>
</li>
</ul>
</li>
</ul>
<div class="section">
<h1 id="introduction">18 Introduction<a class="sectionlink" href="#introduction" title="Link to here">&para;</a>
</h1>
<div class="description">
<p>
</p>
<div class="clear"></div>
<div class="note">
Several test elements use JMeter properties to control their behaviour.
These properties are normally resolved when the class is loaded.
This generally occurs before the test plan starts, so it's not possible to change the settings by using the <span class="code"><a href="../usermanual/functions.html#__setProperty">__setProperty()</a></span> function.
</div>
<div class="clear"></div>
<p>
</p>
</div>
</div>
<div class="section">
<h1 id="samplers">18.1 Samplers<a class="sectionlink" href="#samplers" title="Link to here">&para;</a>
</h1>
<div class="description">
<p>
Samplers perform the actual work of JMeter.
Each sampler (except <a href="../usermanual/component_reference.html#Flow_Control_Action">Flow Control Action</a>) generates one or more sample results.
The sample results have various attributes (success/fail, elapsed time, data size etc.) and can be viewed in the various listeners.
</p>
</div>
<div class="component">
<h2 id="FTP_Request">FTP Request<a class="sectionlink" href="#FTP_Request" title="Link to here">&para;</a>
</h2>
<div class="description">
This controller lets you send an FTP "retrieve file" or "upload file" request to an FTP server.
If you are going to send multiple requests to the same FTP server, consider
using a <a href="../usermanual/component_reference.html#FTP_Request_Defaults">FTP Request Defaults</a> Configuration
Element so you do not have to enter the same information for each FTP Request Generative
Controller. When downloading a file, it can be stored on disk (Local File) or in the Response Data, or both.
<p>
Latency is set to the time it takes to login.
</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/ftptest/ftp-request.png"><img src="../images/screenshots/ftptest/ftp-request.png" width="911" height="274" alt="Screenshot for Control-Panel of FTP Request"></a>
<figcaption>Screenshot of Control-Panel of FTP Request</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="FTP_Request_parms1">
Parameters
<a class="sectionlink" href="#FTP_Request_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-false">Descriptive name for this sampler that is shown in the tree.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Server Name or IP</div>
<div class="description req-true">Domain name or IP address of the FTP server.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Port</div>
<div class="description req-false">Port to use. If this is <span class="code">&gt;0</span>, then this specific port is used,
otherwise JMeter uses the default FTP port.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Remote File:</div>
<div class="description req-true">File to retrieve or name of destination file to upload.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Local File:</div>
<div class="description req-true">File to upload, or destination for downloads (defaults to remote file name).</div>
<div class="required req-true">Yes, if uploading (*)</div>
</div>
<div class="property">
<div class="name req-true">Local File Contents:</div>
<div class="description req-true">Provides the contents for the upload, overrides the Local File property.</div>
<div class="required req-true">Yes, if uploading (*)</div>
</div>
<div class="property">
<div class="name req-true">get(RETR) / put(STOR)</div>
<div class="description req-true">Whether to retrieve or upload a file.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Use Binary mode?</div>
<div class="description req-true">Check this to use Binary mode (default ASCII)</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Save File in Response?</div>
<div class="description req-true">
Whether to store contents of retrieved file in response data.
If the mode is ASCII, then the contents will be visible in the <a href="../usermanual/component_reference.html#View_Results_Tree">View Results Tree</a>.
</div>
<div class="required req-true">Yes, if downloading</div>
</div>
<div class="property">
<div class="name req-false">Username</div>
<div class="description req-false">FTP account username.</div>
<div class="required req-false">Usually</div>
</div>
<div class="property">
<div class="name req-false">Password</div>
<div class="description req-false">FTP account password. N.B. This will be visible in the test plan.</div>
<div class="required req-false">Usually</div>
</div>
</div>
<div class="links">
<div class="title">See also:</div>
<ul class="links">
<li>
<a href="test_plan.html#assertions">Assertions</a>
</li>
<li>
<a href="../usermanual/component_reference.html#FTP_Request_Defaults">FTP Request Defaults</a>
</li>
<li>
<a href="build-ftp-test-plan.html">Building an FTP Test Plan</a>
</li>
</ul>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="HTTP_Request">HTTP Request<a class="sectionlink" href="#HTTP_Request" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>This sampler lets you send an HTTP/HTTPS request to a web server. It
also lets you control whether or not JMeter parses HTML files for images and
other embedded resources and sends HTTP requests to retrieve them.
The following types of embedded resource are retrieved:</p>
<ul>
<li>images</li>
<li>applets</li>
<li>stylesheets (CSS) and resources referenced from those files</li>
<li>external scripts</li>
<li>frames, iframes</li>
<li>background images (body, table, TD, TR)</li>
<li>background sound</li>
</ul>
<p>
The default parser is <span class="code">org.apache.jmeter.protocol.http.parser.LagartoBasedHtmlParser</span>.
This can be changed by using the property "<span class="code">htmlparser.className</span>" - see <span class="code">jmeter.properties</span> for details.
</p>
<p>If you are going to send multiple requests to the same web server, consider
using an <a href="../usermanual/component_reference.html#HTTP_Request_Defaults">HTTP Request Defaults</a>
Configuration Element so you do not have to enter the same information for each
HTTP Request.</p>
<p>Or, instead of manually adding HTTP Requests, you may want to use
JMeter's <a href="../usermanual/component_reference.html#HTTP(S)_Test_Script_Recorder">HTTP(S) Test Script Recorder</a> to create
them. This can save you time if you have a lot of HTTP requests or requests with many
parameters.</p>
<p>
<b>There are two different test elements used to define the samplers:</b>
</p>
<dl>
<dt>AJP/1.3 Sampler</dt>
<dd>uses the Tomcat mod_jk protocol (allows testing of Tomcat in AJP mode without needing Apache httpd)
The AJP Sampler does not support multiple file upload; only the first file will be used.
</dd>
<dt>HTTP Request</dt>
<dd>this has an implementation drop-down box, which selects the HTTP protocol implementation to be used:
<dl>
<dt>
<span class="code">Java</span>
</dt>
<dd>uses the HTTP implementation provided by the JVM.
This has some limitations in comparison with the HttpClient implementations - see below.</dd>
<dt>
<span class="code">HTTPClient4</span>
</dt>
<dd>uses Apache HttpComponents HttpClient 4.x.</dd>
<dt>Blank Value</dt>
<dd>does not set implementation on HTTP Samplers, so relies on HTTP Request Defaults if present or on <span class="code">jmeter.httpsampler</span> property defined in <span class="code">jmeter.properties</span>
</dd>
</dl>
</dd>
</dl>
<p>The Java HTTP implementation has some limitations:</p>
<ul>
<li>There is no control over how connections are re-used.
When a connection is released by JMeter, it may or may not be re-used by the same thread.</li>
<li>The API is best suited to single-threaded usage - various settings
are defined via system properties, and therefore apply to all connections.</li>
<li>No support of Kerberos authentication</li>
<li>It does not support client based certificate testing with Keystore Config.</li>
<li>Better control of Retry mechanism</li>
<li>It does not support virtual hosts.</li>
<li>It supports only the following methods: <span class="code">GET</span>, <span class="code">POST</span>, <span class="code">HEAD</span>, <span class="code">OPTIONS</span>, <span class="code">PUT</span>, <span class="code">DELETE</span> and <span class="code">TRACE</span>
</li>
<li>Better control on DNS Caching with <a href="../usermanual/component_reference.html#DNS_Cache_Manager">DNS Cache Manager</a>
</li>
</ul>
<div class="clear"></div>
<div class="note">Note: the <span class="code">FILE</span> protocol is intended for testing purposes only.
It is handled by the same code regardless of which HTTP Sampler is used.</div>
<div class="clear"></div>
<p>If the request requires server or proxy login authorization (i.e. where a browser would create a pop-up dialog box),
you will also have to add an <a href="../usermanual/component_reference.html#HTTP_Authorization_Manager">HTTP Authorization Manager</a> Configuration Element.
For normal logins (i.e. where the user enters login information in a form), you will need to work out what the form submit button does,
and create an HTTP request with the appropriate method (usually <span class="code">POST</span>)
and the appropriate parameters from the form definition.
If the page uses HTTP, you can use the JMeter Proxy to capture the login sequence.
</p>
<p>
A separate SSL context is used for each thread.
If you want to use a single SSL context (not the standard behaviour of browsers), set the JMeter property:</p>
<pre class="source">
https.sessioncontext.shared=true
</pre>
By default, since version 5.0, the SSL context is retained during a Thread Group iteration and reset for each test iteration.
If in your test plan the same user iterates multiple times, then you should set this to false.
<pre class="source">
httpclient.reset_state_on_thread_group_iteration=true
</pre>
<div class="clear"></div>
<div class="note">
Note: this does not apply to the Java HTTP implementation.
</div>
<div class="clear"></div>
JMeter defaults to the SSL protocol level TLS.
If the server needs a different level, e.g. <span class="code">SSLv3</span>, change the JMeter property, for example:
<pre class="source">
https.default.protocol=SSLv3
</pre>
<p>
JMeter also allows one to enable additional protocols, by changing the property <span class="code">https.socket.protocols</span>.
</p>
<p>If the request uses cookies, then you will also need an
<a href="../usermanual/component_reference.html#HTTP_Cookie_Manager">HTTP Cookie Manager</a>. You can
add either of these elements to the Thread Group or the HTTP Request. If you have
more than one HTTP Request that needs authorizations or cookies, then add the
elements to the Thread Group. That way, all HTTP Request controllers will share the
same Authorization Manager and Cookie Manager elements.</p>
<p>If the request uses a technique called "URL Rewriting" to maintain sessions,
then see section
<a href="build-adv-web-test-plan.html#session_url_rewriting">6.1 Handling User Sessions With URL Rewriting</a>
for additional configuration steps.</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/http-request.png"><img src="../images/screenshots/http-request.png" width="953" height="611" alt="Screenshot for Control-Panel of HTTP Request"></a>
<figcaption>Screenshot of Control-Panel of HTTP Request</figcaption>
</figure>
</div>
<figure>
<a href="../images/screenshots/http-request-advanced-tab.png"><img src="../images/screenshots/http-request-advanced-tab.png" width="951" height="284" alt="HTTP Request Advanced config fields"></a>
<figcaption>HTTP Request Advanced config fields</figcaption>
</figure>
<div class="properties">
<h3 id="HTTP_Request_parms1">
Parameters
<a class="sectionlink" href="#HTTP_Request_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-false">Descriptive name for this sampler that is shown in the tree.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Server</div>
<div class="description req-false">
Domain name or IP address of the web server, e.g. <span class="code">www.example.com</span>. [Do not include the <span class="code">http://</span> prefix.]
Note: If the "<span class="code">Host</span>" header is defined in a Header Manager, then this will be used
as the virtual host name.
<div class="clear"></div>
<div class="note">Server is required, unless:
<ul>
<li>it is provided by <a href="../usermanual/component_reference.html#HTTP_Request_Defaults">HTTP Request Defaults</a>
</li>
<li>or a full URL including scheme, host and port (<span class="code">scheme://host:port</span>) is set in <b>Path</b> field</li>
</ul>
</div>
<div class="clear"></div>
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Port</div>
<div class="description req-false">Port the web server is listening to. Default: <span class="code">80</span>
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Connect Timeout</div>
<div class="description req-false">Connection Timeout. Number of milliseconds to wait for a connection to open.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Response Timeout</div>
<div class="description req-false">Response Timeout. Number of milliseconds to wait for a response.
Note that this applies to each wait for a response. If the server response is sent in several chunks, the overall
elapsed time may be longer than the timeout.
<p>A <a href="../usermanual/component_reference.html#Duration_Assertion">Duration Assertion</a> can be used to detect responses that take too long to complete.</p>
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Server (proxy)</div>
<div class="description req-false">Hostname or IP address of a proxy server to perform request. [Do not include the <span class="code">http://</span> prefix.]</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Port</div>
<div class="description req-false">Port the proxy server is listening to.</div>
<div class="required req-false">No, unless proxy hostname is specified</div>
</div>
<div class="property">
<div class="name req-false">Username</div>
<div class="description req-false">(Optional) username for proxy server.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Password</div>
<div class="description req-false">(Optional) password for proxy server. (N.B. this is stored unencrypted in the test plan)</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Implementation</div>
<div class="description req-false">
<span class="code">Java</span>, <span class="code">HttpClient4</span>.
If not specified (and not defined by HTTP Request Defaults), the default depends on the value of the JMeter property
<span class="code">jmeter.httpsampler</span>, failing that, the HttpClient4 implementation is used.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Protocol</div>
<div class="description req-false">
<span class="code">HTTP</span>, <span class="code">HTTPS</span> or <span class="code">FILE</span>. Default: <span class="code">HTTP</span>
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Method</div>
<div class="description req-true">
<span class="code">GET</span>, <span class="code">POST</span>, <span class="code">HEAD</span>, <span class="code">TRACE</span>,
<span class="code">OPTIONS</span>, <span class="code">PUT</span>, <span class="code">DELETE</span>, <span class="code">PATCH</span> (not supported for
<span class="code">JAVA</span> implementation). With <span class="code">HttpClient4</span>, the following methods related to WebDav are
also allowed: <span class="code">COPY</span>, <span class="code">LOCK</span>, <span class="code">MKCOL</span>, <span class="code">MOVE</span>,
<span class="code">PROPFIND</span>, <span class="code">PROPPATCH</span>, <span class="code">UNLOCK</span>, <span class="code">REPORT</span>, <span class="code">MKCALENDAR</span>,
<span class="code">SEARCH</span>.
<p>More methods can be pre-defined for the HttpClient4 by using the JMeter property
<span class="code">httpsampler.user_defined_methods</span>.</p>
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Content Encoding</div>
<div class="description req-false">
Content encoding to be used (for <span class="code">POST</span>, <span class="code">PUT</span>, <span class="code">PATCH</span> and <span class="code">FILE</span>).
This is the character encoding to be used, and is not related to the Content-Encoding HTTP header.
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Redirect Automatically</div>
<div class="description req-false">
Sets the underlying http protocol handler to automatically follow redirects,
so they are not seen by JMeter, and thus will not appear as samples.
Should only be used for <span class="code">GET</span> and <span class="code">HEAD</span> requests.
The HttpClient sampler will reject attempts to use it for <span class="code">POST</span> or <span class="code">PUT</span>.
<div class="clear"></div>
<div class="note">Warning: see below for information on cookie and header handling.</div>
<div class="clear"></div>
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Follow Redirects</div>
<div class="description req-false">
This only has any effect if "<span class="code">Redirect Automatically</span>" is not enabled.
If set, the JMeter sampler will check if the response is a redirect and follow it if so.
The initial redirect and further responses will appear as additional samples.
The URL and data fields of the parent sample will be taken from the final (non-redirected)
sample, but the parent byte count and elapsed time include all samples.
The latency is taken from the initial response.
Note that the HttpClient sampler may log the following message:
<pre class="source">"Redirect requested but followRedirects is disabled"</pre>
This can be ignored.
<br>
JMeter will collapse paths of the form '<span class="code">/../segment</span>' in
both absolute and relative redirect URLs. For example <span class="code">http://host/one/../two</span> will be collapsed into <span class="code">http://host/two</span>.
If necessary, this behaviour can be suppressed by setting the JMeter property
<span class="code">httpsampler.redirect.removeslashdotdot=false</span>
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Use KeepAlive</div>
<div class="description req-false">JMeter sets the Connection: <span class="code">keep-alive</span> header. This does not work properly with the default HTTP implementation, as connection re-use is not under user-control.
It does work with the Apache HttpComponents HttpClient implementations.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Use multipart/form-data for HTTP POST</div>
<div class="description req-false">
Use a <span class="code">multipart/form-data</span> or <span class="code">application/x-www-form-urlencoded</span> post request
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Browser-compatible headers</div>
<div class="description req-false">
When using <span class="code">multipart/form-data</span>, this suppresses the <span class="code">Content-Type</span> and
<span class="code">Content-Transfer-Encoding</span> headers; only the <span class="code">Content-Disposition</span> header is sent.
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Path</div>
<div class="description req-false">The path to resource (for example, <span class="code">/servlets/myServlet</span>). If the
resource requires query string parameters, add them below in the
"Send Parameters With the Request" section.
<div class="clear"></div>
<div class="note">
As a special case, if the path starts with "<span class="code">http://</span>" or "<span class="code">https://</span>" then this is used as the full URL.
</div>
<div class="clear"></div>
In this case, the server, port and protocol fields are ignored; parameters are also ignored for <span class="code">GET</span> and <span class="code">DELETE</span> methods.
Also please note that the path is not encoded - apart from replacing spaces with <span class="code">%20</span> -
so unsafe characters may need to be encoded to avoid errors such as <span class="code">URISyntaxException</span>.
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Send Parameters With the Request</div>
<div class="description req-false">The query string will
be generated from the list of parameters you provide. Each parameter has a <span class="code">name</span> and
<span class="code">value</span>, the options to encode the parameter, and an option to include or exclude an equals sign (some applications
don't expect an equals sign when the value is the empty string). The query string will be generated in the correct fashion, depending on
the choice of "Method" you made (i.e. if you chose <span class="code">GET</span> or <span class="code">DELETE</span>, the query string will be
appended to the URL, if <span class="code">POST</span> or <span class="code">PUT</span>, then it will be sent separately). Also, if you are
sending a file using a multipart form, the query string will be created using the
multipart form specifications.
<b>See below for some further information on parameter handling.</b>
<p>
Additionally, you can specify whether each parameter should be URL encoded. If you are not sure what this
means, it is probably best to select it. If your values contain characters such as the following then encoding is usually required.:
</p>
<ul>
<li>ASCII Control Chars</li>
<li>Non-ASCII characters</li>
<li>Reserved characters:URLs use some characters for special use in defining their syntax. When these characters are not used in their special role inside a URL, they need to be encoded, example : '<span class="code">$</span>', '<span class="code">&amp;</span>', '<span class="code">+</span>', '<span class="code">,</span>' , '<span class="code">/</span>', '<span class="code">:</span>', '<span class="code">;</span>', '<span class="code">=</span>', '<span class="code">?</span>', '<span class="code">@</span>'</li>
<li>Unsafe characters: Some characters present the possibility of being misunderstood within URLs for various reasons. These characters should also always be encoded, example : '<span class="code"> </span>', '<span class="code">&lt;</span>', '<span class="code">&gt;</span>', '<span class="code">#</span>', '<span class="code">%</span>', &hellip;</li>
</ul>
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">File Path:</div>
<div class="description req-false">Name of the file to send. If left blank, JMeter
does not send a file, if filled in, JMeter automatically sends the request as
a multipart form request.
<p>
If it is a <span class="code">POST</span> or <span class="code">PUT</span> or <span class="code">PATCH</span> request and there is a single file whose 'Parameter name' attribute (below) is omitted,
then the file is sent as the entire body
of the request, i.e. no wrappers are added. This allows arbitrary bodies to be sent. This functionality is present for <span class="code">POST</span> requests,
and also for <span class="code">PUT</span> requests.
<b>See below for some further information on parameter handling.</b>
</p>
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Parameter name:</div>
<div class="description req-false">Value of the "<span class="code">name</span>" web request parameter.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">MIME Type</div>
<div class="description req-false">MIME type (for example, <span class="code">text/plain</span>).
If it is a <span class="code">POST</span> or <span class="code">PUT</span> or <span class="code">PATCH</span> request and either the '<span class="code">name</span>' attribute (below) are omitted or the request body is
constructed from parameter values only, then the value of this field is used as the value of the
<span class="code">content-type</span> request header.
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Retrieve All Embedded Resources from HTML Files</div>
<div class="description req-false">Tell JMeter to parse the HTML file
and send HTTP/HTTPS requests for all images, Java applets, JavaScript files, CSSs, etc. referenced in the file.
See below for more details.
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Save response as MD5 hash?</div>
<div class="description req-false">
If this is selected, then the response is not stored in the sample result.
Instead, the 32 character MD5 hash of the data is calculated and stored instead.
This is intended for testing large amounts of data.
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Embedded URLs must match:</div>
<div class="description req-false">
If present, this must be a regular expression that is used to match against any embedded URLs found.
So if you only want to download embedded resources from <span class="code">http://example.com/</span>, use the expression:
<span class="code">http://example\.com/.*</span>
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Use concurrent pool</div>
<div class="description req-false">Use a pool of concurrent connections to get embedded resources.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Size</div>
<div class="description req-false">Pool size for concurrent connections used to get embedded resources.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Source address type</div>
<div class="description req-false">
<i>[Only for HTTP Request with HTTPClient implementation]</i>
<br>
To distinguish the source address value, select the type of these:
<ul>
<li>Select <i>IP/Hostname</i> to use a specific IP address or a (local) hostname</li>
<li>Select <i>Device</i> to pick the first available address for that interface which
this may be either IPv4 or IPv6</li>
<li>Select <i>Device IPv4</i> to select the IPv4 address of the device name (like <span class="code">eth0</span>, <span class="code">lo</span>, <span class="code">em0</span>, etc.)</li>
<li>Select <i>Device IPv6</i> to select the IPv6 address of the device name (like <span class="code">eth0</span>, <span class="code">lo</span>, <span class="code">em0</span>, etc.)</li>
</ul>
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Source address field</div>
<div class="description req-false">
<i>[Only for HTTP Request with HTTPClient implementation]</i>
<br>
This property is used to enable IP Spoofing.
It overrides the default local IP address for this sample.
The JMeter host must have multiple IP addresses (i.e. IP aliases, network interfaces, devices).
The value can be a host name, IP address, or a network interface device such as "<span class="code">eth0</span>" or "<span class="code">lo</span>" or "<span class="code">wlan0</span>".<br>
If the property <span class="code">httpclient.localaddress</span> is defined, that is used for all HttpClient requests.
</div>
<div class="required req-false">No</div>
</div>
</div>
<div class="clear"></div>
<div class="note">
When using Automatic Redirection, cookies are only sent for the initial URL.
This can cause unexpected behaviour for web-sites that redirect to a local server.
E.g. if <span class="code">www.example.com</span> redirects to <span class="code">www.example.co.uk</span>.
In this case the server will probably return cookies for both URLs, but JMeter will only see the cookies for the last
host, i.e. <span class="code">www.example.co.uk</span>. If the next request in the test plan uses <span class="code">www.example.com</span>,
rather than <span class="code">www.example.co.uk</span>, it will not get the correct cookies.
Likewise, Headers are sent for the initial request, and won't be sent for the redirect.
This is generally only a problem for manually created test plans,
as a test plan created using a recorder would continue from the redirected URL.
</div>
<div class="clear"></div>
<p>
<b>Parameter Handling:</b>
<br>
For the <span class="code">POST</span> and <span class="code">PUT</span> method, if there is no file to send, and the name(s) of the parameter(s) are omitted,
then the body is created by concatenating all the value(s) of the parameters.
Note that the values are concatenated without adding any end-of-line characters.
These can be added by using the <span class="code"><a href="../usermanual/functions.html#__char">__char()</a></span> function in the value fields.
This allows arbitrary bodies to be sent.
The values are encoded if the encoding flag is set.
See also the MIME Type above how you can control the <span class="code">content-type</span> request header that is sent.
<br>
For other methods, if the name of the parameter is missing,
then the parameter is ignored. This allows the use of optional parameters defined by variables.
</p>
<br>
<p>You have the option to switch to <span class="code">Body Data</span> tab when a request has only unnamed parameters
(or no parameters at all).
This option is useful in the following cases (amongst others):</p>
<ul>
<li>GWT RPC HTTP Request</li>
<li>JSON REST HTTP Request</li>
<li>XML REST HTTP Request</li>
<li>SOAP HTTP Request</li>
</ul>
<div class="clear"></div>
<div class="note">
Note that once you leave the Tree node, you cannot switch back to the parameter tab unless you clear the <span class="code">Body Data</span> tab from its data.
</div>
<div class="clear"></div>
<p>
In <span class="code">Body Data</span> mode, each line will be sent with <span class="code">CRLF</span> appended, apart from the last line.
To send a <span class="code">CRLF</span> after the last line of data, just ensure that there is an empty line following it.
(This cannot be seen, except by noting whether the cursor can be placed on the subsequent line.)
</p>
<figure>
<a href="../images/screenshots/http-request-raw-single-parameter.png"><img src="../images/screenshots/http-request-raw-single-parameter.png" width="902" height="421" alt="Figure 1 - HTTP Request with one unnamed parameter"></a>
<figcaption>Figure 1 - HTTP Request with one unnamed parameter</figcaption>
</figure>
<figure>
<a href="../images/screenshots/http-request-confirm-raw-body.png"><img src="../images/screenshots/http-request-confirm-raw-body.png" width="908" height="212" alt="Figure 2 - Confirm dialog to switch"></a>
<figcaption>Figure 2 - Confirm dialog to switch</figcaption>
</figure>
<figure>
<a href="../images/screenshots/http-request-raw-body.png"><img src="../images/screenshots/http-request-raw-body.png" width="905" height="423" alt="Figure 3 - HTTP Request using Body Data"></a>
<figcaption>Figure 3 - HTTP Request using Body Data</figcaption>
</figure>
<p>
<b>Method Handling:</b>
<br>
The <span class="code">GET</span>, <span class="code">DELETE</span>, <span class="code">POST</span>, <span class="code">PUT</span> and <span class="code">PATCH</span> request methods work similarly, except that as of 3.1, only <span class="code">POST</span> method supports multipart requests
or file upload.
The <span class="code">PUT</span> and <span class="code">PATCH</span> method body must be provided as one of the following:</p>
<ul>
<li>define the body as a file with empty Parameter name field; in which case the MIME Type is used as the Content-Type</li>
<li>define the body as parameter value(s) with no name</li>
<li>use the <span class="code">Body Data</span> tab</li>
</ul>
<p>
The <span class="code">GET</span>, <span class="code">DELETE</span> and <span class="code">POST</span> methods have an additional way of passing parameters by using the <span class="code">Parameters</span> tab.
<span class="code">GET</span>, <span class="code">DELETE</span>, <span class="code">PUT</span> and <span class="code">PATCH</span> require a Content-Type.
If not using a file, attach a Header Manager to the sampler and define the Content-Type there.
</p>
<p>JMeter scan responses from embedded resources. It uses the property <span class="code">HTTPResponse.parsers</span>, which is a list of parser ids,
e.g. <span class="code">htmlParser</span>, <span class="code">cssParser</span> and <span class="code">wmlParser</span>. For each id found, JMeter checks two further properties:</p>
<ul>
<li>
<span class="code">id.types</span> - a list of content types</li>
<li>
<span class="code">id.className</span> - the parser to be used to extract the embedded resources</li>
</ul>
<p>See <span class="code">jmeter.properties</span> file for the details of the settings.
If the <span class="code">HTTPResponse.parser</span> property is not set, JMeter reverts to the previous behaviour,
i.e. only <span class="code">text/html</span> responses will be scanned</p>
<b>Emulating slow connections:</b>
<br>
<p>
<span class="code">HttpClient4</span> and <span class="code">Java</span> Sampler support emulation of slow connections; see the following entries in <span class="code">jmeter.properties</span>:
<pre class="source">
# Define characters per second &gt; 0 to emulate slow connections
#httpclient.socket.http.cps=0
#httpclient.socket.https.cps=0
</pre>
However the <span class="code">Java</span> sampler only supports slow HTTPS connections.
</p>
<p>
<b>Response size calculation</b>
<br>
<div class="clear"></div>
<div class="note">
The <span class="code">Java</span> implementation does not include transport overhead such as
chunk headers in the response body size.<br>
The <span class="code">HttpClient4</span> implementation does include the overhead in the response body size,
so the value may be greater than the number of bytes in the response content.
</div>
<div class="clear"></div>
</p>
<p>
<b>Retry handling</b>
<br>
By default retry has been set to 0 for both HttpClient4 and Java implementations, meaning no retry is attempted.<br>
For HttpClient4, the retry count can be overridden by setting the relevant JMeter property, for example:
<pre class="source">
httpclient4.retrycount=3
</pre>
<div class="clear"></div>
<div class="note">
With HC4 Implementation, retry will be done on Idempotent Http Methods by default.
If you want to retry for all methods, then set property
<pre class="source">
httpclient4.request_sent_retry_enabled=true
</pre>
</div>
<div class="clear"></div>
Note that the Java implementation does not retry neither by default, you can change this by setting <pre class="source">http.java.sampler.retries=3</pre>
</p>
<p>
<b>Note: Certificates does not conform to algorithm constraints</b>
<br>
You may encounter the following error: <span class="code">java.security.cert.CertificateException: Certificates does not conform to algorithm constraints</span>
if you run a HTTPS request on a web site with a SSL certificate (itself or one of SSL certificates in its chain of trust) with a signature
algorithm using MD2 (like <span class="code">md2WithRSAEncryption</span>) or with a SSL certificate with a size lower than 1024 bits.
</p>
<p>
This error is related to increased security in Java 8.
</p>
<p>
To allow you to perform your HTTPS request, you can downgrade the security of your Java installation by editing
the Java <span class="code">jdk.certpath.disabledAlgorithms</span> property. Remove the MD2 value or the constraint on size, depending on your case.
</p>
<p>
This property is in this file:</p>
<pre class="source">JAVA_HOME/jre/lib/security/java.security</pre>
<p>See <a href="https://bz.apache.org/bugzilla/show_bug.cgi?id=56357">
Bug
56357</a> for details.
</p>
<div class="links">
<div class="title">See also:</div>
<ul class="links">
<li>
<a href="test_plan.html#assertions">Assertion</a>
</li>
<li>
<a href="build-web-test-plan.html">Building a Web Test Plan</a>
</li>
<li>
<a href="build-adv-web-test-plan.html">Building an Advanced Web Test Plan</a>
</li>
<li>
<a href="../usermanual/component_reference.html#HTTP_Authorization_Manager">HTTP Authorization Manager</a>
</li>
<li>
<a href="../usermanual/component_reference.html#HTTP_Cookie_Manager">HTTP Cookie Manager</a>
</li>
<li>
<a href="../usermanual/component_reference.html#HTTP_Header_Manager">HTTP Header Manager</a>
</li>
<li>
<a href="../usermanual/component_reference.html#HTML_Link_Parser">HTML Link Parser</a>
</li>
<li>
<a href="../usermanual/component_reference.html#HTTP(S)_Test_Script_Recorder">HTTP(S) Test Script Recorder</a>
</li>
<li>
<a href="../usermanual/component_reference.html#HTTP_Request_Defaults">HTTP Request Defaults</a>
</li>
<li>
<a href="build-adv-web-test-plan.html#session_url_rewriting">HTTP Requests and Session ID's: URL Rewriting</a>
</li>
</ul>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="JDBC_Request">JDBC Request<a class="sectionlink" href="#JDBC_Request" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>This sampler lets you send a JDBC Request (an SQL query) to a database.</p>
<p>Before using this you need to set up a
<a href="../usermanual/component_reference.html#JDBC_Connection_Configuration">JDBC Connection Configuration</a> Configuration element
</p>
<p>
If the Variable Names list is provided, then for each row returned by a Select statement, the variables are set up
with the value of the corresponding column (if a variable name is provided), and the count of rows is also set up.
For example, if the Select statement returns 2 rows of 3 columns, and the variable list is <span class="code">A,,C</span>,
then the following variables will be set up:</p>
<pre class="source">
A_#=2 (number of rows)
A_1=column 1, row 1
A_2=column 1, row 2
C_#=2 (number of rows)
C_1=column 3, row 1
C_2=column 3, row 2
</pre>
<p>
If the Select statement returns zero rows, then the <span class="code">A_#</span> and <span class="code">C_#</span> variables would be set to <span class="code">0</span>, and no other variables would be set.
</p>
<p>
Old variables are cleared if necessary - e.g. if the first select retrieves six rows and a second select returns only three rows,
the additional variables for rows four, five and six will be removed.
</p>
<div class="clear"></div>
<div class="note">The latency time is set from the time it took to acquire a connection.</div>
<div class="clear"></div>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/jdbctest/jdbc-request.png"><img src="../images/screenshots/jdbctest/jdbc-request.png" width="710" height="629" alt="Screenshot for Control-Panel of JDBC Request"></a>
<figcaption>Screenshot of Control-Panel of JDBC Request</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="JDBC_Request_parms1">
Parameters
<a class="sectionlink" href="#JDBC_Request_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-false">Descriptive name for this sampler that is shown in the tree.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Variable Name of Pool declared in JDBC Connection Configuration</div>
<div class="description req-true">
Name of the JMeter variable that the connection pool is bound to.
This must agree with the '<span class="code">Variable Name</span>' field of a <a href="../usermanual/component_reference.html#JDBC_Connection_Configuration">JDBC Connection Configuration</a>.
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Query Type</div>
<div class="description req-true">Set this according to the statement type:
<ul>
<li>Select Statement</li>
<li>Update Statement - use this for Inserts and Deletes as well</li>
<li>Callable Statement</li>
<li>Prepared Select Statement</li>
<li>Prepared Update Statement - use this for Inserts and Deletes as well</li>
<li>Commit</li>
<li>Rollback</li>
<li>Autocommit(false)</li>
<li>Autocommit(true)</li>
<li>Edit - this should be a variable reference that evaluates to one of the above</li>
</ul>
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">SQL Query</div>
<div class="description req-true">
SQL query.
<div class="clear"></div>
<div class="note">Do not enter a trailing semi-colon.</div>
<div class="clear"></div>
There is generally no need to use <span class="code">{</span> and <span class="code">}</span> to enclose Callable statements;
however they may be used if the database uses a non-standard syntax.
<div class="clear"></div>
<div class="note">The JDBC driver automatically converts the statement if necessary when it is enclosed in <span class="code">{}</span>.</div>
<div class="clear"></div>
For example:
<ul>
<li>
<span class="code">select * from t_customers where id=23</span>
</li>
<li>
<span class="code">CALL SYSCS_UTIL.SYSCS_EXPORT_TABLE (null, ?, ?, null, null, null)</span>
<ul>
<li>Parameter values: <span class="code">tablename</span>,<span class="code">filename</span>
</li>
<li>Parameter types: <span class="code">VARCHAR</span>,<span class="code">VARCHAR</span>
</li>
</ul>
</li>
</ul>
The second example assumes you are using Apache Derby.
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Parameter values</div>
<div class="description req-true">
Comma-separated list of parameter values. Use <span class="code">]NULL[</span> to indicate a <span class="code">NULL</span> parameter.
(If required, the null string can be changed by defining the property "<span class="code">jdbcsampler.nullmarker</span>".)
<br>
The list must be enclosed in double-quotes if any of the values contain a comma or double-quote,
and any embedded double-quotes must be doubled-up, for example:
<pre class="source">"Dbl-Quote: "" and Comma: ,"</pre>
<div class="clear"></div>
<div class="note">There must be as many values as there are placeholders in the statement even if your parameters are <span class="code">OUT</span> ones.
Be sure to set a value even if the value will not be used (for example in a CallableStatement).</div>
<div class="clear"></div>
</div>
<div class="required req-true">Yes, if a prepared or callable statement has parameters</div>
</div>
<div class="property">
<div class="name req-true">Parameter types</div>
<div class="description req-true">
Comma-separated list of SQL parameter types (e.g. <span class="code">INTEGER</span>, <span class="code">DATE</span>, <span class="code">VARCHAR</span>, <span class="code">DOUBLE</span>) or integer values of Constants. Those integer values can be used, when you use custom database types proposed by driver (For example <span class="code">OracleTypes.CURSOR</span> could be represented by its integer value <span class="code">-10</span>).<br>
These are defined as fields in the class <span class="code">java.sql.Types</span>, see for example:<br>
<a href="http://docs.oracle.com/javase/8/docs/api/java/sql/Types.html">Javadoc for java.sql.Types</a>.<br>
<div class="clear"></div>
<div class="note">Note: JMeter will use whatever types are defined by the runtime JVM,
so if you are running on a different JVM, be sure to check the appropriate documentation</div>
<div class="clear"></div>
<b>If the callable statement has <span class="code">INOUT</span> or <span class="code">OUT</span> parameters, then these must be indicated by prefixing the
appropriate parameter types, e.g. instead of "<span class="code">INTEGER</span>", use "<span class="code">INOUT INTEGER</span>".</b>
<br>
If not specified, "<span class="code">IN</span>" is assumed, i.e. "<span class="code">DATE</span>" is the same as "<span class="code">IN DATE</span>".
<br>
If the type is not one of the fields found in <span class="code">java.sql.Types</span>, JMeter also
accepts the corresponding integer number, e.g. since <span class="code">OracleTypes.CURSOR == -10</span>, you can use "<span class="code">INOUT -10</span>".
<br>
There must be as many types as there are placeholders in the statement.
</div>
<div class="required req-true">Yes, if a prepared or callable statement has parameters</div>
</div>
<div class="property">
<div class="name req-false">Variable Names</div>
<div class="description req-false">Comma-separated list of variable names to hold values returned by Select statements, Prepared Select Statements or CallableStatement.
Note that when used with CallableStatement, list of variables must be in the same sequence as the <span class="code">OUT</span> parameters returned by the call.
If there are less variable names than <span class="code">OUT</span> parameters only as many results shall be stored in the thread-context variables as variable names were supplied.
If more variable names than <span class="code">OUT</span> parameters exist, the additional variables will be ignored</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Result Variable Name</div>
<div class="description req-false">
If specified, this will create an Object variable containing a list of row maps.
Each map contains the column name as the key and the column data as the value. Usage:<br>
<pre class="source">columnValue = vars.getObject("resultObject").get(0).get("Column Name");</pre>
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Query timeout(s)</div>
<div class="description req-false">Set a timeout in seconds for query, empty value means 0 which is infinite. <span class="code">-1</span> means don't set any query timeout
which might be needed for use case or when certain drivers don't support timeout. Defaults to 0.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Limit ResultSet</div>
<div class="description req-false">Limits the number of rows to iterate through the ResultSet. Empty value means <span class="code">-1</span>, e.g. no limitation, which is also the default. This can help to reduce the amount of data to be fetched from the database via the JDBC driver, but affects all possible options of <span class="code">Handle ResultSet</span> respectively &ndash; e.g. incomplete ResultSet and a record count &le; the limit.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Handle ResultSet</div>
<div class="description req-false">Defines how ResultSet returned from callable statements be handled:
<ul>
<li>
<span class="code">Store As String</span> (default) - All variables on Variable Names list are stored as strings, will not iterate through a <span class="code">ResultSet</span> when present on the list. <span class="code">CLOB</span>s will be converted to Strings. <span class="code">BLOB</span>s will be converted to Strings as if they were an UTF-8 encoded byte-array. Both <span class="code">CLOB</span>s and <span class="code">BLOB</span>s will be cut off after <span class="code">jdbcsampler.max_retain_result_size</span> bytes.</li>
<li>
<span class="code">Store As Object</span> - Variables of <span class="code">ResultSet</span> type on Variables Names list will be stored as Object and can be accessed in subsequent tests/scripts and iterated, will not iterate through the <span class="code">ResultSet</span>. <span class="code">CLOB</span>s will be handled as if <span class="code">Store As String</span> was selected. <span class="code">BLOBs</span> will be stored as a byte array. Both <span class="code">CLOB</span>s and <span class="code">BLOB</span>s will be cut off after <span class="code">jdbcsampler.max_retain_result_size</span> bytes.</li>
<li>
<span class="code">Count Records</span> - Variables of <span class="code">ResultSet</span> types will be iterated through showing the count of records as result. Variables will be stored as Strings. For <span class="code">BLOB</span>s the size of the object will be stored.</li>
</ul>
</div>
<div class="required req-false">No</div>
</div>
</div>
<div class="links">
<div class="title">See also:</div>
<ul class="links">
<li>
<a href="build-db-test-plan.html">Building a Database Test Plan</a>
</li>
<li>
<a href="../usermanual/component_reference.html#JDBC_Connection_Configuration">JDBC Connection Configuration</a>
</li>
</ul>
</div>
<div class="clear"></div>
<div class="note">Current Versions of JMeter use UTF-8 as the character encoding. Previously the platform default was used.</div>
<div class="clear"></div>
<div class="clear"></div>
<div class="note">Ensure Variable Name is unique across Test Plan.</div>
<div class="clear"></div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="Java_Request">Java Request<a class="sectionlink" href="#Java_Request" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>This sampler lets you control a java class that implements the
<span class="code">org.apache.jmeter.protocol.java.sampler.JavaSamplerClient</span> interface.
By writing your own implementation of this interface,
you can use JMeter to harness multiple threads, input parameter control, and
data collection.</p>
<p>The pull-down menu provides the list of all such implementations found by
JMeter in its classpath. The parameters can then be specified in the
table below - as defined by your implementation. Two simple examples (<span class="code">JavaTest</span> and <span class="code">SleepTest</span>) are provided.
</p>
<p>
The <span class="code">JavaTest</span> example sampler can be useful for checking test plans, because it allows one to set
values in almost all the fields. These can then be used by Assertions, etc.
The fields allow variables to be used, so the values of these can readily be seen.
</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/java_request.png"><img src="../images/screenshots/java_request.png" width="628" height="365" alt="Screenshot for Control-Panel of Java Request"></a>
<figcaption>Screenshot of Control-Panel of Java Request</figcaption>
</figure>
</div>
<div class="clear"></div>
<div class="note">If the method <span class="code">teardownTest</span> is not overridden by a subclass of <span class="code"><a href="../api/org/apache/jmeter/protocol/java/sampler/AbstractJavaSamplerClient.html">AbstractJavaSamplerClient</a></span>, its <span class="code">teardownTest</span> method will not be called.
This reduces JMeter memory requirements.
This will not have any impact on existing Test plans.
</div>
<div class="clear"></div>
<div class="clear"></div>
<div class="note">The Add/Delete buttons don't serve any purpose at present.</div>
<div class="clear"></div>
<div class="properties">
<h3 id="Java_Request_parms1">
Parameters
<a class="sectionlink" href="#Java_Request_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-false">Descriptive name for this sampler
that is shown in the tree.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Classname</div>
<div class="description req-true">The specific implementation of
the JavaSamplerClient interface to be sampled.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Send Parameters with Request</div>
<div class="description req-false">A list of
arguments that will be passed to the sampled class. All arguments
are sent as Strings. See below for specific settings.</div>
<div class="required req-false">No</div>
</div>
</div>
<p>The following parameters apply to the <span class="code">SleepTest</span> and <span class="code">JavaTest</span> implementations:</p>
<div class="properties">
<h3 id="Java_Request_parms2">
Parameters
<a class="sectionlink" href="#Java_Request_parms2" title="Link to here">&para;</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">Sleep_time</div>
<div class="description req-true">How long to sleep for (ms)</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Sleep_mask</div>
<div class="description req-true">How much "randomness" to add:<br>
The sleep time is calculated as follows:
<pre class="source">totalSleepTime = SleepTime + (System.currentTimeMillis() % SleepMask)</pre>
</div>
<div class="required req-true">Yes</div>
</div>
</div>
<p>The following parameters apply additionally to the <span class="code">JavaTest</span> implementation:</p>
<div class="properties">
<h3 id="Java_Request_parms3">
Parameters
<a class="sectionlink" href="#Java_Request_parms3" title="Link to here">&para;</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">Label</div>
<div class="description req-false">The label to use. If provided, overrides <span class="code">Name</span>
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">ResponseCode</div>
<div class="description req-false">If provided, sets the SampleResult ResponseCode.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">ResponseMessage</div>
<div class="description req-false">If provided, sets the SampleResult ResponseMessage.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Status</div>
<div class="description req-false">If provided, sets the SampleResult Status. If this equals "<span class="code">OK</span>" (ignoring case) then the status is set to success, otherwise the sample is marked as failed.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">SamplerData</div>
<div class="description req-false">If provided, sets the SampleResult SamplerData.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">ResultData</div>
<div class="description req-false">If provided, sets the SampleResult ResultData.</div>
<div class="required req-false">No</div>
</div>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="LDAP_Request">LDAP Request<a class="sectionlink" href="#LDAP_Request" title="Link to here">&para;</a>
</h2>
<div class="description">This Sampler lets you send a different LDAP request(<span class="code">Add</span>, <span class="code">Modify</span>, <span class="code">Delete</span> and <span class="code">Search</span>) to an LDAP server.
<p>If you are going to send multiple requests to the same LDAP server, consider
using an <a href="../usermanual/component_reference.html#LDAP_Request_Defaults">LDAP Request Defaults</a>
Configuration Element so you do not have to enter the same information for each
LDAP Request.</p> The same way the <a href="../usermanual/component_reference.html#Login_Config_Element">Login Config Element</a> also using for Login and password.
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/ldap_request.png"><img src="../images/screenshots/ldap_request.png" width="621" height="462" alt="Screenshot for Control-Panel of LDAP Request"></a>
<figcaption>Screenshot of Control-Panel of LDAP Request</figcaption>
</figure>
</div>
<p>There are two ways to create test cases for testing an LDAP Server.</p>
<ol>
<li>Inbuilt Test cases.</li>
<li>User defined Test cases.</li>
</ol>
<p>There are four test scenarios of testing LDAP. The tests are given below:</p>
<ol>
<li>Add Test
<ol>
<li>Inbuilt test:
<p>This will add a pre-defined entry in the LDAP Server and calculate
the execution time. After execution of the test, the created entry will be
deleted from the LDAP
Server.</p>
</li>
<li>User defined test:
<p>This will add the entry in the LDAP Server. User has to enter all the
attributes in the table.The entries are collected from the table to add. The
execution time is calculated. The created entry will not be deleted after the
test.</p>
</li>
</ol>
</li>
<li>Modify Test
<ol>
<li>Inbuilt test:
<p>This will create a pre-defined entry first, then will modify the
created entry in the LDAP Server.And calculate the execution time. After
execution
of the test, the created entry will be deleted from the LDAP Server.</p>
</li>
<li>User defined test:
<p>This will modify the entry in the LDAP Server. User has to enter all the
attributes in the table. The entries are collected from the table to modify.
The execution time is calculated. The entry will not be deleted from the LDAP
Server.</p>
</li>
</ol>
</li>
<li>Search Test
<ol>
<li>Inbuilt test:
<p>This will create the entry first, then will search if the attributes
are available. It calculates the execution time of the search query. At the
end of the execution,created entry will be deleted from the LDAP Server.</p>
</li>
<li>User defined test:
<p>This will search the user defined entry(Search filter) in the Search
base (again, defined by the user). The entries should be available in the LDAP
Server. The execution time is calculated.</p>
</li>
</ol>
</li>
<li>Delete Test
<ol>
<li>Inbuilt test:
<p>This will create a pre-defined entry first, then it will be deleted
from the LDAP Server. The execution time is calculated.</p>
</li>
<li>User defined test:
<p>This will delete the user-defined entry in the LDAP Server. The entries
should be available in the LDAP Server. The execution time is calculated.</p>
</li>
</ol>
</li>
</ol>
<div class="properties">
<h3 id="LDAP_Request_parms1">
Parameters
<a class="sectionlink" href="#LDAP_Request_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-false">Descriptive name for this sampler that is shown in the tree.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Server Name or IP</div>
<div class="description req-true">Domain name or IP address of the LDAP server.
JMeter assumes the LDAP server is listening on the default port (<span class="code">389</span>).</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Port</div>
<div class="description req-true">Port to connect to (default is <span class="code">389</span>).</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">root DN</div>
<div class="description req-true">Base DN to use for LDAP operations</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Username</div>
<div class="description req-false">LDAP server username.</div>
<div class="required req-false">Usually</div>
</div>
<div class="property">
<div class="name req-false">Password</div>
<div class="description req-false">LDAP server password. (N.B. this is stored unencrypted in the test plan)</div>
<div class="required req-false">Usually</div>
</div>
<div class="property">
<div class="name req-true">Entry DN</div>
<div class="description req-true">the name of the context to create or Modify; may not be empty.
<div class="clear"></div>
<div class="note">You have to set the right attributes of the object yourself. So if you want to add <span class="code">cn=apache,ou=test</span>
you have to add in the table <span class="code">name</span> and <span class="code">value</span> to <span class="code">cn</span> and <span class="code">apache</span>.
</div>
<div class="clear"></div>
</div>
<div class="required req-true">Yes, if User Defined Test and Add Test or Modify Test is selected</div>
</div>
<div class="property">
<div class="name req-true">Delete</div>
<div class="description req-true">the name of the context to Delete; may not be empty</div>
<div class="required req-true">Yes, if User Defined Test and Delete Test is selected</div>
</div>
<div class="property">
<div class="name req-true">Search base</div>
<div class="description req-true">the name of the context or object to search</div>
<div class="required req-true">Yes, if User Defined Test and Search Test is selected</div>
</div>
<div class="property">
<div class="name req-true">Search filter</div>
<div class="description req-true"> the filter expression to use for the search; may not be null</div>
<div class="required req-true">Yes, if User Defined Test and Search Test is selected</div>
</div>
<div class="property">
<div class="name req-true">add test</div>
<div class="description req-true">Use these <span class="code">name</span>, <span class="code">value</span> pairs for creation of the new object in the given context</div>
<div class="required req-true">Yes, if User Defined Test and add Test is selected</div>
</div>
<div class="property">
<div class="name req-true">modify test</div>
<div class="description req-true">Use these <span class="code">name</span>, <span class="code">value</span> pairs for modification of the given context object</div>
<div class="required req-true">Yes, if User Defined Test and Modify Test is selected</div>
</div>
</div>
<div class="links">
<div class="title">See also:</div>
<ul class="links">
<li>
<a href="build-ldap-test-plan.html">Building an LDAP Test Plan</a>
</li>
<li>
<a href="../usermanual/component_reference.html#LDAP_Request_Defaults">LDAP Request Defaults</a>
</li>
</ul>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="LDAP_Extended_Request">LDAP Extended Request<a class="sectionlink" href="#LDAP_Extended_Request" title="Link to here">&para;</a>
</h2>
<div class="description">This Sampler can send all 8 different LDAP requests to an LDAP server. It is an extended version of the LDAP sampler,
therefore it is harder to configure, but can be made much closer resembling a real LDAP session.
<p>If you are going to send multiple requests to the same LDAP server, consider
using an <a href="../usermanual/component_reference.html#LDAP_Extended_Request_Defaults">LDAP Extended Request Defaults</a>
Configuration Element so you do not have to enter the same information for each
LDAP Request.</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/ldapext_request.png"><img src="../images/screenshots/ldapext_request.png" width="619" height="371" alt="Screenshot for Control-Panel of LDAP Extended Request"></a>
<figcaption>Screenshot of Control-Panel of LDAP Extended Request</figcaption>
</figure>
</div>
<p>There are nine test operations defined. These operations are given below:</p>
<dl>
<dt>
<b>Thread bind</b>
</dt>
<dd>
<p>Any LDAP request is part of an LDAP session, so the first thing that should be done is starting a session to the LDAP server.
For starting this session a thread bind is used, which is equal to the LDAP "<span class="code">bind</span>" operation.
The user is requested to give a <span class="code">username</span> (Distinguished name) and <span class="code">password</span>,
which will be used to initiate a session.
When no password, or the wrong password is specified, an anonymous session is started. Take care,
omitting the password will not fail this test, a wrong password will.
(N.B. this is stored unencrypted in the test plan)</p>
<div class="properties">
<h3>
Parameters
</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">Name</div>
<div class="description req-false">Descriptive name for this sampler that is shown in the tree.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Servername</div>
<div class="description req-true">The name (or IP-address) of the LDAP server.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Port</div>
<div class="description req-false">The port number that the LDAP server is listening to. If this is omitted
JMeter assumes the LDAP server is listening on the default port(389).</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">DN</div>
<div class="description req-false">The distinguished name of the base object that will be used for any subsequent operation.
It can be used as a starting point for all operations. You cannot start any operation on a higher level than this DN!</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Username</div>
<div class="description req-false">Full distinguished name of the user as which you want to bind.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Password</div>
<div class="description req-false">Password for the above user. If omitted it will result in an anonymous bind.
If it is incorrect, the sampler will return an error and revert to an anonymous bind. (N.B. this is stored unencrypted in the test plan)</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Connection timeout (in milliseconds)</div>
<div class="description req-false">Timeout for connection, if exceeded connection will be aborted</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Use Secure LDAP Protocol</div>
<div class="description req-false">Use <span class="code">ldaps://</span> scheme instead of <span class="code">ldap://</span>
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Trust All Certificates</div>
<div class="description req-false">Trust all certificates, only used if <span class="code">Use Secure LDAP Protocol</span> is checked</div>
<div class="required req-false">No</div>
</div>
</div>
</dd>
<dt>
<b>Thread unbind</b>
</dt>
<dd>
<p>This is simply the operation to end a session.
It is equal to the LDAP "<span class="code">unbind</span>" operation.</p>
<div class="properties">
<h3>
Parameters
</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">Name</div>
<div class="description req-false">Descriptive name for this sampler that is shown in the tree.</div>
<div class="required req-false">No</div>
</div>
</div>
</dd>
<dt>
<b>Single bind/unbind</b>
</dt>
<dd>
<p> This is a combination of the LDAP "<span class="code">bind</span>" and "<span class="code">unbind</span>" operations.
It can be used for an authentication request/password check for any user. It will open a new session, just to
check the validity of the user/password combination, and end the session again.</p>
<div class="properties">
<h3>
Parameters
</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">Name</div>
<div class="description req-false">Descriptive name for this sampler that is shown in the tree.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Username</div>
<div class="description req-true">Full distinguished name of the user as which you want to bind.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Password</div>
<div class="description req-false">Password for the above user. If omitted it will result in an anonymous bind.
If it is incorrect, the sampler will return an error. (N.B. this is stored unencrypted in the test plan)</div>
<div class="required req-false">No</div>
</div>
</div>
</dd>
<dt>
<b>Rename entry</b>
</dt>
<dd>
<p>This is the LDAP "<span class="code">moddn</span>" operation. It can be used to rename an entry, but
also for moving an entry or a complete subtree to a different place in
the LDAP tree.</p>
<div class="properties">
<h3>
Parameters
</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">Name</div>
<div class="description req-false">Descriptive name for this sampler that is shown in the tree.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Old entry name</div>
<div class="description req-true">The current distinguished name of the object you want to rename or move,
relative to the given DN in the thread bind operation.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">New distinguished name</div>
<div class="description req-true">The new distinguished name of the object you want to rename or move,
relative to the given DN in the thread bind operation.</div>
<div class="required req-true">Yes</div>
</div>
</div>
</dd>
<dt>
<b>Add test</b>
</dt>
<dd>
<p>This is the LDAP "<span class="code">add</span>" operation. It can be used to add any kind of
object to the LDAP server.</p>
<div class="properties">
<h3>
Parameters
</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">Name</div>
<div class="description req-false">Descriptive name for this sampler that is shown in the tree.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Entry DN</div>
<div class="description req-true">Distinguished name of the object you want to add, relative to the given DN in the thread bind operation.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Add test</div>
<div class="description req-true">A list of attributes and their values you want to use for the object.
If you need to add a multiple value attribute, you need to add the same attribute with their respective
values several times to the list.</div>
<div class="required req-true">Yes</div>
</div>
</div>
</dd>
<dt>
<b>Delete test</b>
</dt>
<dd>
<p> This is the LDAP "<span class="code">delete</span>" operation, it can be used to delete an
object from the LDAP tree</p>
<div class="properties">
<h3>
Parameters
</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">Name</div>
<div class="description req-false">Descriptive name for this sampler that is shown in the tree.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Delete</div>
<div class="description req-true">Distinguished name of the object you want to delete, relative to the given DN in the thread bind operation.</div>
<div class="required req-true">Yes</div>
</div>
</div>
</dd>
<dt>
<b>Search test</b>
</dt>
<dd>
<p>This is the LDAP "<span class="code">search</span>" operation, and will be used for defining searches.</p>
<div class="properties">
<h3>
Parameters
</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">Name</div>
<div class="description req-false">Descriptive name for this sampler that is shown in the tree.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Search base</div>
<div class="description req-false">Distinguished name of the subtree you want your
search to look in, relative to the given DN in the thread bind operation.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Search Filter</div>
<div class="description req-true">searchfilter, must be specified in LDAP syntax.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Scope</div>
<div class="description req-false">Use <span class="code">0</span> for baseobject-, <span class="code">1</span> for onelevel- and <span class="code">2</span> for a subtree search. (Default=<span class="code">0</span>)</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Size Limit</div>
<div class="description req-false">Specify the maximum number of results you want back from the server. (default=<span class="code">0</span>, which means no limit.) When the sampler hits the maximum number of results, it will fail with errorcode <span class="code">4</span>
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Time Limit</div>
<div class="description req-false">Specify the maximum amount of (cpu)time (in milliseconds) that the server can spend on your search. Take care, this does not say anything about the response time. (default is <span class="code">0</span>, which means no limit)</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Attributes</div>
<div class="description req-false">Specify the attributes you want to have returned, separated by a semicolon. An empty field will return all attributes</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Return object</div>
<div class="description req-false">Whether the object will be returned (<span class="code">true</span>) or not (<span class="code">false</span>). Default=<span class="code">false</span>
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Dereference aliases</div>
<div class="description req-false">If <span class="code">true</span>, it will dereference aliases, if <span class="code">false</span>, it will not follow them (default=<span class="code">false</span>)</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Parse the search results?</div>
<div class="description req-false">If <span class="code">true</span>, the search results will be added to the response data. If <span class="code">false</span>, a marker - whether results where found or not - will be added to the response data.</div>
<div class="required req-false">No</div>
</div>
</div>
</dd>
<dt>
<b>Modification test</b>
</dt>
<dd>
<p>This is the LDAP "<span class="code">modify</span>" operation. It can be used to modify an object. It
can be used to add, delete or replace values of an attribute. </p>
<div class="properties">
<h3>
Parameters
</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">Name</div>
<div class="description req-false">Descriptive name for this sampler that is shown in the tree.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Entry name</div>
<div class="description req-true">Distinguished name of the object you want to modify, relative
to the given DN in the thread bind operation</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Modification test</div>
<div class="description req-true">The attribute-value-opCode triples. <br>
The <span class="code">opCode</span> can be any valid LDAP operationCode (<span class="code">add</span>, <span class="code">delete</span>, <span class="code">remove</span> or <span class="code">replace</span>).<br>
If you don't specify a value with a <span class="code">delete</span> operation, all values of the given attribute will be deleted. <br>
If you do specify a value in a <span class="code">delete</span> operation, only the given value will be deleted. <br>
If this value is non-existent, the sampler will fail the test.</div>
<div class="required req-true">Yes</div>
</div>
</div>
</dd>
<dt>
<b>Compare</b>
</dt>
<dd>
<p>This is the LDAP "<span class="code">compare</span>" operation. It can be used to compare the value
of a given attribute with some already known value. In reality this is mostly
used to check whether a given person is a member of some group. In such a case
you can compare the DN of the user as a given value, with the values in the
attribute "<span class="code">member</span>" of an object of the type <span class="code">groupOfNames</span>.
If the compare operation fails, this test fails with errorcode <span class="code">49</span>.</p>
<div class="properties">
<h3>
Parameters
</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">Name</div>
<div class="description req-false">Descriptive name for this sampler that is shown in the tree.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Entry DN</div>
<div class="description req-true">The current distinguished name of the object of
which you want to compare an attribute, relative to the given DN in the thread bind operation.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Compare filter</div>
<div class="description req-true">In the form "<span class="code">attribute=value</span>"</div>
<div class="required req-true">Yes</div>
</div>
</div>
</dd>
</dl>
<div class="links">
<div class="title">See also:</div>
<ul class="links">
<li>
<a href="build-ldapext-test-plan.html">Building an LDAP Test Plan</a>
</li>
<li>
<a href="../usermanual/component_reference.html#LDAP_Extended_Request_Defaults">LDAP Extended Request Defaults</a>
</li>
</ul>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="Access_Log_Sampler">Access Log Sampler<a class="sectionlink" href="#Access_Log_Sampler" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>AccessLogSampler was designed to read access logs and generate http requests.
For those not familiar with the access log, it is the log the webserver maintains of every
request it accepted. This means every image, CSS file, JavaScript file, html file, &hellip;</p>
<p>Tomcat uses the common format for access logs. This means any webserver that uses the
common log format can use the AccessLogSampler. Server that use common log format include:
Tomcat, Resin, Weblogic, and SunOne. Common log format looks
like this:</p>
<pre class="source">127.0.0.1 - - [21/Oct/2003:05:37:21 -0500] "GET /index.jsp?%2Findex.jsp= HTTP/1.1" 200 8343</pre>
<div class="clear"></div>
<div class="note">The current implementation of the parser only looks at the text within the quotes that contains one of the HTTP protocol methods (<span class="code">GET</span>, <span class="code">PUT</span>, <span class="code">POST</span>, <span class="code">DELETE</span>, &hellip;).
Everything else is stripped out and ignored. For example, the response code is completely
ignored by the parser. </div>
<div class="clear"></div>
<p>For the future, it might be nice to filter out entries that
do not have a response code of <span class="code">200</span>. Extending the sampler should be fairly simple. There
are two interfaces you have to implement:</p>
<ul>
<li>
<span class="code">org.apache.jmeter.protocol.http.util.accesslog.LogParser</span>
</li>
<li>
<span class="code">org.apache.jmeter.protocol.http.util.accesslog.Generator</span>
</li>
</ul>
<p>The current implementation of AccessLogSampler uses the generator to create a new
HTTPSampler. The servername, port and get images are set by AccessLogSampler. Next,
the parser is called with integer <span class="code">1</span>, telling it to parse one entry. After that,
<span class="code">HTTPSampler.sample()</span> is called to make the request.</p>
<pre class="source">
samp = (HTTPSampler) GENERATOR.generateRequest();
samp.setDomain(this.getDomain());
samp.setPort(this.getPort());
samp.setImageParser(this.isImageParser());
PARSER.parse(1);
res = samp.sample();
res.setSampleLabel(samp.toString());
</pre>
The required methods in <span class="code">LogParser</span> are:
<ul>
<li>
<span class="code">setGenerator(Generator)</span>
</li>
<li>
<span class="code">parse(int)</span>
</li>
</ul>
<p>
Classes implementing <span class="code">Generator</span> interface should provide concrete implementation
for all the methods. For an example of how to implement either interface, refer to
<span class="code">StandardGenerator</span> and <span class="code">TCLogParser</span>.
</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/accesslogsampler.png"><img src="../images/screenshots/accesslogsampler.png" width="702" height="305" alt="Screenshot for Control-Panel of Access Log Sampler"></a>
<figcaption>Screenshot of Control-Panel of Access Log Sampler</figcaption>
</figure>
</div>
<center>
<h2>(Beta Code)</h2>
</center>
<div class="properties">
<h3 id="Access_Log_Sampler_parms1">
Parameters
<a class="sectionlink" href="#Access_Log_Sampler_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-false">Descriptive name for this sampler that is shown in the tree.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Server</div>
<div class="description req-true">Domain name or IP address of the web server.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Protocol</div>
<div class="description req-false">Scheme</div>
<div class="required req-false">No (defaults to http</div>
</div>
<div class="property">
<div class="name req-false">Port</div>
<div class="description req-false">Port the web server is listening to.</div>
<div class="required req-false">No (defaults to 80)</div>
</div>
<div class="property">
<div class="name req-true">Log parser class</div>
<div class="description req-true">The log parser class is responsible for parsing the logs.</div>
<div class="required req-true">Yes (default provided)</div>
</div>
<div class="property">
<div class="name req-false">Filter</div>
<div class="description req-false">The filter class is used to filter out certain lines.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Location of log file</div>
<div class="description req-true">The location of the access log file.</div>
<div class="required req-true">Yes</div>
</div>
</div>
<p>
The <span class="code">TCLogParser</span> processes the access log independently for each thread.
The <span class="code">SharedTCLogParser</span> and <span class="code">OrderPreservingLogParser</span> share access to the file,
i.e. each thread gets the next entry in the log.
</p>
<p>
The <span class="code">SessionFilter</span> is intended to handle Cookies across threads.
It does not filter out any entries, but modifies the cookie manager so that the cookies for a given IP are
processed by a single thread at a time. If two threads try to process samples from the same client IP address,
then one will be forced to wait until the other has completed.
</p>
<p>
The <span class="code">LogFilter</span> is intended to allow access log entries to be filtered by filename and regex,
as well as allowing for the replacement of file extensions. However, it is not currently possible
to configure this via the GUI, so it cannot really be used.
</p>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="BeanShell_Sampler">BeanShell Sampler<a class="sectionlink" href="#BeanShell_Sampler" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>This sampler allows you to write a sampler using the BeanShell scripting language.
</p>
<p>
<b>For full details on using BeanShell, please see the <a href="http://www.beanshell.org/">BeanShell website.</a></b>
<div class="clear"></div>
<div class="note">Migration to <a href="../usermanual/component_reference.html#JSR223_Sampler">JSR223 Sampler</a>+Groovy is highly recommended for performance, support of new Java features and limited maintenance of the BeanShell library.</div>
<div class="clear"></div>
</p>
<p>
The test element supports the <span class="code">ThreadListener</span> and <span class="code">TestListener</span> interface methods.
These must be defined in the initialisation file.
See the file <span class="code">BeanShellListeners.bshrc</span> for example definitions.
</p>
<p>
The BeanShell sampler also supports the <span class="code">Interruptible</span> interface.
The <span class="code">interrupt()</span> method can be defined in the script or the init file.
</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/beanshellsampler.png"><img src="../images/screenshots/beanshellsampler.png" width="848" height="566" alt="Screenshot for Control-Panel of BeanShell Sampler"></a>
<figcaption>Screenshot of Control-Panel of BeanShell Sampler</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="BeanShell_Sampler_parms1">
Parameters
<a class="sectionlink" href="#BeanShell_Sampler_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-false">Descriptive name for this sampler that is shown in the tree.
The name is stored in the script variable Label</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Reset bsh.Interpreter before each call</div>
<div class="description req-true">
If this option is selected, then the interpreter will be recreated for each sample.
This may be necessary for some long running scripts.
For further information, see <a href="best-practices.html#bsh_scripting">Best Practices - BeanShell scripting</a>.
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Parameters</div>
<div class="description req-false">Parameters to pass to the BeanShell script.
This is intended for use with script files; for scripts defined in the GUI, you can use whatever
variable and function references you need within the script itself.
The parameters are stored in the following variables:
<dl>
<dt>
<span class="code">Parameters</span>
</dt>
<dd>string containing the parameters as a single variable</dd>
<dt>
<span class="code">bsh.args</span>
</dt>
<dd>String array containing parameters, split on white-space</dd>
</dl>
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Script file</div>
<div class="description req-false">A file containing the BeanShell script to run.
The file name is stored in the script variable <span class="code">FileName</span>
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Script</div>
<div class="description req-true">The BeanShell script to run.
The return value (if not <span class="code">null</span>) is stored as the sampler result.</div>
<div class="required req-true">Yes (unless script file is provided)</div>
</div>
</div>
<div class="clear"></div>
<div class="note">
N.B. Each Sampler instance has its own BeanShell interpreter,
and Samplers are only called from a single thread
</div>
<div class="clear"></div>
<p>
If the property "<span class="code">beanshell.sampler.init</span>" 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: <span class="code">BeanShellSampler.bshrc</span>.
</p>
<p>
If a script file is supplied, that will be used, otherwise the script will be used.</p>
<div class="clear"></div>
<div class="note">
JMeter processes function and variable references before passing the script field to the interpreter,
so the references will only be resolved once.
Variable and function references in script files will be passed
verbatim to the interpreter, which is likely to cause a syntax error.
In order to use runtime variables, please use the appropriate props methods,
e.g.<span class="code">props.get("START.HMS"); props.put("PROP1","1234");</span>
<br>
BeanShell does not currently support Java 5 syntax such as generics and the enhanced for loop.
</div>
<div class="clear"></div>
<p>Before invoking the script, some variables are set up in the BeanShell interpreter:</p>
<p>The contents of the Parameters field is put into the variable "<span class="code">Parameters</span>".
The string is also split into separate tokens using a single space as the separator, and the resulting list
is stored in the String array <span class="code">bsh.args</span>.</p>
<p>The full list of BeanShell variables that is set up is as follows:</p>
<ul>
<li>
<span class="code">log</span> - the <a href="https://www.slf4j.org/api/org/slf4j/Logger.html">Logger</a>
</li>
<li>
<span class="code">Label</span> - the Sampler label</li>
<li>
<span class="code">FileName</span> - the file name, if any</li>
<li>
<span class="code">Parameters</span> - text from the Parameters field</li>
<li>
<span class="code">bsh.args</span> - the parameters, split as described above</li>
<li>
<span class="code">SampleResult</span> - pointer to the current <a href="../api/org/apache/jmeter/samplers/SampleResult.html">SampleResult</a>
</li>
<li>
<span class="code">ResponseCode</span> defaults to <span class="code">200</span>
</li>
<li>
<span class="code">ResponseMessage</span> defaults to "<span class="code">OK</span>"</li>
<li>
<span class="code">IsSuccess</span> defaults to <span class="code">true</span>
</li>
<li>
<span class="code">ctx</span> - <a href="../api/org/apache/jmeter/threads/JMeterContext.html">JMeterContext</a>
</li>
<li>
<span class="code">vars</span> - <a href="../api/org/apache/jmeter/threads/JMeterVariables.html">JMeterVariables</a> - e.g.
<pre class="source">vars.get("VAR1");
vars.put("VAR2","value");
vars.remove("VAR3");
vars.putObject("OBJ1",new Object());</pre>
</li>
<li>
<span class="code">props</span> - JMeterProperties (class <a href="https://docs.oracle.com/javase/8/docs/api/java/util/Properties.html"><span class="code">java.util.Properties</span></a>) - e.g.
<pre class="source">props.get("START.HMS");
props.put("PROP1","1234");</pre>
</li>
</ul>
<p>When the script completes, control is returned to the Sampler, and it copies the contents
of the following script variables into the corresponding variables in the <a href="../api/org/apache/jmeter/samplers/SampleResult.html">SampleResult</a>:</p>
<ul>
<li>
<span class="code">ResponseCode</span> - for example <span class="code">200</span>
</li>
<li>
<span class="code">ResponseMessage</span> - for example "<span class="code">OK</span>"</li>
<li>
<span class="code">IsSuccess</span> - <span class="code">true</span> or <span class="code">false</span>
</li>
</ul>
<p>The SampleResult ResponseData is set from the return value of the script.
If the script returns null, it can set the response directly, by using the method
<span class="code">SampleResult.setResponseData(data)</span>, where data is either a String or a byte array.
The data type defaults to "<span class="code">text</span>", but can be set to binary by using the method
<span class="code">SampleResult.setDataType(SampleResult.BINARY)</span>.
</p>
<p>The <span class="code">SampleResult</span> variable gives the script full access to all the fields and
methods in the <span class="code">SampleResult</span>. For example, the script has access to the methods
<span class="code">setStopThread(boolean)</span> and <span class="code">setStopTest(boolean)</span>.
Here is a simple (not very useful!) example script:</p>
<pre class="source">
if (bsh.args[0].equalsIgnoreCase("StopThread")) {
log.info("Stop Thread detected!");
SampleResult.setStopThread(true);
}
return "Data from sample with Label "+Label;
//or
SampleResult.setResponseData("My data");
return null;
</pre>
<p>Another example:<br> ensure that the property <span class="code">beanshell.sampler.init=BeanShellSampler.bshrc</span> is defined in <span class="code">jmeter.properties</span>.
The following script will show the values of all the variables in the <span class="code">ResponseData</span> field:
</p>
<pre class="source">
return getVariables();
</pre>
<p>
For details on the methods available for the various classes (<a href="../api/org/apache/jmeter/threads/JMeterVariables.html">JMeterVariables</a>, <a href="../api/org/apache/jmeter/samplers/SampleResult.html">SampleResult</a> etc.) please check the Javadoc or the source code.
Beware however that misuse of any methods can cause subtle faults that may be difficult to find.
</p>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="JSR223_Sampler">JSR223 Sampler<a class="sectionlink" href="#JSR223_Sampler" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>
The JSR223 Sampler allows JSR223 script code to be used to perform a sample or some computation required to create/update variables.
<div class="clear"></div>
<div class="note">
If you don't want to generate a <a href="../api/org/apache/jmeter/samplers/SampleResult.html">SampleResult</a> when this sampler is run, call the following method:
<pre class="source">SampleResult.setIgnore();</pre>
</div>
<div class="clear"></div>
</p>
<p>
The JSR223 test elements have a feature (compilation) that can significantly increase performance.
To benefit from this feature:
</p>
<ul>
<li>Use Script files instead of inlining them. This will make JMeter compile them if this feature is available on ScriptEngine and cache them.</li>
<li>Or Use Script Text and check <span class="code">Cache compiled script if available</span> property.
<div class="clear"></div>
<div class="note">When using this feature, ensure your script code does not use JMeter variables or JMeter function calls directly in script code as caching would only cache first replacement. Instead use script parameters.</div>
<div class="clear"></div>
<div class="clear"></div>
<div class="note">To benefit from caching and compilation, the language engine used for scripting must implement JSR223 <span class="code"><a href="https://docs.oracle.com/javase/8/docs/api/javax/script/Compilable.html">Compilable</a></span> interface (Groovy is one of these, java, beanshell and javascript are not)</div>
<div class="clear"></div>
<div class="clear"></div>
<div class="note">When using Groovy as scripting language and not checking <span class="code">Cache compiled script if available</span> (while caching is recommended), you should set this JVM Property <span class="code">-Dgroovy.use.classvalue=true</span>
due to a Groovy Memory leak as of version 2.4.6, see:
<ul>
<li>
<a href="https://issues.apache.org/jira/browse/GROOVY-7683">GROOVY-7683</a>
</li>
<li>
<a href="https://issues.apache.org/jira/browse/GROOVY-7591">GROOVY-7591</a>
</li>
<li>
<a href="https://bugs.openjdk.java.net/browse/JDK-8136353">JDK-8136353</a>
</li>
</ul>
</div>
<div class="clear"></div>
</li>
</ul>
Cache size is controlled by the following JMeter property (<span class="code">jmeter.properties</span>):
<pre class="source">jsr223.compiled_scripts_cache_size=100</pre>
<div class="clear"></div>
<div class="note">Unlike the <a href="../usermanual/component_reference.html#BeanShell_Sampler">BeanShell Sampler</a>, the interpreter is not saved between invocations.</div>
<div class="clear"></div>
<div class="clear"></div>
<div class="note">
JSR223 Test Elements using Script file or Script text + checked <span class="code">Cache compiled script if available</span> are now compiled if ScriptEngine supports this feature, this enables great performance enhancements.
</div>
<div class="clear"></div>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/jsr223-sampler.png"><img src="../images/screenshots/jsr223-sampler.png" width="861" height="502" alt="Screenshot for Control-Panel of JSR223 Sampler"></a>
<figcaption>Screenshot of Control-Panel of JSR223 Sampler</figcaption>
</figure>
</div>
<div class="clear"></div>
<div class="note">
JMeter processes function and variable references before passing the script field to the interpreter,
so the references will only be resolved once.
Variable and function references in script files will be passed
verbatim to the interpreter, which is likely to cause a syntax error.
In order to use runtime variables, please use the appropriate props methods,
e.g. <pre class="source">props.get("START.HMS");
props.put("PROP1","1234");</pre>
</div>
<div class="clear"></div>
<div class="properties">
<h3 id="JSR223_Sampler_parms1">
Parameters
<a class="sectionlink" href="#JSR223_Sampler_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-false">Descriptive name for this sampler that is shown in the tree.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Scripting Language</div>
<div class="description req-true">Name of the JSR223 scripting language to be used.
<div class="clear"></div>
<div class="note">There are other languages supported than those that appear in the drop-down list.
Others may be available if the appropriate jar is installed in the JMeter lib directory.<br>
Notice that some languages such as Velocity may use a different syntax for JSR223 variables,
e.g. <pre class="source">$log.debug("Hello " + $vars.get("a"));</pre> for Velocity.
</div>
<div class="clear"></div>
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Script File</div>
<div class="description req-false">Name of a file to be used as a JSR223 script, if a relative file path is used, then it will be relative to directory referenced by "<span class="code">user.dir</span>" System property</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Parameters</div>
<div class="description req-false">List of parameters to be passed to the script file or the script.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Cache compiled script if available</div>
<div class="description req-false">If checked (advised) and the language used supports <span class="code"><a href="https://docs.oracle.com/javase/8/docs/api/javax/script/Compilable.html">Compilable</a></span> interface (Groovy is one of these, java, beanshell and javascript are not), JMeter will compile the Script and cache it using it's MD5 hash as unique cache key</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Script</div>
<div class="description req-true">Script to be passed to JSR223 language</div>
<div class="required req-true">Yes (unless script file is provided)</div>
</div>
</div>
<p>
If a script file is supplied, that will be used, otherwise the script will be used.</p>
<p>
Before invoking the script, some variables are set up.
Note that these are JSR223 variables - i.e. they can be used directly in the script.
</p>
<ul>
<li>
<span class="code">log</span> - the <a href="https://www.slf4j.org/api/org/slf4j/Logger.html">Logger</a>
</li>
<li>
<span class="code">Label</span> - the Sampler label</li>
<li>
<span class="code">FileName</span> - the file name, if any</li>
<li>
<span class="code">Parameters</span> - text from the Parameters field</li>
<li>
<span class="code">args</span> - the parameters, split as described above</li>
<li>
<span class="code">SampleResult</span> - pointer to the current <a href="../api/org/apache/jmeter/samplers/SampleResult.html">SampleResult</a>
</li>
<li>
<span class="code">sampler</span> - (<a href="../api/org/apache/jmeter/samplers/Sampler.html">Sampler</a>) - pointer to current Sampler</li>
<li>
<span class="code">ctx</span> - <a href="../api/org/apache/jmeter/threads/JMeterContext.html">JMeterContext</a>
</li>
<li>
<span class="code">vars</span> - <a href="../api/org/apache/jmeter/threads/JMeterVariables.html">JMeterVariables</a> - e.g.
<pre class="source">vars.get("VAR1");
vars.put("VAR2","value");
vars.remove("VAR3");
vars.putObject("OBJ1",new Object());</pre>
</li>
<li>
<span class="code">props</span> - JMeterProperties (class <a href="https://docs.oracle.com/javase/8/docs/api/java/util/Properties.html"><span class="code">java.util.Properties</span></a>) - e.g.
<pre class="source">props.get("START.HMS");
props.put("PROP1","1234");</pre>
</li>
<li>
<span class="code">OUT</span> - System.out - e.g. <span class="code">OUT.println("message")</span>
</li>
</ul>
<p>
The <a href="../api/org/apache/jmeter/samplers/SampleResult.html">SampleResult</a> ResponseData is set from the return value of the script.
If the script returns <span class="code">null</span>, it can set the response directly, by using the method
<span class="code">SampleResult.setResponseData(data)</span>, where data is either a String or a byte array.
The data type defaults to "<span class="code">text</span>", but can be set to binary by using the method
<span class="code">SampleResult.setDataType(SampleResult.BINARY)</span>.
</p>
<p>
The SampleResult variable gives the script full access to all the fields and
methods in the SampleResult. For example, the script has access to the methods
<span class="code">setStopThread(boolean)</span> and <span class="code">setStopTest(boolean)</span>.
</p>
<p>
Unlike the BeanShell Sampler, the JSR223 Sampler does not set the <span class="code">ResponseCode</span>, <span class="code">ResponseMessage</span> and sample status via script variables.
Currently the only way to changes these is via the <a href="../api/org/apache/jmeter/samplers/SampleResult.html">SampleResult</a> methods:
</p>
<ul>
<li>
<span class="code">SampleResult.setSuccessful(true/false)</span>
</li>
<li>
<span class="code">SampleResult.setResponseCode("code")</span>
</li>
<li>
<span class="code">SampleResult.setResponseMessage("message")</span>
</li>
</ul>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="TCP_Sampler">TCP Sampler<a class="sectionlink" href="#TCP_Sampler" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>
The TCP Sampler opens a TCP/IP connection to the specified server.
It then sends the text, and waits for a response.
</p>
<p>
If "<span class="code">Re-use connection</span>" is selected, connections are shared between Samplers in the same thread,
provided that the exact same host name string and port are used.
Different hosts/port combinations will use different connections, as will different threads.
If both of "<span class="code">Re-use connection</span>" and "<span class="code">Close connection</span>" are selected, the socket will be closed after running the sampler.
On the next sampler, another socket will be created. You may want to close a socket at the end of each thread loop.
</p>
<p>
If an error is detected - or "<span class="code">Re-use connection</span>" is not selected - the socket is closed.
Another socket will be reopened on the next sample.
</p>
<p>
The following properties can be used to control its operation:
</p>
<dl>
<dt>
<span class="code">tcp.status.prefix</span>
</dt>
<dd>text that precedes a status number</dd>
<dt>
<span class="code">tcp.status.suffix</span>
</dt>
<dd>text that follows a status number</dd>
<dt>
<span class="code">tcp.status.properties</span>
</dt>
<dd>name of property file to convert status codes to messages</dd>
<dt>
<span class="code">tcp.handler</span>
</dt>
<dd>Name of TCP Handler class (default <span class="code">TCPClientImpl</span>) - only used if not specified on the GUI</dd>
</dl>
The class that handles the connection is defined by the GUI, failing that the property <span class="code">tcp.handler</span>.
If not found, the class is then searched for in the package <span class="code">org.apache.jmeter.protocol.tcp.sampler</span>.
<p>
Users can provide their own implementation.
The class must extend <span class="code">org.apache.jmeter.protocol.tcp.sampler.TCPClient</span>.
</p>
<p>
The following implementations are currently provided.
</p>
<ul>
<li>
<span class="code">TCPClientImpl</span>
</li>
<li>
<span class="code">BinaryTCPClientImpl</span>
</li>
<li>
<span class="code">LengthPrefixedBinaryTCPClientImpl</span>
</li>
</ul>
The implementations behave as follows:
<dl>
<dt>
<span class="code">TCPClientImpl</span>
</dt>
<dd>
This implementation is fairly basic.
When reading the response, it reads until the end of line byte, if this is defined
by setting the property <span class="code">tcp.eolByte</span>, otherwise until the end of the input stream.
You can control charset encoding by setting <span class="code">tcp.charset</span>, which will default to Platform default encoding.
</dd>
<dt>
<span class="code">BinaryTCPClientImpl</span>
</dt>
<dd>
This implementation converts the GUI input, which must be a hex-encoded string, into binary,
and performs the reverse when reading the response.
When reading the response, it reads until the end of message byte, if this is defined
by setting the property <span class="code">tcp.BinaryTCPClient.eomByte</span>, otherwise until the end of the input stream.
</dd>
<dt>
<span class="code">LengthPrefixedBinaryTCPClientImpl</span>
</dt>
<dd>
This implementation extends BinaryTCPClientImpl by prefixing the binary message data with a binary length byte.
The length prefix defaults to 2 bytes.
This can be changed by setting the property <span class="code">tcp.binarylength.prefix.length</span>.
</dd>
<dt>
<b>Timeout handling</b>
</dt>
<dd>
If the timeout is set, the read will be terminated when this expires.
So if you are using an <span class="code">eolByte</span>/<span class="code">eomByte</span>, make sure the timeout is sufficiently long,
otherwise the read will be terminated early.
</dd>
<dt>
<b>Response handling</b>
</dt>
<dd>
If <span class="code">tcp.status.prefix</span> is defined, then the response message is searched for the text following
that up to the suffix. If any such text is found, it is used to set the response code.
The response message is then fetched from the properties file (if provided).
<div class="example">
<div class="title">Usage of pre- and suffix<a class="sectionlink" href="#tcp-prefix-example" title="Link to here">&para;</a>
</div>
For example, if the prefix = "<span class="code">[</span>" and the suffix = "<span class="code">]</span>", then the following response:
<pre class="source">[J28] XI123,23,GBP,CR</pre>
would have the response code <span class="code">J28</span>.
</div>
Response codes in the range "<span class="code">400</span>"-"<span class="code">499</span>" and "<span class="code">500</span>"-"<span class="code">599</span>" are currently regarded as failures;
all others are successful. [This needs to be made configurable!]
</dd>
</dl>
<div class="clear"></div>
<div class="note">The login name/password are not used by the supplied TCP implementations.</div>
<div class="clear"></div>
<br>
Sockets are disconnected at the end of a test run.
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/tcpsampler.png"><img src="../images/screenshots/tcpsampler.png" width="827" height="521" alt="Screenshot for Control-Panel of TCP Sampler"></a>
<figcaption>Screenshot of Control-Panel of TCP Sampler</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="TCP_Sampler_parms1">
Parameters
<a class="sectionlink" href="#TCP_Sampler_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-true">Descriptive name for this element that is shown in the tree.</div>
<div class="required req-true"></div>
</div>
<div class="property">
<div class="name req-false">TCPClient classname</div>
<div class="description req-false">Name of the TCPClient class. Defaults to the property <span class="code">tcp.handler</span>, failing that <span class="code">TCPClientImpl</span>.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">ServerName or IP</div>
<div class="description req-true">Name or IP of TCP server</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Port Number</div>
<div class="description req-true">Port to be used</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Re-use connection</div>
<div class="description req-true">If selected, the connection is kept open. Otherwise it is closed when the data has been read.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Close connection</div>
<div class="description req-true">If selected, the connection will be closed after running the sampler.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">SO_LINGER</div>
<div class="description req-false">Enable/disable <span class="code">SO_LINGER</span> with the specified linger time in seconds when a socket is created. If you set "<span class="code">SO_LINGER</span>" value as <span class="code">0</span>, you may prevent large numbers of sockets sitting around with a <span class="code">TIME_WAIT</span> status.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">End of line(EOL) byte value</div>
<div class="description req-false">Byte value for end of line, set this to a value outside the range <span class="code">-128</span> to <span class="code">+127</span> to skip <span class="code">eol</span> checking. You may set this in <span class="code">jmeter.properties</span> file as well with <span class="code">eolByte</span> property. If you set this in TCP Sampler Config and in <span class="code">jmeter.properties</span> file at the same time, the setting value in the TCP Sampler Config will be used.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Connect Timeout</div>
<div class="description req-false">Connect Timeout (milliseconds, <span class="code">0</span> disables).</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Response Timeout</div>
<div class="description req-false">Response Timeout (milliseconds, <span class="code">0</span> disables).</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Set NoDelay</div>
<div class="description req-true">See <span class="code">java.net.Socket.setTcpNoDelay()</span>.
If selected, this will disable Nagle's algorithm, otherwise Nagle's algorithm will be used.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Text to Send</div>
<div class="description req-true">Text to be sent</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Login User</div>
<div class="description req-false">User Name - not used by default implementation</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Password</div>
<div class="description req-false">Password - not used by default implementation (N.B. this is stored unencrypted in the test plan)</div>
<div class="required req-false">No</div>
</div>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="JMS_Publisher">JMS Publisher<a class="sectionlink" href="#JMS_Publisher" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>
JMS Publisher will publish messages to a given destination (topic/queue). For those not
familiar with JMS, it is the J2EE specification for messaging. There are
numerous JMS servers on the market and several open source options.
</p>
<br>
<div class="clear"></div>
<div class="note">JMeter does not include any JMS implementation jar; this must be downloaded from the JMS provider and put in the lib directory</div>
<div class="clear"></div>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/jmspublisher.png"><img src="../images/screenshots/jmspublisher.png" width="854" height="796" alt="Screenshot for Control-Panel of JMS Publisher"></a>
<figcaption>Screenshot of Control-Panel of JMS Publisher</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="JMS_Publisher_parms1">
Parameters
<a class="sectionlink" href="#JMS_Publisher_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-true">Descriptive name for this element that is shown in the tree.</div>
<div class="required req-true"></div>
</div>
<div class="property">
<div class="name req-true">use JNDI properties file</div>
<div class="description req-true">use <span class="code">jndi.properties</span>.
Note that the file must be on the classpath - e.g. by updating the <span class="code">user.classpath</span> JMeter property.
If this option is not selected, JMeter uses the "<span class="code">JNDI Initial Context Factory</span>" and "<span class="code">Provider URL</span>" fields
to create the connection.
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">JNDI Initial Context Factory</div>
<div class="description req-false">Name of the context factory</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Provider URL</div>
<div class="description req-true">The URL for the JMS provider</div>
<div class="required req-true">Yes, unless using jndi.properties</div>
</div>
<div class="property">
<div class="name req-true">Destination</div>
<div class="description req-true">The message destination (topic or queue name)</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Setup</div>
<div class="description req-true">The destination setup type. With <span class="code">At startup</span>, the destination name is static (i.e. always same name during the test), with <span class="code">Each sample</span>, the destination name is dynamic and is evaluate at each sample (i.e. the destination name may be a variable)</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Authentication</div>
<div class="description req-true">Authentication requirement for the JMS provider</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">User</div>
<div class="description req-false">User Name</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Password</div>
<div class="description req-false">Password (N.B. this is stored unencrypted in the test plan)</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Expiration</div>
<div class="description req-false">
The expiration time (in milliseconds) of the message before it becomes obsolete.
If you do not specify an expiration time, the default value is <span class="code">0</span> (never expires).
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Priority</div>
<div class="description req-false">
The priority level of the message. There are ten priority levels from <span class="code">0</span> (lowest) to <span class="code">9</span> (highest).
If you do not specify a priority level, the default level is <span class="code">4</span>.
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Reconnect on error codes (regex)</div>
<div class="description req-false">Regular expression for JMSException error codes which force reconnection. If empty no reconnection will be done</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Number of samples to aggregate</div>
<div class="description req-true">Number of samples to aggregate</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Message source</div>
<div class="description req-true">Where to obtain the message:
<dl>
<dt>
<span class="code">From File</span>
</dt>
<dd>means the referenced file will be read and reused by all samples. If file name changes it is reloaded since JMeter 3.0</dd>
<dt>
<span class="code">Random File from folder specified below</span>
</dt>
<dd>means a random file will be selected from folder specified below, this folder must contain either files with extension <span class="code">.dat</span> for Bytes Messages, or files with extension <span class="code">.txt</span> or <span class="code">.obj</span> for Object or Text messages</dd>
<dt>
<span class="code">Text area</span>
</dt>
<dd>The Message to use either for Text or Object message</dd>
</dl>
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Message type</div>
<div class="description req-true">Text, Map, Object message or Bytes Message</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Content encoding</div>
<div class="description req-true">Specify the encoding for reading the message source file:
<dl>
<dt>
<span class="code">RAW</span>:</dt>
<dd>No variable support from the file and load it with default system charset.</dd>
<dt>
<span class="code">DEFAULT</span>:</dt>
<dd>Load file with default system encoding, except for XML which relies on XML prolog. If the file contain variables, they will be processed.</dd>
<dt>
<span class="code">Standard charsets</span>:</dt>
<dd>The specified encoding (valid or not) is used for reading the file and processing variables</dd>
</dl>
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Use non-persistent delivery mode?</div>
<div class="description req-false">
Whether to set <span class="code">DeliveryMode.NON_PERSISTENT</span> (defaults to <span class="code">false</span>)
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">JMS Properties</div>
<div class="description req-false">
The JMS Properties are properties specific for the underlying messaging system.
You can setup the name, the value and the class (type) of value. Default type is <span class="code">String</span>.
For example: for WebSphere 5.1 web services you will need to set the JMS Property targetService to test
webservices through JMS.
</div>
<div class="required req-false">No</div>
</div>
</div>
<p>
For the MapMessage type, JMeter reads the source as lines of text.
Each line must have 3 fields, delimited by commas.
The fields are:</p>
<ul>
<li>Name of entry</li>
<li>Object class name, e.g. "<span class="code">String</span>" (assumes <span class="code">java.lang</span> package if not specified)</li>
<li>Object string value</li>
</ul>
<span class="code">valueOf(String)</span>
<pre class="source">
name,String,Example
size,Integer,1234
</pre>
<div class="clear"></div>
<div class="note">
The Object message is implemented and works as follow:
<ul>
<li>Put the JAR that contains your object and its dependencies in <span class="code">jmeter_home/lib/</span> folder</li>
<li>Serialize your object as XML using XStream</li>
<li>Either put result in a file suffixed with <span class="code">.txt</span> or <span class="code">.obj</span> or put XML content directly in Text Area</li>
</ul>
Note that if message is in a file, replacement of properties will not occur while it will if you use Text Area.
</div>
<div class="clear"></div>
<p>
The following table shows some values which may be useful when configuring JMS:
</p>
<table>
<tr>
<th>Apache <a href="http://activemq.apache.org/">ActiveMQ</a></th>
<th>Value(s)</th>
<th>Comment</th>
</tr>
<tr>
<td>Context Factory</td><td><span class="code">org.apache.activemq.jndi.ActiveMQInitialContextFactory</span></td><td>.</td>
</tr>
<tr>
<td>Provider URL</td><td><span class="code">vm://localhost</span></td><td></td>
</tr>
<tr>
<td>Provider URL</td><td><span class="code">vm:(broker:(vm://localhost)?persistent=false)</span></td><td>Disable persistence</td>
</tr>
<tr>
<td>Queue Reference</td><td><span class="code">dynamicQueues/QUEUENAME</span></td>
<td><a href="http://activemq.apache.org/jndi-support.html#JNDISupport-Dynamicallycreatingdestinations">Dynamically define</a> the QUEUENAME to JNDI</td>
</tr>
<tr>
<td>Topic Reference</td><td><span class="code">dynamicTopics/TOPICNAME</span></td>
<td><a href="http://activemq.apache.org/jndi-support.html#JNDISupport-Dynamicallycreatingdestinations">Dynamically define</a> the TOPICNAME to JNDI</td>
</tr>
</table>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="JMS_Subscriber">JMS Subscriber<a class="sectionlink" href="#JMS_Subscriber" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>
JMS Subscriber will subscribe to messages in a given destination (topic or queue). For those not
familiar with JMS, it is the J2EE specification for messaging. There are
numerous JMS servers on the market and several open source options.
</p>
<br>
<div class="clear"></div>
<div class="note">JMeter does not include any JMS implementation jar; this must be downloaded from the JMS provider and put in the lib directory</div>
<div class="clear"></div>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/jmssubscriber.png"><img src="../images/screenshots/jmssubscriber.png" width="739" height="607" alt="Screenshot for Control-Panel of JMS Subscriber"></a>
<figcaption>Screenshot of Control-Panel of JMS Subscriber</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="JMS_Subscriber_parms1">
Parameters
<a class="sectionlink" href="#JMS_Subscriber_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-true">Descriptive name for this element that is shown in the tree.</div>
<div class="required req-true"></div>
</div>
<div class="property">
<div class="name req-true">use JNDI properties file</div>
<div class="description req-true">use <span class="code">jndi.properties</span>.
Note that the file must be on the classpath - e.g. by updating the <span class="code">user.classpath</span> JMeter property.
If this option is not selected, JMeter uses the "<span class="code">JNDI Initial Context Factory</span>" and "<span class="code">Provider URL</span>" fields
to create the connection.
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">JNDI Initial Context Factory</div>
<div class="description req-false">Name of the context factory</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Provider URL</div>
<div class="description req-false">The URL for the JMS provider</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Destination</div>
<div class="description req-true">the message destination (topic or queue name)</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Durable Subscription ID</div>
<div class="description req-false">The ID to use for a durable subscription. On first
use the respective queue will automatically be generated by the JMS provider if it does not exist yet.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Client ID</div>
<div class="description req-false">The Client ID to use when you use a durable subscription.
Be sure to add a variable like <span class="code">${__threadNum}</span> when you have more than one Thread.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">JMS Selector</div>
<div class="description req-false">Message Selector as defined by JMS specification to extract only
messages that respect the Selector condition. Syntax uses subpart of SQL 92.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Setup</div>
<div class="description req-true">The destination setup type. With <span class="code">At startup</span>, the destination name is static (i.e. always same name during the test), with <span class="code">Each sample</span>, the destination name is dynamic and is evaluated at each sample (i.e. the destination name may be a variable)</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Authentication</div>
<div class="description req-true">Authentication requirement for the JMS provider</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">User</div>
<div class="description req-false">User Name</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Password</div>
<div class="description req-false">Password (N.B. this is stored unencrypted in the test plan)</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Number of samples to aggregate</div>
<div class="description req-true">number of samples to aggregate</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Save response</div>
<div class="description req-true">should the sampler store the response. If not, only the response length is returned.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Timeout</div>
<div class="description req-true">Specify the timeout to be applied, in milliseconds. <span class="code">0</span>=none.
This is the overall aggregate timeout, not per sample.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Client</div>
<div class="description req-true">Which client implementation to use.
Both of them create connections which can read messages. However they use a different strategy, as described below:
<dl>
<dt>
<span class="code">MessageConsumer.receive()</span>
</dt>
<dd>calls <span class="code">receive()</span> for every requested message.
Retains the connection between samples, but does not fetch messages unless the sampler is active.
This is best suited to Queue subscriptions.
</dd>
<dt>
<span class="code">MessageListener.onMessage()</span>
</dt>
<dd>establishes a Listener that stores all incoming messages on a queue.
The listener remains active after the sampler completes.
This is best suited to Topic subscriptions.</dd>
</dl>
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Stop between samples?</div>
<div class="description req-true">
If selected, then JMeter calls <span class="code">Connection.stop()</span> at the end of each sample (and calls <span class="code">start()</span> before each sample).
This may be useful in some cases where multiple samples/threads have connections to the same queue.
If not selected, JMeter calls <span class="code">Connection.start()</span> at the start of the thread, and does not call <span class="code">stop()</span> until the end of the thread.
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Separator</div>
<div class="description req-false">
Separator used to separate messages when there is more than one (related to setting Number of samples to aggregate).
Note that <span class="code">\n</span>, <span class="code">\r</span>, <span class="code">\t</span> are accepted.
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Reconnect on error codes (regex)</div>
<div class="description req-false">Regular expression for JMSException error codes which force reconnection. If empty no reconnection will be done</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Pause between errors (ms)</div>
<div class="description req-false">Pause in milliseconds that Subscriber will make when an error occurs</div>
<div class="required req-false">No</div>
</div>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="JMS_Point-to-Point">JMS Point-to-Point<a class="sectionlink" href="#JMS_Point-to-Point" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>
This sampler sends and optionally receives JMS Messages through point-to-point connections (queues).
It is different from pub/sub messages and is generally used for handling transactions.
</p>
<p>
<span class="code">request_only</span> will typically be used to put load on a JMS System.<br>
<span class="code">request_reply</span> will be used when you want to test response time of a JMS service that processes messages sent to the Request Queue as this mode will wait for the response on the Reply queue sent by this service.<br>
<span class="code">browse</span> returns the current queue depth, i.e. the number of messages on the queue.<br>
<span class="code">read</span> reads a message from the queue (if any).<br>
<span class="code">clear</span> clears the queue, i.e. remove all messages from the queue.<br>
</p>
<p>
JMeter use the properties <span class="code">java.naming.security.[principal|credentials]</span> - if present -
when creating the Queue Connection. If this behaviour is not desired, set the JMeter property
<span class="code">JMSSampler.useSecurity.properties=false</span>
</p>
<br>
<div class="clear"></div>
<div class="note">JMeter does not include any JMS implementation jar; this must be downloaded from the JMS provider and put in the lib directory</div>
<div class="clear"></div>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/jms/JMS_Point-to-Point.png"><img src="../images/screenshots/jms/JMS_Point-to-Point.png" width="882" height="804" alt="Screenshot for Control-Panel of JMS Point-to-Point"></a>
<figcaption>Screenshot of Control-Panel of JMS Point-to-Point</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="JMS_Point-to-Point_parms1">
Parameters
<a class="sectionlink" href="#JMS_Point-to-Point_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-true">Descriptive name for this element that is shown in the tree.</div>
<div class="required req-true"></div>
</div>
<div class="property">
<div class="name req-true">QueueConnection Factory</div>
<div class="description req-true">
The JNDI name of the queue connection factory to use for connecting to the messaging system.
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">JNDI Name Request queue</div>
<div class="description req-true">
This is the JNDI name of the queue to which the messages are sent.
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">JNDI Name Reply queue</div>
<div class="description req-false">
The JNDI name of the receiving queue. If a value is provided here and the communication style is <span class="code">Request Response</span>
this queue will be monitored for responses to the requests sent.
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Number of samples to aggregate</div>
<div class="description req-true">Number of samples to aggregate. Only applicable for Communication style Read.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">JMS Selector</div>
<div class="description req-false">
Message Selector as defined by JMS specification to extract only
messages that respect the Selector condition. Syntax uses subpart of SQL 92.
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Communication style</div>
<div class="description req-true">
The Communication style can be <span class="code">Request Only</span> (also known as Fire and Forget), <span class="code">Request Response</span>,
<span class="code">Read</span>, <span class="code">Browse</span>, <span class="code">Clear</span>:
<dl>
<dt>
<span class="code">Request Only</span>
</dt>
<dd> will only send messages and will not monitor replies. As such it can be used to put load on a system.</dd>
<dt>
<span class="code">Request Response</span>
</dt>
<dd> will send messages and monitor the replies it receives. Behaviour depends on the value of the JNDI Name Reply Queue.
If JNDI Name Reply Queue has a value, this queue is used to monitor the results. Matching of request and reply is done with
the message id of the request and the correlation id of the reply. If the JNDI Name Reply Queue is empty, then
temporary queues will be used for the communication between the requestor and the server.
This is very different from the fixed reply queue. With temporary queues the sending thread will block until the reply message has been received.
With <span class="code">Request Response</span> mode, you need to have a Server that listens to messages sent to Request Queue and sends replies to
queue referenced by <span class="code">message.getJMSReplyTo()</span>.</dd>
<dt>
<span class="code">Read</span>
</dt>
<dd> will read a message from an outgoing queue which has no listeners attached. This can be convenient for testing purposes.
This method can be used if you need to handle queues without a binding file (in case the jmeter-jms-skip-jndi library is used),
which only works with the JMS Point-to-Point sampler. In case binding files are used, one can also use the JMS Subscriber Sampler for reading from a queue.</dd>
<dt>
<span class="code">Browse</span>
</dt>
<dd> will determine the current queue depth without removing messages from the queue, returning the number of messages on the queue.</dd>
<dt>
<span class="code">Clear</span>
</dt>
<dd> will clear the queue, i.e. remove all messages from the queue.</dd>
</dl>
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Use alternate fields for message correlation</div>
<div class="description req-true">
These check-boxes select the fields which will be used for matching the response message with the original request.
<dl>
<dt>
<span class="code">Use Request Message Id</span>
</dt>
<dd>if selected, the request JMSMessageID will be used,
otherwise the request JMSCorrelationID will be used.
In the latter case the correlation id must be specified in the request.</dd>
<dt>
<span class="code">Use Response Message Id</span>
</dt>
<dd>if selected, the response JMSMessageID will be used,
otherwise the response JMSCorrelationID will be used.
</dd>
</dl>
There are two frequently used JMS Correlation patterns:
<dl>
<dt>JMS Correlation ID Pattern</dt>
<dd> i.e. match request and response on their correlation Ids
=&gt; deselect both checkboxes, and provide a correlation id.</dd>
<dt>JMS Message ID Pattern</dt>
<dd>i.e. match request message id with response correlation id
=&gt; select "Use Request Message Id" only.
</dd>
</dl>
In both cases the JMS application is responsible for populating the correlation ID as necessary.
<div class="clear"></div>
<div class="note">if the same queue is used to send and receive messages,
then the response message will be the same as the request message.
In which case, either provide a correlation id and clear both checkboxes;
or select both checkboxes to use the message Id for correlation.
This can be useful for checking raw JMS throughput.</div>
<div class="clear"></div>
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Timeout</div>
<div class="description req-true">
The timeout in milliseconds for the reply-messages. If a reply has not been received within the specified
time, the specific testcase fails and the specific reply message received after the timeout is discarded.
Default value is <span class="code">2000</span> ms. <span class="code">0</span> means no timeout.
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Expiration</div>
<div class="description req-false">
The expiration time (in milliseconds) of the message before it becomes obsolete.
If you do not specify an expiration time, the default value is <span class="code">0</span> (never expires).
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Priority</div>
<div class="description req-false">
The priority level of the message. There are ten priority levels from <span class="code">0</span> (lowest) to <span class="code">9</span> (highest).
If you do not specify a priority level, the default level is <span class="code">4</span>.
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Use non-persistent delivery mode?</div>
<div class="description req-true">
Whether to set <span class="code">DeliveryMode.NON_PERSISTENT</span>.
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Content</div>
<div class="description req-false">
The content of the message.
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">JMS Properties</div>
<div class="description req-false">
The JMS Properties are properties specific for the underlying messaging system.
You can setup the name, the value and the class (type) of value. Default type is <span class="code">String</span>.
For example: for WebSphere 5.1 web services you will need to set the JMS Property targetService to test
webservices through JMS.
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Initial Context Factory</div>
<div class="description req-false">
The Initial Context Factory is the factory to be used to look up the JMS Resources.
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">JNDI properties</div>
<div class="description req-false">
The JNDI Properties are the specific properties for the underlying JNDI implementation.
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Provider URL</div>
<div class="description req-false">
The URL for the JMS provider.
</div>
<div class="required req-false">No</div>
</div>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="JUnit_Request">JUnit Request<a class="sectionlink" href="#JUnit_Request" title="Link to here">&para;</a>
</h2>
<div class="description">
The current implementation supports standard JUnit convention and extensions. It also
includes extensions like <span class="code">oneTimeSetUp</span> and <span class="code">oneTimeTearDown</span>. The sampler works like the
<a href="../usermanual/component_reference.html#Java_Request">Java Request</a> with some differences.
<ul>
<li>rather than use JMeter's test interface, it scans the jar files for classes extending JUnit's <span class="code">TestCase</span> class. That includes any class or subclass.</li>
<li>JUnit test jar files should be placed in <span class="code">jmeter/lib/junit</span> instead of <span class="code">/lib</span> directory.
You can also use the "<span class="code">user.classpath</span>" property to specify where to look for <span class="code">TestCase</span> classes.</li>
<li>JUnit sampler does not use name/value pairs for configuration like the <a href="../usermanual/component_reference.html#Java_Request">Java Request</a>. The sampler assumes <span class="code">setUp</span> and <span class="code">tearDown</span> will configure the test correctly.</li>
<li>The sampler measures the elapsed time only for the test method and does not include <span class="code">setUp</span> and <span class="code">tearDown</span>.</li>
<li>Each time the test method is called, JMeter will pass the result to the listeners.</li>
<li>Support for <span class="code">oneTimeSetUp</span> and <span class="code">oneTimeTearDown</span> is done as a method. Since JMeter is multi-threaded, we cannot call <span class="code">oneTimeSetUp</span>/<span class="code">oneTimeTearDown</span> the same way Maven does it.</li>
<li>The sampler reports unexpected exceptions as errors.
There are some important differences between standard JUnit test runners and JMeter's
implementation. Rather than make a new instance of the class for each test, JMeter
creates 1 instance per sampler and reuses it.
This can be changed with checkbox "<span class="code">Create a new instance per sample</span>".</li>
</ul>
The current implementation of the sampler will try to create an instance using the string constructor first. If the test class does not declare a string constructor, the sampler will look for an empty constructor. Example below:
<div class="example">
<div class="title">JUnit Constructors<a class="sectionlink" href="#junit_constructor_example" title="Link to here">&para;</a>
</div>
Empty Constructor:
<pre class="source">
public class myTestCase {
public myTestCase() {}
}
</pre>
String Constructor:
<pre class="source">
public class myTestCase {
public myTestCase(String text) {
super(text);
}
}
</pre>
</div>
By default, JMeter will provide some default values for the success/failure code and message. Users should define a set of unique success and failure codes and use them uniformly across all tests.
<div class="clear"></div>
<div class="note">
<h3>General Guidelines</h3>
If you use <span class="code">setUp</span> and <span class="code">tearDown</span>, make sure the methods are declared public. If you do not, the test may not run properly.
<br>
Here are some general guidelines for writing JUnit tests so they work well with JMeter. Since JMeter runs multi-threaded, it is important to keep certain things in mind.
<ul>
<li>Write the <span class="code">setUp</span> and <span class="code">tearDown</span> methods so they are thread safe. This generally means avoid using static members.</li>
<li>Make the test methods discrete units of work and not long sequences of actions. By keeping the test method to a discrete operation, it makes it easier to combine test methods to create new test plans.</li>
<li>Avoid making test methods depend on each other. Since JMeter allows arbitrary sequencing of test methods, the runtime behavior is different than the default JUnit behavior.</li>
<li>If a test method is configurable, be careful about where the properties are stored. Reading the properties from the Jar file is recommended.</li>
<li>Each sampler creates an instance of the test class, so write your test so the setup happens in <span class="code">oneTimeSetUp</span> and <span class="code">oneTimeTearDown</span>.</li>
</ul>
</div>
<div class="clear"></div>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/junit_sampler.png"><img src="../images/screenshots/junit_sampler.png" width="397" height="536" alt="Screenshot for Control-Panel of JUnit Request"></a>
<figcaption>Screenshot of Control-Panel of JUnit Request</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="JUnit_Request_parms1">
Parameters
<a class="sectionlink" href="#JUnit_Request_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-true">Descriptive name for this element that is shown in the tree.</div>
<div class="required req-true"></div>
</div>
<div class="property">
<div class="name req-true">Search for JUnit4 annotations</div>
<div class="description req-true">Select this to search for JUnit4 tests (<span class="code">@Test</span> annotations)</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Package filter</div>
<div class="description req-true">Comma separated list of packages to show. Example, <span class="code">org.apache.jmeter</span>,<span class="code">junit.framework</span>.</div>
<div class="required req-true"></div>
</div>
<div class="property">
<div class="name req-true">Class name</div>
<div class="description req-true">Fully qualified name of the JUnit test class.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Constructor string</div>
<div class="description req-true">String pass to the string constructor. If a string is set, the sampler will use the
string constructor instead of the empty constructor.</div>
<div class="required req-true"></div>
</div>
<div class="property">
<div class="name req-true">Test method</div>
<div class="description req-true">The method to test.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Success message</div>
<div class="description req-true">A descriptive message indicating what success means.</div>
<div class="required req-true"></div>
</div>
<div class="property">
<div class="name req-true">Success code</div>
<div class="description req-true">An unique code indicating the test was successful.</div>
<div class="required req-true"></div>
</div>
<div class="property">
<div class="name req-true">Failure message</div>
<div class="description req-true">A descriptive message indicating what failure means.</div>
<div class="required req-true"></div>
</div>
<div class="property">
<div class="name req-true">Failure code</div>
<div class="description req-true">An unique code indicating the test failed.</div>
<div class="required req-true"></div>
</div>
<div class="property">
<div class="name req-true">Error message</div>
<div class="description req-true">A description for errors.</div>
<div class="required req-true"></div>
</div>
<div class="property">
<div class="name req-true">Error code</div>
<div class="description req-true">Some code for errors. Does not need to be unique.</div>
<div class="required req-true"></div>
</div>
<div class="property">
<div class="name req-true">Do not call setUp and tearDown</div>
<div class="description req-true">Set the sampler not to call <span class="code">setUp</span> and <span class="code">tearDown</span>.
By default, <span class="code">setUp</span> and <span class="code">tearDown</span> should be called. Not calling those methods could affect the test and make it inaccurate.
This option should only be used with calling <span class="code">oneTimeSetUp</span> and <span class="code">oneTimeTearDown</span>. If the selected method is <span class="code">oneTimeSetUp</span> or <span class="code">oneTimeTearDown</span>,
this option should be checked.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Append assertion errors</div>
<div class="description req-true">Whether or not to append assertion errors to the response message.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Append runtime exceptions</div>
<div class="description req-true">Whether or not to append runtime exceptions to the response message. Only applies if "<span class="code">Append assertion errors</span>" is not selected.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Create a new Instance per sample</div>
<div class="description req-true">Whether or not to create a new JUnit instance for each sample. Defaults to false, meaning JUnit <span class="code">TestCase</span> is created one and reused.</div>
<div class="required req-true">Yes</div>
</div>
</div>
<p>
The following JUnit4 annotations are recognised:
</p>
<dl>
<dt>
<span class="code">@Test</span>
</dt>
<dd>used to find test methods and classes. The "<span class="code">expected</span>" and "<span class="code">timeout</span>" attributes are supported.</dd>
<dt>
<span class="code">@Before</span>
</dt>
<dd>treated the same as <span class="code">setUp()</span> in JUnit3</dd>
<dt>
<span class="code">@After</span>
</dt>
<dd>treated the same as <span class="code">tearDown()</span> in JUnit3</dd>
<dt>
<span class="code">@BeforeClass</span>, <span class="code">@AfterClass</span>
</dt>
<dd>treated as test methods so they can be run independently as required</dd>
</dl>
<div class="clear"></div>
<div class="note">
Note that JMeter currently runs the test methods directly, rather than leaving it to JUnit.
This is to allow the <span class="code">setUp</span>/<span class="code">tearDown</span> methods to be excluded from the sample time.
As a consequence, the sampler time excludes the time taken to call <span class="code">setUp</span>/<span class="code">tearDown</span> methods and their annotation based alternatives.
</div>
<div class="clear"></div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="Mail_Reader_Sampler">Mail Reader Sampler<a class="sectionlink" href="#Mail_Reader_Sampler" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>
The Mail Reader Sampler can read (and optionally delete) mail messages using POP3(S) or IMAP(S) protocols.
</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/mailreader_sampler.png"><img src="../images/screenshots/mailreader_sampler.png" width="595" height="413" alt="Screenshot for Control-Panel of Mail Reader Sampler"></a>
<figcaption>Screenshot of Control-Panel of Mail Reader Sampler</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="Mail_Reader_Sampler_parms1">
Parameters
<a class="sectionlink" href="#Mail_Reader_Sampler_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-true">Descriptive name for this element that is shown in the tree.</div>
<div class="required req-true"></div>
</div>
<div class="property">
<div class="name req-true">Server Type</div>
<div class="description req-true">The protocol used by the provider: e.g. <span class="code">pop3</span>, <span class="code">pop3s</span>, <span class="code">imap</span>, <span class="code">imaps</span>.
or another string representing the server protocol.
For example <span class="code">file</span> for use with the read-only mail file provider.
The actual provider names for POP3 and IMAP are <span class="code">pop3</span> and <span class="code">imap</span>
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Server</div>
<div class="description req-true">Hostname or IP address of the server. See below for use with <span class="code">file</span> protocol.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Port</div>
<div class="description req-false">Port to be used to connect to the server (optional)</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Username</div>
<div class="description req-true">User login name</div>
<div class="required req-true"></div>
</div>
<div class="property">
<div class="name req-true">Password</div>
<div class="description req-true">User login password (N.B. this is stored unencrypted in the test plan)</div>
<div class="required req-true"></div>
</div>
<div class="property">
<div class="name req-true">Folder</div>
<div class="description req-true">The IMAP(S) folder to use. See below for use with <span class="code">file</span> protocol.</div>
<div class="required req-true">Yes, if using IMAP(S)</div>
</div>
<div class="property">
<div class="name req-true">Number of messages to retrieve</div>
<div class="description req-true">Set this to retrieve all or some messages</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Fetch headers only</div>
<div class="description req-true">If selected, only the message headers will be retrieved.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Delete messages from the server</div>
<div class="description req-true">If set, messages will be deleted after retrieval</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Store the message using MIME</div>
<div class="description req-true">Whether to store the message as MIME.
If so, then the entire raw message is stored in the Response Data; the headers are not stored as they are available in the data.
If not, the message headers are stored as Response Headers.
A few headers are stored (<span class="code">Date</span>, <span class="code">To</span>, <span class="code">From</span>, <span class="code">Subject</span>) in the body.
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Use no security features</div>
<div class="description req-true">Indicates that the connection to the server does not use any security protocol.</div>
<div class="required req-true"></div>
</div>
<div class="property">
<div class="name req-true">Use SSL</div>
<div class="description req-true">Indicates that the connection to the server must use the SSL protocol.</div>
<div class="required req-true"></div>
</div>
<div class="property">
<div class="name req-true">Use StartTLS</div>
<div class="description req-true">Indicates that the connection to the server should attempt to start the TLS protocol.</div>
<div class="required req-true"></div>
</div>
<div class="property">
<div class="name req-true">Enforce StartTLS</div>
<div class="description req-true">If the server does not start the TLS protocol the connection will be terminated.</div>
<div class="required req-true"></div>
</div>
<div class="property">
<div class="name req-true">Trust All Certificates</div>
<div class="description req-true">When selected it will accept all certificates independent of the CA.</div>
<div class="required req-true"></div>
</div>
<div class="property">
<div class="name req-true">Use local truststore</div>
<div class="description req-true">When selected it will only accept certificates that are locally trusted.</div>
<div class="required req-true"></div>
</div>
<div class="property">
<div class="name req-true">Local truststore</div>
<div class="description req-true">Path to file containing the trusted certificates.
Relative paths are resolved against the current directory.
<br>Failing that, against the directory containing the test script (JMX file).
</div>
<div class="required req-true"></div>
</div>
</div>
<div class="clear"></div>
<div class="note">You can pass mail related environment properties by adding to user.properties any of the properties described <a href="https://javaee.github.io/javamail/docs/api/com/sun/mail/pop3/package-summary.html">here</a>.</div>
<div class="clear"></div>
<p>
Messages are stored as subsamples of the main sampler.
Multipart message parts are stored as subsamples of the message.
</p>
<p>
<b>Special handling for "<span class="code">file</span>" protocol:</b>
<br>
The <span class="code">file</span> JavaMail provider can be used to read raw messages from files.
The <span class="code">server</span> field is used to specify the path to the parent of the <span class="code">folder</span>.
Individual message files should be stored with the name <span class="code">n.msg</span>,
where <span class="code">n</span> is the message number.
Alternatively, the <span class="code">server</span> field can be the name of a file which contains a single message.
The current implementation is quite basic, and is mainly intended for debugging purposes.
</p>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="Flow_Control_Action">Flow Control Action<a name="Test_Action">
(was:
Test Action
)
</a><a class="sectionlink" href="#Flow_Control_Action" title="Link to here">&para;</a>
</h2>
<div class="description">
The Flow Control Action sampler is a sampler that is intended for use in a conditional controller.
Rather than generate a sample, the test element either pauses or stops the selected target.
<p>This sampler can also be useful in conjunction with the Transaction Controller, as it allows
pauses to be included without needing to generate a sample.
For variable delays, set the pause time to zero, and add a Timer as a child.</p>
<p>
The "<span class="code">Stop</span>" action stops the thread or test after completing any samples that are in progress.
The "<span class="code">Stop Now</span>" action stops the test without waiting for samples to complete; it will interrupt any active samples.
If some threads fail to stop within the 5 second time-limit, a message will be displayed in GUI mode.
You can try using the <span class="code">Stop</span> command to see if this will stop the threads, but if not, you should exit JMeter.
In CLI mode, JMeter will exit if some threads fail to stop within the 5 second time limit.
<div class="clear"></div>
<div class="note">The time to wait can be changed using the JMeter property <span class="code">jmeterengine.threadstop.wait</span>. The time is given in milliseconds.</div>
<div class="clear"></div>
</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/test_action.png"><img src="../images/screenshots/test_action.png" width="467" height="184" alt="Screenshot for Control-Panel of Flow Control Action"></a>
<figcaption>Screenshot of Control-Panel of Flow Control Action</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="Flow_Control_Action_parms1">
Parameters
<a class="sectionlink" href="#Flow_Control_Action_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-true">Descriptive name for this element that is shown in the tree.</div>
<div class="required req-true"></div>
</div>
<div class="property">
<div class="name req-true">Target</div>
<div class="description req-true">
<span class="code">Current Thread</span> / <span class="code">All Threads</span> (ignored for <span class="code">Pause</span> and <span class="code">Go to next loop iteration</span>)</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Action</div>
<div class="description req-true">
<span class="code">Pause</span> / <span class="code">Stop</span> / <span class="code">Stop Now</span> / <span class="code">Go to next loop iteration</span>
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Duration</div>
<div class="description req-true">How long to pause for (milliseconds)</div>
<div class="required req-true">Yes, if Pause is selected</div>
</div>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="SMTP_Sampler">SMTP Sampler<a class="sectionlink" href="#SMTP_Sampler" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>
The SMTP Sampler can send mail messages using SMTP/SMTPS protocol.
It is possible to set security protocols for the connection (SSL and TLS), as well as user authentication.
If a security protocol is used a verification on the server certificate will occur. <br>
Two alternatives to handle this verification are available:<br>
</p>
<dl>
<dt>
<span class="code">Trust all certificates</span>
</dt>
<dd>This will ignore certificate chain verification</dd>
<dt>
<span class="code">Use a local truststore</span>
</dt>
<dd>With this option the certificate chain will be validated against the local truststore file.</dd>
</dl>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/smtp_sampler.png"><img src="../images/screenshots/smtp_sampler.png" width="825" height="728" alt="Screenshot for Control-Panel of SMTP Sampler"></a>
<figcaption>Screenshot of Control-Panel of SMTP Sampler</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="SMTP_Sampler_parms1">
Parameters
<a class="sectionlink" href="#SMTP_Sampler_parms1" title="Link to here">&para;</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">Server</div>
<div class="description req-true">Hostname or IP address of the server. See below for use with <span class="code">file</span> protocol.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Port</div>
<div class="description req-false">Port to be used to connect to the server.
Defaults are: SMTP=25, SSL=465, StartTLS=587
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Connection timeout</div>
<div class="description req-false">Connection timeout value in milliseconds (socket level). Default is infinite timeout.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Read timeout</div>
<div class="description req-false">Read timeout value in milliseconds (socket level). Default is infinite timeout.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Address From</div>
<div class="description req-true">The from address that will appear in the e-mail</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Address To</div>
<div class="description req-true">The destination e-mail address (multiple values separated by "<span class="code">;</span>")</div>
<div class="required req-true">Yes, unless CC or BCC is specified</div>
</div>
<div class="property">
<div class="name req-false">Address To CC</div>
<div class="description req-false">Carbon copy destinations e-mail address (multiple values separated by "<span class="code">;</span>")</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Address To BCC</div>
<div class="description req-false">Blind carbon copy destinations e-mail address (multiple values separated by "<span class="code">;</span>")</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Address Reply-To</div>
<div class="description req-false">Alternate Reply-To address (multiple values separated by "<span class="code">;</span>")</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Use Auth</div>
<div class="description req-true">Indicates if the SMTP server requires user authentication</div>
<div class="required req-true"></div>
</div>
<div class="property">
<div class="name req-true">Username</div>
<div class="description req-true">User login name</div>
<div class="required req-true"></div>
</div>
<div class="property">
<div class="name req-true">Password</div>
<div class="description req-true">User login password (N.B. this is stored unencrypted in the test plan)</div>
<div class="required req-true"></div>
</div>
<div class="property">
<div class="name req-true">Use no security features</div>
<div class="description req-true">Indicates that the connection to the SMTP server does not use any security protocol.</div>
<div class="required req-true"></div>
</div>
<div class="property">
<div class="name req-true">Use SSL</div>
<div class="description req-true">Indicates that the connection to the SMTP server must use the SSL protocol.</div>
<div class="required req-true"></div>
</div>
<div class="property">
<div class="name req-true">Use StartTLS</div>
<div class="description req-true">Indicates that the connection to the SMTP server should attempt to start the TLS protocol.</div>
<div class="required req-true"></div>
</div>
<div class="property">
<div class="name req-true">Enforce StartTLS</div>
<div class="description req-true">If the server does not start the TLS protocol the connection will be terminated.</div>
<div class="required req-true"></div>
</div>
<div class="property">
<div class="name req-true">Trust All Certificates</div>
<div class="description req-true">When selected it will accept all certificates independent of the CA.</div>
<div class="required req-true"></div>
</div>
<div class="property">
<div class="name req-true">Use local truststore</div>
<div class="description req-true">When selected it will only accept certificates that are locally trusted.</div>
<div class="required req-true"></div>
</div>
<div class="property">
<div class="name req-true">Local truststore</div>
<div class="description req-true">Path to file containing the trusted certificates.
Relative paths are resolved against the current directory.
<br>Failing that, against the directory containing the test script (JMX file).
</div>
<div class="required req-true"></div>
</div>
<div class="property">
<div class="name req-false">Override System SSL/TLS Protocols</div>
<div class="description req-false">Specify a custom SSL/TLS protocol as space separated list to use on handshake example <span class="code">TLSv1 TLSv1.1 TLSv1.2</span>. Defaults to all supported protocols.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Subject</div>
<div class="description req-true">The e-mail message subject.</div>
<div class="required req-true"></div>
</div>
<div class="property">
<div class="name req-true">Suppress Subject Header</div>
<div class="description req-true">If selected, the "<span class="code">Subject:</span>" header is omitted from the mail that is sent.
This is different from sending an empty "<span class="code">Subject:</span>" header, though some e-mail clients may display it identically.</div>
<div class="required req-true"></div>
</div>
<div class="property">
<div class="name req-true">Include timestamp in subject</div>
<div class="description req-true">Includes the <span class="code">System.currentTimemillis()</span> in the subject line.</div>
<div class="required req-true"></div>
</div>
<div class="property">
<div class="name req-false">Add Header</div>
<div class="description req-false">Additional headers can be defined using this button.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Message</div>
<div class="description req-true">The message body.</div>
<div class="required req-true"></div>
</div>
<div class="property">
<div class="name req-true">Send plain body (i.e. not multipart/mixed)</div>
<div class="description req-true">
If selected, then send the body as a plain message, i.e. not <span class="code">multipart/mixed</span>, if possible.
If the message body is empty and there is a single file, then send the file contents as the message body.
<div class="clear"></div>
<div class="note">
Note: If the message body is not empty, and there is at least one attached file, then the body is sent as <span class="code">multipart/mixed</span>.
</div>
<div class="clear"></div>
</div>
<div class="required req-true">
No
</div>
</div>
<div class="property">
<div class="name req-true">Attach files</div>
<div class="description req-true">Files to be attached to the message.</div>
<div class="required req-true"></div>
</div>
<div class="property">
<div class="name req-true">Send .eml</div>
<div class="description req-true">If set, the <span class="code">.eml</span> file will be sent instead of the entries in the <span class="code">Subject</span>, <span class="code">Message</span>, and <span class="code">Attach file(s)</span> fields</div>
<div class="required req-true"></div>
</div>
<div class="property">
<div class="name req-true">Calculate message size</div>
<div class="description req-true">Calculates the message size and stores it in the sample result.</div>
<div class="required req-true"></div>
</div>
<div class="property">
<div class="name req-true">Enable debug logging?</div>
<div class="description req-true">If set, then the "<span class="code">mail.debug</span>" property is set to "<span class="code">true</span>"</div>
<div class="required req-true"></div>
</div>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="OS_Process_Sampler">OS Process Sampler<a class="sectionlink" href="#OS_Process_Sampler" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>
The OS Process Sampler is a sampler that can be used to execute commands on the local machine.<br>
It should allow execution of any command that can be run from the command line.<br>
Validation of the return code can be enabled, and the expected return code can be specified.<br>
</p>
<p>
Note that OS shells generally provide command-line parsing.
This varies between OSes, but generally the shell will split parameters on white-space.
Some shells expand wild-card file names; some don't.
The quoting mechanism also varies between OSes.
The sampler deliberately does not do any parsing or quote handling.
The command and its parameters must be provided in the form expected by the executable.
This means that the sampler settings will not be portable between OSes.
</p>
<p>
Many OSes have some built-in commands which are not provided as separate executables.
For example the Windows <span class="code">DIR</span> command is part of the command interpreter (<span class="code">CMD.EXE</span>).
These built-ins cannot be run as independent programs, but have to be provided as arguments to the appropriate command interpreter.
</p>
<p>
For example, the Windows command-line: <span class="code">DIR C:\TEMP</span> needs to be specified as follows:
</p>
<dl>
<dt>Command:</dt>
<dd>
<span class="code">CMD</span>
</dd>
<dt>Param 1:</dt>
<dd>
<span class="code">/C</span>
</dd>
<dt>Param 2:</dt>
<dd>
<span class="code">DIR</span>
</dd>
<dt>Param 3:</dt>
<dd>
<span class="code">C:\TEMP</span>
</dd>
</dl>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/os_process_sampler.png"><img src="../images/screenshots/os_process_sampler.png" width="683" height="582" alt="Screenshot for Control-Panel of OS Process Sampler"></a>
<figcaption>Screenshot of Control-Panel of OS Process Sampler</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="OS_Process_Sampler_parms1">
Parameters
<a class="sectionlink" href="#OS_Process_Sampler_parms1" title="Link to here">&para;</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">Command</div>
<div class="description req-true">The program name to execute.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Working directory</div>
<div class="description req-false">Directory from which command will be executed, defaults to folder referenced by "<span class="code">user.dir</span>" System property</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Command Parameters</div>
<div class="description req-false">Parameters passed to the program name.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Environment Parameters</div>
<div class="description req-false">Key/Value pairs added to environment when running command.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Standard input (stdin)</div>
<div class="description req-false">Name of file from which input is to be taken (<span class="code">STDIN</span>).</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Standard output (stdout</div>
<div class="description req-false">Name of output file for standard output (<span class="code">STDOUT</span>).
If omitted, output is captured and returned as the response data.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Standard error (stderr)</div>
<div class="description req-false">Name of output file for standard error (<span class="code">STDERR</span>).
If omitted, output is captured and returned as the response data.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Check Return Code</div>
<div class="description req-false">If checked, sampler will compare return code with <span class="code">Expected Return Code</span>.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Expected Return Code</div>
<div class="description req-false">Expected return code for System Call, required if "<span class="code">Check Return Code</span>" is checked. Note 500 is used as an error indicator in JMeter so you should not use it.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Timeout</div>
<div class="description req-false">Timeout for command in milliseconds, defaults to <span class="code">0</span>, which means <em>no</em> timeout.
If the timeout expires before the command finishes, JMeter will attempt to kill the OS process.
</div>
<div class="required req-false">No</div>
</div>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="MongoDB_Script_(DEPRECATED)">MongoDB Script (DEPRECATED)<a class="sectionlink" href="#MongoDB_Script_(DEPRECATED)" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>This sampler lets you send a Request to a MongoDB.</p>
<p>Before using this you need to set up a
<a href="../usermanual/component_reference.html#MongoDB_Source_Config">MongoDB Source Config</a> Configuration element
</p>
<div class="clear"></div>
<div class="note">This Element currently uses <span class="code">com.mongodb.DB#eval</span> which takes a global write lock causing a performance impact on the database, see <a href="http://docs.mongodb.org/manual/reference/method/db.eval/"><span class="code">db.eval()</span></a>.
So it is better to avoid using this element for load testing and use JSR223+Groovy scripting using <a href="../api/org/apache/jmeter/protocol/mongodb/config/MongoDBHolder.html">MongoDBHolder</a> instead.
MongoDB Script is more suitable for functional testing or test setup (setup/teardown threads)</div>
<div class="clear"></div>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/mongodb-script.png"><img src="../images/screenshots/mongodb-script.png" width="847" height="635" alt="Screenshot for Control-Panel of MongoDB Script (DEPRECATED)"></a>
<figcaption>Screenshot of Control-Panel of MongoDB Script (DEPRECATED)</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="MongoDB_Script_(DEPRECATED)_parms1">
Parameters
<a class="sectionlink" href="#MongoDB_Script_(DEPRECATED)_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-false">Descriptive name for this sampler that is shown in the tree.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">MongoDB Source</div>
<div class="description req-true">
Name of the JMeter variable that the MongoDB connection is bound to.
This must agree with the '<span class="code">MongoDB Source</span>' field of a MongoDB Source Config.
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Database Name</div>
<div class="description req-true">Database Name, will be used in your script
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Username</div>
<div class="description req-false">
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Password</div>
<div class="description req-false">
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Script</div>
<div class="description req-true">
Mongo script as it would be used in MongoDB shell
</div>
<div class="required req-true">Yes</div>
</div>
</div>
<div class="links">
<div class="title">See also:</div>
<ul class="links">
<li>
<a href="../usermanual/component_reference.html#MongoDB_Source_Config">MongoDB Source Config</a>
</li>
</ul>
</div>
<div class="clear"></div>
<div class="note">Ensure Variable Name is unique across Test Plan.</div>
<div class="clear"></div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<a href="#">^</a>
<div class="component">
<h2 id="Bolt_Request">Bolt Request<a class="sectionlink" href="#Bolt_Request" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>This sampler allows you to run Cypher queries through the Bolt protocol.</p>
<p>Before using this you need to set up a <a href="../usermanual/component_reference.html#Bolt_Connection_Configuration">Bolt Connection Configuration</a>
</p>
<p>Every request uses a connection acquired from the pool and returns it to the pool when the sampler completes.
The connection pool size use the driver defaults (~100) and is not configurable at the moment.</p>
<p>The measured response time corresponds to the "full" query execution, including both
the time to execute the cypher query AND the time to consume the results sent back by the database.</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/bolt-request.png"><img src="../images/screenshots/bolt-request.png" width="711" height="488" alt="Screenshot for Control-Panel of Bolt Request"></a>
<figcaption>Screenshot of Control-Panel of Bolt Request</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="Bolt_Request_parms1">
Parameters
<a class="sectionlink" href="#Bolt_Request_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-false">Descriptive name for this sampler that is shown in the tree.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Comments</div>
<div class="description req-false">Free text for additional details.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Cypher statement</div>
<div class="description req-true">
The query to execute.
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Params</div>
<div class="description req-false">The parameter values, JSON formatted.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Record Query Results</div>
<div class="description req-false">
Whether to add or not query result data to the sampler response (default false).
Note that activating this has a memory overhead, use it wisely.
</div>
<div class="required req-false">No</div>
</div>
</div>
<div class="clear"></div>
<div class="note">It is strongly advised to use query parameters, allowing the database to cache and reuse execution plans.</div>
<div class="clear"></div>
<div class="links">
<div class="title">See also:</div>
<ul class="links">
<li>
<a href="../usermanual/component_reference.html#Bolt_Connection_Configuration">Bolt Connection Configuration</a>
</li>
</ul>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<a href="#">^</a>
</div>
<div class="section">
<h1 id="logic_controllers">18.2 Logic Controllers<a class="sectionlink" href="#logic_controllers" title="Link to here">&para;</a>
</h1>
<div class="description">
<br>Logic Controllers determine the order in which Samplers are processed.</br>
</div>
<div class="component">
<h2 id="Simple_Controller">Simple Controller<a class="sectionlink" href="#Simple_Controller" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>The Simple Logic Controller lets you organize your Samplers and other
Logic Controllers. Unlike other Logic Controllers, this controller provides no functionality beyond that of a
storage device.</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/logic-controller/simple-controller.png"><img src="../images/screenshots/logic-controller/simple-controller.png" width="330" height="77" alt="Screenshot for Control-Panel of Simple Controller"></a>
<figcaption>Screenshot of Control-Panel of Simple Controller</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="Simple_Controller_parms1">
Parameters
<a class="sectionlink" href="#Simple_Controller_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-false">Descriptive name for this controller that is shown in the tree.</div>
<div class="required req-false">No</div>
</div>
</div>
<div class="example">
<div class="title">Using the Simple Controller<a class="sectionlink" href="#simple_controller_example" title="Link to here">&para;</a>
</div>
<p>
<a href="../demos/SimpleTestPlan.jmx">Download</a> this example (see Figure 6).
In this example, we created a Test Plan that sends two Ant HTTP requests and two
Log4J HTTP requests. We grouped the Ant and Log4J requests by placing them inside
Simple Logic Controllers. Remember, the Simple Logic Controller has no effect on how JMeter
processes the controller(s) you add to it. So, in this example, JMeter sends the requests in the
following order: Ant Home Page, Ant News Page, Log4J Home Page, Log4J History Page.</p>
<p>
Note, the File Reporter
is configured to store the results in a file named "<span class="code">simple-test.dat</span>" in the current directory.</p>
<figure>
<a href="../images/screenshots/logic-controller/simple-example.png"><img src="../images/screenshots/logic-controller/simple-example.png" width="585" height="213" alt="Figure 6 Simple Controller Example"></a>
<figcaption>Figure 6 Simple Controller Example</figcaption>
</figure>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="Loop_Controller">Loop Controller<a class="sectionlink" href="#Loop_Controller" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>If you add Generative or Logic Controllers to a Loop Controller, JMeter will
loop through them a certain number of times, in addition to the loop value you
specified for the Thread Group. For example, if you add one HTTP Request to a
Loop Controller with a loop count of two, and configure the Thread Group loop
count to three, JMeter will send a total of <span class="code">2 * 3 = 6</span> HTTP Requests.
<div class="clear"></div>
<div class="note">JMeter will expose the looping index as a variable named <span class="code">__jm__&lt;Name of your element&gt;__idx</span>. So for
example, if your Loop Controller is named LC, then you can access the looping index through <span class="code">${__jm__LC__idx}</span>.
Index starts at 0</div>
<div class="clear"></div>
</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/logic-controller/loop-controller.png"><img src="../images/screenshots/logic-controller/loop-controller.png" width="326" height="114" alt="Screenshot for Control-Panel of Loop Controller"></a>
<figcaption>Screenshot of Control-Panel of Loop Controller</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="Loop_Controller_parms1">
Parameters
<a class="sectionlink" href="#Loop_Controller_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-false">Descriptive name for this controller that is shown in the tree.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Loop Count</div>
<div class="description req-true">
The number of times the subelements of this controller will be iterated each time
through a test run.
<p>The value <span class="code">-1</span> is equivalent to checking the <span class="code">Forever</span> toggle.</p>
<p>
<b>Special Case:</b> The Loop Controller embedded in the <a href="test_plan.html#thread_group">Thread Group</a>
element behaves slightly different. Unless set to forever, it stops the test after
the given number of iterations have been done.</p>
<div class="clear"></div>
<div class="note">When using a function in this field, be aware it may be evaluated multiple times.
Example using <span class="code"><a href="../usermanual/functions.html#__Random">__Random</a></span> will evaluate it to a different value for each child samplers of Loop Controller and result into unwanted behaviour.</div>
<div class="clear"></div>
</div>
<div class="required req-true">Yes, unless "Forever" is checked</div>
</div>
</div>
<div class="example">
<div class="title">Looping Example<a class="sectionlink" href="#loop_example" title="Link to here">&para;</a>
</div>
<p>
<a href="../demos/LoopTestPlan.jmx">Download</a> this example (see Figure 4).
In this example, we created a Test Plan that sends a particular HTTP Request
only once and sends another HTTP Request five times.</p>
<figure>
<a href="../images/screenshots/logic-controller/loop-example.png"><img src="../images/screenshots/logic-controller/loop-example.png" width="506" height="158" alt="Figure 4 - Loop Controller Example"></a>
<figcaption>Figure 4 - Loop Controller Example</figcaption>
</figure>
<p>We configured the Thread Group for a single thread and a loop count value of
one. Instead of letting the Thread Group control the looping, we used a Loop
Controller. You can see that we added one HTTP Request to the Thread Group and
another HTTP Request to a Loop Controller. We configured the Loop Controller
with a loop count value of five.</p>
<p>JMeter will send the requests in the following order: Home Page, News Page,
News Page, News Page, News Page, and News Page.</p>
<div class="clear"></div>
<div class="note">Note, the File Reporter
is configured to store the results in a file named "<span class="code">loop-test.dat</span>" in the current directory.</div>
<div class="clear"></div>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="Once_Only_Controller">Once Only Controller<a class="sectionlink" href="#Once_Only_Controller" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>The Once Only Logic Controller tells JMeter to process the controller(s) inside it only once per Thread, and pass over any requests under it
during further iterations through the test plan.</p>
<p>The Once Only Controller will now execute always during the first iteration of any looping parent controller.
Thus, if the Once Only Controller is placed under a Loop Controller specified to loop 5 times, then the Once Only Controller will execute only on the first iteration through the Loop Controller
(i.e. every 5 times).</p>
<p>
Note this means the Once Only Controller will still behave as previously expected if put under a Thread Group (runs only once per test per Thread),
but now the user has more flexibility in the use of the Once Only Controller.</p>
<p>For testing that requires a login, consider placing the login request in this controller since each thread only needs
to login once to establish a session.</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/logic-controller/once-only-controller.png"><img src="../images/screenshots/logic-controller/once-only-controller.png" width="330" height="78" alt="Screenshot for Control-Panel of Once Only Controller"></a>
<figcaption>Screenshot of Control-Panel of Once Only Controller</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="Once_Only_Controller_parms1">
Parameters
<a class="sectionlink" href="#Once_Only_Controller_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-false">Descriptive name for this controller that is shown in the tree.</div>
<div class="required req-false">No</div>
</div>
</div>
<div class="example">
<div class="title">Once Only Example<a class="sectionlink" href="#once_only_example" title="Link to here">&para;</a>
</div>
<p>
<a href="../demos/OnceOnlyTestPlan.jmx">Download</a> this example (see Figure 5).
In this example, we created a Test Plan that has two threads that send HTTP request.
Each thread sends one request to the Home Page, followed by three requests to the Bug Page.
Although we configured the Thread Group to iterate three times, each JMeter thread only
sends one request to the Home Page because this request lives inside a Once Only Controller.</p>
<figure>
<a href="../images/screenshots/logic-controller/once-only-example.png"><img src="../images/screenshots/logic-controller/once-only-example.png" width="233" height="138" alt="Figure 5. Once Only Controller Example"></a>
<figcaption>Figure 5. Once Only Controller Example</figcaption>
</figure>
<p>Each JMeter thread will send the requests in the following order: Home Page, Bug Page,
Bug Page, Bug Page.</p>
<p>Note, the File Reporter is configured to store the results in a file named "<span class="code">loop-test.dat</span>" in the current directory.</p>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="Interleave_Controller">Interleave Controller<a class="sectionlink" href="#Interleave_Controller" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>If you add Generative or Logic Controllers to an Interleave Controller, JMeter will alternate among each of the
other controllers for each loop iteration. </p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/logic-controller/interleave-controller.png"><img src="../images/screenshots/logic-controller/interleave-controller.png" width="626" height="127" alt="Screenshot for Control-Panel of Interleave Controller"></a>
<figcaption>Screenshot of Control-Panel of Interleave Controller</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="Interleave_Controller_parms1">
Parameters
<a class="sectionlink" href="#Interleave_Controller_parms1" title="Link to here">&para;</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">name</div>
<div class="description req-false">Descriptive name for this controller that is shown in the tree.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">ignore sub-controller blocks</div>
<div class="description req-false">If checked, the interleave controller will treat sub-controllers like single request elements and only allow one request per controller at a time. </div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Interleave across threads</div>
<div class="description req-false">If checked, the interleave controller will alternate among each of its children controllers for each loop iteration but across all threads, for example in a
configuration with 4 threads and 3 child controllers, on first iteration
thread 1 will run first child, thread 2 second child, thread 3 third child, thread 4 first child, on next iteration each thread will run the following child controller</div>
<div class="required req-false">No</div>
</div>
</div>
<div class="example">
<div class="title">Simple Interleave Example<a class="sectionlink" href="#simple_interleave_example" title="Link to here">&para;</a>
</div>
<p>
<a href="../demos/InterleaveTestPlan.jmx">Download</a> this example (see Figure 1). In this example,
we configured the Thread Group to have two threads and a loop count of five, for a total of ten
requests per thread. See the table below for the sequence JMeter sends the HTTP Requests.</p>
<figure>
<a href="../images/screenshots/logic-controller/interleave.png"><img src="../images/screenshots/logic-controller/interleave.png" width="231" height="153" alt="Figure 1 - Interleave Controller Example 1"></a>
<figcaption>Figure 1 - Interleave Controller Example 1</figcaption>
</figure>
<table>
<tr valign="top">
<th>Loop Iteration</th><th>Each JMeter Thread Sends These HTTP Requests</th>
</tr>
<tr valign="top">
<td>1</td><td>News Page</td>
</tr>
<tr valign="top">
<td>1</td><td>Log Page</td>
</tr>
<tr valign="top">
<td>2</td><td>FAQ Page</td>
</tr>
<tr valign="top">
<td>2</td><td>Log Page</td>
</tr>
<tr valign="top">
<td>3</td><td>Gump Page</td>
</tr>
<tr valign="top">
<td>3</td><td>Log Page</td>
</tr>
<tr valign="top">
<td>4</td><td>Because there are no more requests in the controller,<br>
</br> JMeter starts over and sends the first HTTP Request, which is the News Page.</td>
</tr>
<tr valign="top">
<td>4</td><td>Log Page</td>
</tr>
<tr valign="top">
<td>5</td><td>FAQ Page</td>
</tr>
<tr valign="top">
<td>5</td><td>Log Page</td>
</tr>
</table>
</div>
<div class="example">
<div class="title">Useful Interleave Example<a class="sectionlink" href="#useful_interleave_example" title="Link to here">&para;</a>
</div>
<p>
<a href="../demos/InterleaveTestPlan2.jmx">Download</a> another example (see Figure 2). In this
example, we configured the Thread Group
to have a single thread and a loop count of eight. Notice that the Test Plan has an outer Interleave Controller with
two Interleave Controllers inside of it.</p>
<figure>
<a href="../images/screenshots/logic-controller/interleave2.png"><img src="../images/screenshots/logic-controller/interleave2.png" width="251" height="250" alt="
Figure 2 - Interleave Controller Example 2
"></a>
<figcaption>
Figure 2 - Interleave Controller Example 2
</figcaption>
</figure>
<p>The outer Interleave Controller alternates between the
two inner ones. Then, each inner Interleave Controller alternates between each of the HTTP Requests. Each JMeter
thread will send the requests in the following order: Home Page, Interleaved, Bug Page, Interleaved, CVS Page, Interleaved, and FAQ Page, Interleaved.</p>
<p>Note, the File Reporter is configured to store the results in a file named "<span class="code">interleave-test2.dat</span>" in the current directory.</p>
<figure>
<a href="../images/screenshots/logic-controller/interleave3.png"><img src="../images/screenshots/logic-controller/interleave3.png" width="257" height="253" alt="
Figure 3 - Interleave Controller Example 3
"></a>
<figcaption>
Figure 3 - Interleave Controller Example 3
</figcaption>
</figure>
<p>If the two interleave controllers under the main interleave controller were instead simple controllers, then the order would be: Home Page, CVS Page, Interleaved, Bug Page, FAQ Page, Interleaved.</p>
<p>However, if "<span class="code">ignore sub-controller blocks</span>" was checked on the main interleave controller, then the order would be: Home Page, Interleaved, Bug Page, Interleaved, CVS Page, Interleaved, and FAQ Page, Interleaved.</p>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="Random_Controller">Random Controller<a class="sectionlink" href="#Random_Controller" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>The Random Logic Controller acts similarly to the Interleave Controller, except that
instead of going in order through its sub-controllers and samplers, it picks one
at random at each pass.</p>
<div class="clear"></div>
<div class="note">Interactions between multiple controllers can yield complex behavior.
This is particularly true of the Random Controller. Experiment before you assume
what results any given interaction will give</div>
<div class="clear"></div>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/logic-controller/random-controller.png"><img src="../images/screenshots/logic-controller/random-controller.png" width="328" height="100" alt="Screenshot for Control-Panel of Random Controller"></a>
<figcaption>Screenshot of Control-Panel of Random Controller</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="Random_Controller_parms1">
Parameters
<a class="sectionlink" href="#Random_Controller_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-false">Descriptive name for this controller that is shown in the tree.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">ignore sub-controller blocks</div>
<div class="description req-false">If checked, the interleave controller will treat sub-controllers like single request elements and only allow one request per controller at a time. </div>
<div class="required req-false">No</div>
</div>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="Random_Order_Controller">Random Order Controller<a class="sectionlink" href="#Random_Order_Controller" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>The Random Order Controller is much like a Simple Controller in that it will execute each child
element at most once, but the order of execution of the nodes will be random.</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/randomordercontroller.png"><img src="../images/screenshots/randomordercontroller.png" width="328" height="76" alt="Screenshot for Control-Panel of Random Order Controller"></a>
<figcaption>Screenshot of Control-Panel of Random Order Controller</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="Random_Order_Controller_parms1">
Parameters
<a class="sectionlink" href="#Random_Order_Controller_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-false">Descriptive name for this controller that is shown in the tree.</div>
<div class="required req-false">No</div>
</div>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="Throughput_Controller">Throughput Controller<a class="sectionlink" href="#Throughput_Controller" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>The Throughput Controller allows the user to control how often it is executed.
There are two modes:
<ul>
<li>percent execution</li>
<li>total executions</li>
</ul>
<dl>
<dt>
<span class="code">Percent executions</span>
</dt>
<dd>causes the controller to execute a certain percentage of the iterations through the test plan.</dd>
<dt>
<span class="code">Total executions</span>
</dt>
<dd>causes the controller to stop executing after a certain number of executions have occurred.</dd>
</dl>
Like the Once Only Controller, this setting is reset when a parent Loop Controller restarts.
</p>
<div class="clear"></div>
<div class="note">This controller is badly named, as it does not control throughput.
Please refer to the <a href="../usermanual/component_reference.html#Constant_Throughput_Timer">Constant Throughput Timer</a> for an element that can be used to adjust the throughput.
</div>
<div class="clear"></div>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/throughput_controller.png"><img src="../images/screenshots/throughput_controller.png" width="329" height="167" alt="Screenshot for Control-Panel of Throughput Controller"></a>
<figcaption>Screenshot of Control-Panel of Throughput Controller</figcaption>
</figure>
</div>
<div class="clear"></div>
<div class="note">The Throughput Controller can yield very complex behavior when combined with other controllers - in particular with interleave or random controllers as parents (also very useful).</div>
<div class="clear"></div>
<div class="properties">
<h3 id="Throughput_Controller_parms1">
Parameters
<a class="sectionlink" href="#Throughput_Controller_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-false">Descriptive name for this controller that is shown in the tree.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Execution Style</div>
<div class="description req-true">Whether the controller will run in percent executions or total executions mode.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Throughput</div>
<div class="description req-true">A number. For percent execution mode, a number from <span class="code">0</span>-<span class="code">100</span> that indicates the percentage of times the controller will execute. "<span class="code">50</span>" means the controller will execute during half the iterations through the test plan. For total execution mode, the number indicates the total number of times the controller will execute.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Per User</div>
<div class="description req-false">If checked, per user will cause the controller to calculate whether it should execute on a per user (per thread) basis. If unchecked, then the calculation will be global for all users. For example, if using total execution mode, and uncheck "<span class="code">per user</span>", then the number given for throughput will be the total number of executions made. If "<span class="code">per user</span>" is checked, then the total number of executions would be the number of users times the number given for throughput.</div>
<div class="required req-false">No</div>
</div>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="Runtime_Controller">Runtime Controller<a class="sectionlink" href="#Runtime_Controller" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>The Runtime Controller controls how long its children how long its children will run.
Controller will run its children until configured <span class="code">Runtime(s)</span> is exceeded.
</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/runtimecontroller.png"><img src="../images/screenshots/runtimecontroller.png" width="328" height="100" alt="Screenshot for Control-Panel of Runtime Controller"></a>
<figcaption>Screenshot of Control-Panel of Runtime Controller</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="Runtime_Controller_parms1">
Parameters
<a class="sectionlink" href="#Runtime_Controller_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-true">Descriptive name for this controller that is shown in the tree, and used to name the transaction.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Runtime (seconds)</div>
<div class="description req-true">Desired runtime in seconds. 0 means no run.</div>
<div class="required req-true">Yes</div>
</div>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="If_Controller">If Controller<a class="sectionlink" href="#If_Controller" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>The If Controller allows the user to control whether the test elements below it (its children) are run or not.</p>
<p>
By default, the condition is evaluated only once on initial entry, but you have the option to have it evaluated for every runnable element contained in the controller.
</p>
<p>
The best option (default one) is to check <span class="code">Interpret Condition as Variable Expression?</span>, then in the condition field you have 2 options:
<ul>
<li>Option 1 : Use a variable that contains <span class="code">true</span> or <span class="code">false</span>
<div class="clear"></div>
<div class="note">If you want to test if last sample was successful, you can use <span class="code">${JMeterThread.last_sample_ok}</span>
<figure>
<a href="../images/screenshots/if_controller_variable.png"><img src="../images/screenshots/if_controller_variable.png" width="815" height="260" alt="If Controller using Variable"></a>
<figcaption>If Controller using Variable</figcaption>
</figure>
</div>
<div class="clear"></div>
</li>
<li>Option 2 : Use a function (<span class="code">${__jexl3()}</span> is advised) to evaluate an expression that must return <span class="code">true</span> or <span class="code">false</span>
<figure>
<a href="../images/screenshots/if_controller_expression.png"><img src="../images/screenshots/if_controller_expression.png" width="815" height="260" alt="If Controller using expression"></a>
<figcaption>If Controller using expression</figcaption>
</figure>
</li>
</ul>
For example, previously one could use the condition:
<span class="code">${__jexl3(${VAR} == 23)}</span> and this would be evaluated as <span class="code">true</span>/<span class="code">false</span>, the result would then be passed to JavaScript
which would then return <span class="code">true</span>/<span class="code">false</span>. If the Variable Expression option is selected, then the expression is evaluated
and compared with "<span class="code">true</span>", without needing to use JavaScript.
</p>
<div class="clear"></div>
<div class="note">
To test if a variable is undefined (or null) do the following, suppose var is named <span class="code">myVar</span>, expression will be:
<pre class="source">"${myVar}" == "\${myVar}"</pre>
Or use:
<pre class="source">"${myVar}" != "\${myVar}"</pre>
to test if a variable is defined and is not null.
</div>
<div class="clear"></div>
If you uncheck <span class="code">Interpret Condition as Variable Expression?</span>, <span class="code">If Controller</span> will internally use javascript to evaluate the condition
which has a performance penalty that can be very big and make your test less scalable.
<figure>
<a href="../images/screenshots/if_controller_javascript.png"><img src="../images/screenshots/if_controller_javascript.png" width="819" height="265" alt="If Controller using javascript"></a>
<figcaption>If Controller using javascript</figcaption>
</figure>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/if_controller_expression.png"><img src="../images/screenshots/if_controller_expression.png" width="814" height="262" alt="Screenshot for Control-Panel of If Controller"></a>
<figcaption>Screenshot of Control-Panel of If Controller</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="If_Controller_parms1">
Parameters
<a class="sectionlink" href="#If_Controller_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-false">Descriptive name for this controller that is shown in the tree.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Condition (default JavaScript)</div>
<div class="description req-true">By default the condition is interpreted as <b>JavaScript</b> code that returns "<span class="code">true</span>" or "<span class="code">false</span>",
but this can be overridden (see below)</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Interpret Condition as Variable Expression?</div>
<div class="description req-true">If this is selected, then the condition must be an expression that evaluates to "<span class="code">true</span>" (case is ignored).
For example, <span class="code">${FOUND}</span> or <span class="code">${__jexl3(${VAR} &gt; 100)}</span>.
Unlike the JavaScript case, the condition is only checked to see if it matches "<span class="code">true</span>" (case is ignored).
<div class="clear"></div>
<div class="note">Checking this and using <span class="code"><a href="../usermanual/functions.html#__jexl3">__jexl3</a></span> or <span class="code"><a href="../usermanual/functions.html#__groovy">__groovy</a></span> function in Condition is advised for performances</div>
<div class="clear"></div>
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Evaluate for all children</div>
<div class="description req-true">
Should condition be evaluated for all children?
If not checked, then the condition is only evaluated on entry.
</div>
<div class="required req-true">Yes</div>
</div>
</div>
<div class="example">
<div class="title">Examples (JavaScript)<a class="sectionlink" href="#example_if_javascript" title="Link to here">&para;</a>
</div>
<ul>
<li>
<span class="code">${COUNT} &lt; 10</span>
</li>
<li>
<span class="code">"${VAR}" == "abcd"</span>
</li>
</ul>
If there is an error interpreting the code, the condition is assumed to be <span class="code">false</span>, and a message is logged in <span class="code">jmeter.log</span>.
<div class="clear"></div>
<div class="note">Note it is advised to avoid using JavaScript mode for performance.<br>
<br>When using <span class="code"><a href="../usermanual/functions.html#__groovy">__groovy</a></span> take care to not use variable replacement in the string, otherwise if using a variable that changes the script cannot be cached. Instead get the variable using: <span class="code">vars.get("myVar").</span> See the Groovy examples below.</div>
<div class="clear"></div>
</div>
<div class="example">
<div class="title">Examples (Variable Expression)<a class="sectionlink" href="#example_if_variable" title="Link to here">&para;</a>
</div>
<ul>
<li>
<span class="code">${__groovy(vars.get("myVar") != "Invalid" )}</span> (Groovy check myVar is not equal to Invalid)</li>
<li>
<span class="code">${__groovy(vars.get("myInt").toInteger() &lt;=4 )}</span> (Groovy check myInt is less then or equal to 4)</li>
<li>
<span class="code">${__groovy(vars.get("myMissing") != null )}</span> (Groovy check if the myMissing variable is not set)</li>
<li>
<span class="code">${__jexl3(${COUNT} &lt; 10)}</span>
</li>
<li>
<span class="code">${RESULT}</span>
</li>
<li>
<span class="code">${JMeterThread.last_sample_ok}</span> (check if the last sample succeeded)</li>
</ul>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="While_Controller">While Controller<a class="sectionlink" href="#While_Controller" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>
The While Controller runs its children until the condition is "<span class="code">false</span>".
<div class="clear"></div>
<div class="note">JMeter will expose the looping index as a variable named <span class="code">__jm__&lt;Name of your element&gt;__idx</span>. So for
example, if your While Controller is named WC, then you can access the looping index through <span class="code">${__jm__WC__idx}</span>.
Index starts at 0</div>
<div class="clear"></div>
</p>
<p>Possible condition values:</p>
<ul>
<li>blank - exit loop when last sample in loop fails</li>
<li>
<span class="code">LAST</span> - exit loop when last sample in loop fails.
If the last sample just before the loop failed, don't enter loop.</li>
<li>Otherwise - exit (or don't enter) the loop when the condition is equal to the string "<span class="code">false</span>"</li>
</ul>
<div class="clear"></div>
<div class="note">
The condition can be any variable or function that eventually evaluates to the string "<span class="code">false</span>".
This allows the use of <span class="code"><a href="../usermanual/functions.html#__jexl3">__jexl3</a></span>, <span class="code"><a href="../usermanual/functions.html#__groovy">__groovy</a></span> function, properties or variables as needed.
</div>
<div class="clear"></div>
<br>
<div class="clear"></div>
<div class="note">
Note that the condition is evaluated twice, once before starting sampling children and once at end of children sampling, so putting
non idempotent functions in Condition (like <span class="code"><a href="../usermanual/functions.html#__counter">__counter</a></span>) can introduce issues.
</div>
<div class="clear"></div>
<br>
For example:
<ul>
<li>
<span class="code">${VAR}</span> - where <span class="code">VAR</span> is set to false by some other test element</li>
<li>
<span class="code">${__jexl3(${C}==10)}</span>
</li>
<li>
<span class="code">${__jexl3("${VAR2}"=="abcd")}</span>
</li>
<li>
<span class="code">${_P(property)}</span> - where property is set to "<span class="code">false</span>" somewhere else</li>
</ul>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/whilecontroller.png"><img src="../images/screenshots/whilecontroller.png" width="362" height="102" alt="Screenshot for Control-Panel of While Controller"></a>
<figcaption>Screenshot of Control-Panel of While Controller</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="While_Controller_parms1">
Parameters
<a class="sectionlink" href="#While_Controller_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-false">Descriptive name for this controller that is shown in the tree, and used to name the transaction.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Condition</div>
<div class="description req-false">blank, <span class="code">LAST</span>, or variable/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="Switch_Controller">Switch Controller<a class="sectionlink" href="#Switch_Controller" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>
The Switch Controller acts like the <a href="../usermanual/component_reference.html#Interleave_Controller">Interleave Controller</a>
in that it runs one of the subordinate elements on each iteration, but rather than
run them in sequence, the controller runs the element defined by the switch value.
</p>
<div class="clear"></div>
<div class="note">
The switch value can also be a name.
</div>
<div class="clear"></div>
<p>If the switch value is out of range, it will run the zeroth element,
which therefore acts as the default for the numeric case.
It also runs the zeroth element if the value is the empty string.</p>
<p>
If the value is non-numeric (and non-empty), then the Switch Controller looks for the
element with the same name (case is significant).
If none of the names match, then the element named "<span class="code">default</span>" (case not significant) is selected.
If there is no default, then no element is selected, and the controller will not run anything.
</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/switchcontroller.png"><img src="../images/screenshots/switchcontroller.png" width="361" height="106" alt="Screenshot for Control-Panel of Switch Controller"></a>
<figcaption>Screenshot of Control-Panel of Switch Controller</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="Switch_Controller_parms1">
Parameters
<a class="sectionlink" href="#Switch_Controller_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-false">Descriptive name for this controller that is shown in the tree.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Switch Value</div>
<div class="description req-false">The number (or name) of the subordinate element to be invoked. Elements are numbered from 0. Defaults to 0</div>
<div class="required req-false">No</div>
</div>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="ForEach_Controller">ForEach Controller<a class="sectionlink" href="#ForEach_Controller" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>A ForEach controller loops through the values of a set of related variables.
When you add samplers (or controllers) to a ForEach controller, every sample (or controller)
is executed one or more times, where during every loop the variable has a new value.
The input should consist of several variables, each extended with an underscore and a number.
Each such variable must have a value.
So for example when the input variable has the name <span class="code">inputVar</span>, the following variables should have been defined:</p>
<ul>
<li>
<span class="code">inputVar_1 = wendy</span>
</li>
<li>
<span class="code">inputVar_2 = charles</span>
</li>
<li>
<span class="code">inputVar_3 = peter</span>
</li>
<li>
<span class="code">inputVar_4 = john</span>
</li>
</ul>
<p>Note: the "<span class="code">_</span>" separator is now optional.</p>
<p>
When the return variable is given as "<span class="code">returnVar</span>", the collection of samplers and controllers under the ForEach controller will be executed <span class="code">4</span> consecutive times,
with the return variable having the respective above values, which can then be used in the samplers.
</p>
<p>
<div class="clear"></div>
<div class="note">JMeter will expose the looping index as a variable named <span class="code">__jm__&lt;Name of your element&gt;__idx</span>. So for
example, if your Loop Controller is named FEC, then you can access the looping index through <span class="code">${__jm__FEC__idx}</span>.
Index starts at 0</div>
<div class="clear"></div>
</p>
<p>
It is especially suited for running with the regular expression post-processor.
This can "create" the necessary input variables out of the result data of a previous request.
By omitting the "<span class="code">_</span>" separator, the ForEach Controller can be used to loop through the groups by using
the input variable <span class="code">refName_g</span>, and can also loop through all the groups in all the matches
by using an input variable of the form <span class="code">refName_${C}_g</span>, where <span class="code">C</span> is a counter variable.
</p>
<div class="clear"></div>
<div class="note">The ForEach Controller does not run any samples if <span class="code">inputVar_1</span> is <span class="code">null</span>.
This would be the case if the Regular Expression returned no matches.</div>
<div class="clear"></div>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/logic-controller/foreach-controller.png"><img src="../images/screenshots/logic-controller/foreach-controller.png" width="342" height="193" alt="Screenshot for Control-Panel of ForEach Controller"></a>
<figcaption>Screenshot of Control-Panel of ForEach Controller</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="ForEach_Controller_parms1">
Parameters
<a class="sectionlink" href="#ForEach_Controller_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-false">Descriptive name for this controller that is shown in the tree.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Input variable prefix</div>
<div class="description req-false">Prefix for the variable names to be used as input. Defaults to an empty string as prefix.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Start index for loop</div>
<div class="description req-false">Start index (exclusive) for loop over variables (first element is at start index + 1)</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">End index for loop</div>
<div class="description req-false">End index (inclusive) for loop over variables</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Output variable</div>
<div class="description req-false">
The name of the variable which can be used in the loop for replacement in the samplers. Defaults to an empty variable name, which is most probably not wanted.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Use Separator</div>
<div class="description req-true">If not checked, the "<span class="code">_</span>" separator is omitted.</div>
<div class="required req-true">Yes</div>
</div>
</div>
<div class="example">
<div class="title">ForEach Example<a class="sectionlink" href="#foreach_example" title="Link to here">&para;</a>
</div>
<p>
<a href="../demos/forEachTestPlan.jmx">Download</a> this example (see Figure 7).
In this example, we created a Test Plan that sends a particular HTTP Request
only once and sends another HTTP Request to every link that can be found on the page.</p>
<figure>
<a href="../images/screenshots/logic-controller/foreach-example.png"><img src="../images/screenshots/logic-controller/foreach-example.png" width="300" height="158" alt="Figure 7 - ForEach Controller Example"></a>
<figcaption>Figure 7 - ForEach Controller Example</figcaption>
</figure>
<p>We configured the Thread Group for a single thread and a loop count value of
one. You can see that we added one HTTP Request to the Thread Group and
another HTTP Request to the ForEach Controller.</p>
<p>After the first HTTP request, a regular expression extractor is added, which extracts all the html links
out of the return page and puts them in the <span class="code">inputVar</span> variable</p>
<p>In the ForEach loop, a HTTP sampler is added which requests all the links that were extracted from the first returned HTML page.
</p>
</div>
<div class="example">
<div class="title">ForEach Example<a class="sectionlink" href="#foreach_example2" title="Link to here">&para;</a>
</div>
<p>Here is <a href="../demos/ForEachTest2.jmx">another example</a> you can download.
This has two Regular Expressions and ForEach Controllers.
The first RE matches, but the second does not match,
so no samples are run by the second ForEach Controller</p>
<figure>
<a href="../images/screenshots/logic-controller/foreach-example2.png"><img src="../images/screenshots/logic-controller/foreach-example2.png" width="237" height="249" alt="Figure 8 - ForEach Controller Example 2"></a>
<figcaption>Figure 8 - ForEach Controller Example 2</figcaption>
</figure>
<p>The Thread Group has a single thread and a loop count of two.
</p>
<p>
Sample 1 uses the JavaTest Sampler to return the string "<span class="code">a b c d</span>".
</p>
<p>The Regex Extractor uses the expression <span class="code">(\w)\s</span> which matches a letter followed by a space,
and returns the letter (not the space). Any matches are prefixed with the string "<span class="code">inputVar</span>".
</p>
<p>The ForEach Controller extracts all variables with the prefix "<span class="code">inputVar_</span>", and executes its
sample, passing the value in the variable "<span class="code">returnVar</span>". In this case it will set the variable to the values "<span class="code">a</span>" "<span class="code">b</span>" and "<span class="code">c</span>" in turn.
</p>
<p>The <span class="code">For 1</span> Sampler is another Java Sampler which uses the return variable "<span class="code">returnVar</span>" as part of the sample Label
and as the sampler Data.
</p>
<p>
<span class="code">Sample 2</span>, <span class="code">Regex 2</span> and <span class="code">For 2</span> are almost identical, except that the Regex has been changed to "<span class="code">(\w)\sx</span>",
which clearly won't match. Thus the <span class="code">For 2</span> Sampler will not be run.
</p>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="Module_Controller">Module Controller<a class="sectionlink" href="#Module_Controller" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>
The Module Controller provides a mechanism for substituting test plan fragments into the current test plan at run-time.
</p>
<p>
A test plan fragment consists of a Controller and all the test elements (samplers etc.) contained in it.
The fragment can be located in any Thread Group.
If the fragment is located in a Thread Group, then its Controller can be disabled to prevent the fragment being run
except by the Module Controller.
Or you can store the fragments in a dummy Thread Group, and disable the entire Thread Group.
</p>
<p>
There can be multiple fragments, each with a different series of
samplers under them. The module controller can then be used to easily switch between these multiple test cases simply by choosing
the appropriate controller in its drop down box. This provides convenience for running many alternate test plans quickly and easily.
</p>
<p>
A fragment name is made up of the Controller name and all its parent names.
For example:
</p>
<pre>
Test Plan / Protocol: JDBC / Control / Interleave Controller (Module1)
</pre>
<p>
Any <b>fragments used by the Module Controller must have a unique name</b>,
as the name is used to find the target controller when a test plan is reloaded.
For this reason it is best to ensure that the Controller name is changed from the default
- as shown in the example above -
otherwise a duplicate may be accidentally created when new elements are added to the test plan.
</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/module_controller.png"><img src="../images/screenshots/module_controller.png" width="526" height="318" alt="Screenshot for Control-Panel of Module Controller"></a>
<figcaption>Screenshot of Control-Panel of Module Controller</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="Module_Controller_parms1">
Parameters
<a class="sectionlink" href="#Module_Controller_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-false">Descriptive name for this controller that is shown in the tree.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Module to Run</div>
<div class="description req-true">The module controller provides a list of all controllers loaded into the gui. Select
the one you want to substitute in at runtime.</div>
<div class="required req-true">Yes</div>
</div>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="Include_Controller">Include Controller<a class="sectionlink" href="#Include_Controller" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>
The include controller is designed to use an external JMX file. To use it, create a Test Fragment
underneath the Test Plan and add any desired samplers, controllers etc. below it.
Then save the Test Plan. The file is now ready to be included as part of other Test Plans.
</p>
<p>
For convenience, a <a href="../usermanual/component_reference.html#Thread_Group">Thread Group</a> can also be added in the external JMX file for debugging purposes.
A <a href="../usermanual/component_reference.html#Module_Controller">Module Controller</a> can be used to reference the Test Fragment. The <a href="../usermanual/component_reference.html#Thread_Group">Thread Group</a> will be ignored during the
include process.
</p>
<p>
If the test uses a Cookie Manager or User Defined Variables, these should be placed in the top-level
test plan, not the included file, otherwise they are not guaranteed to work.
</p>
<div class="clear"></div>
<div class="note">
This element does not support variables/functions in the filename field.<br>
However, if the property <span class="code">includecontroller.prefix</span> is defined,
the contents are used to prefix the pathname.
</div>
<div class="clear"></div>
<div class="clear"></div>
<div class="note">
When using Include Controller and including the same JMX file, ensure you name the Include Controller differently to avoid facing known issue <a href="https://bz.apache.org/bugzilla/show_bug.cgi?id=50898">
Bug
50898</a>.
</div>
<div class="clear"></div>
<p>
If the file cannot be found at the location given by <span class="code">prefix</span>+<span class="code">Filename</span>, then the controller
attempts to open the <span class="code">Filename</span> relative to the JMX launch directory.
</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/includecontroller.png"><img src="../images/screenshots/includecontroller.png" width="417" height="130" alt="Screenshot for Control-Panel of Include Controller"></a>
<figcaption>Screenshot of Control-Panel of Include Controller</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="Include_Controller_parms1">
Parameters
<a class="sectionlink" href="#Include_Controller_parms1" title="Link to here">&para;</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">Filename</div>
<div class="description req-true">The file to include.</div>
<div class="required req-true">Yes</div>
</div>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="Transaction_Controller">Transaction Controller<a class="sectionlink" href="#Transaction_Controller" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>
The Transaction Controller generates an additional
sample which measures the overall time taken to perform the nested test elements.
</p>
<div class="clear"></div>
<div class="note">
Note: when the check box "<span class="code">Include duration of timer and pre-post processors in generated sample</span>" is checked,
the time includes all processing within the controller scope, not just the samples.
</div>
<div class="clear"></div>
<p>
There are two modes of operation:
</p>
<ul>
<li>additional sample is added after the nested samples</li>
<li>additional sample is added as a parent of the nested samples</li>
</ul>
<p>
The generated sample time includes all the times for the nested samplers excluding by default (since 2.11) timers and processing time of pre/post processors
unless checkbox "<span class="code">Include duration of timer and pre-post processors in generated sample</span>" is checked.
Depending on the clock resolution, it may be slightly longer than the sum of the individual samplers plus timers.
The clock might tick after the controller recorded the start time but before the first sample starts.
Similarly at the end.
</p>
<p>The generated sample is only regarded as successful if all its sub-samples are successful.</p>
<p>
In parent mode, the individual samples can still be seen in the Tree View Listener,
but no longer appear as separate entries in other Listeners.
Also, the sub-samples do not appear in CSV log files, but they can be saved to XML files.
</p>
<div class="clear"></div>
<div class="note">
In parent mode, Assertions (etc.) can be added to the Transaction Controller.
However by default they will be applied to both the individual samples and the overall transaction sample.
To limit the scope of the Assertions, use a Simple Controller to contain the samples, and add the Assertions
to the Simple Controller.
Parent mode controllers do not currently properly support nested transaction controllers of either type.
</div>
<div class="clear"></div>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/transactioncontroller.png"><img src="../images/screenshots/transactioncontroller.png" width="622" height="140" alt="Screenshot for Control-Panel of Transaction Controller"></a>
<figcaption>Screenshot of Control-Panel of Transaction Controller</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="Transaction_Controller_parms1">
Parameters
<a class="sectionlink" href="#Transaction_Controller_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-true">Descriptive name for this controller that is shown in the tree, and used to name the transaction.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Generate Parent Sample</div>
<div class="description req-true">
If checked, then the sample is generated as a parent of the other samples,
otherwise the sample is generated as an independent sample.
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Include duration of timer and pre-post processors in generated sample</div>
<div class="description req-true">
Whether to include timer, pre- and post-processing delays in the generated sample.
Default is <span class="code">false</span>
</div>
<div class="required req-true">Yes</div>
</div>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="Recording_Controller">Recording Controller<a class="sectionlink" href="#Recording_Controller" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>The Recording Controller is a place holder indicating where the proxy server should
record samples to. During test run, it has no effect, similar to the Simple Controller. But during
recording using the <a href="../usermanual/component_reference.html#HTTP(S)_Test_Script_Recorder">HTTP(S) Test Script Recorder</a>, all recorded samples will by default
be saved under the Recording Controller.</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/logic-controller/recording-controller.png"><img src="../images/screenshots/logic-controller/recording-controller.png" width="420" height="79" alt="Screenshot for Control-Panel of Recording Controller"></a>
<figcaption>Screenshot of Control-Panel of Recording Controller</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="Recording_Controller_parms1">
Parameters
<a class="sectionlink" href="#Recording_Controller_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-false">Descriptive name for this controller that is shown in the tree.</div>
<div class="required req-false">No</div>
</div>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="Critical_Section_Controller">Critical Section Controller<a class="sectionlink" href="#Critical_Section_Controller" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>The Critical Section Controller ensures that its children elements (samplers/controllers, etc.) will be executed
by only one thread as a named lock will be taken before executing children of controller.</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/logic-controller/critical-section-controller.png"><img src="../images/screenshots/logic-controller/critical-section-controller.png" width="469" height="129" alt="Screenshot for Control-Panel of Critical Section Controller"></a>
<figcaption>Screenshot of Control-Panel of Critical Section Controller</figcaption>
</figure>
</div>
<p>
The figure below shows an example of using Critical Section Controller, in the figure below 2 Critical Section Controllers ensure
that:
</p>
<ul>
<li>
<span class="code">DS2-${__threadNum}</span> is executed only by one thread at a time</li>
<li>
<span class="code">DS4-${__threadNum}</span> is executed only by one thread at a time</li>
</ul>
<figure>
<a href="../images/screenshots/logic-controller/critical-section-controller-tp.png"><img src="../images/screenshots/logic-controller/critical-section-controller-tp.png" width="276" height="237" alt="Test Plan using Critical Section Controller"></a>
<figcaption>Test Plan using Critical Section Controller</figcaption>
</figure>
<div class="properties">
<h3 id="Critical_Section_Controller_parms1">
Parameters
<a class="sectionlink" href="#Critical_Section_Controller_parms1" title="Link to here">&para;</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">Lock Name</div>
<div class="description req-true">Lock that will be taken by controller, ensure you use different lock names for unrelated sections</div>
<div class="required req-true">Yes</div>
</div>
</div>
<div class="clear"></div>
<div class="note">
Critical Section Controller takes locks only within one JVM, so if using Distributed testing ensure your use case does not rely on all threads of all JVMs blocking.
</div>
<div class="clear"></div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<a href="#">^</a>
</div>
<div class="section">
<h1 id="listeners">18.3 Listeners<a class="sectionlink" href="#listeners" title="Link to here">&para;</a>
</h1>
<div class="description">
<br>
Most of the listeners perform several roles in addition to "listening"
to the test results.
They also provide means to view, save, and read saved test results.
<p>Note that Listeners are processed at the end of the scope in which they are found.</p>
<p>
The saving and reading of test results is generic. The various
listeners have a panel whereby one can specify the file to
which the results will be written (or read from).
By default, the results are stored as XML
files, typically with a "<span class="code">.jtl</span>" extension.
Storing as CSV is the most efficient option, but is less detailed than XML (the other available option).
</p>
<p>
<b>Listeners do <i>not</i> process sample data in CLI mode, but the raw data will be saved if an output
file has been configured.</b>
In order to analyse the data generated by a CLI run, you need to load the file into the appropriate
Listener.
</p>
<div class="clear"></div>
<div class="note">
To read existing results and display them, use the file panel Browse button to open the file.
</div>
<div class="clear"></div>
<p>
If you want to clear any current data before loading a new file, use the menu item
<span class="menuchoice"><span class="guimenuitem">Run</span>&nbsp;&rarr;&nbsp;<span class="guimenuitem">Clear</span>
(<span class="keycombo"><span class="keysym">Ctrl</span>&nbsp;+&nbsp;<span class="keysym">Shift</span>&nbsp;+&nbsp;<span class="keysym">E</span></span>)
</span>
or
<span class="menuchoice"><span class="guimenuitem">Run</span>&nbsp;&rarr;&nbsp;<span class="guimenuitem">Clear All</span>
(<span class="keycombo"><span class="keysym">Ctrl</span>&nbsp;+&nbsp;<span class="keysym">E</span></span>)
</span>
before loading the file.
</p>
<p>Results can be read from XML or CSV format files.
When reading from CSV results files, the header (if present) is used to determine which fields are present.
<b>In order to interpret a header-less CSV file correctly, the appropriate properties must be set in <span class="code">jmeter.properties</span>.</b>
<div class="clear"></div>
<div class="note">
XML files written by JMeter have version 1.0 declared in header while actual file is serialized with 1.1 rules.
(This is done for historical compatibility reasons; see <a href="https://bz.apache.org/bugzilla/show_bug.cgi?id=59973">
Bug
59973</a> and <a href="https://bz.apache.org/bugzilla/show_bug.cgi?id=58679">
Bug
58679</a>)
This causes strict XML parsers to fail. Consider using non-strict XML parsers to read JTL files.
</div>
<div class="clear"></div>
</p>
<div class="clear"></div>
<div class="note">
The file name can contain function and/or variable references.
However variable references do not work in client-server mode (functions work OK).
This is because the file is created on the client, and the client does not run the test locally so does not set up variables.
</div>
<div class="clear"></div>
<p>
<b>Listeners can use a lot of memory if there are a lot of samples.</b>
Most of the listeners currently keep a copy of every sample in their scope, apart from:
</p>
<ul>
<li>Simple Data Writer</li>
<li>BeanShell/JSR223 Listener</li>
<li>Mailer Visualizer</li>
<li>Summary Report</li>
</ul>
<p>
The following Listeners no longer need to keep copies of every single sample.
Instead, samples with the same elapsed time are aggregated.
Less memory is now needed, especially if most samples only take a second or two at most.
</p>
<ul>
<li>Aggregate Report</li>
<li>Aggregate Graph</li>
</ul>
<p>To minimise the amount of memory needed, use the Simple Data Writer, and use the CSV format.</p>
<div class="clear"></div>
<div class="note">
JMeter variables can be saved to the output files.
This can only be specified using a property.
See the <a href="listeners.html#sample_variables">Listener Sample Variables</a> for details
</div>
<div class="clear"></div>
<p>
For full details on setting up the default items to be saved
see the <a href="listeners.html#defaults">Listener Default Configuration</a> documentation.
For details of the contents of the output files,
see the <a href="listeners.html#csvlogformat">CSV log</a> format or
the <a href="listeners.html#xmlformat2.1">XML log</a> format.
</p>
<div class="clear"></div>
<div class="note">The entries in <span class="code">jmeter.properties</span> are used to define the defaults;
these can be overridden for individual listeners by using the Configure button,
as shown below.
The settings in <span class="code">jmeter.properties</span> also apply to the listener that is added
by using the <span class="code">-l</span> command-line flag.
</div>
<div class="clear"></div>
<p>
The figure below shows an example of the result file configuration panel
</p>
<figure>
<a href="../images/screenshots/simpledatawriter.png"><img src="../images/screenshots/simpledatawriter.png" width="741" height="141" alt="Result file configuration panel"></a>
<figcaption>Result file configuration panel</figcaption>
</figure>
<div class="properties">
<h3>
Parameters
</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">Filename</div>
<div class="description req-false">Name of the file containing sample results.
The file name can be specified using either a relative or an absolute path name.
Relative paths are resolved relative to the current working directory (which defaults to the <span class="code">bin/</span> directory).
JMeter also support paths relative to the directory containing the current test plan (JMX file).
If the path name begins with "<span class="code">~/</span>" (or whatever is in the <span class="code">jmeter.save.saveservice.base_prefix</span> JMeter property),
then the path is assumed to be relative to the JMX file location.
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Browse &hellip;</div>
<div class="description req-false">File Browse Button</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Errors</div>
<div class="description req-false">Select this to write/read only results with errors</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Successes</div>
<div class="description req-false">Select this to write/read only results without errors.
If neither <span class="code">Errors</span> nor <span class="code">Successes</span> is selected, then all results are processed.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Configure</div>
<div class="description req-false">Configure Button, see below</div>
<div class="required req-false">No</div>
</div>
</div>
</div>
<div class="component">
<h2 id="Sample_Result_Save_Configuration">Sample Result Save Configuration<a class="sectionlink" href="#Sample_Result_Save_Configuration" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>
Listeners can be configured to save different items to the result log files (JTL) by using the Config popup as shown below.
The defaults are defined as described in the <a href="listeners.html#defaults">Listener Default Configuration</a> documentation.
Items with (<span class="code">CSV</span>) after the name only apply to the CSV format; items with (<span class="code">XML</span>) only apply to XML format.
CSV format cannot currently be used to save any items that include line-breaks.
</p>
<p>
Note that cookies, method and the query string are saved as part of the "<span class="code">Sampler Data</span>" option.
</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/sample_result_config.png"><img src="../images/screenshots/sample_result_config.png" width="760" height="304" alt="Screenshot for Control-Panel of Sample Result Save Configuration"></a>
<figcaption>Screenshot of Control-Panel of Sample Result Save Configuration</figcaption>
</figure>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="Graph_Results">Graph Results<a class="sectionlink" href="#Graph_Results" title="Link to here">&para;</a>
</h2>
<div class="description">
<div class="clear"></div>
<div class="note">
Graph Results MUST NOT BE USED during load test as it consumes a lot of resources (memory and CPU). Use it only for either functional testing or
during Test Plan debugging and Validation.
</div>
<div class="clear"></div>
<p>The Graph Results listener generates a simple graph that plots all sample times. Along
the bottom of the graph, the current sample (black), the current average of all samples (blue), the
current standard deviation (red), and the current throughput rate (green) are displayed in milliseconds.</p>
<p>The throughput number represents the actual number of requests/minute the server handled. This calculation
includes any delays you added to your test and JMeter's own internal processing time. The advantage
of doing the calculation like this is that this number represents something
real - your server in fact handled that many requests per minute, and you can increase the number of threads
and/or decrease the delays to discover your server's maximum throughput. Whereas if you made calculations
that factored out delays and JMeter's processing, it would be unclear what you could conclude from that
number.</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/graph_results.png"><img src="../images/screenshots/graph_results.png" width="915" height="686" alt="Screenshot for Control-Panel of Graph Results"></a>
<figcaption>Screenshot of Control-Panel of Graph Results</figcaption>
</figure>
</div>
<p>The following table briefly describes the items on the graph.
Further details on the precise meaning of the statistical terms can be found on the web
- e.g. Wikipedia - or by consulting a book on statistics.
</p>
<ul>
<li>
<span class="code">Data</span> - plot the actual data values</li>
<li>
<span class="code">Average</span> - plot the Average</li>
<li>
<span class="code">Median</span> - plot the <a href="glossary.html#Median">Median</a> (midway value)</li>
<li>
<span class="code">Deviation</span> - plot the <a href="glossary.html#StandardDeviation">Standard Deviation</a> (a measure of the variation)</li>
<li>
<span class="code">Throughput</span> - plot the number of samples per unit of time</li>
</ul>
<p>The individual figures at the bottom of the display are the current values.
"<span class="code">Latest Sample</span>" is the current elapsed sample time, shown on the graph as "<span class="code">Data</span>".</p>
<p>The value displayed on the top left of graph is the max of 90<sup>th</sup> percentile of response time.</p>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="Assertion_Results">Assertion Results<a class="sectionlink" href="#Assertion_Results" title="Link to here">&para;</a>
</h2>
<div class="description">
<div class="clear"></div>
<div class="note">
Assertion Results MUST NOT BE USED during load test as it consumes a lot of resources (memory and CPU). Use it only for either functional testing or
during Test Plan debugging and Validation.
</div>
<div class="clear"></div>
<p>The Assertion Results visualizer shows the Label of each sample taken.
It also reports failures of any <a href="test_plan.html#assertions">Assertions</a> that
are part of the test plan.</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/assertion_results.png"><img src="../images/screenshots/assertion_results.png" width="954" height="365" alt="Screenshot for Control-Panel of Assertion Results"></a>
<figcaption>Screenshot of Control-Panel of Assertion Results</figcaption>
</figure>
</div>
<div class="links">
<div class="title">See also:</div>
<ul class="links">
<li>
<a href="../usermanual/component_reference.html#Response_Assertion">Response Assertion</a>
</li>
</ul>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="View_Results_Tree">View Results Tree<a class="sectionlink" href="#View_Results_Tree" title="Link to here">&para;</a>
</h2>
<div class="description">
<div class="clear"></div>
<div class="note">
View Results Tree MUST NOT BE USED during load test as it consumes a lot of resources (memory and CPU).
Use it only for either functional testing or during Test Plan debugging and Validation.
</div>
<div class="clear"></div>
The View Results Tree shows a tree of all sample responses, allowing you to view the
response for any sample. In addition to showing the response, you can see the time it took to get
this response, and some response codes.
Note that the Request panel only shows the headers added by JMeter.
It does not show any headers (such as <span class="code">Host</span>) that may be added by the HTTP protocol implementation.
<p>
There are several ways to view the response, selectable by a drop-down box at the bottom of the left hand panel.</p>
<table>
<tr>
<th><b>Renderer</b></th><th><b>Description</b></th>
</tr>
<tr>
<td><span class="code">CSS/JQuery Tester</span></td>
<td>The <i>CSS/JQuery Tester</i> only works for text responses. It shows the plain text in the upper panel.
The "<span class="code">Test</span>" button allows the user to apply the CSS/JQuery to the upper panel and the results
will be displayed in the lower panel.<br>
The CSS/JQuery expression engine can be JSoup or Jodd, syntax of these 2 implementation differs slightly.<br>
For example, the Selector <span class="code">a[class=sectionlink]</span> with attribute <span class="code">href</span> applied to the current JMeter functions page gives the following output:
<br>
<pre class="source">
Match count: 74
Match[1]=#functions
Match[2]=#what_can_do
Match[3]=#where
Match[4]=#how
Match[5]=#function_helper
Match[6]=#functions
Match[7]=#__regexFunction
Match[8]=#__regexFunction_parms
Match[9]=#__counter
&hellip; and so on &hellip;
</pre>
<br>
</td>
</tr>
<tr>
<td><span class="code">Document</span></td>
<td>The <i>Document view</i> will show the extract text from various type of documents like Microsoft Office
(Word, Excel, PowerPoint 97-2003, 2007-2010 (openxml), Apache OpenOffice (writer, calc, impress), HTML,
gzip, jar/zip files (list of content), and some meta-data on "multimedia" files like mp3, mp4, flv, etc. The complete list of
support format is available on <a href="http://tika.apache.org/1.2/formats.html">Apache Tika format page.</a>
<div class="clear"></div>
<div class="note">A requirement to the <span class="code">Document view</span> is to download the <a href="http://tika.apache.org/download.html">
Apache Tika binary package</a> (<span class="code">tika-app-x.x.jar</span>) and put this in <span class="code">JMETER_HOME/lib</span> directory.
</div>
<div class="clear"></div>
If the document is larger than 10 MB, then it won't be displayed.
To change this limit, set the JMeter property <span class="code">document.max_size</span> (unit is byte) or set to <span class="code">0</span> to remove the limit.
<br>
</td>
</tr>
<tr>
<td><span class="code">HTML</span></td>
<td>The <i>HTML view</i> attempts to render the response as
HTML. The rendered HTML is likely to compare poorly to the view one
would get in any web browser; however, it does provide a quick
approximation that is helpful for initial result evaluation.<br>
Images, style-sheets, etc. aren't downloaded.
<br>
</td>
</tr>
<tr>
<td><span class="code">HTML (download resources)</span></td>
<td>If the <i>HTML (download resources) view</i> option is selected, the renderer
may download images, style-sheets, etc. referenced by the HTML code.
<br>
</td>
</tr>
<tr>
<td><span class="code">HTML Source formatted</span></td>
<td>If the <em>HTML Source formatted view</em> option is selected, the renderer will display the HTML source code formatted and cleaned by <a href="https://jsoup.org/">Jsoup</a>.
<br>
</td>
</tr>
<tr>
<td><span class="code">JSON</span></td>
<td>The <i>JSON view</i> will show the response in tree style (also handles JSON embedded in JavaScript).
<br>
</td>
</tr>
<tr>
<td><span class="code">JSON Path Tester</span></td>
<td>The <i>JSON Path Tester view</i> will let you test your JSON-PATH expressions and see the extracted data from a particular response.
<br>
</td>
</tr>
<tr>
<td><span class="code">JSON JMESPath Tester</span></td>
<td>The <i>JSON JMESPath Tester view</i> will let you test your <a href="http://jmespath.org/">JMESPath</a> expressions and see the extracted data from a particular response.
<br>
</td>
</tr>
<tr>
<td><span class="code">Regexp Tester</span></td>
<td>The <i>Regexp Tester view</i> only works for text responses. It shows the plain text in the upper panel.
The "<span class="code">Test</span>" button allows the user to apply the Regular Expression to the upper panel and the results
will be displayed in the lower panel.<br>
The regular expression engine is the same as that used in the Regular Expression Extractor.<br>
For example, the RE <span class="code">(JMeter\w*).*</span> applied to the current JMeter home page gives the following output:
<br>
<pre class="source">
Match count: 26
Match[1][0]=JMeter - Apache JMeter&lt;/title&gt;
Match[1][1]=JMeter
Match[2][0]=JMeter" title="JMeter" border="0"/&gt;&lt;/a&gt;
Match[2][1]=JMeter
Match[3][0]=JMeterCommitters"&gt;Contributors&lt;/a&gt;
Match[3][1]=JMeterCommitters
&hellip; and so on &hellip;
</pre>
<br>
The first number in <span class="code">[]</span> is the match number; the second number is the group.
Group <span class="code">[0]</span> is whatever matched the whole RE.
Group <span class="code">[1]</span> is whatever matched the 1<sup>st</sup> group, i.e. <span class="code">(JMeter\w*)</span> in this case.
See Figure 9b (below).
<br>
</td>
</tr>
<tr>
<td><span class="code">Text</span></td>
<td>
The default <i>Text view</i> shows all of the text contained in the response.
Note that this will only work if the response <span class="code">content-type</span> is considered to be text.
If the <span class="code">content-type</span> begins with any of the following, it is considered as binary,
otherwise it is considered to be text.
<pre class="source">
image/
audio/
video/
</pre>
<br>
</td>
</tr>
<tr>
<td><span class="code">XML</span></td>
<td>The <i>XML view</i> will show response in tree style.
Any DTD nodes or Prolog nodes will not show up in tree; however, response may contain those nodes.
You can right-click on any node and expand or collapse all nodes below it.
<br>
</td>
</tr>
<tr>
<td><span class="code">XPath Tester</span></td>
<td>The <i>XPath Tester</i> only works for text responses. It shows the plain text in the upper panel.
The "<span class="code">Test</span>" button allows the user to apply the XPath query to the upper panel and the results
will be displayed in the lower panel.<br>
</td>
</tr>
<tr>
<td><span class="code">Boundary Extractor Tester </span></td>
<td>The <i>Boundary Extractor Tester</i> only works for text responses. It shows the plain text in the upper panel.
The "<span class="code">Test</span>" button allows the user to apply the Boundary Extractor query to the upper panel and the results
will be displayed in the lower panel.<br>
</td>
</tr>
</table>
<p>
<span class="code">Scroll automatically?</span> option permit to have last node display in tree selection</p>
<div class="clear"></div>
<div class="note">Starting with version 3.2 the number of entries in the View is restricted to the value of the
property <span class="code">view.results.tree.max_results</span> which defaults to <span class="code">500</span> entries. The old
behaviour can be restored by setting the property to <span class="code">0</span>. Beware, that this might consume
a lot of memory.</div>
<div class="clear"></div>
<p>
With <span class="code">Search</span> option, most of the views also allow the displayed data to be searched; the result of the search will be high-lighted
in the display above. For example the Control panel screenshot below shows one result of searching for "<span class="code">Java</span>".
Note that the search operates on the visible text, so you may get different results when searching
the Text and HTML views.
<br>Note: The regular expression uses the Java engine (not ORO engine like the Regular Expression Extractor or Regexp Tester view).
</p>
<p>
If there is no <span class="code">content-type</span> provided, then the content
will not be displayed in the any of the Response Data panels.
You can use <a href="../usermanual/component_reference.html#Save_Responses_to_a_file">Save Responses to a file</a> to save the data in this case.
Note that the response data will still be available in the sample result,
so can still be accessed using Post-Processors.
</p>
<p>If the response data is larger than 200K, then it won't be displayed.
To change this limit, set the JMeter property <span class="code">view.results.tree.max_size</span>.
You can also use save the entire response to a file using
<a href="../usermanual/component_reference.html#Save_Responses_to_a_file">Save Responses to a file</a>.
</p>
<p>
Additional renderers can be created.
The class must implement the interface <span class="code">org.apache.jmeter.visualizers.ResultRenderer</span>
and/or extend the abstract class <span class="code">org.apache.jmeter.visualizers.SamplerResultTab</span>, and the
compiled code must be available to JMeter (e.g. by adding it to the <span class="code">lib/ext</span> directory).
</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/view_results_tree.png"><img src="../images/screenshots/view_results_tree.png" width="910" height="659" alt="Screenshot for Control-Panel of View Results Tree"></a>
<figcaption>Screenshot of Control-Panel of View Results Tree</figcaption>
</figure>
</div>
<p>
The Control Panel (above) shows an example of an HTML display.<br>
Figure 9 (below) shows an example of an XML display.<br>
Figure 9a (below) shows an example of a Regexp tester display.<br>
Figure 9b (below) shows an example of a Document display.<br>
</p>
<div align="center">
<figure>
<a href="../images/screenshots/view_results_tree_xml.png"><img src="../images/screenshots/view_results_tree_xml.png" width="903" height="657" alt="Figure 9 Sample XML display"></a>
<figcaption>Figure 9 Sample XML display</figcaption>
</figure>
<figure>
<a href="../images/screenshots/view_results_tree_regex.png"><img src="../images/screenshots/view_results_tree_regex.png" width="904" height="653" alt="Figure 9a Sample Regexp Test display"></a>
<figcaption>Figure 9a Sample Regexp Test display</figcaption>
</figure>
<figure>
<a href="../images/screenshots/view_results_tree_document.png"><img src="../images/screenshots/view_results_tree_document.png" width="849" height="655" alt="Figure 9b Sample Document (here PDF) display"></a>
<figcaption>Figure 9b Sample Document (here PDF) display</figcaption>
</figure>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="Aggregate_Report">Aggregate Report<a class="sectionlink" href="#Aggregate_Report" title="Link to here">&para;</a>
</h2>
<div class="description">The aggregate report creates a table row for each differently named request in your
test. For each request, it totals the response information and provides request count, min, max,
average, error rate, approximate throughput (request/second) and Kilobytes per second throughput.
Once the test is done, the throughput is the actual through for the duration of the entire test.
<p>
The throughput is calculated from the point of view of the sampler target
(e.g. the remote server in the case of HTTP samples).
JMeter takes into account the total time over which the requests have been generated.
If other samplers and timers are in the same thread, these will increase the total time,
and therefore reduce the throughput value.
So two identical samplers with different names will have half the throughput of two samplers with the same name.
It is important to choose the sampler names correctly to get the best results from
the Aggregate Report.
</p>
<p>
Calculation of the <a href="glossary.html#Median">Median</a> and 90% Line (90<sup>th</sup> <a href="glossary.html#Percentile">percentile</a>) values requires additional memory.
JMeter now combines samples with the same elapsed time, so far less memory is used.
However, for samples that take more than a few seconds, the probability is that fewer samples will have identical times,
in which case more memory will be needed.
Note you can use this listener afterwards to reload a CSV or XML results file which is the recommended way to avoid performance impacts.
See the <a href="../usermanual/component_reference.html#Summary_Report">Summary Report</a> for a similar Listener that does not store individual samples and so needs constant memory.
</p>
<div class="clear"></div>
<div class="note">
Starting with JMeter 2.12, you can configure the 3 percentile values you want to compute, this can be done by setting properties:
<ul>
<li>
<span class="code">aggregate_rpt_pct1</span>: defaults to 90<sup>th</sup> <a href="glossary.html#Percentile">percentile</a>
</li>
<li>
<span class="code">aggregate_rpt_pct2</span>: defaults to 95<sup>th</sup> <a href="glossary.html#Percentile">percentile</a>
</li>
<li>
<span class="code">aggregate_rpt_pct3</span>: defaults to 99<sup>th</sup> <a href="glossary.html#Percentile">percentile</a>
</li>
</ul>
</div>
<div class="clear"></div>
<ul>
<li>
<span class="code">Label</span> - The label of the sample.
If "<span class="code">Include group name in label?</span>" is selected, then the name of the thread group is added as a prefix.
This allows identical labels from different thread groups to be collated separately if required.
</li>
<li>
<span class="code"># Samples</span> - The number of samples with the same label</li>
<li>
<span class="code">Average</span> - The average time of a set of results</li>
<li>
<span class="code">Median</span> - The <a href="glossary.html#Median">median</a> is the time in the middle of a set of results.
50% of the samples took no more than this time; the remainder took at least as long.</li>
<li>
<span class="code">90% Line</span> - 90% of the samples took no more than this time.
The remaining samples took at least as long as this. (90<sup>th</sup> <a href="glossary.html#Percentile">percentile</a>)</li>
<li>
<span class="code">95% Line</span> - 95% of the samples took no more than this time.
The remaining samples took at least as long as this. (95<sup>th</sup> <a href="glossary.html#Percentile">percentile</a>)</li>
<li>
<span class="code">99% Line</span> - 99% of the samples took no more than this time.
The remaining samples took at least as long as this. (99<sup>th</sup> <a href="glossary.html#Percentile">percentile</a>)</li>
<li>
<span class="code">Min</span> - The shortest time for the samples with the same label</li>
<li>Max - The longest time for the samples with the same label</li>
<li>
<span class="code">Error %</span> - Percent of requests with errors</li>
<li>
<span class="code">Throughput</span> - the <a href="glossary.html#Throughput">Throughput</a> is measured in requests per second/minute/hour.
The time unit is chosen so that the displayed rate is at least 1.0.
When the throughput is saved to a CSV file, it is expressed in requests/second,
i.e. 30.0 requests/minute is saved as 0.5.
</li>
<li>
<span class="code">Received KB/sec</span> - The throughput measured in received Kilobytes per second</li>
<li>
<span class="code">Sent KB/sec</span> - The throughput measured in sent Kilobytes per second</li>
</ul>
<p>Times are in milliseconds.</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/aggregate_report.png"><img src="../images/screenshots/aggregate_report.png" width="1206" height="306" alt="Screenshot for Control-Panel of Aggregate Report"></a>
<figcaption>Screenshot of Control-Panel of Aggregate Report</figcaption>
</figure>
</div>
<div align="center">
<p>
The figure below shows an example of selecting the "<span class="code">Include group name</span>" checkbox.
</p>
<figure>
<a href="../images/screenshots/aggregate_report_grouped.png"><img src="../images/screenshots/aggregate_report_grouped.png" width="1207" height="298" alt="Sample &quot;"></a>
<figcaption>Sample "<span class="code">Include group name</span>" display</figcaption>
</figure>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="View_Results_in_Table">View Results in Table<a class="sectionlink" href="#View_Results_in_Table" title="Link to here">&para;</a>
</h2>
<div class="description">This visualizer creates a row for every sample result.
Like the <a href="../usermanual/component_reference.html#View_Results_Tree">View Results Tree</a>, this visualizer uses a lot of memory.
<p>
By default, it only displays the main (parent) samples; it does not display the sub-samples (child samples).
JMeter has a "<span class="code">Child Samples?</span>" check-box.
If this is selected, then the sub-samples are displayed instead of the main samples.
</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/table_results.png"><img src="../images/screenshots/table_results.png" width="966" height="683" alt="Screenshot for Control-Panel of View Results in Table"></a>
<figcaption>Screenshot of Control-Panel of View Results in Table</figcaption>
</figure>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="Simple_Data_Writer">Simple Data Writer<a class="sectionlink" href="#Simple_Data_Writer" title="Link to here">&para;</a>
</h2>
<div class="description">This listener can record results to a file
but not to the UI. It is meant to provide an efficient means of
recording data by eliminating GUI overhead.
When running in CLI mode, the <span class="code">-l</span> flag can be used to create a data file.
The fields to save are defined by JMeter properties.
See the <span class="code">jmeter.properties</span> file for details.
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/simpledatawriter.png"><img src="../images/screenshots/simpledatawriter.png" width="741" height="141" alt="Screenshot for Control-Panel of Simple Data Writer"></a>
<figcaption>Screenshot of Control-Panel of Simple Data Writer</figcaption>
</figure>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="Aggregate_Graph">Aggregate Graph<a class="sectionlink" href="#Aggregate_Graph" title="Link to here">&para;</a>
</h2>
<div class="description">The aggregate graph is similar to the aggregate report. The primary
difference is the aggregate graph provides an easy way to generate bar graphs and save
the graph as a PNG file.</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/aggregate_graph.png"><img src="../images/screenshots/aggregate_graph.png" width="1132" height="872" alt="Screenshot for Control-Panel of Aggregate Graph"></a>
<figcaption>Screenshot of Control-Panel of Aggregate Graph</figcaption>
</figure>
</div>
<div align="center">
<p>
The figure below shows an example of settings to draw this graph.
</p>
<figure>
<a href="../images/screenshots/aggregate_graph_settings.png"><img src="../images/screenshots/aggregate_graph_settings.png" width="1147" height="420" alt="Aggregate graph settings"></a>
<figcaption>Aggregate graph settings</figcaption>
</figure>
</div>
<div class="clear"></div>
<div class="note">Please note: All this parameters <em>aren't</em> saved in JMeter JMX script.</div>
<div class="clear"></div>
<div class="properties">
<h3 id="Aggregate_Graph_parms1">
Parameters
<a class="sectionlink" href="#Aggregate_Graph_parms1" title="Link to here">&para;</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">Column settings</div>
<div class="description req-true">
<ul>
<li>
<span class="code">Columns to display:</span> Choose the column(s) to display in graph.</li>
<li>
<span class="code">Rectangles color:</span> Click on right color rectangle open a popup dialog to choose a custom color for column.</li>
<li>
<span class="code">Foreground color</span> Allow to change the value text color.</li>
<li>
<span class="code">Value font:</span> Allow to define font settings for the text.</li>
<li>
<span class="code">Draw outlines bar?</span> To draw or not the border line on bar chart</li>
<li>
<span class="code">Show number grouping?</span> Show or not the number grouping in Y Axis labels.</li>
<li>
<span class="code">Value labels vertical?</span> Change orientation for value label. (Default is horizontal)</li>
<li>
<span class="code">Column label selection:</span> Filter by result label. A regular expression can be used, example: <span class="code">.*Transaction.*</span>
<br>Before display the graph, click on <span class="code">Apply filter</span> button to refresh internal data.</li>
</ul>
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Title</div>
<div class="description req-false">Define the graph's title on the head of chart. Empty value is the default value : "<span class="code">Aggregate Graph</span>".
The button <span class="code">Synchronize with name</span> define the title with the label of the listener. And define font settings for graph title</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Graph size</div>
<div class="description req-false">Compute the graph size by the width and height depending of the current JMeter's window size.
Use <span class="code">Width</span> and <span class="code">Height</span> fields to define a custom size. The unit is pixel. </div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">X Axis settings</div>
<div class="description req-false">Define the max length of X Axis label (in pixel).</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Y Axis settings</div>
<div class="description req-false">Define a custom maximum value for Y Axis.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Legend</div>
<div class="description req-true">Define the placement and font settings for chart legend</div>
<div class="required req-true">Yes</div>
</div>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="Response_Time_Graph">Response Time Graph<a class="sectionlink" href="#Response_Time_Graph" title="Link to here">&para;</a>
</h2>
<div class="description">
The Response Time Graph draws a line chart showing the evolution of response time during the test, for each labelled request.
If many samples exist for the same timestamp, the mean value is displayed.
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/response_time_graph.png"><img src="../images/screenshots/response_time_graph.png" width="921" height="616" alt="Screenshot for Control-Panel of Response Time Graph"></a>
<figcaption>Screenshot of Control-Panel of Response Time Graph</figcaption>
</figure>
</div>
<div align="center">
<p>
The figure below shows an example of settings to draw this graph.
</p>
<figure>
<a href="../images/screenshots/response_time_graph_settings.png"><img src="../images/screenshots/response_time_graph_settings.png" width="919" height="481" alt="Response time graph settings"></a>
<figcaption>Response time graph settings</figcaption>
</figure>
</div>
<div class="clear"></div>
<div class="note">Please note: All this parameters are saved in JMeter <span class="code">.jmx</span> file.</div>
<div class="clear"></div>
<div class="properties">
<h3 id="Response_Time_Graph_parms1">
Parameters
<a class="sectionlink" href="#Response_Time_Graph_parms1" title="Link to here">&para;</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">Interval (ms)</div>
<div class="description req-true">The time in milliseconds for X axis interval. Samples are grouped according to this value.
Before display the graph, click on <span class="code">Apply interval</span> button to refresh internal data.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Sampler label selection</div>
<div class="description req-false">Filter by result label. A regular expression can be used, ex. <span class="code">.*Transaction.*</span>.
Before display the graph, click on <span class="code">Apply filter</span> button to refresh internal data.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Title</div>
<div class="description req-false">Define the graph's title on the head of chart. Empty value is the default value : "<span class="code">Response Time Graph</span>".
The button <span class="code">Synchronize with name</span> define the title with the label of the listener. And define font settings for graph title</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Line settings</div>
<div class="description req-true">Define the width of the line. Define the type of each value point. Choose <span class="code">none</span> to have a line without mark</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Graph size</div>
<div class="description req-false">Compute the graph size by the width and height depending of the current JMeter's window size.
Use <span class="code">Width</span> and <span class="code">Height</span> fields to define a custom size. The unit is pixel. </div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">X Axis settings</div>
<div class="description req-false">Customize the date format of X axis label.
The syntax is the Java <a href="http://docs.oracle.com/javase/8/docs/api/java/text/SimpleDateFormat.html">SimpleDateFormat API</a>.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Y Axis settings</div>
<div class="description req-false">Define a custom maximum value for Y Axis in milli-seconds. Define the increment for the scale (in ms) Show or not the number grouping in Y Axis labels.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Legend</div>
<div class="description req-true">Define the placement and font settings for chart legend</div>
<div class="required req-true">Yes</div>
</div>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="Mailer_Visualizer">Mailer Visualizer<a class="sectionlink" href="#Mailer_Visualizer" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>The mailer visualizer can be set up to send email if a test run receives too many
failed responses from the server.</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/mailervisualizer.png"><img src="../images/screenshots/mailervisualizer.png" width="860" height="403" alt="Screenshot for Control-Panel of Mailer Visualizer"></a>
<figcaption>Screenshot of Control-Panel of Mailer Visualizer</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="Mailer_Visualizer_parms1">
Parameters
<a class="sectionlink" href="#Mailer_Visualizer_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-false">Descriptive name for this element that is shown in the tree.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">From</div>
<div class="description req-true">Email address to send messages from.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Addressee(s)</div>
<div class="description req-true">Email address to send messages to, comma-separated.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Success Subject</div>
<div class="description req-false">Email subject line for success messages.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Success Limit</div>
<div class="description req-true">Once this number of successful responses is exceeded
<strong>after previously reaching the failure limit</strong>, a success email
is sent. The mailer will thus only send out messages in a sequence of failed-succeeded-failed-succeeded, etc.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Failure Subject</div>
<div class="description req-false">Email subject line for fail messages.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Failure Limit</div>
<div class="description req-true">Once this number of failed responses is exceeded, a failure
email is sent - i.e. set the count to <span class="code">0</span> to send an e-mail on the first failure.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Host</div>
<div class="description req-false">IP address or host name of SMTP server (email redirector)
server.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Port</div>
<div class="description req-false">Port of SMTP server (defaults to <span class="code">25</span>).</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Login</div>
<div class="description req-false">Login used to authenticate.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Password</div>
<div class="description req-false">Password used to authenticate.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Connection security</div>
<div class="description req-false">Type of encryption for SMTP authentication (SSL, TLS or none).</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Test Mail</div>
<div class="description req-false">Press this button to send a test mail</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Failures</div>
<div class="description req-false">A field that keeps a running total of number
of failures so far received.</div>
<div class="required req-false">No</div>
</div>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="BeanShell_Listener">BeanShell Listener<a class="sectionlink" href="#BeanShell_Listener" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>
The BeanShell Listener allows the use of BeanShell for processing samples for saving etc.
</p>
<p>
<b>For full details on using BeanShell, please see the <a href="http://www.beanshell.org/">BeanShell website.</a></b>
<div class="clear"></div>
<div class="note">Migration to <a href="../usermanual/component_reference.html#JSR223_Listener">JSR223 Listener</a>+Groovy is highly recommended for performance, support of new Java features and limited maintenance of the BeanShell library.</div>
<div class="clear"></div>
</p>
<p>
The test element supports the <span class="code">ThreadListener</span> and <span class="code">TestListener</span> methods.
These should be defined in the initialisation file.
See the file <span class="code">BeanShellListeners.bshrc</span> for example definitions.
</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/beanshell_listener.png"><img src="../images/screenshots/beanshell_listener.png" width="844" height="633" alt="Screenshot for Control-Panel of BeanShell Listener"></a>
<figcaption>Screenshot of Control-Panel of BeanShell Listener</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="BeanShell_Listener_parms1">
Parameters
<a class="sectionlink" href="#BeanShell_Listener_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-true">Descriptive name for this element that is shown in the tree.
The name is stored in the script variable Label</div>
<div class="required req-true"></div>
</div>
<div class="property">
<div class="name req-true">Reset bsh.Interpreter before each call</div>
<div class="description req-true">
If this option is selected, then the interpreter will be recreated for each sample.
This may be necessary for some long running scripts.
For further information, see <a href="best-practices.html#bsh_scripting">Best Practices - BeanShell scripting</a>.
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Parameters</div>
<div class="description req-false">Parameters to pass to the BeanShell script.
The parameters are stored in the following variables:
<dl>
<dt>
<span class="code">Parameters</span>
</dt>
<dd>string containing the parameters as a single variable</dd>
<dt>
<span class="code">bsh.args</span>
</dt>
<dd>String array containing parameters, split on white-space</dd>
</dl>
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Script file</div>
<div class="description req-false">A file containing the BeanShell script to run.
The file name is stored in the script variable <span class="code">FileName</span>
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Script</div>
<div class="description req-true">The BeanShell script to run. The return value is ignored.</div>
<div class="required req-true">Yes (unless script file is provided)</div>
</div>
</div>
<p>Before invoking the script, some variables are set up in the BeanShell interpreter:</p>
<ul>
<li>
<span class="code">log</span> - (<a href="https://www.slf4j.org/api/org/slf4j/Logger.html">Logger</a>) - can be used to write to the log file</li>
<li>
<span class="code">ctx</span> - (<a href="../api/org/apache/jmeter/threads/JMeterContext.html">JMeterContext</a>) - gives access to the context</li>
<li>
<span class="code">vars</span> - (<a href="../api/org/apache/jmeter/threads/JMeterVariables.html">JMeterVariables</a>) - gives read/write access to variables: <pre class="source">vars.get(key);
vars.put(key,val);
vars.putObject("OBJ1",new Object());
</pre>
</li>
<li>
<span class="code">props</span> - (JMeterProperties - class <a href="https://docs.oracle.com/javase/8/docs/api/java/util/Properties.html"><span class="code">java.util.Properties</span></a>) - e.g. <span class="code">props.get("START.HMS");</span> <span class="code">props.put("PROP1","1234");</span>
</li>
<li>
<span class="code">sampleResult</span>, <span class="code">prev</span> - (<a href="../api/org/apache/jmeter/samplers/SampleResult.html">SampleResult</a>) - gives access to the previous <a href="../api/org/apache/jmeter/samplers/SampleResult.html">SampleResult</a>
</li>
<li>
<span class="code">sampleEvent</span> (<a href="../api/org/apache/jmeter/samplers/SampleEvent.html">SampleEvent</a>) gives access to the current sample event</li>
</ul>
<p>For details of all the methods available on each of the above variables, please check the Javadoc</p>
<p>If the property <span class="code">beanshell.listener.init</span> is defined, this is used to load an initialisation file, which can be used to define methods etc. for use in the BeanShell script.</p>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="Summary_Report">Summary Report<a class="sectionlink" href="#Summary_Report" title="Link to here">&para;</a>
</h2>
<div class="description">The summary report creates a table row for each differently named request in your
test. This is similar to the <a href="../usermanual/component_reference.html#Aggregate_Report">Aggregate Report</a> , except that it uses less memory.
<p>
The throughput is calculated from the point of view of the sampler target
(e.g. the remote server in the case of HTTP samples).
JMeter takes into account the total time over which the requests have been generated.
If other samplers and timers are in the same thread, these will increase the total time,
and therefore reduce the throughput value.
So two identical samplers with different names will have half the throughput of two samplers with the same name.
It is important to choose the sampler labels correctly to get the best results from
the Report.
</p>
<ul>
<li>
<span class="code">Label</span> - The label of the sample.
If "<span class="code">Include group name in label?</span>" is selected, then the name of the thread group is added as a prefix.
This allows identical labels from different thread groups to be collated separately if required.
</li>
<li>
<span class="code"># Samples</span> - The number of samples with the same label</li>
<li>
<span class="code">Average</span> - The average elapsed time of a set of results</li>
<li>
<span class="code">Min</span> - The lowest elapsed time for the samples with the same label</li>
<li>
<span class="code">Max</span> - The longest elapsed time for the samples with the same label</li>
<li>
<span class="code">Std. Dev.</span> - the <a href="glossary.html#StandardDeviation">Standard Deviation</a> of the sample elapsed time</li>
<li>
<span class="code">Error %</span> - Percent of requests with errors</li>
<li>
<span class="code">Throughput</span> - the <a href="glossary.html#Throughput">Throughput</a> is measured in requests per second/minute/hour.
The time unit is chosen so that the displayed rate is at least <span class="code">1.0</span>.
When the throughput is saved to a CSV file, it is expressed in requests/second,
i.e. 30.0 requests/minute is saved as <span class="code">0.5</span>.
</li>
<li>
<span class="code">Received KB/sec</span> - The throughput measured in Kilobytes per second</li>
<li>
<span class="code">Sent KB/sec</span> - The throughput measured in Kilobytes per second</li>
<li>
<span class="code">Avg. Bytes</span> - average size of the sample response in bytes.</li>
</ul>
<p>Times are in milliseconds.</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/summary_report.png"><img src="../images/screenshots/summary_report.png" width="1204" height="300" alt="Screenshot for Control-Panel of Summary Report"></a>
<figcaption>Screenshot of Control-Panel of Summary Report</figcaption>
</figure>
</div>
<div align="center">
<p>
The figure below shows an example of selecting the "<span class="code">Include group name</span>" checkbox.
</p>
<figure>
<a href="../images/screenshots/summary_report_grouped.png"><img src="../images/screenshots/summary_report_grouped.png" width="1208" height="302" alt="Sample &quot;"></a>
<figcaption>Sample "<span class="code">Include group name</span>" display</figcaption>
</figure>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="Save_Responses_to_a_file">Save Responses to a file<a class="sectionlink" href="#Save_Responses_to_a_file" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>
This test element can be placed anywhere in the test plan.
For each sample in its scope, it will create a file of the response Data.
The primary use for this is in creating functional tests, but it can also
be useful where the response is too large to be displayed in the
<a href="../usermanual/component_reference.html#View_Results_Tree">View Results Tree</a> Listener.
The file name is created from the specified prefix, plus a number (unless this is disabled, see below).
The file extension is created from the document type, if known.
If not known, the file extension is set to '<span class="code">unknown</span>'.
If numbering is disabled, and adding a suffix is disabled, then the file prefix is
taken as the entire file name. This allows a fixed file name to be generated if required.
The generated file name is stored in the sample response, and can be saved
in the test log output file if required.
</p>
<p>
The current sample is saved first, followed by any sub-samples (child samples).
If a variable name is provided, then the names of the files are saved in the order
that the sub-samples appear. See below.
</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/savetofile.png"><img src="../images/screenshots/savetofile.png" width="488" height="251" alt="Screenshot for Control-Panel of Save Responses to a file"></a>
<figcaption>Screenshot of Control-Panel of Save Responses to a file</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="Save_Responses_to_a_file_parms1">
Parameters
<a class="sectionlink" href="#Save_Responses_to_a_file_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-false">Descriptive name for this element that is shown in the tree.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Filename Prefix (can include folders)</div>
<div class="description req-true">Prefix for the generated file names; this can include a directory name.
Relative paths are resolved relative to the current working directory (which defaults to the <span class="code">bin/</span> directory).
JMeter also supports paths relative to the directory containing the current test plan (JMX file).
If the path name begins with "<span class="code">~/</span>" (or whatever is in the <span class="code">jmeter.save.saveservice.base_prefix</span> JMeter property),
then the path is assumed to be relative to the JMX file location. <br>
If parent folders in prefix do not exists, JMeter will create them and stop test if it fails.
<div class="clear"></div>
<div class="note">Please note that Filename Prefix must not contain Thread related data, so don't use any Variable (<span class="code">${varName}</span>) or functions like <span class="code">${__threadNum}</span> in this field</div>
<div class="clear"></div>
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Variable Name containing saved file name</div>
<div class="description req-false">
Name of a variable in which to save the generated file name (so it can be used later in the test plan).
If there are sub-samples then a numeric suffix is added to the variable name.
E.g. if the variable name is <span class="code">FILENAME</span>, then the parent sample file name is saved in the variable <span class="code">FILENAME</span>,
and the filenames for the child samplers are saved in <span class="code">FILENAME1</span>, <span class="code">FILENAME2</span> etc.
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Minimum Length of sequence number</div>
<div class="description req-false">If "<span class="code">Don't add number to prefix</span>" is not checked, then numbers added to prefix will be padded by <span class="code">0</span> so that prefix is has size of this value. Defaults to <span class="code">0</span>.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Save Failed Responses only</div>
<div class="description req-true">If selected, then only failed responses are saved</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Save Successful Responses only</div>
<div class="description req-true">If selected, then only successful responses are saved</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Don't add number to prefix</div>
<div class="description req-true">If selected, then no number is added to the prefix. If you select this option, make sure that the prefix is unique or the file may be overwritten.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Don't add content type suffix</div>
<div class="description req-true">If selected, then no suffix is added. If you select this option, make sure that the prefix is unique or the file may be overwritten.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Add timestamp</div>
<div class="description req-true">If selected, then date will be included in file suffix following format <span class="code">yyyyMMdd-HHmm_</span>
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Don't Save Transaction Controller SampleResult</div>
<div class="description req-true">If selected, then SamplerResult generated by Transaction Controller will be ignored</div>
<div class="required req-true">Yes</div>
</div>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="JSR223_Listener">JSR223 Listener<a class="sectionlink" href="#JSR223_Listener" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>
The JSR223 Listener allows JSR223 script code to be applied to sample results.
</p>
</div>
<div class="properties">
<h3 id="JSR223_Listener_parms1">
Parameters
<a class="sectionlink" href="#JSR223_Listener_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-false">Descriptive name for this element that is shown in the tree.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Language</div>
<div class="description req-true">The JSR223 language to be used</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Parameters</div>
<div class="description req-false">Parameters to pass to the script.
The parameters are stored in the following variables:
<dl>
<dt>
<span class="code">Parameters</span>
</dt>
<dd>string containing the parameters as a single variable</dd>
<dt>
<span class="code">args</span>
</dt>
<dd>String array containing parameters, split on white-space</dd>
</dl>
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Script file</div>
<div class="description req-false">A file containing the script to run, if a relative file path is used, then it will be relative to directory referenced by "<span class="code">user.dir</span>" System property</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Script compilation caching</div>
<div class="description req-false">Unique String across Test Plan that JMeter will use to cache result of Script compilation if language used supports <span class="code"><a href="https://docs.oracle.com/javase/8/docs/api/javax/script/Compilable.html">Compilable</a></span> interface (Groovy is one of these, java, beanshell and javascript are not).
<div class="clear"></div>
<div class="note">See note in JSR223 Sampler Java System property if you're using Groovy without checking this option</div>
<div class="clear"></div>
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Script</div>
<div class="description req-true">The script to run.</div>
<div class="required req-true">Yes (unless script file is provided)</div>
</div>
</div>
<p>
Before invoking the script, some variables are set up.
Note that these are JSR223 variables - i.e. they can be used directly in the script.
</p>
<dl>
<dt>
<span class="code">log</span>
</dt>
<dd>(<a href="https://www.slf4j.org/api/org/slf4j/Logger.html">Logger</a>) - can be used to write to the log file</dd>
<dt>
<span class="code">Label</span>
</dt>
<dd>the String Label</dd>
<dt>
<span class="code">FileName</span>
</dt>
<dd>the script file name (if any)</dd>
<dt>
<span class="code">Parameters</span>
</dt>
<dd>the parameters (as a String)</dd>
<dt>
<span class="code">args</span>
</dt>
<dd>the parameters as a String array (split on whitespace)</dd>
<dt>
<span class="code">ctx</span>
</dt>
<dd>(<a href="../api/org/apache/jmeter/threads/JMeterContext.html">JMeterContext</a>) - gives access to the context</dd>
<dt>
<span class="code">vars</span>
</dt>
<dd>(<a href="../api/org/apache/jmeter/threads/JMeterVariables.html">JMeterVariables</a>) - gives read/write access to variables: <pre class="source">vars.get(key);
vars.put(key,val);
vars.putObject("OBJ1",new Object());
vars.getObject("OBJ2");</pre>
</dd>
<dt>
<span class="code">props</span>
</dt>
<dd>(JMeterProperties - class <a href="https://docs.oracle.com/javase/8/docs/api/java/util/Properties.html"><span class="code">java.util.Properties</span></a>) - e.g. <span class="code">props.get("START.HMS");</span> <span class="code">props.put("PROP1","1234");</span>
</dd>
<dt>
<span class="code">sampleResult</span>, <span class="code">prev</span>
</dt>
<dd>(<a href="../api/org/apache/jmeter/samplers/SampleResult.html">SampleResult</a>) - gives access to the SampleResult</dd>
<dt>
<span class="code">sampleEvent</span>
</dt>
<dd>(<a href="../api/org/apache/jmeter/samplers/SampleEvent.html">SampleEvent</a>) - gives access to the SampleEvent</dd>
<dt>
<span class="code">sampler</span>
</dt>
<dd>(<a href="../api/org/apache/jmeter/samplers/Sampler.html">Sampler</a>)- gives access to the last sampler</dd>
<dt>
<span class="code">OUT</span>
</dt>
<dd>
<span class="code">System.out</span> - e.g. <span class="code">OUT.println("message")</span>
</dd>
</dl>
<p>For details of all the methods available on each of the above variables, please check the Javadoc</p>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="Generate_Summary_Results">Generate Summary Results<a class="sectionlink" href="#Generate_Summary_Results" title="Link to here">&para;</a>
</h2>
<div class="description">This test element can be placed anywhere in the test plan.
Generates a summary of the test run so far to the log file and/or
standard output. Both running and differential totals are shown.
Output is generated every <span class="code">n</span> seconds (default 30 seconds) on the appropriate
time boundary, so that multiple test runs on the same time will be synchronised.
See <span class="code">jmeter.properties</span> file for the summariser configuration items:
<pre class="source">
# Define the following property to automatically start a summariser with that name
# (applies to CLI mode only)
#summariser.name=summary
#
# interval between summaries (in seconds) default 3 minutes
#summariser.interval=30
#
# Write messages to log file
#summariser.log=true
#
# Write messages to System.out
#summariser.out=true
</pre>
This element is mainly intended for batch (CLI) runs.
The output looks like the following:
<pre class="source">
label + 16 in 0:00:12 = 1.3/s Avg: 1608 Min: 1163 Max: 2009 Err: 0 (0.00%) Active: 5 Started: 5 Finished: 0
label + 82 in 0:00:30 = 2.7/s Avg: 1518 Min: 1003 Max: 2020 Err: 0 (0.00%) Active: 5 Started: 5 Finished: 0
label = 98 in 0:00:42 = 2.3/s Avg: 1533 Min: 1003 Max: 2020 Err: 0 (0.00%)
label + 85 in 0:00:30 = 2.8/s Avg: 1505 Min: 1008 Max: 2005 Err: 0 (0.00%) Active: 5 Started: 5 Finished: 0
label = 183 in 0:01:13 = 2.5/s Avg: 1520 Min: 1003 Max: 2020 Err: 0 (0.00%)
label + 79 in 0:00:30 = 2.7/s Avg: 1578 Min: 1089 Max: 2012 Err: 0 (0.00%) Active: 5 Started: 5 Finished: 0
label = 262 in 0:01:43 = 2.6/s Avg: 1538 Min: 1003 Max: 2020 Err: 0 (0.00%)
label + 80 in 0:00:30 = 2.7/s Avg: 1531 Min: 1013 Max: 2014 Err: 0 (0.00%) Active: 5 Started: 5 Finished: 0
label = 342 in 0:02:12 = 2.6/s Avg: 1536 Min: 1003 Max: 2020 Err: 0 (0.00%)
label + 83 in 0:00:31 = 2.7/s Avg: 1512 Min: 1003 Max: 1982 Err: 0 (0.00%) Active: 5 Started: 5 Finished: 0
label = 425 in 0:02:43 = 2.6/s Avg: 1531 Min: 1003 Max: 2020 Err: 0 (0.00%)
label + 83 in 0:00:29 = 2.8/s Avg: 1487 Min: 1023 Max: 2013 Err: 0 (0.00%) Active: 5 Started: 5 Finished: 0
label = 508 in 0:03:12 = 2.6/s Avg: 1524 Min: 1003 Max: 2020 Err: 0 (0.00%)
label + 78 in 0:00:30 = 2.6/s Avg: 1594 Min: 1013 Max: 2016 Err: 0 (0.00%) Active: 5 Started: 5 Finished: 0
label = 586 in 0:03:43 = 2.6/s Avg: 1533 Min: 1003 Max: 2020 Err: 0 (0.00%)
label + 80 in 0:00:30 = 2.7/s Avg: 1516 Min: 1013 Max: 2005 Err: 0 (0.00%) Active: 5 Started: 5 Finished: 0
label = 666 in 0:04:12 = 2.6/s Avg: 1531 Min: 1003 Max: 2020 Err: 0 (0.00%)
label + 86 in 0:00:30 = 2.9/s Avg: 1449 Min: 1004 Max: 2017 Err: 0 (0.00%) Active: 5 Started: 5 Finished: 0
label = 752 in 0:04:43 = 2.7/s Avg: 1522 Min: 1003 Max: 2020 Err: 0 (0.00%)
label + 65 in 0:00:24 = 2.7/s Avg: 1579 Min: 1007 Max: 2003 Err: 0 (0.00%) Active: 0 Started: 5 Finished: 5
label = 817 in 0:05:07 = 2.7/s Avg: 1526 Min: 1003 Max: 2020 Err: 0 (0.00%)
</pre>
The "<span class="code">label</span>" is the name of the element.
The <span class="code">"+"</span> means that the line is a delta line, i.e. shows the changes since the last output.<br>
The <span class="code">"="</span> means that the line is a total line, i.e. it shows the running total.<br>
Entries in the JMeter log file also include time-stamps.
The example "<span class="code">817 in 0:05:07 = 2.7/s</span>" means that there were 817 samples recorded in 5 minutes and 7 seconds,
and that works out at 2.7 samples per second.<br>
The <span class="code">Avg</span> (Average), <span class="code">Min</span> (Minimum) and <span class="code">Max</span> (Maximum) times are in milliseconds.<br>
"<span class="code">Err</span>" means number of errors (also shown as percentage).<br>
The last two lines will appear at the end of a test.
They will not be synchronised to the appropriate time boundary.
Note that the initial and final deltas may be for less than the interval (in the example above this is 30 seconds).
The first delta will generally be lower, as JMeter synchronizes to the interval boundary.
The last delta will be lower, as the test will generally not finish on an exact interval boundary.
<p>
The label is used to group sample results together.
So if you have multiple Thread Groups and want to summarize across them all, then use the same label
- or add the summariser to the Test Plan (so all thread groups are in scope).
Different summary groupings can be implemented
by using suitable labels and adding the summarisers to appropriate parts of the test plan.
</p>
<div class="clear"></div>
<div class="note">
In CLI mode by default a Generate Summary Results listener named "<span class="code">summariser</span>" is configured, if you have already added one to your Test Plan, ensure you name it differently
otherwise results will be accumulated under this label (summary) leading to wrong results (sum of total samples + samples located under the Parent of Generate Summary Results listener).<br>
This is not a bug but a design choice allowing to summarize across thread groups.
</div>
<div class="clear"></div>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/summary.png"><img src="../images/screenshots/summary.png" width="364" height="76" alt="Screenshot for Control-Panel of Generate Summary Results"></a>
<figcaption>Screenshot of Control-Panel of Generate Summary Results</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="Generate_Summary_Results_parms1">
Parameters
<a class="sectionlink" href="#Generate_Summary_Results_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-true">Descriptive name for this element that is shown in the tree.
It appears as the "<span class="code">label</span>" in the output. Details for all elements with the same label will be added together.
</div>
<div class="required req-true">Yes</div>
</div>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="Comparison_Assertion_Visualizer">Comparison Assertion Visualizer<a class="sectionlink" href="#Comparison_Assertion_Visualizer" title="Link to here">&para;</a>
</h2>
<div class="description">
The Comparison Assertion Visualizer shows the results of any <a href="../usermanual/component_reference.html#Compare_Assertion">Compare Assertion</a> elements.
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/comparison_assertion_visualizer.png"><img src="../images/screenshots/comparison_assertion_visualizer.png" width="718" height="454" alt="Screenshot for Control-Panel of Comparison Assertion Visualizer"></a>
<figcaption>Screenshot of Control-Panel of Comparison Assertion Visualizer</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="Comparison_Assertion_Visualizer_parms1">
Parameters
<a class="sectionlink" href="#Comparison_Assertion_Visualizer_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-true">Descriptive name for this element that is shown in the tree.
</div>
<div class="required req-true">Yes</div>
</div>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="Backend_Listener">Backend Listener<a class="sectionlink" href="#Backend_Listener" title="Link to here">&para;</a>
</h2>
<div class="description">
The backend listener is an Asynchronous listener that enables you to plug custom implementations of <a href="../api/org/apache/jmeter/visualizers/backend/BackendListenerClient.html">BackendListenerClient</a>.
By default, a Graphite implementation is provided.
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/backend_listener.png"><img src="../images/screenshots/backend_listener.png" width="705" height="350" alt="Screenshot for Control-Panel of Backend Listener"></a>
<figcaption>Screenshot of Control-Panel of Backend Listener</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="Backend_Listener_parms1">
Parameters
<a class="sectionlink" href="#Backend_Listener_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-true">Descriptive name for this element that is shown in the tree.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Backend Listener implementation</div>
<div class="description req-true">Class of the <span class="code">BackendListenerClient</span> implementation.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Async Queue size</div>
<div class="description req-true">Size of the queue that holds the SampleResults while they are processed asynchronously.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Parameters</div>
<div class="description req-true">Parameters of the <span class="code">BackendListenerClient</span> implementation.</div>
<div class="required req-true">Yes</div>
</div>
</div>
<p>The following parameters apply to the <a href="../api/org/apache/jmeter/visualizers/backend/graphite/GraphiteBackendListenerClient.html">GraphiteBackendListenerClient</a> implementation:</p>
<div class="properties">
<h3 id="Backend_Listener_parms2">
Parameters
<a class="sectionlink" href="#Backend_Listener_parms2" title="Link to here">&para;</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">graphiteMetricsSender</div>
<div class="description req-true">
<span class="code">org.apache.jmeter.visualizers.backend.graphite.TextGraphiteMetricsSender</span> or <span class="code">org.apache.jmeter.visualizers.backend.graphite.PickleGraphiteMetricsSender</span>
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">graphiteHost</div>
<div class="description req-true">Graphite or InfluxDB (with Graphite plugin enabled) server host</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">graphitePort</div>
<div class="description req-true">Graphite or InfluxDB (with Graphite plugin enabled) server port, defaults to <span class="code">2003</span>. Note <span class="code">PickleGraphiteMetricsSender</span> (port <span class="code">2004</span>) can only talk to Graphite server.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">rootMetricsPrefix</div>
<div class="description req-true">Prefix of metrics sent to backend. Defaults to "<span class="code">jmeter</span>."
Note that JMeter does not add a separator between the root prefix and the samplerName which is why the trailing dot is currently needed.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">summaryOnly</div>
<div class="description req-true">Only send a summary with no detail. Defaults to <span class="code">true</span>.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">samplersList</div>
<div class="description req-true">Defines the names (labels) of sample results to be sent to the back end.
If <span class="code">useRegexpForSamplersList=false</span> this is a list of semi-colon separated names.
If <span class="code">useRegexpForSamplersList=true</span> this is a regular expression which will be matched against the names.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">useRegexpForSamplersList</div>
<div class="description req-true">Consider samplersList as a regular expression to select the samplers for which you want to report metrics to backend. Defaults to <span class="code">false</span>.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">percentiles</div>
<div class="description req-true">The percentiles you want to send to the backend.
A percentile may contain a fractional part, for example <span class="code">12.5</span>.
(The separator is always ".")
List must be semicolon separated. Generally 3 or 4 values should be sufficient.</div>
<div class="required req-true">Yes</div>
</div>
</div>
<p>See also <a href="realtime-results.html">Real-time results</a> for more details.</p>
<figure>
<a href="../images/screenshots/grafana_dashboard.png"><img src="../images/screenshots/grafana_dashboard.png" width="1265" height="581" alt="Grafana dashboard"></a>
<figcaption>Grafana dashboard</figcaption>
</figure>
<p>Since JMeter 3.2, a new implementation has been added that allows writing directly in InfluxDB with a custom schema, it is called <span class="code">InfluxdbBackendListenerClient</span>. Since JMeter 5.2, <span class="code">InfluxdbBackendListenerClient</span> supports both InfluxDB v1 and v2.</p>
<p>The following parameters apply to the <a href="../api/org/apache/jmeter/visualizers/backend/influxdb/InfluxdbBackendListenerClient.html">InfluxdbBackendListenerClient</a> implementation:</p>
<div class="properties">
<h3 id="Backend_Listener_parms3">
Parameters
<a class="sectionlink" href="#Backend_Listener_parms3" title="Link to here">&para;</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">influxdbMetricsSender</div>
<div class="description req-true">
<span class="code">org.apache.jmeter.visualizers.backend.influxdb.HttpMetricsSender</span>
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">influxdbUrl</div>
<div class="description req-true">Influx URL (example: <span class="code">http://influxHost:8086/write?db=jmeter</span>)</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">influxdbToken</div>
<div class="description req-false">InfluxDB 2 <a href="https://v2.docs.influxdata.com/v2.0/security/">authentication token</a> (example: <span class="code">HE9yIdAPzWJDspH_tCc2UvdKZpX==</span>); since 5.2.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">application</div>
<div class="description req-true">Name of tested application. This value is stored in the '<span class="code">events</span>' measurement as a tag named '<span class="code">application</span>' </div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">measurement</div>
<div class="description req-true">Measurement as per <a href="https://docs.influxdata.com/influxdb/v1.1/write_protocols/line_protocol_reference/">Influx Line Protocol Reference</a>. Defaults to "<span class="code">jmeter</span>".</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">summaryOnly</div>
<div class="description req-true">Only send a summary with no detail. Defaults to <span class="code">true</span>.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">samplersRegex</div>
<div class="description req-true">Regular expression which will be matched against the names of samples and sent to the back end.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">testTitle</div>
<div class="description req-true">Test name. Defaults to <span class="code">Test name</span>. This value is stored in the '<span class="code">events</span>' measurement as a field named '<span class="code">text</span>'. JMeter generate automatically at the start and the end of the test an annotation with this value ending with ' started' and ' ended'</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">eventTags</div>
<div class="description req-false">Grafana allow to display tag for each annotation. You can fill them here. This value is stored in the '<span class="code">events</span>' measurement as a tag named '<span class="code">tags</span>'.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">percentiles</div>
<div class="description req-true">The percentiles you want to send to the backend.
A percentile may contain a fractional part, for example <span class="code">12.5</span>
(The separator is always "<span class="code">.</span>").
List must be semicolon separated. Generally three or four values should be sufficient.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">TAG_WhatEverYouWant</div>
<div class="description req-false">You can add as many custom tags as you want. For each of them, create a new line and prefix its name by "<span class="code">TAG_</span>"</div>
<div class="required req-false">No</div>
</div>
</div>
<p>See also <a href="realtime-results.html">Real-time results</a> and <a href="http://docs.grafana.org/reference/annotations/#influxdb-annotations">Influxdb annotations in Grafana</a> for more details.
There is also a <a href="realtime-results.html#influxdb_v2">subsection on configuring the listener for InfluxDB v2</a>.
</p>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<a href="#">^</a>
</div>
<div class="section">
<h1 id="config_elements">18.4 Configuration Elements<a class="sectionlink" href="#config_elements" title="Link to here">&para;</a>
</h1>
<div class="description">
<br>
Configuration elements can be used to set up defaults and variables for later use by samplers.
Note that these elements are processed at the start of the scope in which they are found,
i.e. before any samplers in the same scope.
<br>
</div>
<div class="component">
<h2 id="CSV_Data_Set_Config">CSV Data Set Config<a class="sectionlink" href="#CSV_Data_Set_Config" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>
CSV Data Set Config is used to read lines from a file, and split them into variables.
It is easier to use than the <span class="code"><a href="../usermanual/functions.html#__CSVRead">__CSVRead()</a></span> and <span class="code"><a href="../usermanual/functions.html#__StringFromFile">__StringFromFile()</a></span> functions.
It is well suited to handling large numbers of variables, and is also useful for testing with
"random" and unique values.</p>
<p>Generating unique random values at run-time is expensive in terms of CPU and memory, so just create the data
in advance of the test. If necessary, the "random" data from the file can be used in conjunction with
a run-time parameter to create different sets of values from each run - e.g. using concatenation - which is
much cheaper than generating everything at run-time.
</p>
<p>
JMeter allows values to be quoted; this allows the value to contain a delimiter.
If "<span class="code">allow quoted data</span>" is enabled, a value may be enclosed in double-quotes.
These are removed. To include double-quotes within a quoted field, use two double-quotes.
For example:
</p>
<pre class="source">
1,"2,3","4""5" =&gt;
1
2,3
4"5
</pre>
<p>
JMeter supports CSV files which have a header line defining the column names.
To enable this, leave the "<span class="code">Variable Names</span>" field empty. The correct delimiter must be provided.
</p>
<p>
JMeter supports CSV files with quoted data that includes new-lines.
</p>
<p>
By default, the file is only opened once, and each thread will use a different line from the file.
However the order in which lines are passed to threads depends on the order in which they execute,
which may vary between iterations.
Lines are read at the start of each test iteration.
The file name and mode are resolved in the first iteration.
</p>
<p>
See the description of the Share mode below for additional options.
If you want each thread to have its own set of values, then you will need to create a set of files,
one for each thread. For example <span class="code">test1.csv</span>, <span class="code">test2.csv</span>, &hellip;, <span class="code">test<em>n</em>.csv</span>. Use the filename
<span class="code">test${__threadNum}.csv</span> and set the "<span class="code">Sharing mode</span>" to "<span class="code">Current thread</span>".
</p>
<div class="clear"></div>
<div class="note">CSV Dataset variables are defined at the start of each test iteration.
As this is after configuration processing is completed,
they cannot be used for some configuration items - such as JDBC Config -
that process their contents at configuration time (see <a href="https://bz.apache.org/bugzilla/show_bug.cgi?id=40394">
Bug
40394</a>)
However the variables do work in the HTTP Auth Manager, as the <span class="code">username</span> etc. are processed at run-time.
</div>
<div class="clear"></div>
<p>
As a special case, the string "<span class="code">\t</span>" (without quotes) in the delimiter field is treated as a Tab.
</p>
<p>
When the end of file (<span class="code"><abbr title="end of file">EOF</abbr></span>) is reached, and the recycle option is <span class="code">true</span>, reading starts again with the first line of the file.
</p>
<p>
If the recycle option is <span class="code">false</span>, and stopThread is <span class="code">false</span>, then all the variables are set to <span class="code">&lt;EOF&gt;</span> when the end of file is reached.
This value can be changed by setting the JMeter property <span class="code">csvdataset.eofstring</span>.
</p>
<p>
If the Recycle option is <span class="code">false</span>, and Stop Thread is <span class="code">true</span>, then reaching <span class="code"><abbr title="end of file">EOF</abbr></span> will cause the thread to be stopped.
</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/csvdatasetconfig.png"><img src="../images/screenshots/csvdatasetconfig.png" width="433" height="281" alt="Screenshot for Control-Panel of CSV Data Set Config"></a>
<figcaption>Screenshot of Control-Panel of CSV Data Set Config</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="CSV_Data_Set_Config_parms1">
Parameters
<a class="sectionlink" href="#CSV_Data_Set_Config_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-true">Descriptive name for this element that is shown in the tree.</div>
<div class="required req-true"></div>
</div>
<div class="property">
<div class="name req-true">Filename</div>
<div class="description req-true">Name of the file to be read.
<b>Relative file names are resolved with respect to the path of the active test plan.</b>
<b>For distributed testing, the CSV file must be stored on the server host system in the correct relative directory to where the JMeter server is started.</b>
Absolute file names are also supported, but note that they are unlikely to work in remote mode,
unless the remote server has the same directory structure.
If the same physical file is referenced in two different ways - e.g. <span class="code">csvdata.txt</span> and <span class="code">./csvdata.txt</span> -
then these are treated as different files.
If the OS does not distinguish between upper and lower case, <span class="code">csvData.TXT</span> would also be opened separately.
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">File Encoding</div>
<div class="description req-false">The encoding to be used to read the file, if not the platform default.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Variable Names</div>
<div class="description req-false">List of variable names. The names must be separated by the delimiter character. They can be quoted using double-quotes.
JMeter supports CSV header lines:
if the variable name field empty, then the first line of the file is read and interpreted as the list of column names.
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Use first line as Variable Names</div>
<div class="description req-false">
Ignore first line of CSV file, it will only be used if Variable Names is not empty,
if Variable Names is empty the first line must contain the headers.
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Delimiter</div>
<div class="description req-true">Delimiter to be used to split the records in the file.
If there are fewer values on the line than there are variables the remaining variables are not updated -
so they will retain their previous value (if any).</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Allow quoted data?</div>
<div class="description req-true">Should the CSV file allow values to be quoted?
If enabled, then values can be enclosed in <span class="code">"</span> - double-quote - allowing values to contain a delimiter.
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Recycle on EOF?</div>
<div class="description req-true">Should the file be re-read from the beginning on reaching <span class="code"><abbr title="end of file">EOF</abbr></span>? (default is <span class="code">true</span>)</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Stop thread on EOF?</div>
<div class="description req-true">Should the thread be stopped on <span class="code"><abbr title="end of file">EOF</abbr></span>, if Recycle is false? (default is <span class="code">false</span>)</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Sharing mode</div>
<div class="description req-true">
<ul>
<li>
<span class="code">All threads</span> - (the default) the file is shared between all the threads.</li>
<li>
<span class="code">Current thread group</span> - each file is opened once for each thread group in which the element appears</li>
<li>
<span class="code">Current thread</span> - each file is opened separately for each thread</li>
<li>
<span class="code">Identifier</span> - all threads sharing the same identifier share the same file.
So for example if you have 4 thread groups, you could use a common id for two or more of the groups
to share the file between them.
Or you could use the thread number to share the file between the same thread numbers in different thread groups.
</li>
</ul>
</div>
<div class="required req-true">Yes</div>
</div>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="FTP_Request_Defaults">FTP Request Defaults<a class="sectionlink" href="#FTP_Request_Defaults" title="Link to here">&para;</a>
</h2>
<div class="description"></div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/ftp-config/ftp-request-defaults.png"><img src="../images/screenshots/ftp-config/ftp-request-defaults.png" width="520" height="202" alt="Screenshot for Control-Panel of FTP Request Defaults"></a>
<figcaption>Screenshot of Control-Panel of FTP Request Defaults</figcaption>
</figure>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="DNS_Cache_Manager">DNS Cache Manager<a class="sectionlink" href="#DNS_Cache_Manager" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>The DNS Cache Manager element allows to test applications, which have several servers behind load balancers (CDN, etc.),
when user receives content from different IP's. By default JMeter uses JVM DNS cache. That's why
only one server from the cluster receives load. DNS Cache Manager resolves names for each thread separately each iteration and
saves results of resolving to its internal DNS Cache, which is independent from both JVM and OS DNS caches.
</p>
<p>
A mapping for static hosts can be used to simulate something like <span class="code">/etc/hosts</span> file.
These entries will be preferred over the custom resolver. <span class="code">Use custom DNS resolver</span> has to be enabled,
if you want to use this mapping.
</p>
<div class="example">
<div class="title">Usage of static host table<a class="sectionlink" href="#static_host_table" title="Link to here">&para;</a>
</div>
<p>Say, you have a test server, that you want to reach with a name, that is not (yet) set up in your DNS servers.
For our example, this would be <span class="code">www.example.com</span> for the server name, which you want to reach at the
IP of the server <span class="code">a123.another.example.org</span>.
</p>
<p>You could change your workstation and add an entry to your <span class="code">/etc/hosts</span> file - or the equivalent for
your OS, or add an entry to the Static Host Table of the DNS Cache Manager.
</p>
<p>You would type <span class="code">www.example.com</span> into the first column (<span class="code">Host</span>) and
<span class="code">a123.another.example.org</span> into the second column (<span class="code">Hostname or IP address</span>).
As the name of the second column implies, you could even use the IP address of your test server there.
</p>
<p>The IP address for the test server will be looked up by using the custom DNS resolver. When none is given, the
system DNS resolver will be used.
</p>
<p>Now you can use <span class="code">www.example.com</span> in your HTTPClient4 samplers and the requests will be made against
<span class="code">a123.another.example.org</span> with all headers set to <span class="code">www.example.com</span>.
</p>
</div>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/dns-cache-manager.png"><img src="../images/screenshots/dns-cache-manager.png" width="712" height="387" alt="Screenshot for Control-Panel of DNS Cache Manager"></a>
<figcaption>Screenshot of Control-Panel of DNS Cache Manager</figcaption>
</figure>
</div>
<div class="clear"></div>
<div class="note">DNS Cache Manager is designed for using in the root of Thread Group or Test Plan. Do not place it as child element of particular HTTP Sampler
</div>
<div class="clear"></div>
<div class="clear"></div>
<div class="note">DNS Cache Manager works only with HTTP requests using HTTPClient4 implementation.</div>
<div class="clear"></div>
<div class="properties">
<h3 id="DNS_Cache_Manager_parms1">
Parameters
<a class="sectionlink" href="#DNS_Cache_Manager_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-false">Descriptive name for this element that is shown in the tree. </div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Clear cache each Iteration</div>
<div class="description req-false">If selected, DNS cache of every Thread is cleared each time new iteration is started.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Use system DNS resolver</div>
<div class="description req-false">System DNS resolver will be used. For correct work edit
<span class="code">$JAVA_HOME/jre/lib/security/java.security</span> and add <span class="code">networkaddress.cache.ttl=0</span>
</div>
<div class="required req-false">N/A</div>
</div>
<div class="property">
<div class="name req-false">Use custom DNS resolver</div>
<div class="description req-false">Custom DNS resolver (from dnsjava library) will be used.</div>
<div class="required req-false">N/A</div>
</div>
<div class="property">
<div class="name req-false">Hostname or IP address</div>
<div class="description req-false">List of DNS servers to use. If empty, network configuration DNS will used.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Add Button</div>
<div class="description req-false">Add an entry to the DNS servers table.</div>
<div class="required req-false">N/A</div>
</div>
<div class="property">
<div class="name req-false">Delete Button</div>
<div class="description req-false">Delete the currently selected table entry.</div>
<div class="required req-false">N/A</div>
</div>
<div class="property">
<div class="name req-false">Host and Hostname or IP address</div>
<div class="description req-false">Mapping of hostnames to a static host entry which will be resolved using the custom DNS resolver.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Add static host Button</div>
<div class="description req-false">Add an entry to the static hosts table.</div>
<div class="required req-false">N/A</div>
</div>
<div class="property">
<div class="name req-false">Delete static host Button</div>
<div class="description req-false">Delete the currently selected static host in the table.</div>
<div class="required req-false">N/A</div>
</div>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="HTTP_Authorization_Manager">HTTP Authorization Manager<a class="sectionlink" href="#HTTP_Authorization_Manager" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>The Authorization Manager lets you specify one or more user logins for web pages that are
restricted using server authentication. You see this type of authentication when you use
your browser to access a restricted page, and your browser displays a login dialog box. JMeter
transmits the login information when it encounters this type of page.</p>
<p>
The Authorization headers may not be shown in the Tree View Listener "<span class="code">Request</span>" tab.
The Java implementation does pre-emptive authentication, but it does not
return the Authorization header when JMeter fetches the headers.
The HttpComponents (HC 4.5.X) implementation defaults to pre-emptive since 3.2 and the header will be shown.
To disable this, set the values as below, in which case authentication will only be performed in response to a challenge.
</p>
<p>
In the file <span class="code">jmeter.properties</span> set <span class="code">httpclient4.auth.preemptive=false</span>
</p>
<div class="clear"></div>
<div class="note">
Note: the above settings only apply to the HttpClient sampler.
</div>
<div class="clear"></div>
<div class="clear"></div>
<div class="note">
When looking for a match against a URL, JMeter checks each entry in turn, and stops when it finds the first match.
Thus the most specific URLs should appear first in the list, followed by less specific ones.
Duplicate URLs will be ignored.
If you want to use different usernames/passwords for different threads, you can use variables.
These can be set up using a <a href="../usermanual/component_reference.html#CSV_Data_Set_Config">CSV Data Set Config</a> Element (for example).
</div>
<div class="clear"></div>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/http-config/http-auth-manager.png"><img src="../images/screenshots/http-config/http-auth-manager.png" width="538" height="340" alt="Screenshot for Control-Panel of HTTP Authorization Manager"></a>
<figcaption>Screenshot of Control-Panel of HTTP Authorization Manager</figcaption>
</figure>
</div>
<div class="clear"></div>
<div class="note">If there is more than one Authorization Manager in the scope of a Sampler,
there is currently no way to specify which one is to be used.</div>
<div class="clear"></div>
<div class="properties">
<h3 id="HTTP_Authorization_Manager_parms1">
Parameters
<a class="sectionlink" href="#HTTP_Authorization_Manager_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-false">Descriptive name for this element that is shown in the tree. </div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Clear auth on each iteration?</div>
<div class="description req-true">Used by Kerberos authentication. If checked, authentication will be done on each iteration of Main Thread Group loop even if it has already been done in a previous one.
This is usually useful if each main thread group iteration represents behaviour of one Virtual User.
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Base URL</div>
<div class="description req-true">A partial or complete URL that matches one or more HTTP Request URLs. As an example,
say you specify a Base URL of "<span class="code">http://localhost/restricted/</span>" with a <span class="code">Username</span> of "<span class="code">jmeter</span>" and
a <span class="code">Password</span> of "<span class="code">jmeter</span>". If you send an HTTP request to the URL
"<span class="code">http://localhost/restricted/ant/myPage.html</span>", the Authorization Manager sends the login
information for the user named, "<span class="code">jmeter</span>".</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Username</div>
<div class="description req-true">The username to authorize.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Password</div>
<div class="description req-true">The password for the user. (N.B. this is stored unencrypted in the test plan)</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Domain</div>
<div class="description req-false">The domain to use for NTLM.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Realm</div>
<div class="description req-false">The realm to use for NTLM.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Mechanism</div>
<div class="description req-false">Type of authentication to perform. JMeter can perform different types of authentications based on used Http Samplers:
<dl>
<dt>Java</dt>
<dd>
<span class="code">BASIC</span>
</dd>
<dt>HttpClient 4</dt>
<dd>
<span class="code">BASIC</span>, <span class="code">DIGEST</span> and <span class="code">Kerberos</span>
</dd>
</dl>
</div>
<div class="required req-false">No</div>
</div>
</div>
<div class="clear"></div>
<div class="note">
The Realm only applies to the HttpClient sampler.
</div>
<div class="clear"></div>
<br>
<b>Kerberos Configuration:</b>
<p>To configure Kerberos you need to setup at least two JVM system properties:</p>
<ul>
<li>
<span class="code">-Djava.security.krb5.conf=krb5.conf</span>
</li>
<li>
<span class="code">-Djava.security.auth.login.config=jaas.conf</span>
</li>
</ul>
<p>
You can also configure those two properties in the file <span class="code">bin/system.properties</span>.
Look at the two sample configuration files (<span class="code">krb5.conf</span> and <span class="code">jaas.conf</span>) located in the JMeter <span class="code">bin</span> folder
for references to more documentation, and tweak them to match your Kerberos configuration.
</p>
<p>
Delegation of credentials is disabled by default for SPNEGO. If you want to enable it, you can do so by setting the property <span class="code">kerberos.spnego.delegate_cred</span> to <span class="code">true</span>.
</p>
<p>
When generating a SPN for Kerberos SPNEGO authentication IE and Firefox will omit the port number
from the URL. Chrome has an option (<span class="code">--enable-auth-negotiate-port</span>) to include the port
number if it differs from the standard ones (<span class="code">80</span> and <span class="code">443</span>). That behavior
can be emulated by setting the following JMeter property as below.
</p>
<p>
In <span class="code">jmeter.properties</span> or <span class="code">user.properties</span>, set:
</p>
<ul>
<li>
<span class="code">kerberos.spnego.strip_port=false</span>
</li>
</ul>
<br>
<b>Controls:</b>
<ul>
<li>
<span class="code">Add</span> Button - Add an entry to the authorization table.</li>
<li>
<span class="code">Delete</span> Button - Delete the currently selected table entry.</li>
<li>
<span class="code">Load</span> Button - Load a previously saved authorization table and add the entries to the existing
authorization table entries.</li>
<li>
<span class="code">Save As</span> Button - Save the current authorization table to a file.</li>
</ul>
<div class="clear"></div>
<div class="note">When you save the Test Plan, JMeter automatically saves all of the authorization
table entries - including any passwords, which are not encrypted.</div>
<div class="clear"></div>
<div class="example">
<div class="title">Authorization Example<a class="sectionlink" href="#authorization_example" title="Link to here">&para;</a>
</div>
<p>
<a href="../demos/AuthManagerTestPlan.jmx">Download</a> this example. In this example, we created a Test Plan on a local server that sends three HTTP requests, two requiring a login and the
other is open to everyone. See figure 10 to see the makeup of our Test Plan. On our server, we have a restricted
directory named, "<span class="code">secret</span>", which contains two files, "<span class="code">index.html</span>" and "<span class="code">index2.html</span>". We created a login id named, "<span class="code">kevin</span>",
which has a password of "<span class="code">spot</span>". So, in our Authorization Manager, we created an entry for the restricted directory and
a username and password (see figure 11). The two HTTP requests named "<span class="code">SecretPage1</span>" and "<span class="code">SecretPage2</span>" make requests
to "<span class="code">/secret/index.html</span>" and "<span class="code">/secret/index2.html</span>". The other HTTP request, named "<span class="code">NoSecretPage</span>" makes a request to
"<span class="code">/index.html</span>".</p>
<figure>
<a href="../images/screenshots/http-config/auth-manager-example1a.png"><img src="../images/screenshots/http-config/auth-manager-example1a.png" width="452" height="177" alt="Figure 10 - Test Plan"></a>
<figcaption>Figure 10 - Test Plan</figcaption>
</figure>
<figure>
<a href="../images/screenshots/http-config/auth-manager-example1b.png"><img src="../images/screenshots/http-config/auth-manager-example1b.png" width="641" height="329" alt="Figure 11 - Authorization Manager Control Panel"></a>
<figcaption>Figure 11 - Authorization Manager Control Panel</figcaption>
</figure>
<p>When we run the Test Plan, JMeter looks in the Authorization table for the URL it is requesting. If the Base URL matches
the URL, then JMeter passes this information along with the request.</p>
<div class="clear"></div>
<div class="note">You can download the Test Plan, but since it is built as a test for our local server, you will not
be able to run it. However, you can use it as a reference in constructing your own Test Plan.</div>
<div class="clear"></div>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="HTTP_Cache_Manager">HTTP Cache Manager<a class="sectionlink" href="#HTTP_Cache_Manager" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>
The HTTP Cache Manager is used to add caching functionality to HTTP requests within its scope to simulate browser cache feature.
Each Virtual User thread has its own Cache. By default, Cache Manager will store up to 5000 items in cache per Virtual User thread, using LRU algorithm.
Use property "<span class="code">maxSize</span>" to modify this value. Note that the more you increase this value the more HTTP Cache Manager will consume memory, so be sure to adapt the <span class="code">-Xmx</span> JVM option accordingly.
</p>
<p>
If a sample is successful (i.e. has response code <span class="code">2xx</span>) then the <span class="code">Last-Modified</span> and <span class="code">Etag</span> (and <span class="code">Expired</span> if relevant) values are saved for the URL.
Before executing the next sample, the sampler checks to see if there is an entry in the cache,
and if so, the <span class="code">If-Last-Modified</span> and <span class="code">If-None-Match</span> conditional headers are set for the request.
</p>
<p>
Additionally, if the "<span class="code">Use Cache-Control/Expires header</span>" option is selected, then the <span class="code">Cache-Control</span>/<span class="code">Expires</span> value is checked against the current time.
If the request is a <span class="code">GET</span> request, and the timestamp is in the future, then the sampler returns immediately,
without requesting the URL from the remote server. This is intended to emulate browser behaviour.
Note that if <span class="code">Cache-Control</span> header is "<span class="code">no-cache</span>", the response will be stored in cache as pre-expired,
so will generate a conditional <span class="code">GET</span> request.
If <span class="code">Cache-Control</span> has any other value,
the "<span class="code">max-age</span>" expiry option is processed to compute entry lifetime, if missing then expire header will be used, if also missing entry will be cached
as specified in <a href="https://tools.ietf.org/html/2616#section-13.2.4">RFC 2616 section 13.2.4</a> using <span class="code">Last-Modified</span> time and response Date.
</p>
<div class="clear"></div>
<div class="note">
If the requested document has not changed since it was cached, then the response body will be empty.
Likewise if the <span class="code">Expires</span> date is in the future.
This may cause problems for Assertions.
</div>
<div class="clear"></div>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/http-config/http-cache-manager.png"><img src="../images/screenshots/http-config/http-cache-manager.png" width="511" height="196" alt="Screenshot for Control-Panel of HTTP Cache Manager"></a>
<figcaption>Screenshot of Control-Panel of HTTP Cache Manager</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="HTTP_Cache_Manager_parms1">
Parameters
<a class="sectionlink" href="#HTTP_Cache_Manager_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-false">Descriptive name for this element that is shown in the tree. </div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Clear cache each iteration</div>
<div class="description req-true">
If selected, then the cache is cleared at the start of the thread.
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Use Cache Control/Expires header when processing GET requests</div>
<div class="description req-true">See description above.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Max Number of elements in cache</div>
<div class="description req-true">See description above.</div>
<div class="required req-true">Yes</div>
</div>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="HTTP_Cookie_Manager">HTTP Cookie Manager<a class="sectionlink" href="#HTTP_Cookie_Manager" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>The Cookie Manager element has two functions:<br>
First, it stores and sends cookies just like a web browser. If you have an HTTP Request and
the response contains a cookie, the Cookie Manager automatically stores that cookie and will
use it for all future requests to that particular web site. Each JMeter thread has its own
"cookie storage area". So, if you are testing a web site that uses a cookie for storing
session information, each JMeter thread will have its own session.
Note that such cookies do not appear on the Cookie Manager display, but they can be seen using
the <a href="../usermanual/component_reference.html#View_Results_Tree">View Results Tree</a> Listener.
</p>
<p>
JMeter checks that received cookies are valid for the URL.
This means that cross-domain cookies are not stored.
If you have bugged behaviour or want Cross-Domain cookies to be used, define the JMeter property "<span class="code">CookieManager.check.cookies=false</span>".
</p>
<p>
Received Cookies can be stored as JMeter thread variables.
To save cookies as variables, define the property "<span class="code">CookieManager.save.cookies=true</span>".
Also, cookies names are prefixed with "<span class="code">COOKIE_</span>" before they are stored (this avoids accidental corruption of local variables)
To revert to the original behaviour, define the property "<span class="code">CookieManager.name.prefix= </span>" (one or more spaces).
If enabled, the value of a cookie with the name <span class="code">TEST</span> can be referred to as <span class="code">${COOKIE_TEST}</span>.
</p>
<p>Second, you can manually add a cookie to the Cookie Manager. However, if you do this,
the cookie will be shared by all JMeter threads.</p>
<p>Note that such Cookies are created with an Expiration time far in the future</p>
<p>
Cookies with <span class="code">null</span> values are ignored by default.
This can be changed by setting the JMeter property: <span class="code">CookieManager.delete_null_cookies=false</span>.
Note that this also applies to manually defined cookies - any such cookies will be removed from the display when it is updated.
Note also that the cookie name must be unique - if a second cookie is defined with the same name, it will replace the first.
</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/http-config/http-cookie-manager.png"><img src="../images/screenshots/http-config/http-cookie-manager.png" width="653" height="373" alt="Screenshot for Control-Panel of HTTP Cookie Manager"></a>
<figcaption>Screenshot of Control-Panel of HTTP Cookie Manager</figcaption>
</figure>
</div>
<div class="clear"></div>
<div class="note">If there is more than one Cookie Manager in the scope of a Sampler,
there is currently no way to specify which one is to be used.
Also, a cookie stored in one cookie manager is not available to any other manager,
so use multiple Cookie Managers with care.</div>
<div class="clear"></div>
<div class="properties">
<h3 id="HTTP_Cookie_Manager_parms1">
Parameters
<a class="sectionlink" href="#HTTP_Cookie_Manager_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-false">Descriptive name for this element that is shown in the tree. </div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Clear Cookies each Iteration</div>
<div class="description req-true">If selected, all server-defined cookies are cleared each time the main Thread Group loop is executed.
Any cookie defined in the GUI are not cleared.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Cookie Policy</div>
<div class="description req-true">The cookie policy that will be used to manage the cookies.
"<span class="code">standard</span>" is the default since 3.0, and should work in most cases.
See <a href="https://hc.apache.org/httpcomponents-client-ga/tutorial/html/statemgmt.html#d5e515">Cookie specifications</a> and
<a href="http://hc.apache.org/httpcomponents-client-ga/httpclient/apidocs/org/apache/http/cookie/CookieSpec.html">CookieSpec implementations</a>
[Note: "<span class="code">ignoreCookies</span>" is equivalent to omitting the CookieManager.]
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Implementation</div>
<div class="description req-true">
<span class="code">HC4CookieHandler</span> (HttpClient 4.5.X API).
Default is <span class="code">HC4CookieHandler</span> since 3.0.
<br>
<i>[Note: If you have a website to test with IPv6 address, choose <span class="code">HC4CookieHandler</span> (IPv6 compliant)]</i>
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">User-Defined Cookies</div>
<div class="description req-false">This
gives you the opportunity to use hardcoded cookies that will be used by all threads during the test execution.
<br>
The "<span class="code">domain</span>" is the hostname of the server (without <span class="code">http://</span>); the port is currently ignored.
</div>
<div class="required req-false">No (discouraged, unless you know what you're doing)</div>
</div>
<div class="property">
<div class="name req-false">Add Button</div>
<div class="description req-false">Add an entry to the cookie table.</div>
<div class="required req-false">N/A</div>
</div>
<div class="property">
<div class="name req-false">Delete Button</div>
<div class="description req-false">Delete the currently selected table entry.</div>
<div class="required req-false">N/A</div>
</div>
<div class="property">
<div class="name req-false">Load Button</div>
<div class="description req-false">Load a previously saved cookie table and add the entries to the existing
cookie table entries.</div>
<div class="required req-false">N/A</div>
</div>
<div class="property">
<div class="name req-false">Save As Button</div>
<div class="description req-false">
Save the current cookie table to a file (does not save any cookies extracted from HTTP Responses).
</div>
<div class="required req-false">N/A</div>
</div>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="HTTP_Request_Defaults">HTTP Request Defaults<a class="sectionlink" href="#HTTP_Request_Defaults" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>This element lets you set default values that your HTTP Request controllers use. For example, if you are
creating a Test Plan with 25 HTTP Request controllers and all of the requests are being sent to the same server,
you could add a single HTTP Request Defaults element with the "<span class="code">Server Name or IP</span>" field filled in. Then, when
you add the 25 HTTP Request controllers, leave the "<span class="code">Server Name or IP</span>" field empty. The controllers will inherit
this field value from the HTTP Request Defaults element.</p>
<div class="clear"></div>
<div class="note">
All port values are treated equally; a sampler that does not specify a port will use the HTTP Request Defaults port, if one is provided.
</div>
<div class="clear"></div>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/http-config/http-request-defaults.png"><img src="../images/screenshots/http-config/http-request-defaults.png" width="879" height="469" alt="Screenshot for Control-Panel of HTTP Request Defaults"></a>
<figcaption>Screenshot of Control-Panel of HTTP Request Defaults</figcaption>
</figure>
</div>
<figure>
<a href="../images/screenshots/http-config/http-request-defaults-advanced-tab.png"><img src="../images/screenshots/http-config/http-request-defaults-advanced-tab.png" width="881" height="256" alt="HTTP Request Advanced config fields"></a>
<figcaption>HTTP Request Advanced config fields</figcaption>
</figure>
<div class="properties">
<h3 id="HTTP_Request_Defaults_parms1">
Parameters
<a class="sectionlink" href="#HTTP_Request_Defaults_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-false">Descriptive name for this element that is shown in the tree.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Server</div>
<div class="description req-false">Domain name or IP address of the web server. E.g. <span class="code">www.example.com</span>. [Do not include the <span class="code">http://</span> prefix.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Port</div>
<div class="description req-false">Port the web server is listening to.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Connect Timeout</div>
<div class="description req-false">Connection Timeout. Number of milliseconds to wait for a connection to open.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Response Timeout</div>
<div class="description req-false">Response Timeout. Number of milliseconds to wait for a response.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Implementation</div>
<div class="description req-false">
<span class="code">Java</span>, <span class="code">HttpClient4</span>.
If not specified the default depends on the value of the JMeter property
<span class="code">jmeter.httpsampler</span>, failing that, the <span class="code">Java</span> implementation is used.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Protocol</div>
<div class="description req-false">
<span class="code">HTTP</span> or <span class="code">HTTPS</span>.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Content encoding</div>
<div class="description req-false">The encoding to be used for the request.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Path</div>
<div class="description req-false">The path to resource (for example, <span class="code">/servlets/myServlet</span>). If the
resource requires query string parameters, add them below in the "<span class="code">Send Parameters With the Request</span>" section.
Note that the path is the default for the full path, not a prefix to be applied to paths
specified on the HTTP Request screens.
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Send Parameters With the Request</div>
<div class="description req-false">The query string will
be generated from the list of parameters you provide. Each parameter has a <i>name</i> and
<i>value</i>. The query string will be generated in the correct fashion, depending on
the choice of "<span class="code">Method</span>" you made (i.e. if you chose <span class="code">GET</span>, the query string will be
appended to the URL, if <span class="code">POST</span>, then it will be sent separately). Also, if you are
sending a file using a multipart form, the query string will be created using the
multipart form specifications.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Server (proxy)</div>
<div class="description req-false">Hostname or IP address of a proxy server to perform request. [Do not include the <span class="code">http://</span> prefix.]</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Port</div>
<div class="description req-false">Port the proxy server is listening to.</div>
<div class="required req-false">No, unless proxy hostname is specified</div>
</div>
<div class="property">
<div class="name req-false">Username</div>
<div class="description req-false">(Optional) username for proxy server.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Password</div>
<div class="description req-false">(Optional) password for proxy server. (N.B. this is stored unencrypted in the test plan)</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Retrieve All Embedded Resources from HTML Files</div>
<div class="description req-false">Tell JMeter to parse the HTML file
and send HTTP/HTTPS requests for all images, Java applets, JavaScript files, CSSs, etc. referenced in the file.
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Use concurrent pool</div>
<div class="description req-false">Use a pool of concurrent connections to get embedded resources.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Size</div>
<div class="description req-false">Pool size for concurrent connections used to get embedded resources.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Embedded URLs must match:</div>
<div class="description req-false">
If present, this must be a regular expression that is used to match against any embedded URLs found.
So if you only want to download embedded resources from <span class="code">http://example.com/</span>, use the expression:
<span class="code">http://example\.com/.*</span>
</div>
<div class="required req-false">No</div>
</div>
</div>
<div class="clear"></div>
<div class="note">
Note: radio buttons only have two states - on or off.
This makes it impossible to override settings consistently
- does off mean off, or does it mean use the current default?
JMeter uses the latter (otherwise defaults would not work at all).
So if the button is off, then a later element can set it on,
but if the button is on, a later element cannot set it off.
</div>
<div class="clear"></div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="HTTP_Header_Manager">HTTP Header Manager<a class="sectionlink" href="#HTTP_Header_Manager" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>The Header Manager lets you add or override HTTP request headers.</p>
<p>
<b>JMeter now supports multiple Header Managers</b>. The header entries are merged to form the list for the sampler.
If an entry to be merged matches an existing header name, it replaces the previous entry.
This allows one to set up a default set of headers, and apply adjustments to particular samplers.
Note that an empty value for a header does not remove an existing header, it justs replace its value.
</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/http-config/http-header-manager.png"><img src="../images/screenshots/http-config/http-header-manager.png" width="767" height="239" alt="Screenshot for Control-Panel of HTTP Header Manager"></a>
<figcaption>Screenshot of Control-Panel of HTTP Header Manager</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="HTTP_Header_Manager_parms1">
Parameters
<a class="sectionlink" href="#HTTP_Header_Manager_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-false">Descriptive name for this element that is shown in the tree. </div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Name (Header)</div>
<div class="description req-false">Name of the request header.
Two common request headers you may want to experiment with
are "<span class="code">User-Agent</span>" and "<span class="code">Referer</span>".</div>
<div class="required req-false">No (You should have at least one, however)</div>
</div>
<div class="property">
<div class="name req-false">Value</div>
<div class="description req-false">Request header value.</div>
<div class="required req-false">No (You should have at least one, however)</div>
</div>
<div class="property">
<div class="name req-false">Add Button</div>
<div class="description req-false">Add an entry to the header table.</div>
<div class="required req-false">N/A</div>
</div>
<div class="property">
<div class="name req-false">Delete Button</div>
<div class="description req-false">Delete the currently selected table entry.</div>
<div class="required req-false">N/A</div>
</div>
<div class="property">
<div class="name req-false">Load Button</div>
<div class="description req-false">Load a previously saved header table and add the entries to the existing
header table entries.</div>
<div class="required req-false">N/A</div>
</div>
<div class="property">
<div class="name req-false">Save As Button</div>
<div class="description req-false">Save the current header table to a file.</div>
<div class="required req-false">N/A</div>
</div>
</div>
<div class="example">
<div class="title">Header Manager example<a class="sectionlink" href="#header_manager_example" title="Link to here">&para;</a>
</div>
<p>
<a href="../demos/HeaderManagerTestPlan.jmx">Download</a> this example. In this example, we created a Test Plan
that tells JMeter to override the default "<span class="code">User-Agent</span>" request header and use a particular Internet Explorer agent string
instead. (see figures 12 and 13).</p>
<figure>
<a href="../images/screenshots/http-config/header-manager-example1a.png"><img src="../images/screenshots/http-config/header-manager-example1a.png" width="247" height="121" alt="Figure 12 - Test Plan"></a>
<figcaption>Figure 12 - Test Plan</figcaption>
</figure>
<figure>
<a href="../images/screenshots/http-config/header-manager-example1b.png"><img src="../images/screenshots/http-config/header-manager-example1b.png" width="" height="" alt="Figure 13 - Header Manager Control Panel"></a>
<figcaption>Figure 13 - Header Manager Control Panel</figcaption>
</figure>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="Java_Request_Defaults">Java Request Defaults<a class="sectionlink" href="#Java_Request_Defaults" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>The Java Request Defaults component lets you set default values for Java testing. See the <a href="../usermanual/component_reference.html#Java_Request">Java Request</a>.</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/java_defaults.png"><img src="../images/screenshots/java_defaults.png" width="685" height="373" alt="Screenshot for Control-Panel of Java Request Defaults"></a>
<figcaption>Screenshot of Control-Panel of Java Request Defaults</figcaption>
</figure>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="JDBC_Connection_Configuration">JDBC Connection Configuration<a class="sectionlink" href="#JDBC_Connection_Configuration" title="Link to here">&para;</a>
</h2>
<div class="description">Creates a database connection (used by <a href="../usermanual/component_reference.html#JDBC_Request">JDBC Request</a>Sampler)
from the supplied JDBC Connection settings. The connection may be optionally pooled between threads.
Otherwise each thread gets its own connection.
The connection configuration name is used by the JDBC Sampler to select the appropriate
connection.
The used pool is DBCP, see <a href="https://commons.apache.org/proper/commons-dbcp/configuration.html">BasicDataSource Configuration Parameters</a>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/jdbc-config/jdbc-conn-config.png"><img src="../images/screenshots/jdbc-config/jdbc-conn-config.png" width="1055" height="738" alt="Screenshot for Control-Panel of JDBC Connection Configuration"></a>
<figcaption>Screenshot of Control-Panel of JDBC Connection Configuration</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="JDBC_Connection_Configuration_parms1">
Parameters
<a class="sectionlink" href="#JDBC_Connection_Configuration_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-false">Descriptive name for the connection configuration that is shown in the tree.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Variable Name for created pool</div>
<div class="description req-true">The name of the variable the connection is tied to.
Multiple connections can be used, each tied to a different variable, allowing JDBC Samplers
to select the appropriate connection.
<div class="clear"></div>
<div class="note">Each name must be different. If there are two configuration elements using the same name,
only one will be saved. JMeter logs a message if a duplicate name is detected.</div>
<div class="clear"></div>
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Max Number of Connections</div>
<div class="description req-true">
Maximum number of connections allowed in the pool.
In most cases, <b>set this to zero (0)</b>.
This means that each thread will get its own pool with a single connection in it, i.e.
the connections are not shared between threads.
<br>
If you really want to use shared pooling (why?), then set the max count to the same as the number of threads
to ensure threads don't wait on each other.
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Max Wait (ms)</div>
<div class="description req-true">Pool throws an error if the timeout period is exceeded in the
process of trying to retrieve a connection, see <a href="https://commons.apache.org/proper/commons-dbcp/api-2.1.1/org/apache/commons/dbcp2/BasicDataSource.html#getMaxWaitMillis--">BasicDataSource.html#getMaxWaitMillis</a>
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Time Between Eviction Runs (ms)</div>
<div class="description req-true">The number of milliseconds to sleep between runs of the idle object evictor thread. When non-positive, no idle object evictor thread will be run. (Defaults to "<span class="code">60000</span>", 1 minute).
See <a href="https://commons.apache.org/proper/commons-dbcp/api-2.1.1/org/apache/commons/dbcp2/BasicDataSource.html#getTimeBetweenEvictionRunsMillis--">BasicDataSource.html#getTimeBetweenEvictionRunsMillis</a>
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Auto Commit</div>
<div class="description req-true">Turn auto commit on or off for the connections.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Transaction isolation</div>
<div class="description req-true">Transaction isolation level</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Preinit Pool</div>
<div class="description req-false">The connection pool can be initialized instantly. If set to <span class="code">False</span> (default), the JDBC request samplers using this pool might measure higher response times for the first queries &ndash; as the connection establishment time for the whole pool is included.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Init SQL statements separated by new line</div>
<div class="description req-false">A Collection of SQL statements that will be used to initialize physical connections when they are first created. These statements are executed only once - when the configured connection factory creates the connection. </div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Test While Idle</div>
<div class="description req-true">Test idle connections of the pool, see <a href="https://commons.apache.org/proper/commons-dbcp/api-2.1.1/org/apache/commons/dbcp2/BasicDataSource.html#getTestWhileIdle--">BasicDataSource.html#getTestWhileIdle</a>.
Validation Query will be used to test it.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Soft Min Evictable Idle Time(ms)</div>
<div class="description req-true">Minimum amount of time a connection may sit idle in the pool before it is eligible for eviction by the idle object evictor, with the extra condition that at least <span class="code">minIdle</span> connections remain in the pool.
See <a href="https://commons.apache.org/proper/commons-dbcp/api-2.1.1/org/apache/commons/dbcp2/BasicDataSource.html#getSoftMinEvictableIdleTimeMillis--">BasicDataSource.html#getSoftMinEvictableIdleTimeMillis</a>.
Defaults to 5000 (5 seconds)
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Validation Query</div>
<div class="description req-false">A simple query used to determine if the database is still responding.
This defaults to the '<span class="code">isValid()</span>' method of the jdbc driver, which is suitable for many databases.
However some may require a different query; for example Oracle something like '<span class="code">SELECT 1 FROM DUAL</span>' could be used.
<p>The list of the validation queries can be configured with <span class="code">jdbc.config.check.query</span> property and are by default:</p>
<dl>
<dt>hsqldb</dt>
<dd>
<span class="code">select 1 from INFORMATION_SCHEMA.SYSTEM_USERS</span>
</dd>
<dt>Oracle</dt>
<dd>
<span class="code">select 1 from dual</span>
</dd>
<dt>DB2</dt>
<dd>
<span class="code">select 1 from sysibm.sysdummy1</span>
</dd>
<dt>MySQL or MariaDB</dt>
<dd>
<span class="code">select 1</span>
</dd>
<dt>Microsoft SQL Server (MS JDBC driver)</dt>
<dd>
<span class="code">select 1</span>
</dd>
<dt>PostgreSQL</dt>
<dd>
<span class="code">select 1</span>
</dd>
<dt>Ingres</dt>
<dd>
<span class="code">select 1</span>
</dd>
<dt>Derby</dt>
<dd>
<span class="code">values 1</span>
</dd>
<dt>H2</dt>
<dd>
<span class="code">select 1</span>
</dd>
<dt>Firebird</dt>
<dd>
<span class="code">select 1 from rdb$database</span>
</dd>
<dt>Exasol</dt>
<dd>
<span class="code">select 1</span>
</dd>
</dl>
<div class="clear"></div>
<div class="note">The list come from <a href="https://stackoverflow.com/questions/10684244/dbcp-validationquery-for-different-databases">stackoverflow entry on different database validation queries</a> and it can be incorrect</div>
<div class="clear"></div>
<div class="clear"></div>
<div class="note">Note this validation query is used on pool creation to validate it even if "<span class="code">Test While Idle</span>" suggests query would only be used on idle connections.
This is DBCP behaviour.</div>
<div class="clear"></div>
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Database URL</div>
<div class="description req-true">JDBC Connection string for the database.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">JDBC Driver class</div>
<div class="description req-true">Fully qualified name of driver class. (Must be in
JMeter's classpath - easiest to copy <span class="code">.jar</span> file into JMeter's <span class="code">/lib</span> directory).
<p>The list of the preconfigured jdbc driver classes can be configured with <span class="code">jdbc.config.jdbc.driver.class</span> property and are by default:</p>
<dl>
<dt>hsqldb</dt>
<dd>org.hsqldb.jdbc.JDBCDriver</dd>
<dt>Oracle</dt>
<dd>oracle.jdbc.OracleDriver</dd>
<dt>DB2</dt>
<dd>com.ibm.db2.jcc.DB2Driver</dd>
<dt>MySQL</dt>
<dd>com.mysql.jdbc.Driver</dd>
<dt>Microsoft SQL Server (MS JDBC driver)</dt>
<dd>com.microsoft.sqlserver.jdbc.SQLServerDriver or com.microsoft.jdbc.sqlserver.SQLServerDriver</dd>
<dt>PostgreSQL</dt>
<dd>org.postgresql.Driver</dd>
<dt>Ingres</dt>
<dd>com.ingres.jdbc.IngresDriver</dd>
<dt>Derby</dt>
<dd>org.apache.derby.jdbc.ClientDriver</dd>
<dt>H2</dt>
<dd>org.h2.Driver</dd>
<dt>Firebird</dt>
<dd>org.firebirdsql.jdbc.FBDriver</dd>
<dt>Apache Derby</dt>
<dd>org.apache.derby.jdbc.ClientDriver</dd>
<dt>MariaDB</dt>
<dd>org.mariadb.jdbc.Driver</dd>
<dt>SQLite</dt>
<dd>org.sqlite.JDBC</dd>
<dt>Sybase AES</dt>
<dd>net.sourceforge.jtds.jdbc.Driver</dd>
<dt>Exasol</dt>
<dd>com.exasol.jdbc.EXADriver</dd>
</dl>
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Username</div>
<div class="description req-false">Name of user to connect as.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Password</div>
<div class="description req-false">Password to connect with. (N.B. this is stored unencrypted in the test plan)</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Connection Properties</div>
<div class="description req-false">Connection Properties to set when establishing connection (like <span class="code">internal_logon=sysdba</span> for Oracle for example)</div>
<div class="required req-false">No</div>
</div>
</div>
<p>Different databases and JDBC drivers require different JDBC settings.
The Database URL and JDBC Driver class are defined by the provider of the JDBC implementation.</p>
<p>Some possible settings are shown below. Please check the exact details in the JDBC driver documentation.</p>
<p>
If JMeter reports <span class="code">No suitable driver</span>, then this could mean either:
</p>
<ul>
<li>The driver class was not found. In this case, there will be a log message such as <span class="code">DataSourceElement: Could not load driver: {classname} java.lang.ClassNotFoundException: {classname}</span>
</li>
<li>The driver class was found, but the class does not support the connection string. This could be because of a syntax error in the connection string, or because the wrong classname was used.</li>
</ul>
<p>
If the database server is not running or is not accessible, then JMeter will report a <span class="code">java.net.ConnectException</span>.
</p>
<p>Some examples for databases and their parameters are given below.</p>
<dl>
<dt>MySQL</dt>
<dd>
<dl>
<dt>Driver class</dt>
<dd>
<span class="code">com.mysql.jdbc.Driver</span>
</dd>
<dt>Database URL</dt>
<dd>
<span class="code">jdbc:mysql://host[:port]/dbname</span>
</dd>
</dl>
</dd>
<dt>PostgreSQL</dt>
<dd>
<dl>
<dt>Driver class</dt>
<dd>
<span class="code">org.postgresql.Driver</span>
</dd>
<dt>Database URL</dt>
<dd>
<span class="code">jdbc:postgresql:{dbname}</span>
</dd>
</dl>
</dd>
<dt>Oracle</dt>
<dd>
<dl>
<dt>Driver class</dt>
<dd>
<span class="code">oracle.jdbc.OracleDriver</span>
</dd>
<dt>Database URL</dt>
<dd>
<span class="code">jdbc:oracle:thin:@//host:port/service</span> OR <span class="code">jdbc:oracle:thin:@(description=(address=(host={mc-name})(protocol=tcp)(port={port-no}))(connect_data=(sid={sid})))</span>
</dd>
</dl>
</dd>
<dt>Ingress (2006)</dt>
<dd>
<dl>
<dt>Driver class</dt>
<dd>
<span class="code">ingres.jdbc.IngresDriver</span>
</dd>
<dt>Database URL</dt>
<dd>
<span class="code">jdbc:ingres://host:port/db[;attr=value]</span>
</dd>
</dl>
</dd>
<dt>Microsoft SQL Server (MS JDBC driver)</dt>
<dd>
<dl>
<dt>Driver class</dt>
<dd>
<span class="code">com.microsoft.sqlserver.jdbc.SQLServerDriver</span>
</dd>
<dt>Database URL</dt>
<dd>
<span class="code">jdbc:sqlserver://host:port;DatabaseName=dbname</span>
</dd>
</dl>
</dd>
<dt>Apache Derby</dt>
<dd>
<dl>
<dt>Driver class</dt>
<dd>
<span class="code">org.apache.derby.jdbc.ClientDriver</span>
</dd>
<dt>Database URL</dt>
<dd>
<span class="code">jdbc:derby://server[:port]/databaseName[;URLAttributes=value[;&hellip;]]</span>
</dd>
</dl>
</dd>
<dt>MariaDB</dt>
<dd>
<dl>
<dt>Driver class</dt>
<dd>
<span class="code">org.mariadb.jdbc.Driver</span>
</dd>
<dt>Database URL</dt>
<dd>
<span class="code">jdbc:mariadb://host[:port]/dbname[;URLAttributes=value[;&hellip;]]</span>
</dd>
</dl>
</dd>
<dt>Exasol (see also <a href="https://docs.exasol.com/connect_exasol/drivers/jdbc.htm">JDBC driver documentation</a>)</dt>
<dd>
<dl>
<dt>Driver class</dt>
<dd>
<span class="code">com.exasol.jdbc.EXADriver</span>
</dd>
<dt>Database URL</dt>
<dd>
<span class="code">jdbc:exa:host[:port][;schema=SCHEMA_NAME][;prop_x=value_x]</span>
</dd>
</dl>
</dd>
</dl>
<div class="clear"></div>
<div class="note">The above may not be correct - please check the relevant JDBC driver documentation.</div>
<div class="clear"></div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="Keystore_Configuration">Keystore Configuration<a class="sectionlink" href="#Keystore_Configuration" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>The Keystore Config Element lets you configure how Keystore will be loaded and which keys it will use.
This component is typically used in HTTPS scenarios where you don't want to take into account keystore initialization into account in response time.</p>
<p>To use this element, you need to setup first a Java Key Store with the client certificates you want to test, to do that:
</p>
<ol>
<li>Create your certificates either with Java <span class="code">keytool</span> utility or through your PKI</li>
<li>If created by PKI, import your keys in Java Key Store by converting them to a format acceptable by JKS</li>
<li>Then reference the keystore file through the two JVM properties (or add them in <span class="code">system.properties</span>):
<ul>
<li>
<span class="code">-Djavax.net.ssl.keyStore=path_to_keystore</span>
</li>
<li>
<span class="code">-Djavax.net.ssl.keyStorePassword=password_of_keystore</span>
</li>
</ul>
</li>
</ol>
<p>To use PKCS11 as the source for the store, you need to set <span class="code">javax.net.ssl.keyStoreType</span> to <span class="code">PKCS11</span>
and <span class="code">javax.net.ssl.keyStore</span> to <span class="code">NONE</span>.</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/keystore_config.png"><img src="../images/screenshots/keystore_config.png" width="441" height="189" alt="Screenshot for Control-Panel of Keystore Configuration"></a>
<figcaption>Screenshot of Control-Panel of Keystore Configuration</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="Keystore_Configuration_parms1">
Parameters
<a class="sectionlink" href="#Keystore_Configuration_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-false">Descriptive name for this element that is shown in the tree. </div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Preload</div>
<div class="description req-true">Whether or not to preload Keystore. Setting it to <span class="code">true</span> is usually the best option.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Variable name holding certificate alias</div>
<div class="description req-false">Variable name that will contain the alias to use for authentication by client certificate. Variable value will be filled from CSV Data Set for example. In the screenshot, "<span class="code">certificat_ssl</span>" will also be a variable in CSV Data Set. Defaults to <span class="code">clientCertAliasVarName</span>
</div>
<div class="required req-false">False</div>
</div>
<div class="property">
<div class="name req-true">Alias Start Index</div>
<div class="description req-true">The index of the first key to use in Keystore, 0-based.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Alias End Index</div>
<div class="description req-true">The index of the last key to use in Keystore, 0-based. When using "<span class="code">Variable name holding certificate alias</span>" ensure it is large enough so that all keys are loaded at startup. Default to -1 which means load all.</div>
<div class="required req-true">Yes</div>
</div>
</div>
<div class="clear"></div>
<div class="note">
To make JMeter use more than one certificate you need to ensure that:
<ul>
<li>
<span class="code">https.use.cached.ssl.context=false</span> is set in <span class="code">jmeter.properties</span> or <span class="code">user.properties</span>
</li>
<li>You use HTTPClient 4 implementation for HTTP Request</li>
</ul>
</div>
<div class="clear"></div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="Login_Config_Element">Login Config Element<a class="sectionlink" href="#Login_Config_Element" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>The Login Config Element lets you add or override username and password settings in samplers that use username and password as part of their setup.</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/login-config.png"><img src="../images/screenshots/login-config.png" width="459" height="126" alt="Screenshot for Control-Panel of Login Config Element"></a>
<figcaption>Screenshot of Control-Panel of Login Config Element</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="Login_Config_Element_parms1">
Parameters
<a class="sectionlink" href="#Login_Config_Element_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-false">Descriptive name for this element that is shown in the tree. </div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Username</div>
<div class="description req-false">The default username to use.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Password</div>
<div class="description req-false">The default password to use. (N.B. this is stored unencrypted in the test plan)</div>
<div class="required req-false">No</div>
</div>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="LDAP_Request_Defaults">LDAP Request Defaults<a class="sectionlink" href="#LDAP_Request_Defaults" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>The LDAP Request Defaults component lets you set default values for LDAP testing. See the <a href="../usermanual/component_reference.html#LDAP_Request">LDAP Request</a>.</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/ldap_defaults.png"><img src="../images/screenshots/ldap_defaults.png" width="689" height="232" alt="Screenshot for Control-Panel of LDAP Request Defaults"></a>
<figcaption>Screenshot of Control-Panel of LDAP Request Defaults</figcaption>
</figure>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="LDAP_Extended_Request_Defaults">LDAP Extended Request Defaults<a class="sectionlink" href="#LDAP_Extended_Request_Defaults" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>The LDAP Extended Request Defaults component lets you set default values for extended LDAP testing. See the <a href="../usermanual/component_reference.html#LDAP_Extended_Request">LDAP Extended Request</a>.</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/ldapext_defaults.png"><img src="../images/screenshots/ldapext_defaults.png" width="686" height="184" alt="Screenshot for Control-Panel of LDAP Extended Request Defaults"></a>
<figcaption>Screenshot of Control-Panel of LDAP Extended Request Defaults</figcaption>
</figure>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="TCP_Sampler_Config">TCP Sampler Config<a class="sectionlink" href="#TCP_Sampler_Config" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>
The TCP Sampler Config provides default data for the TCP Sampler
</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/tcpsamplerconfig.png"><img src="../images/screenshots/tcpsamplerconfig.png" width="826" height="450" alt="Screenshot for Control-Panel of TCP Sampler Config"></a>
<figcaption>Screenshot of Control-Panel of TCP Sampler Config</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="TCP_Sampler_Config_parms1">
Parameters
<a class="sectionlink" href="#TCP_Sampler_Config_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-true">Descriptive name for this element that is shown in the tree.</div>
<div class="required req-true"></div>
</div>
<div class="property">
<div class="name req-false">TCPClient classname</div>
<div class="description req-false">Name of the TCPClient class. Defaults to the property <span class="code">tcp.handler</span>, failing that <span class="code">TCPClientImpl</span>.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">ServerName or IP</div>
<div class="description req-true">Name or IP of TCP server</div>
<div class="required req-true"></div>
</div>
<div class="property">
<div class="name req-true">Port Number</div>
<div class="description req-true">Port to be used</div>
<div class="required req-true"></div>
</div>
<div class="property">
<div class="name req-true">Re-use connection</div>
<div class="description req-true">If selected, the connection is kept open. Otherwise it is closed when the data has been read.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Close connection</div>
<div class="description req-true">If selected, the connection will be closed after running the sampler.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">SO_LINGER</div>
<div class="description req-false">Enable/disable <span class="code">SO_LINGER</span> with the specified linger time in seconds when a socket is created. If you set "<span class="code">SO_LINGER</span>" value as <span class="code">0</span>, you may prevent large numbers of sockets sitting around with a <span class="code">TIME_WAIT</span> status.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">End of line(EOL) byte value</div>
<div class="description req-false">Byte value for end of line, set this to a value outside the range <span class="code">-128</span> to <span class="code">+127</span> to skip EOL checking. You may set this in <span class="code">jmeter.properties</span> file as well with the <span class="code">tcp.eolByte</span> property. If you set this in TCP Sampler Config and in <span class="code">jmeter.properties</span> file at the same time, the setting value in the TCP Sampler Config will be used.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Connect Timeout</div>
<div class="description req-false">Connect Timeout (milliseconds, 0 disables).</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Response Timeout</div>
<div class="description req-false">Response Timeout (milliseconds, 0 disables).</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Set Nodelay</div>
<div class="description req-true">Should the nodelay property be set?</div>
<div class="required req-true"></div>
</div>
<div class="property">
<div class="name req-true">Text to Send</div>
<div class="description req-true">Text to be sent</div>
<div class="required req-true"></div>
</div>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="User_Defined_Variables">User Defined Variables<a class="sectionlink" href="#User_Defined_Variables" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>The User Defined Variables element lets you define an <b>initial set of variables</b>, just as in the <a href="../usermanual/component_reference.html#Test_Plan">Test Plan</a>.
<div class="clear"></div>
<div class="note">
Note that all the UDV elements in a test plan - no matter where they are - are processed at the start.
</div>
<div class="clear"></div>
So you cannot reference variables which are defined as part of a test run, e.g. in a Post-Processor.
</p>
<p>
<b>
UDVs should not be used with functions that generate different results each time they are called.
Only the result of the first function call will be saved in the variable.
</b>
However, UDVs can be used with functions such as <span class="code"><a href="../usermanual/functions.html#__P">__P()</a></span>, for example:
</p>
<pre class="source">
HOST ${__P(host,localhost)}
</pre>
<p>
which would define the variable "<span class="code">HOST</span>" to have the value of the JMeter property "<span class="code">host</span>", defaulting to "<span class="code">localhost</span>" if not defined.
</p>
<p>
For defining variables during a test run, see <a href="../usermanual/component_reference.html#User_Parameters">User Parameters</a>.
UDVs are processed in the order they appear in the Plan, from top to bottom.
</p>
<p>
For simplicity, it is suggested that UDVs are placed only at the start of a Thread Group
(or perhaps under the Test Plan itself).
</p>
<p>
Once the Test Plan and all UDVs have been processed, the resulting set of variables is
copied to each thread to provide the initial set of variables.
</p>
<p>
If a runtime element such as a User Parameters Pre-Processor or Regular Expression Extractor defines a variable
with the same name as one of the UDV variables, then this will replace the initial value, and all other test
elements in the thread will see the updated value.
</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/user_defined_variables.png"><img src="../images/screenshots/user_defined_variables.png" width="741" height="266" alt="Screenshot for Control-Panel of User Defined Variables"></a>
<figcaption>Screenshot of Control-Panel of User Defined Variables</figcaption>
</figure>
</div>
<div class="clear"></div>
<div class="note">
If you have more than one Thread Group, make sure you use different names for different values, as UDVs are shared between Thread Groups.
Also, the variables are not available for use until after the element has been processed,
so you cannot reference variables that are defined in the same element.
You can reference variables defined in earlier UDVs or on the Test Plan.
</div>
<div class="clear"></div>
<div class="properties">
<h3 id="User_Defined_Variables_parms1">
Parameters
<a class="sectionlink" href="#User_Defined_Variables_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-true">Descriptive name for this element that is shown in the tree.</div>
<div class="required req-true"></div>
</div>
<div class="property">
<div class="name req-true">User Defined Variables</div>
<div class="description req-true">Variable name/value pairs. The string under the "<span class="code">Name</span>"
column is what you'll need to place inside the brackets in <span class="code">${&hellip;}</span> constructs to use the variables later on. The
whole <span class="code">${&hellip;}</span> will then be replaced by the string in the "<span class="code">Value</span>" column.</div>
<div class="required req-true"></div>
</div>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="Random_Variable">Random Variable<a class="sectionlink" href="#Random_Variable" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>
The Random Variable Config Element is used to generate random numeric strings and store them in variable for use later.
It's simpler than using <a href="../usermanual/component_reference.html#User_Defined_Variables">User Defined Variables</a> together with the <span class="code"><a href="../usermanual/functions.html#__Random">__Random()</a></span> function.
</p>
<p>
The output variable is constructed by using the random number generator,
and then the resulting number is formatted using the format string.
The number is calculated using the formula <span class="code">minimum+Random.nextInt(maximum-minimum+1)</span>.
<span class="code">Random.nextInt()</span> requires a positive integer.
This means that <span class="code">maximum-minimum</span> - i.e. the range - must be less than <span class="code">2147483647</span>,
however the <span class="code">minimum</span> and <span class="code">maximum</span> values can be any <span class="code">long</span> values so long as the range is OK.
</p>
<div class="clear"></div>
<div class="note">As the random value is evaluated at the start of each iteration, it is probably not a good idea
to use a variable other than a property as a value for the minimum or maximum. It would be zero on the first iteration.</div>
<div class="clear"></div>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/random_variable.png"><img src="../images/screenshots/random_variable.png" width="495" height="286" alt="Screenshot for Control-Panel of Random Variable"></a>
<figcaption>Screenshot of Control-Panel of Random Variable</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="Random_Variable_parms1">
Parameters
<a class="sectionlink" href="#Random_Variable_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-true">Descriptive name for this element that is shown in the tree.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Variable Name</div>
<div class="description req-true">The name of the variable in which to store the random string.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Format String</div>
<div class="description req-false">The <span class="code">java.text.DecimalFormat</span> format string to be used.
For example "<span class="code">000</span>" which will generate numbers with at least 3 digits,
or "<span class="code">USER_000</span>" which will generate output of the form <span class="code">USER_nnn</span>.
If not specified, the default is to generate the number using <span class="code">Long.toString()</span>
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Minimum Value</div>
<div class="description req-true">The minimum value (<span class="code">long</span>) of the generated random 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">The maximum value (<span class="code">long</span>) of the generated random number.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Random Seed</div>
<div class="description req-false">The seed for the random number generator.
If you use the same seed value with Per Thread set to <span class="code">true</span>, you will get the same value for each Thread as per
<a href="http://docs.oracle.com/javase/8/docs/api/java/util/Random.html">Random</a> class.
If no seed is set, Default constructor of Random will be used.
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Per Thread(User)?</div>
<div class="description req-true">If <span class="code">False</span>, the generator is shared between all threads in the thread group.
If <span class="code">True</span>, then each thread has its own random generator.</div>
<div class="required req-true">Yes</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">&para;</a>
</h2>
<div class="description">
<p>Allows the user to create a counter that can be referenced anywhere
in the Thread Group. The counter config lets the user configure a starting point, a maximum,
and the increment. The counter will loop from the start to the max, and then start over
with the start, continuing on like that until the test is ended. </p>
<p>The counter uses a long to store the value, so the range is from <span class="code">-2^63</span> to <span class="code">2^63-1</span>.</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/counter.png"><img src="../images/screenshots/counter.png" width="404" height="262" alt="Screenshot for Control-Panel of Counter"></a>
<figcaption>Screenshot of Control-Panel of Counter</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="Counter_parms1">
Parameters
<a class="sectionlink" href="#Counter_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-true">Descriptive name for this element that is shown in the tree.</div>
<div class="required req-true"></div>
</div>
<div class="property">
<div class="name req-false">Starting value</div>
<div class="description req-false">The starting value for the counter. The counter will equal this
value during the first iteration (defaults to 0).</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Increment</div>
<div class="description req-true">How much to increment the counter by after each
iteration (defaults to 0, meaning no increment).</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Maximum value</div>
<div class="description req-false">If the counter exceeds the maximum, then it is reset to the <span class="code">Starting value</span>.
Default is <span class="code">Long.MAX_VALUE</span>
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Format</div>
<div class="description req-false">Optional format, e.g. <span class="code">000</span> will format as <span class="code">001</span>, <span class="code">002</span>, etc.
This is passed to <span class="code">DecimalFormat</span>, so any valid formats can be used.
If there is a problem interpreting the format, then it is ignored.
[The default format is generated using <span class="code">Long.toString()</span>]
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Exported Variable Name</div>
<div class="description req-false">This will be the variable name under which the counter value is available.
If you name it <span class="code">counterA</span>, you can then access it using <span class="code">${counterA}</span>
as explained in <a href="functions.html">user-defined values</a> (By default, it creates an empty string variable that can be accessed using <span class="code">${}</span> but this is highly discouraged)</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Track Counter Independently for each User</div>
<div class="description req-false">In other words, is this a global counter, or does each user get their
own counter? If unchecked, the counter is global (i.e., user #1 will get value "<span class="code">1</span>", and user #2 will get value "<span class="code">2</span>" on
the first iteration). If checked, each user has an independent counter.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Reset counter on each Thread Group Iteration</div>
<div class="description req-false">This option is only available when counter is tracked per User, if checked,
counter will be reset to <span class="code">Start</span> value on each Thread Group iteration. This can be useful when Counter is inside a Loop Controller.</div>
<div class="required req-false">No</div>
</div>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="Simple_Config_Element">Simple Config Element<a class="sectionlink" href="#Simple_Config_Element" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>The Simple Config Element lets you add or override arbitrary values in samplers. You can choose the name of the value
and the value itself. Although some adventurous users might find a use for this element, it's here primarily for developers as a basic
GUI that they can use while developing new JMeter components.</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/simple_config_element.png"><img src="../images/screenshots/simple_config_element.png" width="627" height="282" alt="Screenshot for Control-Panel of Simple Config Element"></a>
<figcaption>Screenshot of Control-Panel of Simple Config Element</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="Simple_Config_Element_parms1">
Parameters
<a class="sectionlink" href="#Simple_Config_Element_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-true">Descriptive name for this element that is shown in the tree. </div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Parameter Name</div>
<div class="description req-true">The name of each parameter. These values are internal to JMeter's workings and
are not generally documented. Only those familiar with the code will know these values.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Parameter Value</div>
<div class="description req-true">The value to apply to that parameter.</div>
<div class="required req-true">Yes</div>
</div>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="MongoDB_Source_Config_(DEPRECATED)">MongoDB Source Config (DEPRECATED)<a class="sectionlink" href="#MongoDB_Source_Config_(DEPRECATED)" title="Link to here">&para;</a>
</h2>
<div class="description">Creates a MongoDB connection (used by <a href="../usermanual/component_reference.html#MongoDB_Script">MongoDB Script</a>Sampler)
from the supplied Connection settings. Each thread gets its own connection.
The connection configuration name is used by the JDBC Sampler to select the appropriate
connection.
<p>
You can then access <span class="code">com.mongodb.DB</span> object in Beanshell or JSR223 Test Elements through the element <a href="../api/org/apache/jmeter/protocol/mongodb/config/MongoDBHolder.html">MongoDBHolder</a>
using this code</p>
<pre class="source">
import com.mongodb.DB;
import org.apache.jmeter.protocol.mongodb.config.MongoDBHolder;
DB db = MongoDBHolder.getDBFromSource("value of property MongoDB Source",
"value of property Database Name");
&hellip;
</pre>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/mongodb-source-config.png"><img src="../images/screenshots/mongodb-source-config.png" width="1233" height="618" alt="Screenshot for Control-Panel of MongoDB Source Config (DEPRECATED)"></a>
<figcaption>Screenshot of Control-Panel of MongoDB Source Config (DEPRECATED)</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="MongoDB_Source_Config_(DEPRECATED)_parms1">
Parameters
<a class="sectionlink" href="#MongoDB_Source_Config_(DEPRECATED)_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-false">Descriptive name for the connection configuration that is shown in the tree.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Server Address List</div>
<div class="description req-true">Mongo DB Servers</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">MongoDB Source</div>
<div class="description req-true">The name of the variable the connection is tied to.
<div class="clear"></div>
<div class="note">Each name must be different. If there are two configuration elements using the same name, only one will be saved.</div>
<div class="clear"></div>
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Keep Trying</div>
<div class="description req-false">
If <span class="code">true</span>, the driver will keep trying to connect to the same server in case that the socket cannot be established.<br>
There is maximum amount of time to keep retrying, which is 15s by default.<br>This can be useful to avoid some exceptions being thrown when a server is down temporarily by blocking the operations.
<br>It can also be useful to smooth the transition to a new master (so that a new master is elected within the retry time).<br>
<div class="clear"></div>
<div class="note">Note that when using this flag
<ul>
<li>for a replica set, the driver will try to connect to the old master for that time, instead of failing over to the new one right away </li>
<li>this does not prevent exception from being thrown in read/write operations on the socket, which must be handled by application.</li>
</ul>
Even if this flag is false, the driver already has mechanisms to automatically recreate broken connections and retry the read operations.
</div>
<div class="clear"></div>
Default is <span class="code">false</span>.
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Maximum connections per host</div>
<div class="description req-false"></div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Connection timeout</div>
<div class="description req-false">
The connection timeout in milliseconds.<br>It is used solely when establishing a new connection <span class="code">Socket.connect(java.net.SocketAddress, int)</span>
<br>Default is <span class="code">0</span> and means no timeout.
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Maximum retry time</div>
<div class="description req-false">
The maximum amount of time in milliseconds to spend retrying to open connection to the same server.<br>Default is <span class="code">0</span>, which means to use the default 15s if <span class="code">autoConnectRetry</span> is on.
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Maximum wait time</div>
<div class="description req-false">
The maximum wait time in milliseconds that a thread may wait for a connection to become available.<br>Default is <span class="code">120,000</span>.
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Socket timeout</div>
<div class="description req-false">
The socket timeout in milliseconds It is used for I/O socket read and write operations <span class="code">Socket.setSoTimeout(int)</span>
<br>Default is <span class="code">0</span> and means no timeout.
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Socket keep alive</div>
<div class="description req-false">
This flag controls the socket keep alive feature that keeps a connection alive through firewalls <span class="code">Socket.setKeepAlive(boolean)</span>
<br>
Default is <span class="code">false</span>.
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">ThreadsAllowedToBlockForConnectionMultiplier</div>
<div class="description req-false">
This multiplier, multiplied with the connectionsPerHost setting, gives the maximum number of threads that may be waiting for a connection to become available from the pool.<br>
All further threads will get an exception right away.<br>
For example if <span class="code">connectionsPerHost</span> is <span class="code">10</span> and <span class="code">threadsAllowedToBlockForConnectionMultiplier</span> is <span class="code">5</span>, then up to 50 threads can wait for a connection.<br>
Default is <span class="code">5</span>.
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Write Concern : Safe</div>
<div class="description req-false">
If <span class="code">true</span> the driver will use a <span class="code">WriteConcern</span> of <span class="code">WriteConcern.SAFE</span> for all operations.<br>
If <span class="code">w</span>, <span class="code">wtimeout</span>, <span class="code">fsync</span> or <span class="code">j</span> are specified, this setting is ignored.<br>
Default is <span class="code">false</span>.
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Write Concern : Fsync</div>
<div class="description req-false">
The <span class="code">fsync</span> value of the global <span class="code">WriteConcern</span>.<br>
Default is <span class="code">false</span>.
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Write Concern : Wait for Journal</div>
<div class="description req-false">
The <span class="code">j</span> value of the global <span class="code">WriteConcern</span>.<br>
Default is <span class="code">false</span>.
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Write Concern : Wait for servers</div>
<div class="description req-false">
The <span class="code">w</span> value of the global <span class="code">WriteConcern</span>.<br>Default is <span class="code">0</span>.
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Write Concern : Wait timeout</div>
<div class="description req-false">
The <span class="code">wtimeout</span> value of the global <span class="code">WriteConcern</span>.<br>Default is <span class="code">0</span>.
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Write Concern : Continue on error</div>
<div class="description req-false">
If batch inserts should continue after the first error
</div>
<div class="required req-false">No</div>
</div>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<a href="#">^</a>
<div class="component">
<h2 id="Bolt_Connection_Configuration">Bolt Connection Configuration<a class="sectionlink" href="#Bolt_Connection_Configuration" title="Link to here">&para;</a>
</h2>
<div class="description">Creates a Bolt connection pool (used by <a href="../usermanual/component_reference.html#Bolt_Request">Bolt Request</a> Sampler)
from the supplied Connection settings.
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/bolt-connection-config.png"><img src="../images/screenshots/bolt-connection-config.png" width="711" height="170" alt="Screenshot for Control-Panel of Bolt Connection Configuration"></a>
<figcaption>Screenshot of Control-Panel of Bolt Connection Configuration</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="Bolt_Connection_Configuration_parms1">
Parameters
<a class="sectionlink" href="#Bolt_Connection_Configuration_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-false">Descriptive name for this sampler that is shown in the tree.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Comments</div>
<div class="description req-false">Free text for additional details.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Bolt URI</div>
<div class="description req-true">The database URI.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Username</div>
<div class="description req-false">User account.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Password</div>
<div class="description req-false">User credentials.</div>
<div class="required req-false">No</div>
</div>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<a href="#">^</a>
</div>
<div class="section">
<h1 id="assertions">18.5 Assertions<a class="sectionlink" href="#assertions" title="Link to here">&para;</a>
</h1>
<div class="description">
<p>
Assertions are used to perform additional checks on samplers, and are processed after <b>every sampler</b>
in the same scope.
To ensure that an Assertion is applied only to a particular sampler, add it as a child of the sampler.
</p>
<div class="clear"></div>
<div class="note">
Note: Unless documented otherwise, Assertions are not applied to sub-samples (child samples) -
only to the parent sample.
In the case of JSR223 and BeanShell Assertions, the script can retrieve sub-samples using the method
<span class="code">prev.getSubResults()</span> which returns an array of SampleResults.
The array will be empty if there are none.
</div>
<div class="clear"></div>
<p>
Assertions can be applied to either the main sample, the sub-samples or both.
The default is to apply the assertion to the main sample only.
If the Assertion supports this option, then there will be an entry on the GUI which looks like the following:
</p>
<figure>
<a href="../images/screenshots/assertion/assertionscope.png"><img src="../images/screenshots/assertion/assertionscope.png" width="658" height="54" alt="Assertion Scope"></a>
<figcaption>Assertion Scope</figcaption>
</figure>
or the following
<figure>
<a href="../images/screenshots/assertion/assertionscopevar.png"><img src="../images/screenshots/assertion/assertionscopevar.png" width="841" height="55" alt="Assertion Scope"></a>
<figcaption>Assertion Scope</figcaption>
</figure>
<p>
If a sub-sampler fails and the main sample is successful,
then the main sample will be set to failed status and an Assertion Result will be added.
If the JMeter variable option is used, it is assumed to relate to the main sample, and
any failure will be applied to the main sample only.
</p>
<div class="clear"></div>
<div class="note">
The variable <span class="code">JMeterThread.last_sample_ok</span> is updated to
"<span class="code">true</span>" or "<span class="code">false</span>" after all assertions for a sampler have been run.
</div>
<div class="clear"></div>
</div>
<div class="component">
<h2 id="Response_Assertion">Response Assertion<a class="sectionlink" href="#Response_Assertion" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>The response assertion control panel lets you add pattern strings to be compared against various
fields of the request or response.
The pattern strings are:
</p>
<ul>
<li>
<span class="code">Contains</span>, <span class="code">Matches</span>: Perl5-style regular expressions</li>
<li>
<span class="code">Equals</span>, <span class="code">Substring</span>: plain text, case-sensitive</li>
</ul>
<p>
A summary of the pattern matching characters can be found at <a href="http://jakarta.apache.org/oro/api/org/apache/oro/text/regex/package-summary.html">ORO Perl5 regular expressions.</a>
</p>
<p>You can also choose whether the strings will be expected
to <b>match</b> the entire response, or if the response is only expected to <b>contain</b> the
pattern. You can attach multiple assertions to any controller for additional flexibility.</p>
<p>Note that the pattern string should not include the enclosing delimiters,
i.e. use <span class="code">Price: \d+</span> not <span class="code">/Price: \d+/</span>.
</p>
<p>
By default, the pattern is in multi-line mode, which means that the "<span class="code">.</span>" meta-character does not match newline.
In multi-line mode, "<span class="code">^</span>" and "<span class="code">$</span>" match the start or end of any line anywhere within the string
- not just the start and end of the entire string. Note that <span class="code">\s</span> does match new-line.
Case is also significant. To override these settings, one can use the <i>extended regular expression</i> syntax.
For example:
</p>
<dl>
<dt>
<span class="code">(?i)</span>
</dt>
<dd>ignore case</dd>
<dt>
<span class="code">(?s)</span>
</dt>
<dd>treat target as single line, i.e. "<span class="code">.</span>" matches new-line</dd>
<dt>
<span class="code">(?is)</span>
</dt>
<dd>both the above</dd>
</dl>
These can be used anywhere within the expression and remain in effect until overridden. E.g.
<dl>
<dt>
<span class="code">(?i)apple(?-i) Pie</span>
</dt>
<dd>matches "<span class="code">ApPLe Pie</span>", but not "<span class="code">ApPLe pIe</span>"</dd>
<dt>
<span class="code">(?s)Apple.+?Pie</span>
</dt>
<dd>matches <span class="code">Apple</span> followed by <span class="code">Pie</span>, which may be on a subsequent line.</dd>
<dt>
<span class="code">Apple(?s).+?Pie</span>
</dt>
<dd>same as above, but it's probably clearer to use the <span class="code">(?s)</span> at the start.</dd>
</dl>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/assertion/assertion.png"><img src="../images/screenshots/assertion/assertion.png" width="909" height="607" alt="Screenshot for Control-Panel of Response Assertion"></a>
<figcaption>Screenshot of Control-Panel of Response Assertion</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="Response_Assertion_parms1">
Parameters
<a class="sectionlink" href="#Response_Assertion_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-false">Descriptive name for this element that is shown in the tree.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Apply to:</div>
<div class="description req-true">
This is for use with samplers that can generate sub-samples,
e.g. HTTP Sampler with embedded resources, Mail Reader or samples generated by the Transaction Controller.
<ul>
<li>
<span class="code">Main sample only</span> - only applies to the main sample</li>
<li>
<span class="code">Sub-samples only</span> - only applies to the sub-samples</li>
<li>
<span class="code">Main sample and sub-samples</span> - applies to both.</li>
<li>
<span class="code">JMeter Variable Name to use</span> - assertion is to be applied to the contents of the named variable</li>
</ul>
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Field to Test</div>
<div class="description req-true">Instructs JMeter which field of the Request or Response to test.
<ul>
<li>
<span class="code">Text Response</span> - the response text from the server, i.e. the body, excluding any HTTP headers.</li>
<li>
<span class="code">Request data</span> - the request text sent to the server, i.e. the body, excluding any HTTP headers.</li>
<li>
<span class="code">Response Code</span> - e.g. <span class="code">200</span>
</li>
<li>
<span class="code">Response Message</span> - e.g. <span class="code">OK</span>
</li>
<li>
<span class="code">Response Headers</span>, including Set-Cookie headers (if any)</li>
<li>
<span class="code">Request Headers</span>
</li>
<li>
<span class="code">URL sampled</span>
</li>
<li>
<span class="code">Document (text)</span> - the extract text from various type of documents via Apache Tika (see <a href="../usermanual/component_reference.html#View_Results_Tree">View Results Tree</a> Document view section).</li>
</ul>
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Ignore status</div>
<div class="description req-true">Instructs JMeter to set the status to success initially.
<p>
The overall success of the sample is determined by combining the result of the
assertion with the existing Response status.
When the <span class="code">Ignore Status</span> checkbox is selected, the Response status is forced
to successful before evaluating the Assertion.
</p>
HTTP Responses with statuses in the <span class="code">4xx</span> and <span class="code">5xx</span> ranges are normally
regarded as unsuccessful.
The "<span class="code">Ignore status</span>" checkbox can be used to set the status successful before performing further checks.
Note that this will have the effect of clearing any previous assertion failures,
so make sure that this is only set on the first assertion.
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Pattern Matching Rules</div>
<div class="description req-true">Indicates how the text being tested
is checked against the pattern.
<ul>
<li>
<span class="code">Contains</span> - true if the text contains the regular expression pattern</li>
<li>
<span class="code">Matches</span> - true if the whole text matches the regular expression pattern</li>
<li>
<span class="code">Equals</span> - true if the whole text equals the pattern string (case-sensitive)</li>
<li>
<span class="code">Substring</span> - true if the text contains the pattern string (case-sensitive)</li>
</ul>
<span class="code">Equals</span> and <span class="code">Substring</span> patterns are plain strings, not regular expressions.
<span class="code">NOT</span> may also be selected to invert the result of the check.
<span class="code">OR</span> Apply each assertion in OR combination (if 1 pattern to test matches, Assertion will be ok) instead of AND (All patterns must match so that Assertion is OK).</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Patterns to Test</div>
<div class="description req-true">A list of patterns to
be tested.
Each pattern is tested separately.
If a pattern fails, then further patterns are not checked.
There is no difference between setting up
one Assertion with multiple patterns and setting up multiple Assertions with one
pattern each (assuming the other options are the same).
<div class="clear"></div>
<div class="note">However, when the <span class="code">Ignore Status</span> checkbox is selected, this has the effect of cancelling any
previous assertion failures - so make sure that the <span class="code">Ignore Status</span> checkbox is only used on
the first Assertion.</div>
<div class="clear"></div>
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Custom failure message</div>
<div class="description req-false">Lets you define the failure message that will replace the generated one
</div>
<div class="required req-false">No</div>
</div>
</div>
<p>
The pattern is a Perl5-style regular expression, but without the enclosing brackets.
</p>
<div class="example">
<div class="title">Assertion Examples<a class="sectionlink" href="#assertion_examples" title="Link to here">&para;</a>
</div>
<center>
<figure>
<a href="../images/screenshots/assertion/example1a.png"><img src="../images/screenshots/assertion/example1a.png" width="266" height="117" alt="Figure 14 - Test Plan"></a>
<figcaption>Figure 14 - Test Plan</figcaption>
</figure>
<figure>
<a href="../images/screenshots/assertion/example1b.png"><img src="../images/screenshots/assertion/example1b.png" width="920" height="451" alt="Figure 15 - Assertion Control Panel with Pattern"></a>
<figcaption>Figure 15 - Assertion Control Panel with Pattern</figcaption>
</figure>
<figure>
<a href="../images/screenshots/assertion/example1c-pass.png"><img src="../images/screenshots/assertion/example1c-pass.png" width="801" height="230" alt="Figure 16 - Assertion Listener Results (Pass)"></a>
<figcaption>Figure 16 - Assertion Listener Results (Pass)</figcaption>
</figure>
<figure>
<a href="../images/screenshots/assertion/example1c-fail.png"><img src="../images/screenshots/assertion/example1c-fail.png" width="800" height="233" alt="Figure 17 - Assertion Listener Results (Fail)"></a>
<figcaption>Figure 17 - Assertion Listener Results (Fail)</figcaption>
</figure>
</center>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="Duration_Assertion">Duration Assertion<a class="sectionlink" href="#Duration_Assertion" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>The Duration Assertion tests that each response was received within a given amount
of time. Any response that takes longer than the given number of milliseconds (specified by the
user) is marked as a failed response.</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/duration_assertion.png"><img src="../images/screenshots/duration_assertion.png" width="606" height="187" alt="Screenshot for Control-Panel of Duration Assertion"></a>
<figcaption>Screenshot of Control-Panel of Duration Assertion</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="Duration_Assertion_parms1">
Parameters
<a class="sectionlink" href="#Duration_Assertion_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-true">Descriptive name for this element that is shown in the tree.</div>
<div class="required req-true"></div>
</div>
<div class="property">
<div class="name req-true">Duration in Milliseconds</div>
<div class="description req-true">The maximum number of milliseconds
each response is allowed before being marked as failed.</div>
<div class="required req-true">Yes</div>
</div>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="Size_Assertion">Size Assertion<a class="sectionlink" href="#Size_Assertion" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>The Size Assertion tests that each response contains the right number of bytes in it. You can specify that
the size be equal to, greater than, less than, or not equal to a given number of bytes.</p>
<div class="clear"></div>
<div class="note">An empty response is treated as being 0 bytes rather than reported as an error.</div>
<div class="clear"></div>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/size_assertion.png"><img src="../images/screenshots/size_assertion.png" width="732" height="358" alt="Screenshot for Control-Panel of Size Assertion"></a>
<figcaption>Screenshot of Control-Panel of Size Assertion</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="Size_Assertion_parms1">
Parameters
<a class="sectionlink" href="#Size_Assertion_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-true">Descriptive name for this element that is shown in the tree.</div>
<div class="required req-true"></div>
</div>
<div class="property">
<div class="name req-true">Apply to:</div>
<div class="description req-true">
This is for use with samplers that can generate sub-samples,
e.g. HTTP Sampler with embedded resources, Mail Reader or samples generated by the Transaction Controller.
<ul>
<li>
<span class="code">Main sample only</span> - assertion only applies to the main sample</li>
<li>
<span class="code">Sub-samples only</span> - assertion only applies to the sub-samples</li>
<li>
<span class="code">Main sample and sub-samples</span> - assertion applies to both.</li>
<li>
<span class="code">JMeter Variable Name to use</span> - assertion is to be applied to the contents of the named variable</li>
</ul>
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Size in bytes</div>
<div class="description req-true">The number of bytes to use in testing the size of the response (or value of the JMeter variable).</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Type of Comparison</div>
<div class="description req-true">Whether to test that the response is equal to, greater than, less than,
or not equal to, the number of bytes specified.</div>
<div class="required req-true">Yes</div>
</div>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="XML_Assertion">XML Assertion<a class="sectionlink" href="#XML_Assertion" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>The XML Assertion tests that the response data consists of a formally correct XML document. It does not
validate the XML based on a DTD or schema or do any further validation.</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/xml_assertion.png"><img src="../images/screenshots/xml_assertion.png" width="470" height="85" alt="Screenshot for Control-Panel of XML Assertion"></a>
<figcaption>Screenshot of Control-Panel of XML Assertion</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="XML_Assertion_parms1">
Parameters
<a class="sectionlink" href="#XML_Assertion_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-true">Descriptive name for this element that is shown in the tree.</div>
<div class="required req-true"></div>
</div>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="BeanShell_Assertion">BeanShell Assertion<a class="sectionlink" href="#BeanShell_Assertion" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>The BeanShell Assertion allows the user to perform assertion checking using a BeanShell script.
</p>
<p>
<b>For full details on using BeanShell, please see the <a href="http://www.beanshell.org/">BeanShell website.</a></b>
<div class="clear"></div>
<div class="note">Migration to <a href="../usermanual/component_reference.html#JSR223_Assertion">JSR223 Assertion</a>+Groovy is highly recommended for performance, support of new Java features and limited maintenance of the BeanShell library.</div>
<div class="clear"></div>
</p>
<p>
Note that a different Interpreter is used for each independent occurrence of the assertion
in each thread in a test script, but the same Interpreter is used for subsequent invocations.
This means that variables persist across calls to the assertion.
</p>
<p>
All Assertions are called from the same thread as the sampler.
</p>
<p>
If the property "<span class="code">beanshell.assertion.init</span>" 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 <span class="code">bin</span> directory: <span class="code">BeanShellAssertion.bshrc</span>
</p>
<p>
The test element supports the <span class="code">ThreadListener</span> and <span class="code">TestListener</span> methods.
These should be defined in the initialisation file.
See the file <span class="code">BeanShellListeners.bshrc</span> for example definitions.
</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/beanshell_assertion.png"><img src="../images/screenshots/beanshell_assertion.png" width="849" height="633" alt="Screenshot for Control-Panel of BeanShell Assertion"></a>
<figcaption>Screenshot of Control-Panel of BeanShell Assertion</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="BeanShell_Assertion_parms1">
Parameters
<a class="sectionlink" href="#BeanShell_Assertion_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-true">Descriptive name for this element that is shown in the tree.
The name is stored in the script variable <span class="code">Label</span>
</div>
<div class="required req-true"></div>
</div>
<div class="property">
<div class="name req-true">Reset bsh.Interpreter before each call</div>
<div class="description req-true">
If this option is selected, then the interpreter will be recreated for each sample.
This may be necessary for some long running scripts.
For further information, see <a href="best-practices.html#bsh_scripting">Best Practices - BeanShell scripting</a>.
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Parameters</div>
<div class="description req-false">Parameters to pass to the BeanShell script.
The parameters are stored in the following variables:
<ul>
<li>
<span class="code">Parameters</span> - string containing the parameters as a single variable</li>
<li>
<span class="code">bsh.args</span> - String array containing parameters, split on white-space</li>
</ul>
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Script file</div>
<div class="description req-false">A file containing the BeanShell script to run. This overrides the script.
The file name is stored in the script variable <span class="code">FileName</span>
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Script</div>
<div class="description req-true">The BeanShell script to run. The return value is ignored.</div>
<div class="required req-true">Yes (unless script file is provided)</div>
</div>
</div>
<p>There's a <a href="../demos/BeanShellAssertion.bsh">sample script</a> you can try.</p>
<p>
Before invoking the script, some variables are set up in the BeanShell interpreter.
These are strings unless otherwise noted:
</p>
<ul>
<li>
<span class="code">log</span> - the <a href="https://www.slf4j.org/api/org/slf4j/Logger.html">Logger</a> Object. (e.g.) <span class="code">log.warn("Message"[,Throwable])</span>
</li>
<li>
<span class="code">SampleResult</span>, <span class="code">prev</span> - the <a href="../api/org/apache/jmeter/samplers/SampleResult.html">SampleResult</a> Object; read-write</li>
<li>
<span class="code">Response</span> - the response Object; read-write</li>
<li>
<span class="code">Failure</span> - boolean; read-write; used to set the Assertion status</li>
<li>
<span class="code">FailureMessage</span> - String; read-write; used to set the Assertion message</li>
<li>
<span class="code">ResponseData</span> - the response body (byte [])</li>
<li>
<span class="code">ResponseCode</span> - e.g. <span class="code">200</span>
</li>
<li>
<span class="code">ResponseMessage</span> - e.g. <span class="code">OK</span>
</li>
<li>
<span class="code">ResponseHeaders</span> - contains the HTTP headers</li>
<li>
<span class="code">RequestHeaders</span> - contains the HTTP headers sent to the server</li>
<li>
<span class="code">SampleLabel</span>
</li>
<li>
<span class="code">SamplerData</span> - data that was sent to the server</li>
<li>
<span class="code">ctx</span> - <a href="../api/org/apache/jmeter/threads/JMeterContext.html">JMeterContext</a>
</li>
<li>
<span class="code">vars</span> - <a href="../api/org/apache/jmeter/threads/JMeterVariables.html">JMeterVariables</a> - e.g.
<pre class="source">vars.get("VAR1");
vars.put("VAR2","value");
vars.putObject("OBJ1",new Object());</pre>
</li>
<li>
<span class="code">props</span> - JMeterProperties (class <a href="https://docs.oracle.com/javase/8/docs/api/java/util/Properties.html"><span class="code">java.util.Properties</span></a>) - e.g.
<pre class="source">props.get("START.HMS");
props.put("PROP1","1234");</pre>
</li>
</ul>
<p>The following methods of the Response object may be useful:</p>
<ul>
<li>
<span class="code">setStopThread(boolean)</span>
</li>
<li>
<span class="code">setStopTest(boolean)</span>
</li>
<li>
<span class="code">String getSampleLabel()</span>
</li>
<li>
<span class="code">setSampleLabel(String)</span>
</li>
</ul>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="MD5Hex_Assertion">MD5Hex Assertion<a class="sectionlink" href="#MD5Hex_Assertion" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>The MD5Hex Assertion allows the user to check the MD5 hash of the response data.</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/assertion/MD5HexAssertion.png"><img src="../images/screenshots/assertion/MD5HexAssertion.png" width="398" height="130" alt="Screenshot for Control-Panel of MD5Hex Assertion"></a>
<figcaption>Screenshot of Control-Panel of MD5Hex Assertion</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="MD5Hex_Assertion_parms1">
Parameters
<a class="sectionlink" href="#MD5Hex_Assertion_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-true">Descriptive name for this element that is shown in the tree.</div>
<div class="required req-true"></div>
</div>
<div class="property">
<div class="name req-true">MD5 sum</div>
<div class="description req-true">32 hex digits representing the MD5 hash (case not significant)</div>
<div class="required req-true">Yes</div>
</div>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="HTML_Assertion">HTML Assertion<a class="sectionlink" href="#HTML_Assertion" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>The HTML Assertion allows the user to check the HTML syntax of the response data using JTidy.</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/assertion/HTMLAssertion.png"><img src="../images/screenshots/assertion/HTMLAssertion.png" width="505" height="341" alt="Screenshot for Control-Panel of HTML Assertion"></a>
<figcaption>Screenshot of Control-Panel of HTML Assertion</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="HTML_Assertion_parms1">
Parameters
<a class="sectionlink" href="#HTML_Assertion_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-true">Descriptive name for this element that is shown in the tree.</div>
<div class="required req-true"></div>
</div>
<div class="property">
<div class="name req-true">doctype</div>
<div class="description req-true">
<span class="code">omit</span>, <span class="code">auto</span>, <span class="code">strict</span> or <span class="code">loose</span>
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Format</div>
<div class="description req-true">
<span class="code">HTML</span>, <span class="code">XHTML</span> or <span class="code">XML</span>
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Errors only</div>
<div class="description req-true">Only take note of errors?</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Error threshold</div>
<div class="description req-true">Number of errors allowed before classing the response as failed</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Warning threshold</div>
<div class="description req-true">Number of warnings allowed before classing the response as failed</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Filename</div>
<div class="description req-false">Name of file to which report is written</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_Assertion">XPath Assertion<a class="sectionlink" href="#XPath_Assertion" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>The XPath Assertion tests a document for well formedness, has the option
of validating against a DTD, or putting the document through JTidy and testing for an
XPath. If that XPath exists, the Assertion is true. Using "<span class="code">/</span>" will match any well-formed
document, and is the default XPath Expression.
The assertion also supports boolean expressions, such as "<span class="code">count(//*error)=2</span>".
See <a href="http://www.w3.org/TR/xpath">http://www.w3.org/TR/xpath</a> for more information
on XPath.
</p>
Some sample expressions:
<ul>
<li>
<span class="code">//title[text()='Text to match']</span> - matches <span class="code">&lt;title&gt;Text to match&lt;/title&gt;</span> anywhere in the response</li>
<li>
<span class="code">/title[text()='Text to match']</span> - matches <span class="code">&lt;title&gt;Text to match&lt;/title&gt;</span> at root level in the response</li>
</ul>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/xpath_assertion.png"><img src="../images/screenshots/xpath_assertion.png" width="871" height="615" alt="Screenshot for Control-Panel of XPath Assertion"></a>
<figcaption>Screenshot of Control-Panel of XPath Assertion</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="XPath_Assertion_parms1">
Parameters
<a class="sectionlink" href="#XPath_Assertion_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-false">Descriptive name for this element that is shown in the tree.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Use Tidy (tolerant parser)</div>
<div class="description req-true">Use Tidy, i.e. be tolerant of XML/HTML errors</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Quiet</div>
<div class="description req-false">Sets the Tidy Quiet flag</div>
<div class="required req-false">If Tidy is selected</div>
</div>
<div class="property">
<div class="name req-false">Report Errors</div>
<div class="description req-false">If a Tidy error occurs, then set the Assertion accordingly</div>
<div class="required req-false">If Tidy is selected</div>
</div>
<div class="property">
<div class="name req-false">Show warnings</div>
<div class="description req-false">Sets the Tidy showWarnings option</div>
<div class="required req-false">If Tidy is selected</div>
</div>
<div class="property">
<div class="name req-false">Use Namespaces</div>
<div class="description req-false">Should namespaces be honoured? (see note below on NAMESPACES)</div>
<div class="required req-false">If Tidy is not selected</div>
</div>
<div class="property">
<div class="name req-false">Validate XML</div>
<div class="description req-false">Check the document against its schema.</div>
<div class="required req-false">If Tidy is not selected</div>
</div>
<div class="property">
<div class="name req-false">Ignore Whitespace</div>
<div class="description req-false">Ignore Element Whitespace.</div>
<div class="required req-false">If Tidy is not selected</div>
</div>
<div class="property">
<div class="name req-false">Fetch External DTDs</div>
<div class="description req-false">If selected, external DTDs are fetched.</div>
<div class="required req-false">If Tidy is not selected</div>
</div>
<div class="property">
<div class="name req-true">XPath Assertion</div>
<div class="description req-true">XPath to match in the document.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Invert assertion(will fail if above conditions met)</div>
<div class="description req-false">True if a XPath expression is not matched or returns false</div>
<div class="required req-false">No</div>
</div>
</div>
<div class="clear"></div>
<div class="note">
The non-tolerant parser can be quite slow, as it may need to download the DTD etc.
</div>
<div class="clear"></div>
<div class="clear"></div>
<div class="note">
<b>NAMESPACES</b>
<br>
As a work-round for namespace limitations of the Xalan XPath parser (implementation on which JMeter is based) you need to:
<ul>
<li>provide a Properties file (if for example your file is named namespaces.properties) which contains mappings for the namespace prefixes:
<pre class="source">
prefix1=http\://foo.apache.org
prefix2=http\://toto.apache.org
&hellip;
</pre>
</li>
<li>reference this file in <span class="code">user.properties</span> file using the property:
<pre class="source">xpath.namespace.config=namespaces.properties</pre>
</li>
</ul>
</div>
<div class="clear"></div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="XPath2_Assertion">XPath2 Assertion<a class="sectionlink" href="#XPath2_Assertion" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>The XPath2 Assertion tests a document for well formedness. Using "<span class="code">/</span>" will match any well-formed
document, and is the default XPath2 Expression.
The assertion also supports boolean expressions, such as "<span class="code">count(//*error)=2</span>".
</p>
Some sample expressions:
<ul>
<li>
<span class="code">//title[text()='Text to match']</span> - matches <span class="code">&lt;title&gt;Text to match&lt;/title&gt;</span> anywhere in the response</li>
<li>
<span class="code">/title[text()='Text to match']</span> - matches <span class="code">&lt;title&gt;Text to match&lt;/title&gt;</span> at root level in the response</li>
</ul>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/xpath_assertion.png"><img src="../images/screenshots/xpath_assertion.png" width="871" height="615" alt="Screenshot for Control-Panel of XPath2 Assertion"></a>
<figcaption>Screenshot of Control-Panel of XPath2 Assertion</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="XPath2_Assertion_parms1">
Parameters
<a class="sectionlink" href="#XPath2_Assertion_parms1" title="Link to here">&para;</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">Namespaces aliases list</div>
<div class="description req-false">List of namespaces aliases you want to use to parse the document, one line per declaration.
You must specify them as follow : <span class="code">prefix=namespace</span>. This implementation makes it easier to
use namespaces than with the old XPathExtractor version.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">XPath2 Assertion</div>
<div class="description req-true">XPath to match in the document.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Invert assertion</div>
<div class="description req-false">Will fail if xpath expression returns true or matches, succeed otherwise</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Namespace aliases list</div>
<div class="description req-false">List of namespace aliases prefix=full namespace (one per line)</div>
<div class="required req-false">No</div>
</div>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="XML_Schema_Assertion">XML Schema Assertion<a class="sectionlink" href="#XML_Schema_Assertion" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>The XML Schema Assertion allows the user to validate a response against an XML Schema.</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/assertion/XMLSchemaAssertion.png"><img src="../images/screenshots/assertion/XMLSchemaAssertion.png" width="472" height="132" alt="Screenshot for Control-Panel of XML Schema Assertion"></a>
<figcaption>Screenshot of Control-Panel of XML Schema Assertion</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="XML_Schema_Assertion_parms1">
Parameters
<a class="sectionlink" href="#XML_Schema_Assertion_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-true">Descriptive name for this element that is shown in the tree.</div>
<div class="required req-true"></div>
</div>
<div class="property">
<div class="name req-true">File Name</div>
<div class="description req-true">Specify XML Schema File Name</div>
<div class="required req-true">Yes</div>
</div>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="JSR223_Assertion">JSR223 Assertion<a class="sectionlink" href="#JSR223_Assertion" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>
The JSR223 Assertion allows JSR223 script code to be used to check the status of the previous sample.
</p>
</div>
<div class="properties">
<h3 id="JSR223_Assertion_parms1">
Parameters
<a class="sectionlink" href="#JSR223_Assertion_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-false">Descriptive name for this element that is shown in the tree.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Language</div>
<div class="description req-true">The JSR223 language to be used</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Parameters</div>
<div class="description req-false">Parameters to pass to the script.
The parameters are stored in the following variables:
<ul>
<li>
<span class="code">Parameters</span> - string containing the parameters as a single variable</li>
<li>
<span class="code">args</span> - String array containing parameters, split on white-space</li>
</ul>
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Script file</div>
<div class="description req-false">A file containing the script to run, if a relative file path is used, then it will be relative to directory referenced by "<span class="code">user.dir</span>" System property</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Script compilation caching</div>
<div class="description req-false">Unique String across Test Plan that JMeter will use to cache result of Script compilation if language used supports <span class="code"><a href="https://docs.oracle.com/javase/8/docs/api/javax/script/Compilable.html">Compilable</a></span> interface (Groovy is one of these, java, BeanShell and JavaScript are not)
<div class="clear"></div>
<div class="note">See note in JSR223 Sampler Java System property if you're using Groovy without checking this option</div>
<div class="clear"></div>
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Script</div>
<div class="description req-true">The script to run.</div>
<div class="required req-true">Yes (unless script file is provided)</div>
</div>
</div>
<p>The following variables are set up for use by the script:</p>
<ul>
<li>
<span class="code">log</span> - (<a href="https://www.slf4j.org/api/org/slf4j/Logger.html">Logger</a>) - can be used to write to the log file</li>
<li>
<span class="code">Label</span> - the String Label</li>
<li>
<span class="code">Filename</span> - the script file name (if any)</li>
<li>
<span class="code">Parameters</span> - the parameters (as a String)</li>
<li>
<span class="code">args</span> - the parameters as a String array (split on whitespace)</li>
<li>
<span class="code">ctx</span> - (<a href="../api/org/apache/jmeter/threads/JMeterContext.html">JMeterContext</a>) - gives access to the context</li>
<li>
<span class="code">vars</span> - (<a href="../api/org/apache/jmeter/threads/JMeterVariables.html">JMeterVariables</a>) - gives read/write access to variables:
<pre class="source">
vars.get(key);
vars.put(key,val);
vars.putObject("OBJ1",new Object());
vars.getObject("OBJ2");
</pre>
</li>
<li>
<span class="code">props</span> - (JMeterProperties - class <a href="https://docs.oracle.com/javase/8/docs/api/java/util/Properties.html"><span class="code">java.util.Properties</span></a>) - e.g.
<pre class="source">
props.get("START.HMS");
props.put("PROP1","1234");
</pre>
</li>
<li>
<span class="code">SampleResult</span>, <span class="code">prev</span> - (<a href="../api/org/apache/jmeter/samplers/SampleResult.html">SampleResult</a>) - gives access to the previous SampleResult (if any)</li>
<li>
<span class="code">sampler</span> - (<a href="../api/org/apache/jmeter/samplers/Sampler.html">Sampler</a>) - gives access to the current sampler</li>
<li>
<span class="code">OUT</span> - <span class="code">System.out</span> - e.g. <span class="code">OUT.println("message")</span>
</li>
<li>
<span class="code">AssertionResult</span> - (<a href="../api/org/apache/jmeter/assertions/AssertionResult.html">AssertionResult</a>) - the assertion result</li>
</ul>
<p>
The script can check various aspects of the <a href="../api/org/apache/jmeter/samplers/SampleResult.html">SampleResult</a>.
If an error is detected, the script should use <span class="code">AssertionResult.setFailureMessage("message")</span> and <span class="code">AssertionResult.setFailure(true)</span>.
</p>
<p>For further details of all the methods available on each of the above variables, please check the Javadoc</p>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="Compare_Assertion">Compare Assertion<a class="sectionlink" href="#Compare_Assertion" title="Link to here">&para;</a>
</h2>
<div class="description">
<div class="clear"></div>
<div class="note">
Compare Assertion <b>must not be used</b> during load test as it consumes a lot of resources (memory and CPU). Use it only for either functional testing or
during Test Plan debugging and Validation.
</div>
<div class="clear"></div>
The Compare Assertion can be used to compare sample results within its scope.
Either the contents or the elapsed time can be compared, and the contents can be filtered before comparison.
The assertion comparisons can be seen in the <a href="../usermanual/component_reference.html#Comparison_Assertion_Visualizer">Comparison Assertion Visualizer</a>.
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/assertion/compare.png"><img src="../images/screenshots/assertion/compare.png" width="580" height="302" alt="Screenshot for Control-Panel of Compare Assertion"></a>
<figcaption>Screenshot of Control-Panel of Compare Assertion</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="Compare_Assertion_parms1">
Parameters
<a class="sectionlink" href="#Compare_Assertion_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-false">Descriptive name for this element that is shown in the tree.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Compare Content</div>
<div class="description req-true">Whether or not to compare the content (response data)</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Compare Time</div>
<div class="description req-true">If the value is &ge;0, then check if the response time difference is no greater than the value.
I.e. if the value is <span class="code">0</span>, then the response times must be exactly equal.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Comparison Filters</div>
<div class="description req-false">Filters can be used to remove strings from the content comparison.
For example, if the page has a time-stamp, it might be matched with: "<span class="code">Time: \d\d:\d\d:\d\d</span>" and replaced with a dummy fixed time "<span class="code">Time: HH:MM:SS</span>".
</div>
<div class="required req-false">No</div>
</div>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="SMIME_Assertion">SMIME Assertion<a class="sectionlink" href="#SMIME_Assertion" title="Link to here">&para;</a>
</h2>
<div class="description">
The SMIME Assertion can be used to evaluate the sample results from the Mail Reader Sampler.
This assertion verifies if the body of a mime message is signed or not. The signature can also be verified against a specific signer certificate.
As this is a functionality that is not necessarily needed by most users, additional jars need to be downloaded and added to <span class="code">JMETER_HOME/lib</span>:<br>
<ul>
<li>
<span class="code">bcmail-xxx.jar</span> (BouncyCastle SMIME/CMS)</li>
<li>
<span class="code">bcprov-xxx.jar</span> (BouncyCastle Provider)</li>
</ul>
These need to be <a href="http://www.bouncycastle.org/latest_releases.html">downloaded from BouncyCastle.</a>
<p>
If using the <a href="../usermanual/component_reference.html#Mail_Reader_Sampler">Mail Reader Sampler</a>,
please ensure that you select "<span class="code">Store the message using MIME (raw)</span>" otherwise the Assertion won't be able to process the message correctly.
</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/assertion/smime.png"><img src="../images/screenshots/assertion/smime.png" width="471" height="428" alt="Screenshot for Control-Panel of SMIME Assertion"></a>
<figcaption>Screenshot of Control-Panel of SMIME Assertion</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="SMIME_Assertion_parms1">
Parameters
<a class="sectionlink" href="#SMIME_Assertion_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-false">Descriptive name for this element that is shown in the tree.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Verify Signature</div>
<div class="description req-true">If selected, the assertion will verify if it is a valid signature according to the parameters defined in the <span class="code">Signer Certificate</span> box.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Message not signed</div>
<div class="description req-true">Whether or not to expect a signature in the message</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Signer Certificate</div>
<div class="description req-true">"<span class="code">No Check</span>" means that it will not perform signature verification. "<span class="code">Check values</span>" is used to verify the signature against the inputs provided. And "<span class="code">Certificate file</span>" will perform the verification against a specific certificate file.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Message Position</div>
<div class="description req-true">
The Mail sampler can retrieve multiple messages in a single sample.
Use this field to specify which message will be checked.
Messages are numbered from <span class="code">0</span>, so <span class="code">0</span> means the first message.
Negative numbers count from the LAST message; <span class="code">-1</span> means LAST, <span class="code">-2</span> means penultimate etc.
</div>
<div class="required req-true">Yes</div>
</div>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="JSON_Assertion">JSON Assertion<a class="sectionlink" href="#JSON_Assertion" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>
This component allows you to perform validations of JSON documents.
First, it will parse the JSON and fail if the data is not JSON.
Second, it will search for specified path, using syntax from <a href="https://github.com/json-path/JsonPath">Jayway JsonPath 1.2.0</a>. If the path is not found, it will fail.
Third, if JSON path was found in the document, and validation against expected value was requested, it will perform validation. For the <span class="code">null</span> value there is special checkbox in the GUI.
Note that if the path will return array object, it will be iterated and if expected value is found, the assertion will succeed. To validate empty array use <span class="code">[]</span> string. Also, if patch will return dictionary object, it will be converted to string before comparison.
</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/assertion/json_assertion.png"><img src="../images/screenshots/assertion/json_assertion.png" width="1095" height="307" alt="Screenshot for Control-Panel of JSON Assertion"></a>
<figcaption>Screenshot of Control-Panel of JSON Assertion</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="JSON_Assertion_parms1">
Parameters
<a class="sectionlink" href="#JSON_Assertion_parms1" title="Link to here">&para;</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">Assert JSON Path exists</div>
<div class="description req-true">Path to JSON element for assert.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Additionally assert value</div>
<div class="description req-false">Select checkbox if you want make assert with some value</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Match as regular expression</div>
<div class="description req-false">Select checkbox if you want use regular expression</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Expected Value</div>
<div class="description req-false">Value for assert or regular expression for match</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Expect null</div>
<div class="description req-false">Select checkbox if you expect null</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Invert assertion (will fail if above conditions met)</div>
<div class="description req-false">Invert assertion (will fail if above conditions met)</div>
<div class="required req-false">No</div>
</div>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="JSON_JMESPath_Assertion">JSON JMESPath Assertion<a class="sectionlink" href="#JSON_JMESPath_Assertion" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>
This component allows you to perform assertion on JSON documents content using <a href="http://jmespath.org/" target="blank">JMESPath</a>.
First, it will parse the JSON and fail if the data is not JSON. <br>
Second, it will search for specified path, using JMESPath syntax. <br>
If the path is not found, it will fail. <br>
Third, if JMES path was found in the document, and validation against expected value was requested, it will perform this additional check.
If you want to check for nullity, use the <span class="code">Expect null</span> checkbox. <br>
Note that the path cannot be null as the expression JMESPath will not be compiled and an error will occur.
Even if you expect an empty or null response, you must put a valid JMESPath expression.
</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/assertion/jmespath_assertion.png"><img src="../images/screenshots/assertion/jmespath_assertion.png" width="903" height="305" alt="Screenshot for Control-Panel of JSON JMESPath Assertion"></a>
<figcaption>Screenshot of Control-Panel of JSON JMESPath Assertion</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="JSON_JMESPath_Assertion_parms1">
Parameters
<a class="sectionlink" href="#JSON_JMESPath_Assertion_parms1" title="Link to here">&para;</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">Assert JMESPath exists</div>
<div class="description req-true">Check that JMESPath to JSON element exists</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Additionally assert value</div>
<div class="description req-false">Select checkbox if you check the extracted JMESPath against an expected one</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Match as regular expression</div>
<div class="description req-false">Select checkbox if you want to use a regular expression for matching</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Expected Value</div>
<div class="description req-false">Value to use for exact matching or regular expression if <span class="code">Match as regular expression</span> is checked</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Expect null</div>
<div class="description req-false">Select checkbox if you expect the value to be null</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Invert assertion (will fail if above conditions met)</div>
<div class="description req-false">Invert assertion (will fail if above conditions met)</div>
<div class="required req-false">No</div>
</div>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<a href="#">^</a>
</div>
<div class="section">
<h1 id="timers">18.6 Timers<a class="sectionlink" href="#timers" title="Link to here">&para;</a>
</h1>
<div class="description">
<div class="clear"></div>
<div class="note">
Since version 3.1, a new feature (in Beta mode as of JMeter 3.1 and subject to changes) has been implemented which provides the following feature.<br>
You can apply a multiplication factor on the sleep delays computed by Random timer by setting property <span class="code">timer.factor=float number</span> where float number is a decimal positive number.<br>
JMeter will multiply this factor by the computed sleep delay. This feature can be used by:
<ul>
<li>
<a href="../usermanual/component_reference.html#Gaussian_Random_Timer">Gaussian Random Timer</a>
</li>
<li>
<a href="../usermanual/component_reference.html#Poisson_Random_Timer">Poisson Random Timer</a>
</li>
<li>
<a href="../usermanual/component_reference.html#Uniform_Random_Timer">Uniform Random Timer</a>
</li>
</ul>
</div>
<div class="clear"></div>
<div class="clear"></div>
<div class="note">
Note that timers are processed <b>before</b> each sampler in the scope in which they are found;
if there are several timers in the same scope, <b>all</b> the timers will be processed <b>before
each</b> sampler.
<br>
Timers are only processed in conjunction with a sampler.
A timer which is not in the same scope as a sampler will not be processed at all.
<br>
To apply a timer to a single sampler, add the timer as a child element of the sampler.
The timer will be applied before the sampler is executed.
To apply a timer after a sampler, either add it to the next sampler, or add it as the
child of a <a href="../usermanual/component_reference.html#Flow_Control_Action">Flow Control Action</a> Sampler.
</div>
<div class="clear"></div>
</div>
<div class="component">
<h2 id="Constant_Timer">Constant Timer<a class="sectionlink" href="#Constant_Timer" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>If you want to have each thread pause for the same amount of time between
requests, use this timer.</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/timers/constant_timer.png"><img src="../images/screenshots/timers/constant_timer.png" width="372" height="100" alt="Screenshot for Control-Panel of Constant Timer"></a>
<figcaption>Screenshot of Control-Panel of Constant Timer</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="Constant_Timer_parms1">
Parameters
<a class="sectionlink" href="#Constant_Timer_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-false">Descriptive name for this timer that is shown in the tree.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Thread Delay</div>
<div class="description req-true">Number of milliseconds to pause.</div>
<div class="required req-true">Yes</div>
</div>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="Gaussian_Random_Timer">Gaussian Random Timer<a class="sectionlink" href="#Gaussian_Random_Timer" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>This timer pauses each thread request for a random amount of time, with most
of the time intervals occurring near a particular value.
The total delay is the sum of the Gaussian distributed value (with mean <span class="code">0.0</span> and standard deviation <span class="code">1.0</span>) times
the deviation value you specify, and the offset value.
Another way to explain it, in Gaussian Random Timer, the variation around constant offset has a Gaussian curve distribution.
</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/timers/gauss_random_timer.png"><img src="../images/screenshots/timers/gauss_random_timer.png" width="372" height="156" alt="Screenshot for Control-Panel of Gaussian Random Timer"></a>
<figcaption>Screenshot of Control-Panel of Gaussian Random Timer</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="Gaussian_Random_Timer_parms1">
Parameters
<a class="sectionlink" href="#Gaussian_Random_Timer_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-false">Descriptive name for this timer that is shown in the tree</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Deviation</div>
<div class="description req-true">Deviation in milliseconds.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Constant Delay Offset</div>
<div class="description req-true">Number of milliseconds to pause in addition
to the random delay.</div>
<div class="required req-true">Yes</div>
</div>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="Uniform_Random_Timer">Uniform Random Timer<a class="sectionlink" href="#Uniform_Random_Timer" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>This timer pauses each thread request for a random amount of time, with
each time interval having the same probability of occurring. The total delay
is the sum of the random value and the offset value.</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/timers/uniform_random_timer.png"><img src="../images/screenshots/timers/uniform_random_timer.png" width="372" height="157" alt="Screenshot for Control-Panel of Uniform Random Timer"></a>
<figcaption>Screenshot of Control-Panel of Uniform Random Timer</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="Uniform_Random_Timer_parms1">
Parameters
<a class="sectionlink" href="#Uniform_Random_Timer_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-false">Descriptive name for this timer that is shown in the tree. </div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Random Delay Maximum</div>
<div class="description req-true">Maximum random number of milliseconds to
pause.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Constant Delay Offset</div>
<div class="description req-true">Number of milliseconds to pause in addition
to the random delay.</div>
<div class="required req-true">Yes</div>
</div>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="Constant_Throughput_Timer">Constant Throughput Timer<a class="sectionlink" href="#Constant_Throughput_Timer" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>This timer introduces variable pauses, calculated to keep the total throughput (in terms of samples per minute) as close as possible to a give figure. Of course the throughput will be lower if the server is not capable of handling it, or if other timers or time-consuming test elements prevent it.</p>
<p>
N.B. although the Timer is called the Constant Throughput timer, the throughput value does not need to be constant.
It can be defined in terms of a variable or function call, and the value can be changed during a test.
The value can be changed in various ways:
</p>
<ul>
<li>using a counter variable</li>
<li>using a <span class="code">__jexl3</span>, <span class="code">__groovy</span> function to provide a changing value</li>
<li>using the remote BeanShell server to change a JMeter property</li>
</ul>
<p>See <a href="best-practices.html">Best Practices</a> for further details.
<div class="clear"></div>
<div class="note">
Note that the throughput value should not be changed too often during a test
- it will take a while for the new value to take effect.
</div>
<div class="clear"></div>
</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/timers/constant_throughput_timer.png"><img src="../images/screenshots/timers/constant_throughput_timer.png" width="636" height="146" alt="Screenshot for Control-Panel of Constant Throughput Timer"></a>
<figcaption>Screenshot of Control-Panel of Constant Throughput Timer</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="Constant_Throughput_Timer_parms1">
Parameters
<a class="sectionlink" href="#Constant_Throughput_Timer_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-false">Descriptive name for this timer that is shown in the tree. </div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Target Throughput</div>
<div class="description req-true">Throughput we want the timer to try to generate.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Calculate Throughput based on</div>
<div class="description req-true">
<ul>
<li>
<span class="code">this thread only</span> - each thread will try to maintain the target throughput. The overall throughput will be proportional to the number of active threads.</li>
<li>
<span class="code">all active threads in current thread group</span> - the target throughput is divided amongst all the active threads in the group.
Each thread will delay as needed, based on when it last ran.</li>
<li>
<span class="code">all active threads</span> - the target throughput is divided amongst all the active threads in all Thread Groups.
Each thread will delay as needed, based on when it last ran.
In this case, each other Thread Group will need a Constant Throughput timer with the same settings.</li>
<li>
<span class="code">all active threads in current thread group (shared)</span> - as above, but each thread is delayed based on when any thread in the group last ran.</li>
<li>
<span class="code">all active threads (shared)</span> - as above; each thread is delayed based on when any thread last ran.</li>
</ul>
</div>
<div class="required req-true">Yes</div>
</div>
<p>The shared and non-shared algorithms both aim to generate the desired throughput, and will produce similar results.<br>
The shared algorithm should generate a more accurate overall transaction rate.<br>
The non-shared algorithm should generate a more even spread of transactions across threads.</p>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="Precise_Throughput_Timer">Precise Throughput Timer<a class="sectionlink" href="#Precise_Throughput_Timer" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>This timer introduces variable pauses, calculated to keep the total throughput (e.g. in terms of samples per minute) as close as possible to a give figure. Of course the throughput will be lower if the server is not capable of handling it, or if other timers, or if there's not enough threads, or time-consuming test elements prevent it.</p>
<p>Although the Timer is called Precise Throughput Timer, it does not aim to produce precisely the same number of samples over one-second intervals during the test.</p>
<p>The timer works best for rates under 36000 requests/hour, however your mileage might vary (see monitoring section below if your goals are
vastly different).</p>
<h4>Best location of a Precise Throughput Timer in a Test Plan</h4>
<p>As you might know, the timers are inherited by all the siblings and their child elements. That is why one of the best places for
<span class="code">Precise Throughput Timer</span> is under the first element in a test loop. For instance, you might add a dummy sampler at the beginning,
and place the timer under that dummy sampler</p>
<h4>Produced schedule</h4>
<p>
<span class="code">Precise Throughput Timer</span> models <a href="https://en.wikipedia.org/wiki/Poisson_point_process">Poisson arrivals</a> schedule. That schedule often happens in a real-life, so it makes sense to use that for load testing.
For instance, it naturally might generate samples that are close together thus it might reveal concurrency issues. Even if you manage to generate Poisson arrivals
with <a href="../usermanual/component_reference.html#Poisson_Random_Timer">Poisson Random Timer</a>, it would be susceptible to the issues listed below. For instance, true Poisson arrivals might have indefinitely long
pause, and that is not practical for load testing. For instance, "regular" Poisson arrivals with 1 per second rate might end up with 50 samples over 60 second long test.</p>
<p>
<a href="../usermanual/component_reference.html#Constant_Throughput_Timer">Constant Throughput Timer</a> converges to the specified rate, however it tends to produce samples at even intervals.</p>
<h4>Ramp-up and startup spike</h4>
<p>You might used "ramp-up" or similar approaches to avoid a spike at the test start. For instance, if you configure <a href="../usermanual/component_reference.html#Thread_Group">Thread Group</a> to have
100 threads, and set <span class="code">Ramp-up Period</span> to 0 (or to a small number), then all the threads would start at the same time, and it would produce an unwanted spike of the load. On top of that, if you set <span class="code">Ramp-up Period</span> too high, it might result in "too few" threads being available at the very beginning to achieve
the required load.</p>
<p>
<span class="code">Precise Throughput Timer</span> schedules executions in a random way, so it can be used to generate constant load, and it is recommended to set both
<span class="code">Ramp-up Period</span> and <span class="code">Delay</span> to <span class="code">0</span>.</p>
<h4>Multiple thread groups starting at the same time</h4>
<p>A variation of <span class="code">Ramp-up</span> issue might appear when <a href="../usermanual/component_reference.html#Test_Plan">Test Plan</a> includes multiple <a href="../usermanual/component_reference.html#Thread_Group">Thread Group</a>s. To mitigate that issue
one typically adds "random" delay to each <a href="../usermanual/component_reference.html#Thread_Group">Thread Group</a> so threads start at different times.</p>
<p>
<span class="code">Precise Throughput Timer</span> avoids that issue since it schedules executions in a random way. You do not need to add extra random delays to mitigate startup spike</p>
<h4>Number of iterations per hour</h4>
<p>One of the basic requirements is to issue N samples per M minutes. Let it be 60 iterations per hour. Business customers would not understand if you report load test
results with 57 executions "just because the random was random". In order to generate 60 iterations per hour, you need to configure as follows (other parameters
could be left with their default values)</p>
<ul>
<li>
<span class="code">Target throughput (samples)</span>: 60</li>
<li>
<span class="code">Throughput period (seconds)</span>: 3600</li>
<li>
<span class="code">Test duration (seconds)</span>: 3600</li>
</ul>
<p>The first two options set the throughput. Even though 60/3600, 30/1800, and 120/7200 represent exactly the same load level, pick the one that represents
business requirements better. For instance, if the requirement is to test for "60 sample per hour", then set 60/3600. If the requirement is to test "1 sample per minute",
then set 1/60.</p>
<p>
<span class="code">Test duration (seconds)</span> is there so the timer ensures exact number of samples for a given test duration. <span class="code">Precise Throughput Timer</span> creates
a schedule for the samples at the test startup. For instance, if you
wish to perform 5 minutes test with 60 per hour throughput, you would set <span class="code">Test duration (seconds)</span> to 300. This enables to configure throughput
in a business-friendly way. Note: <span class="code">Test duration (seconds)</span> does <b>not</b> limit test duration. It is just a hint for the timer.</p>
<h4>Number of threads and think times</h4>
<p>One of the common pitfalls is to adjust number of threads and think times in order to end up with the desired throughput. Even though it might work, that approach
results in lots of time spent on the test runs. It might require to adjust threads and delays again when new application version arrives.</p>
<p>
<span class="code">Precise Throughput Timer</span> enables to set throughput goal and go for it no matter how well application performs. In order to do that, <span class="code">Precise Throughput Timer</span>
creates a schedule at the test startup, then it uses that schedule to release threads. The main driver for the think times and number of threads should be business
requirements, not the desire to match throughput somehow.</p>
<p>For instance, if you application is used by support engineers in a call center. Suppose there are 2 engineers in the call center, and the target throughput is 1 per minute.
Suppose it takes 4 minutes for the engineer to read and review the web page. For that case you should set 2 threads in the group, use 4 minutes
for think time delays, and specify 1 per minute in <span class="code">Precise Throughput Timer</span>. Of course it would result in something around 2samples/4minutes=0.5 per minute
and the result of such a test means "you need more support engineers in a call center" or "you need to reduce the time it takes an engineer to fulfill a task".</p>
<h4>Testing low rates and repeatable tests</h4>
<p>Testing at low rates (e.g. 60 per hour) requires to know the desired test profile. For instance, if you need to inject load at even intervals (e.g. 60 seconds in between)
then you'd better use <a href="../usermanual/component_reference.html#Constant_Throughput_Timer">Constant Throughput Timer</a>. However, if you need to have randomized schedule (e.g. to model real users that execute reports),
then <span class="code">Precise Throughput Timer</span> is your friend.</p>
<p>When comparing outcomes of multiple load tests, it is useful to be able to repeat exactly the same test profile. For instance, if action X (e.g. "Profit Report")
is invoked after 5 minutes of the test start, then it would be nice to replicate that pattern for subsequent test executions. Replicating the same load pattern
simplifies analysis of the test results (e.g. CPU% chart).</p>
<p>
<span class="code">Random seed (change from 0 to random)</span> enables to control the seed value that is used by <span class="code">Precise Throughput Timer</span>. By default it is
initialized with <span class="code">0</span> and that means random seed is used for each test execution. If you need to have repeatable load pattern, then change
<span class="code">Random seed</span> so some random value. The general advice is to use non-zero seed, and "0 by default" is an implementation limit.</p>
<p>Note: when using multiple thread groups with same throughput rates and same non-zero seed it might result in unwanted firing the samples at the same time.</p>
<h4>Testing high rates and/or long test durations</h4>
<p>
<span class="code">Precise Throughput Timer</span> generates the schedule and keeps it in memory. In most cases it should not be a problem,
however, remember that you might want to keep the schedule shorter than 1'000'000 samples.
It takes ~200ms to generate a schedule for 1'000'000 samples, and the schedule consumes 8 megabytes in the heap.
Schedule for 10 million entries takes 1-2 second to build and it consumes 80 megabytes in the heap.
</p>
<p>For instance, if you want to perform 2-week long test with 5'000 per hour rate, then you probably want to have exactly 5'000 samples
for each hour. You can set <span class="code">Test duration (seconds)</span> property of the timer of the timer to 1 hour.
Then the timer would create a schedule of 5'000 samples for an hour, and when the schedule is exhausted, the timer would generate
a schedule for the next hour.</p>
<p>At the same time, you can set <span class="code">Test duration (seconds)</span> to 2 weeks, and the timer would generate a schedule with
<span class="code">168'000 samples = 2 weeks * 5'000 samples/hour = 2*7*24*500</span>. The schedule would take ~30ms to generate, and it would
consume a little more than 1 megabyte.</p>
<h4>Bursty load</h4>
<p>There might be a case when all the samples should come in pairs, triples, etc. Certain cases might be solved via <a href="../usermanual/component_reference.html#Synchronizing_Timer">Synchronizing Timer</a>, however
<span class="code">Precise Throughput Timer</span> has native way to issue requests in packs. This behavior is disabled by default, and it is controlled with "Batched departures"
settings</p>
<ul>
<li>
<span class="code">Number of threads in the batch (threads)</span>. Specifies the number of samples in a batch. Note the overall number of samples will still be in line with <span class="code">Target Throughput</span>
</li>
<li>
<span class="code">Delay between threads in the batch (ms)</span>. For instance, if set to 42, and the batch size is 3, then threads will depart at x, x+42ms, x+84ms</li>
</ul>
<h4>Variable load rate</h4>
<p>Even though property values (e.g. throughput) can be defined via expressions, it is recommended to keep the value more or less the same through the test, as it takes time to recompute the new schedule to adapt new values.</p>
<h4>Monitoring</h4>
<p>As next schedule is generated, <span class="code">Precise Throughput Timer</span> logs a message to <span class="code">jmeter.log</span>:
<span class="code">2018-01-04 17:34:03,635 INFO o.a.j.t.ConstantPoissonProcessGenerator: Generated 21 timings (... 20 required, rate 1.0, duration 20, exact lim 20000,
i21) in 0 ms. First 15 events will be fired at: 1.1869653574244292 (+1.1869653574244292), 1.4691340403043207 (+0.2821686828798915),
3.638151706179226 (+2.169017665874905), 3.836357090410566 (+0.19820538423134026), 4.709330071408575 (+0.8729729809980085), 5.61330076999953 (+0.903970698590955),
...</span>
This shows that schedule generation took 0ms, and it shows absolute timestamps in seconds. In the case above, the rate was set to be 1 per second, and the actual timestamps
became 1.2 sec, 1.5 sec, 3.6 sec, 3.8 sec, 4.7 sec, and so on.</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/timers/precise_throughput_timer.png"><img src="../images/screenshots/timers/precise_throughput_timer.png" width="573" height="407" alt="Screenshot for Control-Panel of Precise Throughput Timer"></a>
<figcaption>Screenshot of Control-Panel of Precise Throughput Timer</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="Precise_Throughput_Timer_parms1">
Parameters
<a class="sectionlink" href="#Precise_Throughput_Timer_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-false">Descriptive name for this timer that is shown in the tree</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Target throughput (in samples per 'throughput period')</div>
<div class="description req-true">Maximum number of samples you want to obtain per "throughput period", including all threads in group, from all affected samplers.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Throughput period (seconds)</div>
<div class="description req-true">Throughput period. For example, if "throughput" is set to 42 and "throughput period" to 21 sec, then you'll get 2 samples per second.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Test duration (seconds)</div>
<div class="description req-true">This is used to ensure you'll get throughput*duration samples during "test duration" timeframe.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Number of threads in the batch (threads)</div>
<div class="description req-true">If the value exceeds 1, then multiple threads depart from the timer simultaneously. Average throughput still meets "throughput" value.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Delay between threads in the batch (ms)</div>
<div class="description req-true">For instance, if set to 42, and the batch size is 3, then threads will depart at x, x+42ms, x+84ms.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Random seed (change from 0 to random)</div>
<div class="description req-true">Note: different timers should better have different seed values. Constant seed ensures timer generates the same delays each test start. The value of "0" means the timer is truly random (non-repeatable from one execution to another)..</div>
<div class="required req-true">Yes</div>
</div>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="Synchronizing_Timer">Synchronizing Timer<a class="sectionlink" href="#Synchronizing_Timer" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>
The purpose of the SyncTimer is to block threads until X number of threads have been blocked, and
then they are all released at once. A SyncTimer can thus create large instant loads at various
points of the test plan.
</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/timers/sync_timer.png"><img src="../images/screenshots/timers/sync_timer.png" width="410" height="145" alt="Screenshot for Control-Panel of Synchronizing Timer"></a>
<figcaption>Screenshot of Control-Panel of Synchronizing Timer</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="Synchronizing_Timer_parms1">
Parameters
<a class="sectionlink" href="#Synchronizing_Timer_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-false">Descriptive name for this timer that is shown in the tree. </div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Number of Simultaneous Users to Group by</div>
<div class="description req-true">Number of threads to release at once. Setting it to <span class="code">0</span> is equivalent to setting it to Number of threads in Thread Group.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Timeout in milliseconds</div>
<div class="description req-false">If set to <span class="code">0</span>, Timer will wait for the number of threads to reach the value in "<span class="code">Number of Simultaneous Users to Group</span>". If superior to <span class="code">0</span>, then timer will wait at max "<span class="code">Timeout in milliseconds</span>" for the number of Threads. If after the timeout interval the number of users waiting is not reached, timer will stop waiting. Defaults to <span class="code">0</span>
</div>
<div class="required req-false">No</div>
</div>
</div>
<div class="clear"></div>
<div class="note">
If timeout in milliseconds is set to <span class="code">0</span> and number of threads never reaches "<span class="code">Number of Simultaneous Users to Group by</span>" then Test will pause infinitely.
Only a forced stop will stop it. Setting Timeout in milliseconds is an option to consider in this case.
</div>
<div class="clear"></div>
<div class="clear"></div>
<div class="note">
Synchronizing timer blocks only within one JVM, so if using Distributed testing ensure you never set "<span class="code">Number of Simultaneous Users to Group by</span>" to a value superior to the number of users
of its containing Thread group considering 1 injector only.
</div>
<div class="clear"></div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="BeanShell_Timer">BeanShell Timer<a class="sectionlink" href="#BeanShell_Timer" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>
The BeanShell Timer can be used to generate a delay.
</p>
<p>
<b>For full details on using BeanShell, please see the <a href="http://www.beanshell.org/">BeanShell website.</a></b>
<div class="clear"></div>
<div class="note">Migration to <a href="../usermanual/component_reference.html#JSR223_Timer">JSR223 Timer</a>+Groovy is highly recommended for performance, support of new Java features and limited maintenance of the BeanShell library.</div>
<div class="clear"></div>
</p>
<p>
The test element supports the <span class="code">ThreadListener</span> and <span class="code">TestListener</span> methods.
These should be defined in the initialisation file.
See the file <span class="code">BeanShellListeners.bshrc</span> for example definitions.
</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/timers/beanshell_timer.png"><img src="../images/screenshots/timers/beanshell_timer.png" width="846" height="636" alt="Screenshot for Control-Panel of BeanShell Timer"></a>
<figcaption>Screenshot of Control-Panel of BeanShell Timer</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="BeanShell_Timer_parms1">
Parameters
<a class="sectionlink" href="#BeanShell_Timer_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-false">Descriptive name for this element that is shown in the tree.
The name is stored in the script variable <span class="code">Label</span>
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Reset bsh.Interpreter before each call</div>
<div class="description req-true">
If this option is selected, then the interpreter will be recreated for each sample.
This may be necessary for some long running scripts.
For further information, see <a href="best-practices.html#bsh_scripting">Best Practices - BeanShell scripting</a>.
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Parameters</div>
<div class="description req-false">Parameters to pass to the BeanShell script.
The parameters are stored in the following variables:
<ul>
<li>
<span class="code">Parameters</span> - string containing the parameters as a single variable</li>
<li>
<span class="code">bsh.args</span> - String array containing parameters, split on white-space</li>
</ul>
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Script file</div>
<div class="description req-false">
A file containing the BeanShell script to run.
The file name is stored in the script variable <span class="code">FileName</span>
The return value is used as the number of milliseconds to wait.
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Script</div>
<div class="description req-true">
The BeanShell script. The return value is used as the number of milliseconds to wait.
</div>
<div class="required req-true">Yes (unless script file is provided)</div>
</div>
</div>
<p>Before invoking the script, some variables are set up in the BeanShell interpreter:</p>
<ul>
<li>
<span class="code">log</span> - (<a href="https://www.slf4j.org/api/org/slf4j/Logger.html">Logger</a>) - can be used to write to the log file</li>
<li>
<span class="code">ctx</span> - (<a href="../api/org/apache/jmeter/threads/JMeterContext.html">JMeterContext</a>) - gives access to the context</li>
<li>
<span class="code">vars</span> - (<a href="../api/org/apache/jmeter/threads/JMeterVariables.html">JMeterVariables</a>) - gives read/write access to variables: <pre class="source">
vars.get(key);
vars.put(key,val);
vars.putObject("OBJ1",new Object());
</pre>
</li>
<li>
<span class="code">props</span> - (JMeterProperties - class java.util.Properties) - e.g. <span class="code">props.get("START.HMS");</span> <span class="code">props.put("PROP1","1234");</span>
</li>
<li>
<span class="code">prev</span> - (<a href="../api/org/apache/jmeter/samplers/SampleResult.html">SampleResult</a>) - gives access to the previous <span class="code">SampleResult</span> (if any)</li>
</ul>
<p>For details of all the methods available on each of the above variables, please check the Javadoc</p>
<p>If the property <span class="code">beanshell.timer.init</span> is defined, this is used to load an initialisation file, which can be used to define methods etc. for use in the BeanShell script.</p>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="JSR223_Timer">JSR223 Timer<a class="sectionlink" href="#JSR223_Timer" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>
The JSR223 Timer can be used to generate a delay using a JSR223 scripting language,
</p>
</div>
<div class="properties">
<h3 id="JSR223_Timer_parms1">
Parameters
<a class="sectionlink" href="#JSR223_Timer_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-false">Descriptive name for this element that is shown in the tree.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">ScriptLanguage</div>
<div class="description req-true">
The scripting language to be used.
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Parameters</div>
<div class="description req-false">Parameters to pass to the script.
The parameters are stored in the following variables:
<ul>
<li>
<span class="code">Parameters</span> - string containing the parameters as a single variable</li>
<li>
<span class="code">args</span> - String array containing parameters, split on white-space</li>
</ul>
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Script file</div>
<div class="description req-false">
A file containing the script to run, if a relative file path is used, then it will be relative to directory referenced by "<span class="code">user.dir</span>" System property
The return value is converted to a long integer and used as the number of milliseconds to wait.
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Script compilation caching</div>
<div class="description req-false">Unique String across Test Plan that JMeter will use to cache result of Script compilation if language used supports <span class="code"><a href="https://docs.oracle.com/javase/8/docs/api/javax/script/Compilable.html">Compilable</a></span> interface (Groovy is one of these, java, beanshell and javascript are not)
<div class="clear"></div>
<div class="note">See note in JSR223 Sampler Java System property if you're using Groovy without checking this option</div>
<div class="clear"></div>
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Script</div>
<div class="description req-true">
The script. The return value is used as the number of milliseconds to wait.
</div>
<div class="required req-true">Yes (unless script file is provided)</div>
</div>
</div>
<p>Before invoking the script, some variables are set up in the script interpreter:</p>
<ul>
<li>
<span class="code">log</span> - (<a href="https://www.slf4j.org/api/org/slf4j/Logger.html">Logger</a>) - can be used to write to the log file</li>
<li>
<span class="code">ctx</span> - (<a href="../api/org/apache/jmeter/threads/JMeterContext.html">JMeterContext</a>) - gives access to the context</li>
<li>
<span class="code">vars</span> - (<a href="../api/org/apache/jmeter/threads/JMeterVariables.html">JMeterVariables</a>) - gives read/write access to variables: <pre class="source">vars.get(key);
vars.put(key,val);
vars.putObject("OBJ1",new Object());</pre>
</li>
<li>
<span class="code">props</span> - (JMeterProperties - class java.util.Properties) - e.g. <span class="code">props.get("START.HMS");</span> <span class="code">props.put("PROP1","1234");</span>
</li>
<li>
<span class="code">sampler</span> - (<a href="../api/org/apache/jmeter/samplers/Sampler.html">Sampler</a>) - the current Sampler</li>
<li>
<span class="code">Label</span> - the name of the Timer</li>
<li>
<span class="code">FileName</span> - the file name (if any)</li>
<li>
<span class="code">OUT</span> - System.out</li>
</ul>
<p>For details of all the methods available on each of the above variables, please check the Javadoc</p>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="Poisson_Random_Timer">Poisson Random Timer<a class="sectionlink" href="#Poisson_Random_Timer" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>This timer pauses each thread request for a random amount of time, with most
of the time intervals occurring near a particular value. The total delay is the
sum of the Poisson distributed value, and the offset value.</p>
<p>Note: if you want to model Poisson arrivals, consider using <a href="../usermanual/component_reference.html#Precise_Throughput_Timer">Precise Throughput Timer</a> instead.</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/timers/poisson_random_timer.png"><img src="../images/screenshots/timers/poisson_random_timer.png" width="341" height="182" alt="Screenshot for Control-Panel of Poisson Random Timer"></a>
<figcaption>Screenshot of Control-Panel of Poisson Random Timer</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="Poisson_Random_Timer_parms1">
Parameters
<a class="sectionlink" href="#Poisson_Random_Timer_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-false">Descriptive name for this timer that is shown in the tree</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Lambda</div>
<div class="description req-true">Lambda value in milliseconds.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Constant Delay Offset</div>
<div class="description req-true">Number of milliseconds to pause in addition
to the random delay.</div>
<div class="required req-true">Yes</div>
</div>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<a href="#">^</a>
</div>
<div class="section">
<h1 id="preprocessors">18.7 Pre Processors<a class="sectionlink" href="#preprocessors" title="Link to here">&para;</a>
</h1>
<div class="description">
<br>
Preprocessors are used to modify the Samplers in their scope.
<br>
</div>
<div class="component">
<h2 id="HTML_Link_Parser">HTML Link Parser<a class="sectionlink" href="#HTML_Link_Parser" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>This modifier parses HTML response from the server and extracts
links and forms. A URL test sample that passes through this modifier will be examined to
see if it "matches" any of the links or forms extracted
from the immediately previous response. It would then replace the values in the URL
test sample with appropriate values from the matching link or form. Perl-type regular
expressions are used to find matches.</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/html_link_parser.png"><img src="../images/screenshots/html_link_parser.png" width="373" height="79" alt="Screenshot for Control-Panel of HTML Link Parser"></a>
<figcaption>Screenshot of Control-Panel of HTML Link Parser</figcaption>
</figure>
</div>
<div class="clear"></div>
<div class="note">
Matches are performed using <span class="code">protocol</span>, <span class="code">host</span>, <span class="code">path</span> and <span class="code">parameter names</span>.
The target sampler cannot contain parameters that are not in the response links.
</div>
<div class="clear"></div>
<div class="clear"></div>
<div class="note">
If using distributed testing, ensure you switch mode (see <span class="code">jmeter.properties</span>) so that it's not a stripping one, see <a href="https://bz.apache.org/bugzilla/show_bug.cgi?id=56376">
Bug
56376</a>
</div>
<div class="clear"></div>
<div class="example">
<div class="title">Spidering Example<a class="sectionlink" href="#spider_example" title="Link to here">&para;</a>
</div>
<p>Consider a simple example: let's say you wanted JMeter to "spider" through your site,
hitting link after link parsed from the HTML returned from your server (this is not
actually the most useful thing to do, but it serves as a good example). You would create
a <a href="../usermanual/component_reference.html#Simple_Controller">Simple Controller</a>, and add the "HTML Link Parser" to it. Then, create an
HTTP Request, and set the domain to "<span class="code">.*</span>", and the path likewise. This will
cause your test sample to match with any link found on the returned pages. If you wanted to
restrict the spidering to a particular domain, then change the domain value
to the one you want. Then, only links to that domain will be followed.
</p>
</div>
<div class="example">
<div class="title">Poll Example<a class="sectionlink" href="#poll_example" title="Link to here">&para;</a>
</div>
<p>A more useful example: given a web polling application, you might have a page with
several poll options as radio buttons for the user to select. Let's say the values
of the poll options are very dynamic - maybe user generated. If you wanted JMeter to
test the poll, you could either create test samples with hardcoded values chosen, or you
could let the HTML Link Parser parse the form, and insert a random poll option into
your URL test sample. To do this, follow the above example, except, when configuring
your Web Test controller's URL options, be sure to choose "<span class="code">POST</span>" as the
method. Put in hard-coded values for the <span class="code">domain</span>, <span class="code">path</span>, and any additional form parameters.
Then, for the actual radio button parameter, put in the name (let's say it's called "<span class="code">poll_choice</span>"),
and then "<span class="code">.*</span>" for the value of that parameter. When the modifier examines
this URL test sample, it will find that it "matches" the poll form (and
it shouldn't match any other form, given that you've specified all the other aspects of
the URL test sample), and it will replace your form parameters with the matching
parameters from the form. Since the regular expression "<span class="code">.*</span>" will match with
anything, the modifier will probably have a list of radio buttons to choose from. It
will choose at random, and replace the value in your URL test sample. Each time through
the test, a new random value will be chosen.</p>
<figure>
<a href="../images/screenshots/modification.png"><img src="../images/screenshots/modification.png" width="1250" height="493" alt="Figure 18 - Online Poll Example"></a>
<figcaption>Figure 18 - Online Poll Example</figcaption>
</figure>
<div class="clear"></div>
<div class="note">One important thing to remember is that you must create a test sample immediately
prior that will return an HTML page with the links and forms that are relevant to
your dynamic test sample.</div>
<div class="clear"></div>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="HTTP_URL_Re-writing_Modifier">HTTP URL Re-writing Modifier<a class="sectionlink" href="#HTTP_URL_Re-writing_Modifier" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>This modifier works similarly to the HTML Link Parser, except it has a specific purpose for which
it is easier to use than the HTML Link Parser, and more efficient. For web applications that
use URL Re-writing to store session ids instead of cookies, this element can be attached at the
ThreadGroup level, much like the <a href="../usermanual/component_reference.html#HTTP_Cookie_Manager">HTTP Cookie Manager</a>. Simply give it the name
of the session id parameter, and it will find it on the page and add the argument to every
request of that ThreadGroup.</p>
<p>Alternatively, this modifier can be attached to select requests and it will modify only them.
Clever users will even determine that this modifier can be used to grab values that elude the
<a href="../usermanual/component_reference.html#HTML_Link_Parser">HTML Link Parser</a>.</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/url_rewriter.png"><img src="../images/screenshots/url_rewriter.png" width="579" height="239" alt="Screenshot for Control-Panel of HTTP URL Re-writing Modifier"></a>
<figcaption>Screenshot of Control-Panel of HTTP URL Re-writing Modifier</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="HTTP_URL_Re-writing_Modifier_parms1">
Parameters
<a class="sectionlink" href="#HTTP_URL_Re-writing_Modifier_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-false">Descriptive name given to this element in the test tree.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Session Argument Name</div>
<div class="description req-true">The name of the parameter to grab from
previous response. This modifier will find the parameter anywhere it exists on the page, and
grab the value assigned to it, whether it's in an HREF or a form.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Path Extension</div>
<div class="description req-false">Some web apps rewrite URLs by appending
a semi-colon plus the session id parameter. Check this box if that is so.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Do not use equals in path extension</div>
<div class="description req-false">Some web apps rewrite URLs without using an "<span class="code">=</span>" sign between the parameter name and value (such as Intershop Enfinity).</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Do not use questionmark in path extension</div>
<div class="description req-false">Prevents the query string to end up in the path extension (such as Intershop Enfinity).</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Cache Session Id?</div>
<div class="description req-true">
Should the value of the session Id be saved for later use when the session Id is not present?
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">URL Encode</div>
<div class="description req-false">
URL Encode value when writing parameter
</div>
<div class="required req-false">No</div>
</div>
</div>
<div class="clear"></div>
<div class="note">
If using distributed testing, ensure you switch mode (see <span class="code">jmeter.properties</span>) so that it's not a stripping one, see <a href="https://bz.apache.org/bugzilla/show_bug.cgi?id=56376">
Bug
56376</a>.
</div>
<div class="clear"></div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="User_Parameters">User Parameters<a class="sectionlink" href="#User_Parameters" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>Allows the user to specify values for User Variables specific to individual threads.</p>
<p>User Variables can also be specified in the Test Plan but not specific to individual threads. This panel allows
you to specify a series of values for any User Variable. For each thread, the variable will be assigned one of the values from the series
in sequence. If there are more threads than values, the values get re-used. For example, this can be used to assign a distinct
user id to be used by each thread. User variables can be referenced in any field of any JMeter Component.</p>
<p>The variable is specified by clicking the <span class="code">Add Variable</span> button in the bottom of the panel and filling in the Variable name in the '<span class="code">Name:</span>' column.
To add a new value to the series, click the '<span class="code">Add User</span>' button and fill in the desired value in the newly added column.</p>
<p>Values can be accessed in any test component in the same thread group, using the <a href="functions.html">function syntax</a>: <span class="code">${variable}</span>.</p>
<p>See also the <a href="../usermanual/component_reference.html#CSV_Data_Set_Config">CSV Data Set Config</a> element, which is more suitable for large numbers of parameters</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/user_params.png"><img src="../images/screenshots/user_params.png" width="703" height="303" alt="Screenshot for Control-Panel of User Parameters"></a>
<figcaption>Screenshot of Control-Panel of User Parameters</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="User_Parameters_parms1">
Parameters
<a class="sectionlink" href="#User_Parameters_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-true">Descriptive name for this element that is shown in the tree.</div>
<div class="required req-true"></div>
</div>
<div class="property">
<div class="name req-true">Update Once Per Iteration</div>
<div class="description req-true">A flag to indicate whether the User Parameters element
should update its variables only once per iteration. if you embed functions into the UP, then you may need greater
control over how often the values of the variables are updated. Keep this box checked to ensure the values are
updated each time through the UP's parent controller. Uncheck the box, and the UP will update the parameters for
every sample request made within its <a href="test_plan.html#scoping_rules">scope</a>.</div>
<div class="required req-true">Yes</div>
</div>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="BeanShell_PreProcessor">BeanShell PreProcessor<a class="sectionlink" href="#BeanShell_PreProcessor" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>
The BeanShell PreProcessor allows arbitrary code to be applied before taking a sample.
</p>
<p>
<b>For full details on using BeanShell, please see the <a href="http://www.beanshell.org/">BeanShell website.</a></b>
<div class="clear"></div>
<div class="note">Migration to <a href="../usermanual/component_reference.html#JSR223_PreProcessor">JSR223 PreProcessor</a>+Groovy is highly recommended for performance, support of new Java features and limited maintenance of the BeanShell library.</div>
<div class="clear"></div>
</p>
<p>
The test element supports the <span class="code">ThreadListener</span> and <span class="code">TestListener</span> methods.
These should be defined in the initialisation file.
See the file <span class="code">BeanShellListeners.bshrc</span> for example definitions.
</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/beanshell_preprocessor.png"><img src="../images/screenshots/beanshell_preprocessor.png" width="845" height="633" alt="Screenshot for Control-Panel of BeanShell PreProcessor"></a>
<figcaption>Screenshot of Control-Panel of BeanShell PreProcessor</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="BeanShell_PreProcessor_parms1">
Parameters
<a class="sectionlink" href="#BeanShell_PreProcessor_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-false">Descriptive name for this element that is shown in the tree.
The name is stored in the script variable <span class="code">Label</span>
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Reset bsh.Interpreter before each call</div>
<div class="description req-true">
If this option is selected, then the interpreter will be recreated for each sample.
This may be necessary for some long running scripts.
For further information, see <a href="best-practices.html#bsh_scripting">Best Practices - BeanShell scripting</a>.
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Parameters</div>
<div class="description req-false">Parameters to pass to the BeanShell script.
The parameters are stored in the following variables:
<ul>
<li>
<span class="code">Parameters</span> - string containing the parameters as a single variable</li>
<li>
<span class="code">bsh.args</span> - String array containing parameters, split on white-space</li>
</ul>
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Script file</div>
<div class="description req-false">A file containing the BeanShell script to run.
The file name is stored in the script variable <span class="code">FileName</span>
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Script</div>
<div class="description req-true">The BeanShell script. The return value is ignored.</div>
<div class="required req-true">Yes (unless script file is provided)</div>
</div>
</div>
<p>Before invoking the script, some variables are set up in the BeanShell interpreter:</p>
<ul>
<li>
<span class="code">log</span> - (<a href="https://www.slf4j.org/api/org/slf4j/Logger.html">Logger</a>) - can be used to write to the log file</li>
<li>
<span class="code">ctx</span> - (<a href="../api/org/apache/jmeter/threads/JMeterContext.html">JMeterContext</a>) - gives access to the context</li>
<li>
<span class="code">vars</span> - (<a href="../api/org/apache/jmeter/threads/JMeterVariables.html">JMeterVariables</a>) - gives read/write access to variables: <pre class="source">vars.get(key);
vars.put(key,val);
vars.putObject("OBJ1",new Object());</pre>
</li>
<li>
<span class="code">props</span> - (JMeterProperties - class java.util.Properties) - e.g. <span class="code">props.get("START.HMS");</span> <span class="code">props.put("PROP1","1234");</span>
</li>
<li>
<span class="code">prev</span> - (<a href="../api/org/apache/jmeter/samplers/SampleResult.html">SampleResult</a>) - gives access to the previous SampleResult (if any)</li>
<li>
<span class="code">sampler</span> - (<a href="../api/org/apache/jmeter/samplers/Sampler.html">Sampler</a>)- gives access to the current sampler</li>
</ul>
<p>For details of all the methods available on each of the above variables, please check the Javadoc</p>
<p>If the property <span class="code">beanshell.preprocessor.init</span> is defined, this is used to load an initialisation file, which can be used to define methods etc. for use in the BeanShell script.</p>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="JSR223_PreProcessor">JSR223 PreProcessor<a class="sectionlink" href="#JSR223_PreProcessor" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>
The JSR223 PreProcessor allows JSR223 script code to be applied before taking a sample.
</p>
</div>
<div class="properties">
<h3 id="JSR223_PreProcessor_parms1">
Parameters
<a class="sectionlink" href="#JSR223_PreProcessor_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-false">Descriptive name for this element that is shown in the tree.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Language</div>
<div class="description req-true">The JSR223 language to be used</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Parameters</div>
<div class="description req-false">Parameters to pass to the script.
The parameters are stored in the following variables:
<ul>
<li>
<span class="code">Parameters</span> - string containing the parameters as a single variable</li>
<li>
<span class="code">args</span> - String array containing parameters, split on white-space</li>
</ul>
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Script file</div>
<div class="description req-false">A file containing the script to run, if a relative file path is used, then it will be relative to directory referenced by "<span class="code">user.dir</span>" System property</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Script compilation caching</div>
<div class="description req-false">Unique String across Test Plan that JMeter will use to cache result of Script compilation if language used supports <span class="code"><a href="https://docs.oracle.com/javase/8/docs/api/javax/script/Compilable.html">Compilable</a></span> interface (Groovy is one of these, java, beanshell and javascript are not)
<div class="clear"></div>
<div class="note">See note in JSR223 Sampler Java System property if you're using Groovy without checking this option</div>
<div class="clear"></div>
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Script</div>
<div class="description req-true">The script to run.</div>
<div class="required req-true">Yes (unless script file is provided)</div>
</div>
</div>
<p>The following JSR223 variables are set up for use by the script:</p>
<ul>
<li>
<span class="code">log</span> - (<a href="https://www.slf4j.org/api/org/slf4j/Logger.html">Logger</a>) - can be used to write to the log file</li>
<li>
<span class="code">Label</span> - the String Label</li>
<li>
<span class="code">FileName</span> - the script file name (if any)</li>
<li>
<span class="code">Parameters</span> - the parameters (as a String)</li>
<li>
<span class="code">args</span> - the parameters as a String array (split on whitespace)</li>
<li>
<span class="code">ctx</span> - (<a href="../api/org/apache/jmeter/threads/JMeterContext.html">JMeterContext</a>) - gives access to the context</li>
<li>
<span class="code">vars</span> - (<a href="../api/org/apache/jmeter/threads/JMeterVariables.html">JMeterVariables</a>) - gives read/write access to variables: <pre class="source">vars.get(key);
vars.put(key,val);
vars.putObject("OBJ1",new Object());
vars.getObject("OBJ2");</pre>
</li>
<li>
<span class="code">props</span> - (JMeterProperties - class java.util.Properties) - e.g. <span class="code">props.get("START.HMS");</span> <span class="code">props.put("PROP1","1234");</span>
</li>
<li>
<span class="code">sampler</span> - (<a href="../api/org/apache/jmeter/samplers/Sampler.html">Sampler</a>)- gives access to the current sampler</li>
<li>
<span class="code">OUT</span> - System.out - e.g. <span class="code">OUT.println("message")</span>
</li>
</ul>
<p>For details of all the methods available on each of the above variables, please check the Javadoc</p>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="JDBC_PreProcessor">JDBC PreProcessor<a class="sectionlink" href="#JDBC_PreProcessor" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>
The JDBC PreProcessor enables you to run some SQL statement just before a sample runs.
This can be useful if your JDBC Sample requires some data to be in DataBase and you cannot compute this in a setup Thread group.
For details, see <a href="../usermanual/component_reference.html#JDBC_Request">JDBC Request</a>.
</p>
<p>
See the following Test plan:
</p>
<div class="links">
<div class="title">See also:</div>
<ul class="links">
<li>
<a href="../demos/JDBC-Pre-Post-Processor.jmx">Test Plan using JDBC Pre/Post Processor</a>
</li>
</ul>
</div>
<p>
In the linked test plan, "<span class="code">Create Price Cut-Off</span>" JDBC PreProcessor calls a stored procedure to create a Price Cut-Off in Database,
this one will be used by "<span class="code">Calculate Price cut off</span>".
</p>
<figure>
<a href="../images/screenshots/jdbc-pre-processor.png"><img src="../images/screenshots/jdbc-pre-processor.png" width="818" height="394" alt="Create Price Cut-Off Preprocessor"></a>
<figcaption>Create Price Cut-Off Preprocessor</figcaption>
</figure>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="RegEx_User_Parameters">RegEx User Parameters<a class="sectionlink" href="#RegEx_User_Parameters" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>Allows to specify dynamic values for HTTP parameters extracted from another HTTP Request using regular expressions.
RegEx User Parameters are specific to individual threads.</p>
<p>This component allows you to specify reference name of a regular expression that extracts names and values of HTTP request parameters.
Regular expression group numbers must be specified for parameter's name and also for parameter's value.
Replacement will only occur for parameters in the Sampler that uses this RegEx User Parameters which name matches </p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/regex_user_params.png"><img src="../images/screenshots/regex_user_params.png" width="727" height="138" alt="Screenshot for Control-Panel of RegEx User Parameters"></a>
<figcaption>Screenshot of Control-Panel of RegEx User Parameters</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="RegEx_User_Parameters_parms1">
Parameters
<a class="sectionlink" href="#RegEx_User_Parameters_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-true">Descriptive name for this element that is shown in the tree.</div>
<div class="required req-true"></div>
</div>
<div class="property">
<div class="name req-true">Regular Expression Reference Name</div>
<div class="description req-true">Name of a reference to a regular expression</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Parameter names regexp group number</div>
<div class="description req-true">Group number of regular expression used to extract parameter names</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Parameter values regex group number</div>
<div class="description req-true">Group number of regular expression used to extract parameter values</div>
<div class="required req-true">Yes</div>
</div>
</div>
<div class="example">
<div class="title">Regexp Example<a class="sectionlink" href="#regex_user_param_example" title="Link to here">&para;</a>
</div>
<p>Suppose we have a request which returns a form with 3 input parameters and we want to extract the value of 2 of them to inject them in next request</p>
<ol>
<li>Create Post Processor Regular Expression for first HTTP Request
<ul>
<li>
<span class="code">refName</span> - set name of a regular expression Expression (<span class="code">listParams</span>)</li>
<li>
<span class="code">regular expression</span> - expression that will extract input names and input values attributes
<br>
Ex: <span class="code">input name="([^"]+?)" value="([^"]+?)"</span>
</li>
<li>
<span class="code">template</span> - would be empty</li>
<li>
<span class="code">match nr</span> - <span class="code">-1</span> (in order to iterate through all the possible matches)</li>
</ul>
</li>
<li>Create Pre Processor RegEx User Parameters for second HTTP Request
<ul>
<li>
<span class="code">refName</span> - set the same reference name of a regular expression, would be <span class="code">listParams</span> in our example</li>
<li>
<span class="code">parameter names group number</span> - group number of regular expression for parameter names, would be <span class="code">1</span> in our example</li>
<li>
<span class="code">parameter values group number</span> - group number of regular expression for parameter values, would be <span class="code">2</span> in our example</li>
</ul>
</li>
</ol>
</div>
<p>See also the <a href="../usermanual/component_reference.html#Regular_Expression_Extractor">Regular Expression Extractor</a> element, which is used to extract parameters names and values</p>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="links">
<div class="title">See also:</div>
<ul class="links">
<li>
<a href="../demos/RegEx-User-Parameters.jmx">Test Plan showing how to use RegEx User Parameters</a>
</li>
</ul>
</div>
<div class="component">
<h2 id="Sample_Timeout">Sample Timeout<a class="sectionlink" href="#Sample_Timeout" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>This Pre-Processor schedules a timer task to interrupt a sample if it takes too long to complete.
The timeout is ignored if it is zero or negative.
For this to work, the sampler must implement Interruptible.
The following samplers are known to do so:<br>
AJP, BeanShell, FTP, HTTP, Soap, AccessLog, MailReader, JMS Subscriber, TCPSampler, TestAction, JavaSampler
</p>
<p>
The test element is intended for use where individual timeouts such as Connection Timeout or Response Timeout are insufficient,
or where the Sampler does not support timeouts.
The timeout should be set sufficiently long so that it is not triggered in normal tests, but short enough that it interrupts samples
that are stuck.
</p>
<p>
[By default, JMeter uses a Callable to interrupt the sampler.
This executes in the same thread as the timer, so if the interrupt takes a long while,
it may delay the processing of subsequent timeouts.
This is not expected to be a problem, but if necessary the property <span class="code">InterruptTimer.useRunnable</span>
can be set to <span class="code">true</span> to use a separate Runnable thread instead of the Callable.]
</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/sample_timeout.png"><img src="../images/screenshots/sample_timeout.png" width="316" height="138" alt="Screenshot for Control-Panel of Sample Timeout"></a>
<figcaption>Screenshot of Control-Panel of Sample Timeout</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="Sample_Timeout_parms1">
Parameters
<a class="sectionlink" href="#Sample_Timeout_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-false">Descriptive name for this timer that is shown in the tree.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Sample Timeout</div>
<div class="description req-true">If the sample takes longer to complete, it will be interrupted.</div>
<div class="required req-true">Yes</div>
</div>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<a href="#">^</a>
</div>
<div class="section">
<h1 id="postprocessors">18.8 Post-Processors<a class="sectionlink" href="#postprocessors" title="Link to here">&para;</a>
</h1>
<div class="description">
<p>
As the name suggests, Post-Processors are applied after samplers. Note that they are
applied to <b>all</b> the samplers in the same scope, so to ensure that a post-processor
is applied only to a particular sampler, add it as a child of the sampler.
</p>
<div class="clear"></div>
<div class="note">
Note: Unless documented otherwise, Post-Processors are not applied to sub-samples (child samples) -
only to the parent sample.
In the case of JSR223 and BeanShell post-processors, the script can retrieve sub-samples using the method
<span class="code">prev.getSubResults()</span> which returns an array of SampleResults.
The array will be empty if there are none.
</div>
<div class="clear"></div>
<p>
Post-Processors are run before Assertions, so they do not have access to any Assertion Results, nor will
the sample status reflect the results of any Assertions. If you require access to Assertion Results, try
using a Listener instead. Also note that the variable <span class="code">JMeterThread.last_sample_ok</span> is set to "<span class="code">true</span>" or "<span class="code">false</span>"
after all Assertions have been run.
</p>
</div>
<div class="component">
<h2 id="Regular_Expression_Extractor">Regular Expression Extractor<a class="sectionlink" href="#Regular_Expression_Extractor" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>Allows the user to extract values from a server response using a Perl-type regular expression. As a post-processor,
this element will execute after each Sample request in its scope, applying the regular expression, extracting the requested values,
generate the template string, and store the result into the given variable name.</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/regex_extractor.png"><img src="../images/screenshots/regex_extractor.png" width="1127" height="277" alt="Screenshot for Control-Panel of Regular Expression Extractor"></a>
<figcaption>Screenshot of Control-Panel of Regular Expression Extractor</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="Regular_Expression_Extractor_parms1">
Parameters
<a class="sectionlink" href="#Regular_Expression_Extractor_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-true">Descriptive name for this element that is shown in the tree.</div>
<div class="required req-true"></div>
</div>
<div class="property">
<div class="name req-true">Apply to:</div>
<div class="description req-true">
This is for use with samplers that can generate sub-samples,
e.g. HTTP Sampler with embedded resources, Mail Reader or samples generated by the Transaction Controller.
<ul>
<li>
<span class="code">Main sample only</span> - only applies to the main sample</li>
<li>
<span class="code">Sub-samples only</span> - only applies to the sub-samples</li>
<li>
<span class="code">Main sample and sub-samples</span> - applies to both.</li>
<li>
<span class="code">JMeter Variable Name to use</span> - extraction is to be applied to the contents of the named variable</li>
</ul>
Matching is applied to all qualifying samples in turn.
For example if there is a main sample and 3 sub-samples, each of which contains a single match for the regex,
(i.e. 4 matches in total).
For match number = <span class="code">3</span>, Sub-samples only, the extractor will match the 3<sup>rd</sup> sub-sample.
For match number = <span class="code">3</span>, Main sample and sub-samples, the extractor will match the 2<sup>nd</sup> sub-sample (1<sup>st</sup> match is main sample).
For match number = <span class="code">0</span> or negative, all qualifying samples will be processed.
For match number &gt; <span class="code">0</span>, matching will stop as soon as enough matches have been found.
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Field to check</div>
<div class="description req-true">
The following fields can be checked:
<ul>
<li>
<span class="code">Body</span> - the body of the response, e.g. the content of a web-page (excluding headers)</li>
<li>
<span class="code">Body (unescaped)</span> - the body of the response, with all Html escape codes replaced.
Note that Html escapes are processed without regard to context, so some incorrect substitutions
may be made.
<div class="clear"></div>
<div class="note">Note that this option highly impacts performances, so use it only when absolutely necessary and be aware of its impacts</div>
<div class="clear"></div>
</li>
<li>
<span class="code">Body as a Document</span> - the extract text from various type of documents via Apache Tika (see <a href="../usermanual/component_reference.html#View_Results_Tree">View Results Tree</a> Document view section).
<div class="clear"></div>
<div class="note">Note that the Body as a Document option can impact performances, so ensure it is OK for your test</div>
<div class="clear"></div>
</li>
<li>
<span class="code">Request Headers</span> - may not be present for non-HTTP samples</li>
<li>
<span class="code">Response Headers</span> - may not be present for non-HTTP samples</li>
<li>
<span class="code">URL</span>
</li>
<li>
<span class="code">Response Code</span> - e.g. <span class="code">200</span>
</li>
<li>
<span class="code">Response Message</span> - e.g. <span class="code">OK</span>
</li>
</ul>
Headers can be useful for HTTP samples; it may not be present for other sample types.
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Name of created variable</div>
<div class="description req-true">The name of the JMeter variable in which to store the result. Also note that each group is stored as <span class="code">[refname]_g#</span>, where <span class="code">[refname]</span> is the string you entered as the reference name, and <span class="code">#</span> is the group number, where group <span class="code">0</span> is the entire match, group <span class="code">1</span> is the match from the first set of parentheses, etc.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Regular Expression</div>
<div class="description req-true">The regular expression used to parse the response data.
This must contain at least one set of parentheses "<span class="code">()</span>" to capture a portion of the string, unless using the group <span class="code">$0$</span>.
Do not enclose the expression in <span class="code">/ /</span> - unless of course you want to match these characters as well.
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Template</div>
<div class="description req-true">The template used to create a string from the matches found. This is an arbitrary string
with special elements to refer to groups within the regular expression. The syntax to refer to a group is: '<span class="code">$1$</span>' to refer to
group <span class="code">1</span>, '<span class="code">$2$</span>' to refer to group <span class="code">2</span>, etc. <span class="code">$0$</span> refers to whatever the entire expression matches.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Match No. (0 for Random)</div>
<div class="description req-true">Indicates which match to use. The regular expression may match multiple times.
<ul>
<li>Use a value of zero to indicate JMeter should choose a match at random.</li>
<li>A positive number N means to select the n<sup>th</sup> match.</li>
<li> Negative numbers are used in conjunction with the <a href="../usermanual/component_reference.html#ForEach_Controller">ForEach Controller</a> - see below.</li>
</ul>
</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">
If the regular expression does not match, then the reference variable will be set to the default value.
This is particularly useful for debugging tests. If no default is provided, then it is difficult to tell
whether the regular expression did not match, or the RE element was not processed or maybe the wrong variable
is being used.
<p>
However, if you have several test elements that set the same variable,
you may wish to leave the variable unchanged if the expression does not match.
In this case, remove the default value once debugging is complete.
</p>
</div>
<div class="required req-false">No, but recommended</div>
</div>
<div class="property">
<div class="name req-false">Use empty default value</div>
<div class="description req-false">
If the checkbox is checked and <span class="code">Default Value</span> is empty, then JMeter will set the variable to empty string instead of not setting it.
Thus when you will for example use <span class="code">${var}</span> (if <span class="code">Reference Name</span> is var) in your Test Plan, if the extracted value is not found then
<span class="code">${var}</span> will be equal to empty string instead of containing <span class="code">${var}</span> which may be useful if extracted value is optional.
</div>
<div class="required req-false">No</div>
</div>
</div>
<p>
If the match number is set to a non-negative number, and a match occurs, the variables are set as follows:
</p>
<ul>
<li>
<span class="code">refName</span> - the value of the template</li>
<li>
<span class="code">refName_g<em>n</em></span>, where <span class="code">n</span>=<span class="code">0</span>,<span class="code">1</span>,<span class="code">2</span> - the groups for the match</li>
<li>
<span class="code">refName_g</span> - the number of groups in the Regex (excluding <span class="code">0</span>)</li>
</ul>
<p>
If no match occurs, then the <span class="code">refName</span> variable is set to the default (unless this is absent).
Also, the following variables are removed:
</p>
<ul>
<li>
<span class="code">refName_g0</span>
</li>
<li>
<span class="code">refName_g1</span>
</li>
<li>
<span class="code">refName_g</span>
</li>
</ul>
<p>
If the match number is set to a negative number, then all the possible matches in the sampler data are processed.
The variables are set as follows:
</p>
<ul>
<li>
<span class="code">refName_matchNr</span> - the number of matches found; could be <span class="code">0</span>
</li>
<li>
<span class="code">refName_<em>n</em></span>, where <span class="code">n</span> = <span class="code">1</span>, <span class="code">2</span>, <span class="code">3</span> etc. - the strings as generated by the template</li>
<li>
<span class="code">refName_<em>n</em>_g<em>m</em></span>, where <span class="code">m</span>=<span class="code">0</span>, <span class="code">1</span>, <span class="code">2</span> - the groups for match <span class="code">n</span>
</li>
<li>
<span class="code">refName</span> - always set to the default value</li>
<li>
<span class="code">refName_g<em>n</em></span> - not set</li>
</ul>
<p>
Note that the <span class="code">refName</span> variable is always set to the default value in this case,
and the associated group variables are not set.
</p>
<p>See also <a href="../usermanual/component_reference.html#Response_Assertion">Response Assertion</a> for some examples of how to specify modifiers,
and <a href="regular_expressions.html"> for further information on JMeter regular expressions.</a>
</p>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="CSS_Selector_Extractor">CSS Selector Extractor<a name="CSS/JQuery_Extractor">
(was:
CSS/JQuery Extractor
)
</a><a class="sectionlink" href="#CSS_Selector_Extractor" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>Allows the user to extract values from a server HTML response using a CSS Selector syntax. As a post-processor,
this element will execute after each Sample request in its scope, applying the CSS/JQuery expression, extracting the requested nodes,
extracting the node as text or attribute value and store the result into the given variable name.</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/css_extractor_attr.png"><img src="../images/screenshots/css_extractor_attr.png" width="826" height="276" alt="Screenshot for Control-Panel of CSS Selector Extractor"></a>
<figcaption>Screenshot of Control-Panel of CSS Selector Extractor</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="CSS_Selector_Extractor_parms1">
Parameters
<a class="sectionlink" href="#CSS_Selector_Extractor_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-true">Descriptive name for this element that is shown in the tree.</div>
<div class="required req-true"></div>
</div>
<div class="property">
<div class="name req-true">Apply to:</div>
<div class="description req-true">
This is for use with samplers that can generate sub-samples,
e.g. HTTP Sampler with embedded resources, Mail Reader or samples generated by the Transaction Controller.
<ul>
<li>
<span class="code">Main sample only</span> - only applies to the main sample</li>
<li>
<span class="code">Sub-samples only</span> - only applies to the sub-samples</li>
<li>
<span class="code">Main sample and sub-samples</span> - applies to both.</li>
<li>
<span class="code">JMeter Variable Name to use</span> - extraction is to be applied to the contents of the named variable</li>
</ul>
Matching is applied to all qualifying samples in turn.
For example if there is a main sample and 3 sub-samples, each of which contains a single match for the regex,
(i.e. 4 matches in total).
For match number = <span class="code">3</span>, Sub-samples only, the extractor will match the 3<sup>rd</sup> sub-sample.
For match number = <span class="code">3</span>, Main sample and sub-samples, the extractor will match the 2<sup>nd</sup> sub-sample (1<sup>st</sup> match is main sample).
For match number = <span class="code">0</span> or negative, all qualifying samples will be processed.
For match number &gt; <span class="code">0</span>, matching will stop as soon as enough matches have been found.
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">CSS Selector Implementation</div>
<div class="description req-false">
2 Implementations for CSS/JQuery based syntax are supported:
<ul>
<li>
<a href="http://jsoup.org/">JSoup</a>
</li>
<li>
<a href="http://jodd.org/doc/lagarto/index.html">Jodd-Lagarto (CSSelly)</a>
</li>
</ul>
If selector is set to empty, default implementation(JSoup) will be used.
</div>
<div class="required req-false">False</div>
</div>
<div class="property">
<div class="name req-true">Name of created variable</div>
<div class="description req-true">The name of the JMeter variable in which to store the result.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">CSS/JQuery expression</div>
<div class="description req-true">The CSS/JQuery selector used to select nodes from the response data.
Selector, selectors combination and pseudo-selectors are supported, examples:
<ul>
<li>
<span class="code">E[foo]</span> - an <span class="code">E</span> element with a "<span class="code">foo</span>" attribute</li>
<li>
<span class="code">ancestor child</span> - child elements that descend from ancestor, e.g. <span class="code">.body p</span> finds <span class="code">p</span> elements anywhere under a block with class "<span class="code">body</span>"</li>
<li>
<span class="code">:lt(n)</span> - find elements whose sibling index (i.e. its position in the DOM tree relative to its parent) is less than <span class="code">n</span>; e.g. <span class="code">td:lt(3)</span>
</li>
<li>
<span class="code">:contains(text)</span> - find elements that contain the given <span class="code">text</span>. The search is case-insensitive; e.g. <span class="code">p:contains(jsoup)</span>
</li>
<li>&hellip;</li>
</ul>
For more details on syntax, see:
<ul>
<li>
<a href="http://jsoup.org/cookbook/extracting-data/selector-syntax">JSoup</a>
</li>
<li>
<a href="http://jodd.org/doc/csselly/">Jodd-Lagarto (CSSelly)</a>
</li>
</ul>
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Attribute</div>
<div class="description req-false">
Name of attribute (as per HTML syntax) to extract from nodes that matched the selector. If empty, then the combined text of this element and all its children will be returned.<br>
This is the equivalent <a href="http://jsoup.org/apidocs/org/jsoup/nodes/Node.html#attr%28java.lang.String%29">Element#attr(name)</a> function for JSoup if an attribute is set.<br>
<figure>
<a href="../images/screenshots/css_extractor_attr.png"><img src="../images/screenshots/css_extractor_attr.png" width="826" height="275" alt="CSS Extractor with attribute value set"></a>
<figcaption>CSS Extractor with attribute value set</figcaption>
</figure>
<br>
If empty this is the equivalent of <a href="http://jsoup.org/apidocs/org/jsoup/nodes/Element.html#text%28%29">Element#text()</a> function for JSoup if not value is set for attribute.
<figure>
<a href="../images/screenshots/css_extractor_noattr.png"><img src="../images/screenshots/css_extractor_noattr.png" width="825" height="275" alt="CSS Extractor with no attribute set"></a>
<figcaption>CSS Extractor with no attribute set</figcaption>
</figure>
</div>
<div class="required req-false">false</div>
</div>
<div class="property">
<div class="name req-true">Match No. (0 for Random)</div>
<div class="description req-true">Indicates which match to use. The CSS/JQuery selector may match multiple times.
<ul>
<li>Use a value of zero to indicate JMeter should choose a match at random.</li>
<li>A positive number <span class="code">N</span> means to select the n<sup>th</sup> match.</li>
<li> Negative numbers are used in conjunction with the <a href="../usermanual/component_reference.html#ForEach_Controller">ForEach Controller</a> - see below.</li>
</ul>
</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">
If the expression does not match, then the reference variable will be set to the default value.
This is particularly useful for debugging tests. If no default is provided, then it is difficult to tell
whether the expression did not match, or the CSS/JQuery element was not processed or maybe the wrong variable
is being used.
<p>
However, if you have several test elements that set the same variable,
you may wish to leave the variable unchanged if the expression does not match.
In this case, remove the default value once debugging is complete.
</p>
</div>
<div class="required req-false">No, but recommended</div>
</div>
<div class="property">
<div class="name req-false">Use empty default value</div>
<div class="description req-false">
If the checkbox is checked and <span class="code">Default Value</span> is empty, then JMeter will set the variable to empty string instead of not setting it.
Thus when you will for example use <span class="code">${var}</span> (if <span class="code">Reference Name</span> is var) in your Test Plan, if the extracted value is not found then
<span class="code">${var}</span> will be equal to empty string instead of containing <span class="code">${var}</span> which may be useful if extracted value is optional.
</div>
<div class="required req-false">No</div>
</div>
</div>
<p>
If the match number is set to a non-negative number, and a match occurs, the variables are set as follows:
</p>
<ul>
<li>
<span class="code">refName</span> - the value of the template</li>
</ul>
<p>
If no match occurs, then the <span class="code">refName</span> variable is set to the default (unless this is absent).
</p>
<p>
If the match number is set to a negative number, then all the possible matches in the sampler data are processed.
The variables are set as follows:
</p>
<ul>
<li>
<span class="code">refName_matchNr</span> - the number of matches found; could be <span class="code">0</span>
</li>
<li>
<span class="code">refName_n</span>, where <span class="code">n</span> = <span class="code">1</span>, <span class="code">2</span>, <span class="code">3</span>, etc. - the strings as generated by the template</li>
<li>
<span class="code">refName</span> - always set to the default value</li>
</ul>
<p>
Note that the <span class="code">refName</span> variable is always set to the default value in this case.
</p>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="XPath2_Extractor">XPath2 Extractor<a class="sectionlink" href="#XPath2_Extractor" title="Link to here">&para;</a>
</h2>
<div class="description">This test element allows the user to extract value(s) from structured response - XML or (X)HTML -
using XPath2 query language.
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/xpath2_extractor.png"><img src="../images/screenshots/xpath2_extractor.png" width="926" height="333" alt="Screenshot for Control-Panel of XPath2 Extractor"></a>
<figcaption>Screenshot of Control-Panel of XPath2 Extractor</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="XPath2_Extractor_parms1">
Parameters
<a class="sectionlink" href="#XPath2_Extractor_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-false">Descriptive name for this element that is shown in the tree.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Apply to:</div>
<div class="description req-true">
This is for use with samplers that can generate sub-samples,
e.g. HTTP Sampler with embedded resources, Mail Reader or samples generated by the Transaction Controller.
<ul>
<li>
<span class="code">Main sample only</span> - only applies to the main sample</li>
<li>
<span class="code">Sub-samples only</span> - only applies to the sub-samples</li>
<li>
<span class="code">Main sample and sub-samples</span> - applies to both.</li>
<li>
<span class="code">JMeter Variable Name to use</span> - extraction is to be applied to the contents of the named variable</li>
</ul>
XPath matching is applied to all qualifying samples in turn, and all the matching results will be returned.
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Return entire XPath fragment instead of text content?</div>
<div class="description req-true">
If selected, the fragment will be returned rather than the text content.<br>
For example <span class="code">//title</span> would return "<span class="code">&lt;title&gt;Apache JMeter&lt;/title&gt;</span>" rather than "<span class="code">Apache JMeter</span>".<br>
In this case, <span class="code">//title/text()</span> would return "<span class="code">Apache JMeter</span>".
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Name of created variable</div>
<div class="description req-true">The name of the JMeter variable in which to store the result.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">XPath Query</div>
<div class="description req-true">Element query in XPath 2.0 language. Can return more than one match.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Match No. (0 for Random)</div>
<div class="description req-false">If the XPath Path query leads to many results, you can choose which one(s) to extract as Variables:
<ul>
<li>
<span class="code">0</span> : means random (default value)</li>
<li>
<span class="code">-1</span> means extract all results, they will be named as <span class="code"><em>&lt;variable name&gt;</em>_N</span> (where <span class="code">N</span> goes from 1 to Number of results)</li>
<li>
<span class="code">X</span> : means extract the X<sup>th</sup> result. If this X<sup>th</sup> is greater than number of matches, then nothing is returned. Default value will be used</li>
</ul>
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Default Value</div>
<div class="description req-true">Default value returned when no match found.
It is also returned if the node has no value and the fragment option is not selected.</div>
<div class="required req-true">yes</div>
</div>
<div class="property">
<div class="name req-false">Namespaces aliases list</div>
<div class="description req-false">List of namespaces aliases you want to use to parse the document, one line per declaration.
You must specify them as follow : <span class="code">prefix=namespace</span>. This implementation makes it easier to
use namespaces than with the old XPathExtractor version.</div>
<div class="required req-false">No</div>
</div>
</div>
<p>To allow for use in a <a href="../usermanual/component_reference.html#ForEach_Controller">ForEach Controller</a>, it works exactly the same as the above XPath Extractor</p>
<p>XPath2 Extractor provides some interestings tools such as an improved syntax and much more functions than in it's first version.</p>
<p>Here are some exemples : </p>
<dl>
<dt>
<span class="code">abs(/book/page[2])</span>
</dt>
<dd>extracts 2<sup>nd</sup> absolute value of the page from a book</dd>
<dt>
<span class="code">avg(/librarie/book/page)</span>
</dt>
<dd>extracts the average number of page from all the books in the libraries</dd>
<dt>
<span class="code">compare(/book[1]/page[2],/book[2]/page[2])</span>
</dt>
<dd>return Integer value equal 0 to if the 2<sup>nd</sup> page of the first book is equal to the 2<sup>nd</sup> page of the 2<sup>nd</sup> book, else return -1.</dd>
</dl>
<p>To see more information about these functions, please check <a href="http://saxon.sourceforge.net/saxon7.9.1/functions.html">xPath2 functions</a>
</p>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="XPath_Extractor">XPath Extractor<a class="sectionlink" href="#XPath_Extractor" title="Link to here">&para;</a>
</h2>
<div class="description">This test element allows the user to extract value(s) from
structured response - XML or (X)HTML - using XPath
query language.
<div class="clear"></div>
<div class="note">Since JMeter 5.0, you should use <a href="../usermanual/component_reference.html#XPath2_Extractor">XPath2 Extractor</a> as it provides better and easier namespace management, better performances and support for XPath 2.0</div>
<div class="clear"></div>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/xpath_extractor.png"><img src="../images/screenshots/xpath_extractor.png" width="729" height="317" alt="Screenshot for Control-Panel of XPath Extractor"></a>
<figcaption>Screenshot of Control-Panel of XPath Extractor</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="XPath_Extractor_parms1">
Parameters
<a class="sectionlink" href="#XPath_Extractor_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-false">Descriptive name for this element that is shown in the tree.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Apply to:</div>
<div class="description req-true">
This is for use with samplers that can generate sub-samples,
e.g. HTTP Sampler with embedded resources, Mail Reader or samples generated by the Transaction Controller.
<ul>
<li>
<span class="code">Main sample only</span> - only applies to the main sample</li>
<li>
<span class="code">Sub-samples only</span> - only applies to the sub-samples</li>
<li>
<span class="code">Main sample and sub-samples</span> - applies to both.</li>
<li>
<span class="code">JMeter Variable Name to use</span> - extraction is to be applied to the contents of the named variable</li>
</ul>
XPath matching is applied to all qualifying samples in turn, and all the matching results will be returned.
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Use Tidy (tolerant parser)</div>
<div class="description req-true">If checked use Tidy to parse HTML response into XHTML.
<ul>
<li>"<span class="code">Use Tidy</span>" should be checked on for HTML response. Such response is converted to valid XHTML (XML compatible HTML) using Tidy</li>
<li>"<span class="code">Use Tidy</span>" should be unchecked for both XHTML or XML response (for example RSS)</li>
</ul>
<div class="clear"></div>
<div class="note">For HTML, CSS Selector Extractor is the correct and performing solution. Don't use XPath for HTML extractions.</div>
<div class="clear"></div>
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Quiet</div>
<div class="description req-false">Sets the Tidy Quiet flag</div>
<div class="required req-false">If Tidy is selected</div>
</div>
<div class="property">
<div class="name req-false">Report Errors</div>
<div class="description req-false">If a Tidy error occurs, then set the Assertion accordingly</div>
<div class="required req-false">If Tidy is selected</div>
</div>
<div class="property">
<div class="name req-false">Show warnings</div>
<div class="description req-false">Sets the Tidy showWarnings option</div>
<div class="required req-false">If Tidy is selected</div>
</div>
<div class="property">
<div class="name req-false">Use Namespaces</div>
<div class="description req-false">
If checked, then the XML parser will use namespace resolution.(see note below on NAMESPACES)
Note that currently only namespaces declared on the root element will be recognised.
See below for user-definition of additional workspace names.
</div>
<div class="required req-false">If Tidy is not selected</div>
</div>
<div class="property">
<div class="name req-false">Validate XML</div>
<div class="description req-false">Check the document against its schema.</div>
<div class="required req-false">If Tidy is not selected</div>
</div>
<div class="property">
<div class="name req-false">Ignore Whitespace</div>
<div class="description req-false">Ignore Element Whitespace.</div>
<div class="required req-false">If Tidy is not selected</div>
</div>
<div class="property">
<div class="name req-false">Fetch External DTDs</div>
<div class="description req-false">If selected, external DTDs are fetched.</div>
<div class="required req-false">If Tidy is not selected</div>
</div>
<div class="property">
<div class="name req-true">Return entire XPath fragment instead of text content?</div>
<div class="description req-true">
If selected, the fragment will be returned rather than the text content.<br>
For example <span class="code">//title</span> would return "<span class="code">&lt;title&gt;Apache JMeter&lt;/title&gt;</span>" rather than "<span class="code">Apache JMeter</span>".<br>
In this case, <span class="code">//title/text()</span> would return "<span class="code">Apache JMeter</span>".
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Name of created variable</div>
<div class="description req-true">The name of the JMeter variable in which to store the result.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">XPath Query</div>
<div class="description req-true">Element query in XPath language. Can return more than one match.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Match No. (0 for Random)</div>
<div class="description req-false">If the XPath Path query leads to many results, you can choose which one(s) to extract as Variables:
<ul>
<li>
<span class="code">0</span> : means random</li>
<li>
<span class="code">-1</span> means extract all results (default value), they will be named as <span class="code"><em>&lt;variable name&gt;</em>_N</span> (where <span class="code">N</span> goes from 1 to Number of results)</li>
<li>
<span class="code">X</span> : means extract the X<sup>th</sup> result. If this X<sup>th</sup> is greater than number of matches, then nothing is returned. Default value will be used</li>
</ul>
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Default Value</div>
<div class="description req-true">Default value returned when no match found.
It is also returned if the node has no value and the fragment option is not selected.</div>
<div class="required req-true"></div>
</div>
</div>
<p>To allow for use in a <a href="../usermanual/component_reference.html#ForEach_Controller">ForEach Controller</a>, the following variables are set on return:</p>
<ul>
<li>
<span class="code">refName</span> - set to first (or only) match; if no match, then set to default</li>
<li>
<span class="code">refName_matchNr</span> - set to number of matches (may be <span class="code">0</span>)</li>
<li>
<span class="code">refName_n</span> - <span class="code">n</span>=<span class="code">1</span>, <span class="code">2</span>, <span class="code">3</span>, etc. Set to the 1<sup>st</sup>, 2<sup>nd</sup> 3<sup>rd</sup> match etc.
</li>
</ul>
<div class="clear"></div>
<div class="note">Note: The next <span class="code">refName_n</span> variable is set to <span class="code">null</span> - e.g. if there are 2 matches, then <span class="code">refName_3</span> is set to <span class="code">null</span>,
and if there are no matches, then <span class="code">refName_1</span> is set to <span class="code">null</span>.
</div>
<div class="clear"></div>
<p>XPath is query language targeted primarily for XSLT transformations. However it is useful as generic query language for structured data too. See
<a href="http://www.topxml.com/xsl/xpathref.asp">XPath Reference</a> or <a href="http://www.w3.org/TR/xpath">XPath specification</a> for more information. Here are few examples:
</p>
<dl>
<dt>
<span class="code">/html/head/title</span>
</dt>
<dd>extracts title element from HTML response</dd>
<dt>
<span class="code">/book/page[2]</span>
</dt>
<dd>extracts 2<sup>nd</sup> page from a book</dd>
<dt>
<span class="code">/book/page</span>
</dt>
<dd>extracts all pages from a book</dd>
<dt>
<span class="code">//form[@name='countryForm']//select[@name='country']/option[text()='Czech Republic'])/@value</span>
</dt>
<dd>extracts value attribute of option element that match text '<span class="code">Czech Republic</span>'
inside of select element with name attribute '<span class="code">country</span>' inside of
form with name attribute '<span class="code">countryForm</span>'</dd>
</dl>
<div class="clear"></div>
<div class="note">When "<span class="code">Use Tidy</span>" is checked on - resulting XML document may slightly differ from original HTML response:
<ul>
<li>All elements and attribute names are converted to lowercase</li>
<li>Tidy attempts to correct improperly nested elements. For example - original (incorrect) <span class="code">ul/font/li</span> becomes correct <span class="code">ul/li/font</span>
</li>
</ul>
See <a href="http://jtidy.sf.net">Tidy homepage</a> for more information.
</div>
<div class="clear"></div>
<div class="clear"></div>
<div class="note">
<b>NAMESPACES</b>
<br>
As a work-round for namespace limitations of the Xalan XPath parser (implementation on which JMeter is based) you need to:
<ul>
<li>provide a Properties file (if for example your file is named namespaces.properties) which contains mappings for the namespace prefixes:
<pre class="source">
prefix1=http\://foo.apache.org
prefix2=http\://toto.apache.org
&hellip;
</pre>
</li>
<li>reference this file in <span class="code">user.properties</span> file using the property:
<pre class="source">xpath.namespace.config=namespaces.properties</pre>
</li>
</ul>
</div>
<div class="clear"></div>
<p></p>
<pre class="source">//mynamespace:tagname</pre>
<pre class="source">//*[local-name()='tagname' and namespace-uri()='uri-for-namespace']</pre>
<span class="code">uri-for-namespace</span><span class="code">mynamespace</span>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="JSON_JMESPath_Extractor">JSON JMESPath Extractor<a class="sectionlink" href="#JSON_JMESPath_Extractor" title="Link to here">&para;</a>
</h2>
<div class="description">This test element allows the user to extract value(s) from
structured response - XML or (X)HTML - using JMESPath
query language.
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/extractor/jmespath_extractor.png"><img src="../images/screenshots/extractor/jmespath_extractor.png" width="896" height="205" alt="Screenshot for Control-Panel of JSON JMESPath Extractor"></a>
<figcaption>Screenshot of Control-Panel of JSON JMESPath Extractor</figcaption>
</figure>
</div>
<div class="clear"></div>
<div class="note">In the XPATH Extractor we support to extract multiple xpaths at the same time, but in JMES Extractor only
one JMES Expression can be entered at a time.
</div>
<div class="clear"></div>
<div class="properties">
<h3 id="JSON_JMESPath_Extractor_parms1">
Parameters
<a class="sectionlink" href="#JSON_JMESPath_Extractor_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-false">Descriptive name for this element that is shown in the tree.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Apply to:</div>
<div class="description req-true">
This is for use with samplers that can generate sub-samples,
e.g. HTTP Sampler with embedded resources, Mail Reader or samples generated by the Transaction Controller.
<ul>
<li>
<span class="code">Main sample only</span> - only applies to the main sample</li>
<li>
<span class="code">Sub-samples only</span> - only applies to the sub-samples</li>
<li>
<span class="code">Main sample and sub-samples</span> - applies to both.</li>
<li>
<span class="code">JMeter Variable Name to use</span> - extraction is to be applied to the contents of the named variable</li>
</ul>
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Name of created variable</div>
<div class="description req-true">The name of the JMeter variable in which to store the result.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">JMESPath expressions</div>
<div class="description req-true">Element query in JMESPath query language. Can return the matched result.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Match No. (0 for Random)</div>
<div class="description req-false">If the JMESPath query leads to many results, you can choose which one(s) to extract as Variables:
<ul>
<li>
<span class="code">0</span> : means random</li>
<li>
<span class="code">-1</span> means extract all results (default value), they will be named as <span class="code"><em>&lt;variable name&gt;</em>_N</span> (where <span class="code">N</span> goes from 1 to Number of results)</li>
<li>
<span class="code">X</span> : means extract the X<sup>th</sup> result. If this X<sup>th</sup> is greater than number of matches, then nothing is returned. Default value will be used</li>
</ul>
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Default Value</div>
<div class="description req-true">Default value returned when no match found.
It is also returned if the node has no value and the fragment option is not selected.</div>
<div class="required req-true"></div>
</div>
</div>
<p>JMESPath is a query language for JSON. It is described in an ABNF grammar with a complete specification. This ensures that the language syntax is precisely defined.
See <a href="http://jmespath.org/">JMESPath Reference</a> for more information. Here are also some examples <a href="http://jmespath.org/tutorial.html">JMESPath Example</a>.
</p>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="Result_Status_Action_Handler">Result Status Action Handler<a class="sectionlink" href="#Result_Status_Action_Handler" title="Link to here">&para;</a>
</h2>
<div class="description">This test element allows the user to stop the thread or the whole test if the relevant sampler failed.
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/resultstatusactionhandler.png"><img src="../images/screenshots/resultstatusactionhandler.png" width="613" height="133" alt="Screenshot for Control-Panel of Result Status Action Handler"></a>
<figcaption>Screenshot of Control-Panel of Result Status Action Handler</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="Result_Status_Action_Handler_parms1">
Parameters
<a class="sectionlink" href="#Result_Status_Action_Handler_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-true">Descriptive name for this element that is shown in the tree.</div>
<div class="required req-true"></div>
</div>
<div class="property">
<div class="name req-true">Action to be taken after a Sampler error</div>
<div class="description req-true">
Determines what happens if a sampler error occurs, either because the sample itself failed or an assertion failed.
The possible choices are:
<ul>
<li>
<span class="code">Continue</span> - ignore the error and continue with the test</li>
<li>
<span class="code">Start next thread loop</span> - does not execute samplers following the sampler in error for the current iteration and restarts the loop on next iteration</li>
<li>
<span class="code">Stop Thread</span> - current thread exits</li>
<li>
<span class="code">Stop Test</span> - the entire test is stopped at the end of any current samples.</li>
<li>
<span class="code">Stop Test Now</span> - the entire test is stopped abruptly. Any current samplers are interrupted if possible.</li>
</ul>
</div>
<div class="required req-true">
No
</div>
</div>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="BeanShell_PostProcessor">BeanShell PostProcessor<a class="sectionlink" href="#BeanShell_PostProcessor" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>
The BeanShell PreProcessor allows arbitrary code to be applied after taking a sample.
</p>
<p>BeanShell Post-Processor no longer ignores samples with zero-length result data</p>
<p>
<b>For full details on using BeanShell, please see the <a href="http://www.beanshell.org/">BeanShell website.</a></b>
<div class="clear"></div>
<div class="note">Migration to <a href="../usermanual/component_reference.html#JSR223_PostProcessor">JSR223 PostProcessor</a>+Groovy is highly recommended for performance, support of new Java features and limited maintenance of the BeanShell library.</div>
<div class="clear"></div>
</p>
<p>
The test element supports the <span class="code">ThreadListener</span> and <span class="code">TestListener</span> methods.
These should be defined in the initialisation file.
See the file <span class="code">BeanShellListeners.bshrc</span> for example definitions.
</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/beanshell_postprocessor.png"><img src="../images/screenshots/beanshell_postprocessor.png" width="847" height="633" alt="Screenshot for Control-Panel of BeanShell PostProcessor"></a>
<figcaption>Screenshot of Control-Panel of BeanShell PostProcessor</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="BeanShell_PostProcessor_parms1">
Parameters
<a class="sectionlink" href="#BeanShell_PostProcessor_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-false">Descriptive name for this element that is shown in the tree.
The name is stored in the script variable <span class="code">Label</span>
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Reset bsh.Interpreter before each call</div>
<div class="description req-true">
If this option is selected, then the interpreter will be recreated for each sample.
This may be necessary for some long running scripts.
For further information, see <a href="best-practices.html#bsh_scripting">Best Practices - BeanShell scripting</a>.
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Parameters</div>
<div class="description req-false">Parameters to pass to the BeanShell script.
The parameters are stored in the following variables:
<ul>
<li>
<span class="code">Parameters</span> - string containing the parameters as a single variable</li>
<li>
<span class="code">bsh.args</span> - String array containing parameters, split on white-space</li>
</ul>
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Script file</div>
<div class="description req-false">A file containing the BeanShell script to run.
The file name is stored in the script variable <span class="code">FileName</span>
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Script</div>
<div class="description req-true">The BeanShell script. The return value is ignored.</div>
<div class="required req-true">Yes (unless script file is provided)</div>
</div>
</div>
<p>The following BeanShell variables are set up for use by the script:</p>
<ul>
<li>
<span class="code">log</span> - (<a href="https://www.slf4j.org/api/org/slf4j/Logger.html">Logger</a>) - can be used to write to the log file</li>
<li>
<span class="code">ctx</span> - (<a href="../api/org/apache/jmeter/threads/JMeterContext.html">JMeterContext</a>) - gives access to the context</li>
<li>
<span class="code">vars</span> - (<a href="../api/org/apache/jmeter/threads/JMeterVariables.html">JMeterVariables</a>) - gives read/write access to variables: <pre class="source">vars.get(key);
vars.put(key,val);
vars.putObject("OBJ1",new Object());</pre>
</li>
<li>
<span class="code">props</span> - (JMeterProperties - class java.util.Properties) - e.g. <span class="code">props.get("START.HMS");</span> <span class="code">props.put("PROP1","1234");</span>
</li>
<li>
<span class="code">prev</span> - (<a href="../api/org/apache/jmeter/samplers/SampleResult.html">SampleResult</a>) - gives access to the previous SampleResult</li>
<li>
<span class="code">data</span> - (byte [])- gives access to the current sample data</li>
</ul>
<p>For details of all the methods available on each of the above variables, please check the Javadoc</p>
<p>If the property <span class="code">beanshell.postprocessor.init</span> is defined, this is used to load an initialisation file, which can be used to define methods etc. for use in the BeanShell script.</p>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="JSR223_PostProcessor">JSR223 PostProcessor<a class="sectionlink" href="#JSR223_PostProcessor" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>
The JSR223 PostProcessor allows JSR223 script code to be applied after taking a sample.
</p>
</div>
<div class="properties">
<h3 id="JSR223_PostProcessor_parms1">
Parameters
<a class="sectionlink" href="#JSR223_PostProcessor_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-false">Descriptive name for this element that is shown in the tree.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Language</div>
<div class="description req-true">The JSR223 language to be used</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Parameters</div>
<div class="description req-false">Parameters to pass to the script.
The parameters are stored in the following variables:
<ul>
<li>
<span class="code">Parameters</span> - string containing the parameters as a single variable</li>
<li>
<span class="code">args</span> - String array containing parameters, split on white-space</li>
</ul>
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Script file</div>
<div class="description req-false">A file containing the script to run, if a relative file path is used, then it will be relative to directory referenced by "<span class="code">user.dir</span>" System property</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Script compilation caching</div>
<div class="description req-false">Unique String across Test Plan that JMeter will use to cache result of Script compilation if language used supports <span class="code"><a href="https://docs.oracle.com/javase/8/docs/api/javax/script/Compilable.html">Compilable</a></span> interface (Groovy is one of these, java, beanshell and javascript are not)
<div class="clear"></div>
<div class="note">See note in JSR223 Sampler Java System property if you're using Groovy without checking this option</div>
<div class="clear"></div>
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Script</div>
<div class="description req-true">The script to run.</div>
<div class="required req-true">Yes (unless script file is provided)</div>
</div>
</div>
<p>
Before invoking the script, some variables are set up.
Note that these are JSR223 variables - i.e. they can be used directly in the script.
</p>
<ul>
<li>
<span class="code">log</span> - (<a href="https://www.slf4j.org/api/org/slf4j/Logger.html">Logger</a>) - can be used to write to the log file</li>
<li>
<span class="code">Label</span> - the String Label</li>
<li>
<span class="code">FileName</span> - the script file name (if any)</li>
<li>
<span class="code">Parameters</span> - the parameters (as a String)</li>
<li>
<span class="code">args</span> - the parameters as a String array (split on whitespace)</li>
<li>
<span class="code">ctx</span> - (<a href="../api/org/apache/jmeter/threads/JMeterContext.html">JMeterContext</a>) - gives access to the context</li>
<li>
<span class="code">vars</span> - (<a href="../api/org/apache/jmeter/threads/JMeterVariables.html">JMeterVariables</a>) - gives read/write access to variables: <pre class="source">vars.get(key);
vars.put(key,val);
vars.putObject("OBJ1",new Object());
vars.getObject("OBJ2");</pre>
</li>
<li>
<span class="code">props</span> - (JMeterProperties - class java.util.Properties) - e.g. <span class="code">props.get("START.HMS");</span> <span class="code">props.put("PROP1","1234");</span>
</li>
<li>
<span class="code">prev</span> - (<a href="../api/org/apache/jmeter/samplers/SampleResult.html">SampleResult</a>) - gives access to the previous SampleResult (if any)</li>
<li>
<span class="code">sampler</span> - (<a href="../api/org/apache/jmeter/samplers/Sampler.html">Sampler</a>)- gives access to the current sampler</li>
<li>
<span class="code">OUT</span> - System.out - e.g. <span class="code">OUT.println("message")</span>
</li>
</ul>
<p>For details of all the methods available on each of the above variables, please check the Javadoc</p>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="JDBC_PostProcessor">JDBC PostProcessor<a class="sectionlink" href="#JDBC_PostProcessor" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>
The JDBC PostProcessor enables you to run some SQL statement just after a sample has run.
This can be useful if your JDBC Sample changes some data and you want to reset state to what it was before the JDBC sample run.
</p>
</div>
<div class="links">
<div class="title">See also:</div>
<ul class="links">
<li>
<a href="../demos/JDBC-Pre-Post-Processor.jmx">Test Plan using JDBC Pre/Post Processor</a>
</li>
</ul>
</div>
<p>
In the linked test plan, "<span class="code">JDBC PostProcessor</span>" JDBC PostProcessor calls a stored procedure to delete from Database the Price Cut-Off that was created by PreProcessor.
</p>
<figure>
<a href="../images/screenshots/jdbc-post-processor.png"><img src="../images/screenshots/jdbc-post-processor.png" width="818" height="399" alt="JDBC PostProcessor"></a>
<figcaption>JDBC PostProcessor</figcaption>
</figure>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="JSON_Extractor">JSON Extractor<a class="sectionlink" href="#JSON_Extractor" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>
The JSON PostProcessor enables you extract data from JSON responses using JSON-PATH syntax. This post processor is very similar to Regular expression extractor.
It must be placed as a child of HTTP Sampler or any other sampler that has responses.
It will allow you to extract in a very easy way text content, see <a href="https://github.com/json-path/JsonPath">JSON Path syntax</a>.
</p>
</div>
<div class="properties">
<h3 id="JSON_Extractor_parms1">
Parameters
<a class="sectionlink" href="#JSON_Extractor_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-false">Descriptive name for this element that is shown in the tree.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Names of created variables</div>
<div class="description req-true">Semi-colon separated names of variables that will contain the results of JSON-PATH expressions (must match number of JSON-PATH expressions)</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">JSON Path Expressions</div>
<div class="description req-true">Semi-colon separated JSON-PATH expressions (must match number of variables)</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Default Values</div>
<div class="description req-false">Semi-colon separated default values if JSON-PATH expressions do not return any result(must match number of variables)</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Match No. (0 for Random)</div>
<div class="description req-false">If the JSON Path query leads to many results, you can choose which one(s) to extract as Variables:
<ul>
<li>
<span class="code">0</span> : means random (Default Value)</li>
<li>
<span class="code">-1</span> means extract all results, they will be named as <span class="code"><em>&lt;variable name&gt;</em>_N</span> (where <span class="code">N</span> goes from 1 to Number of results)</li>
<li>
<span class="code">X</span> : means extract the X<sup>th</sup> result. If this X<sup>th</sup> is greater than number of matches, then nothing is returned. Default value will be used</li>
</ul>
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Compute concatenation var</div>
<div class="description req-false">If many results are found, plugin will concatenate them using &lsquo;<span class="code">,</span>&rsquo; separator and store it in a var named <span class="code"><em>&lt;variable name&gt;</em>_ALL</span>
</div>
<div class="required req-false">No</div>
</div>
</div>
<figure>
<a href="../images/screenshots/json-post-processor.png"><img src="../images/screenshots/json-post-processor.png" width="855" height="276" alt="JSON PostProcessor"></a>
<figcaption>JSON PostProcessor</figcaption>
</figure>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="Boundary_Extractor">Boundary Extractor<a class="sectionlink" href="#Boundary_Extractor" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>Allows the user to extract values from a server response using left and right boundaries. As a post-processor,
this element will execute after each Sample request in its scope, testing the boundaries, extracting the requested values,
generate the template string, and store the result into the given variable name.</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/extractor/boundary_extractor.png"><img src="../images/screenshots/extractor/boundary_extractor.png" width="1078" height="315" alt="Screenshot for Control-Panel of Boundary Extractor"></a>
<figcaption>Screenshot of Control-Panel of Boundary Extractor</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="Boundary_Extractor_parms1">
Parameters
<a class="sectionlink" href="#Boundary_Extractor_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-true">Descriptive name for this element that is shown in the tree.</div>
<div class="required req-true"></div>
</div>
<div class="property">
<div class="name req-true">Apply to:</div>
<div class="description req-true">
This is for use with samplers that can generate sub-samples,
e.g. HTTP Sampler with embedded resources, Mail Reader or samples generated by the Transaction Controller.
<ul>
<li>
<span class="code">Main sample only</span> - only applies to the main sample</li>
<li>
<span class="code">Sub-samples only</span> - only applies to the sub-samples</li>
<li>
<span class="code">Main sample and sub-samples</span> - applies to both.</li>
<li>
<span class="code">JMeter Variable Name to use</span> - assertion is to be applied to the contents of the named variable</li>
</ul>
Matching is applied to all qualifying samples in turn.
For example if there is a main sample and 3 sub-samples, each of which contains a single match test,
(i.e. 4 matches in total).
For match number = <span class="code">3</span>, Sub-samples only, the extractor will match the 3<sup>rd</sup> sub-sample.
For match number = <span class="code">3</span>, Main sample and sub-samples, the extractor will match the 2<sup>nd</sup> sub-sample (1<sup>st</sup> match is main sample).
For match number = <span class="code">0</span> or negative, all qualifying samples will be processed.
For match number &gt; <span class="code">0</span>, matching will stop as soon as enough matches have been found.
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Field to check</div>
<div class="description req-true">
The following fields can be checked:
<ul>
<li>
<span class="code">Body</span> - the body of the response, e.g. the content of a web-page (excluding headers)</li>
<li>
<span class="code">Body (unescaped)</span> - the body of the response, with all Html escape codes replaced.
Note that Html escapes are processed without regard to context, so some incorrect substitutions
may be made.
<div class="clear"></div>
<div class="note">Note that this option highly impacts performances, so use it only when absolutely necessary and be aware of its impacts</div>
<div class="clear"></div>
</li>
<li>
<span class="code">Body as a Document</span> - the extract text from various type of documents via Apache Tika (see <a href="../usermanual/component_reference.html#View_Results_Tree">View Results Tree</a> Document view section).
<div class="clear"></div>
<div class="note">Note that the Body as a Document option can impact performances, so ensure it is OK for your test</div>
<div class="clear"></div>
</li>
<li>
<span class="code">Request Headers</span> - may not be present for non-HTTP samples</li>
<li>
<span class="code">Response Headers</span> - may not be present for non-HTTP samples</li>
<li>
<span class="code">URL</span>
</li>
<li>
<span class="code">Response Code</span> - e.g. <span class="code">200</span>
</li>
<li>
<span class="code">Response Message</span> - e.g. <span class="code">OK</span>
</li>
</ul>
Headers can be useful for HTTP samples; it may not be present for other sample types.
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Name of created variable</div>
<div class="description req-true">The name of the JMeter variable in which to store the result. Also note that each group is stored as <span class="code">[refname]_g#</span>, where <span class="code">[refname]</span> is the string you entered as the reference name, and <span class="code">#</span> is the group number, where group <span class="code">0</span> is the entire match, group <span class="code">1</span> is the match from the first set of parentheses, etc.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Left Boundary</div>
<div class="description req-false">Left boundary of value to find</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Right Boundary</div>
<div class="description req-false">Right boundary of value to find</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Match No. (0 for Random)</div>
<div class="description req-true">Indicates which match to use. The boundaries may match multiple times.
<ul>
<li>Use a value of zero to indicate JMeter should choose a match at random.</li>
<li>A positive number N means to select the n<sup>th</sup> match.</li>
<li> Negative numbers are used in conjunction with the <a href="../usermanual/component_reference.html#ForEach_Controller">ForEach Controller</a> - see below.</li>
</ul>
</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">
If the boundaries do not match, then the reference variable will be set to the default value.
This is particularly useful for debugging tests. If no default is provided, then it is difficult to tell
whether the boundaries did not match, or maybe the wrong variable
is being used.
<p>
However, if you have several test elements that set the same variable,
you may wish to leave the variable unchanged if the expression does not match.
In this case, remove the default value once debugging is complete.
</p>
</div>
<div class="required req-false">No, but recommended</div>
</div>
</div>
<p>
If the match number is set to a non-negative number, and a match occurs, the variables are set as follows:
</p>
<ul>
<li>
<span class="code">refName</span> - the value of the extraction</li>
</ul>
<p>
If no match occurs, then the <span class="code">refName</span> variable is set to the default (unless this is absent).
</p>
<p>
If the match number is set to a negative number, then all the possible matches in the sampler data are processed.
The variables are set as follows:
</p>
<ul>
<li>
<span class="code">refName_matchNr</span> - the number of matches found; could be <span class="code">0</span>
</li>
<li>
<span class="code">refName_<em>n</em></span>, where <span class="code">n</span> = <span class="code">1</span>, <span class="code">2</span>, <span class="code">3</span> etc. - the strings as generated by the template</li>
<li>
<span class="code">refName_<em>n</em>_g<em>m</em></span>, where <span class="code">m</span>=<span class="code">0</span>, <span class="code">1</span>, <span class="code">2</span> - the groups for match <span class="code">n</span>
</li>
<li>
<span class="code">refName</span> - always set to the default value</li>
</ul>
<p>
Note that the <span class="code">refName</span> variable is always set to the default value in this case,
and the associated group variables are not set.
</p>
<div class="clear"></div>
<div class="note">If both left and right boundary are null, the whole data selected in scope is returned</div>
<div class="clear"></div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
</div>
<div class="section">
<h1 id="Miscellaneous_Features">18.9 Miscellaneous Features<a class="sectionlink" href="#Miscellaneous_Features" title="Link to here">&para;</a>
</h1>
<div class="description">
<br>
</div>
<div class="component">
<h2 id="Test_Plan">Test Plan<a class="sectionlink" href="#Test_Plan" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>
The Test Plan is where the overall settings for a test are specified.
</p>
<p>
Static variables can be defined for values that are repeated throughout a test, such as server names.
For example the variable <span class="code">SERVER</span> could be defined as <span class="code">www.example.com</span>, and the rest of the test plan
could refer to it as <span class="code">${SERVER}</span>. This simplifies changing the name later.
</p>
<p>
If the same variable name is reused on one of more
<a href="../usermanual/component_reference.html#User_Defined_Variables">User Defined Variables</a> Configuration elements,
the value is set to the last definition in the test plan (reading from top to bottom).
Such variables should be used for items that may change between test runs,
but which remain the same during a test run.
</p>
<p>
<div class="clear"></div>
<div class="note">Note that the Test Plan cannot refer to variables it defines.</div>
<div class="clear"></div>
If you need to construct other variables from the Test Plan variables,
use a <a href="../usermanual/component_reference.html#User_Defined_Variables">User Defined Variables</a> test element.
</p>
<p>
Selecting Functional Testing instructs JMeter to save the additional sample information
- Response Data and Sampler Data - to all result files.
This increases the resources needed to run a test, and may adversely impact JMeter performance.
If more data is required for a particular sampler only, then add a Listener to it, and configure the fields as required.
<div class="clear"></div>
<div class="note">The option does not affect CSV result files, which cannot currently store such information.</div>
<div class="clear"></div>
</p>
<p>Also, an option exists here to instruct JMeter to run the <a href="../usermanual/component_reference.html#Thread_Group">Thread Group</a> serially rather than in parallel.</p>
<p>Run tearDown Thread Groups after shutdown of main threads:
if selected, the tearDown groups (if any) will be run after graceful shutdown of the main threads.
The tearDown threads won't be run if the test is forcibly stopped.
</p>
<p>
Test plan now provides an easy way to add classpath setting to a specific test plan.
The feature is additive, meaning that you can add jar files or directories,
but removing an entry requires restarting JMeter.
<div class="clear"></div>
<div class="note">Note that this cannot be used to add JMeter GUI plugins, because they are processed earlier.</div>
<div class="clear"></div>
However it can be useful for utility jars such as JDBC drivers. The jars are only added to
the search path for the JMeter loader, not for the system class loader.
</p>
<p>
JMeter properties also provides an entry for loading additional classpaths.
In <span class="code">jmeter.properties</span>, edit "<span class="code">user.classpath</span>" or "<span class="code">plugin_dependency_paths</span>" to include additional libraries.
See <a href="get-started.html#classpath">JMeter's Classpath</a> and
<a href="get-started.html#configuring_jmeter">Configuring JMeter</a> for details.
</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/testplan.png"><img src="../images/screenshots/testplan.png" width="560" height="457" alt="Screenshot for Control-Panel of Test Plan"></a>
<figcaption>Screenshot of Control-Panel of Test Plan</figcaption>
</figure>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="Thread_Group">Thread Group<a class="sectionlink" href="#Thread_Group" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>A Thread Group defines a pool of users that will execute a particular test case against your server. In the Thread Group GUI, you can control the number of users simulated (number of threads), the ramp up time (how long it takes to start all the threads), the number of times to perform the test, and optionally, a start and stop time for the test.</p>
<p>
See also <a href="../usermanual/component_reference.html#tearDown_Thread_Group">tearDown Thread Group</a> and <a href="../usermanual/component_reference.html#setUp_Thread_Group">setUp Thread Group</a>.
</p>
<p>
When using the scheduler, JMeter runs the thread group until either the number of loops is reached or the duration/end-time is reached - whichever occurs first.
Note that the condition is only checked between samples; when the end condition is reached, that thread will stop.
JMeter does not interrupt samplers which are waiting for a response, so the end time may be delayed arbitrarily.
</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/threadgroup.png"><img src="../images/screenshots/threadgroup.png" width="911" height="390" alt="Screenshot for Control-Panel of Thread Group"></a>
<figcaption>Screenshot of Control-Panel of Thread Group</figcaption>
</figure>
</div>
<p>
Since JMeter 3.0, you can run a selection of Thread Group by selecting them and right clicking. A popup menu will appear:
<figure>
<a href="../images/screenshots/threadgroup-popup-menu.png"><img src="../images/screenshots/threadgroup-popup-menu.png" width="461" height="818" alt="Popup menu to start a selection of Thread Groups"></a>
<figcaption>Popup menu to start a selection of Thread Groups</figcaption>
</figure>
<br>Notice you have 3 options to run the selection of Thread Groups:
<ul>
<li>Start : Start the selected thread groups only</li>
<li>Start no pauses : Start the selected thread groups only but without running the timers</li>
<li>Validate : Start the selected thread groups only using validation mode. Per default this runs the Thread Group in validation mode (see below)</li>
</ul>
<b>Validation Mode:</b>
<br>
This mode enables rapid validation of a Thread Group by running it with 1 thread, 1 iteration, no timers and no <span class="code">Startup delay</span> set to 0.
Behaviour can be modified with some properties by setting in user.properties:
<ul>
<li>
<span class="code">testplan_validation.nb_threads_per_thread_group</span> : Number of threads to use to validate a Thread Group, by default 1</li>
<li>
<span class="code">testplan_validation.ignore_timers</span> : Ignore timers when validating the thread group of plan, by default 1</li>
<li>
<span class="code">testplan_validation.number_iterations</span> : Number of iterations to use to validate a Thread Group</li>
<li>
<span class="code">testplan_validation.tpc_force_100_pct</span> : Whether to force Throughput Controller in percentage mode to run as if percentage was 100%. Defaults to false</li>
</ul>
</p>
<div class="properties">
<h3 id="Thread_Group_parms1">
Parameters
<a class="sectionlink" href="#Thread_Group_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-true">Descriptive name for this element that is shown in the tree.</div>
<div class="required req-true"></div>
</div>
<div class="property">
<div class="name req-true">Action to be taken after a Sampler error</div>
<div class="description req-true">
Determines what happens if a sampler error occurs, either because the sample itself failed or an assertion failed.
The possible choices are:
<ul>
<li>
<span class="code">Continue</span> - ignore the error and continue with the test</li>
<li>
<span class="code">Start Next Thread Loop</span> - ignore the error, start next loop and continue with the test</li>
<li>
<span class="code">Stop Thread</span> - current thread exits</li>
<li>
<span class="code">Stop Test</span> - the entire test is stopped at the end of any current samples.</li>
<li>
<span class="code">Stop Test Now</span> - the entire test is stopped abruptly. Any current samplers are interrupted if possible.</li>
</ul>
</div>
<div class="required req-true">
No
</div>
</div>
<div class="property">
<div class="name req-true">Number of Threads</div>
<div class="description req-true">Number of users to simulate.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Ramp-up Period</div>
<div class="description req-true">How long JMeter should take to get all the threads started. If there are 10 threads and a ramp-up time of 100 seconds, then each thread will begin 10 seconds after the previous thread started, for a total time of 100 seconds to get the test fully up to speed.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Loop Count</div>
<div class="description req-true">Number of times to perform the test case. Alternatively, "<span class="code">infinite</span>" can be selected causing the test to run until manually stopped or end of the thread lifetime is reached.</div>
<div class="required req-true">Yes, unless Infinite is selected</div>
</div>
<div class="property">
<div class="name req-true">Delay Thread creation until needed</div>
<div class="description req-true">
If selected, threads are created only when the appropriate proportion of the ramp-up time has elapsed.
This is most appropriate for tests with a ramp-up time that is significantly longer than the time to execute a single thread.
I.e. where earlier threads finish before later ones start.
<br>
If not selected, all threads are created when the test starts (they then pause for the appropriate proportion of the ramp-up time).
This is the original default, and is appropriate for tests where threads are active throughout most of the test.
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Specify Thread lifetime</div>
<div class="description req-true">If selected, confines Thread operation time to the given bounds</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Duration (seconds)</div>
<div class="description req-false">
If the scheduler checkbox is selected, one can choose a relative end time.
JMeter will use this to calculate the End Time.
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Startup delay (seconds)</div>
<div class="description req-false">
If the scheduler checkbox is selected, one can choose a relative startup delay.
JMeter will use this to calculate the Start Time.
</div>
<div class="required req-false">No</div>
</div>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="WorkBench">WorkBench<a class="sectionlink" href="#WorkBench" title="Link to here">&para;</a>
</h2>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="SSL_Manager">SSL Manager<a class="sectionlink" href="#SSL_Manager" title="Link to here">&para;</a>
</h2>
<p>
The SSL Manager is a way to select a client certificate so that you can test
applications that use Public Key Infrastructure (PKI).
It is only needed if you have not set up the appropriate System properties.
</p>
<div class="clear"></div>
<div class="note">If you want to test client certificate authentication, see <a href="../usermanual/component_reference.html#Keystore_Configuration">Keystore Configuration</a>
</div>
<div class="clear"></div>
<b>Choosing a Client Certificate</b>
<p>
You may either use a Java Key Store (JKS) format key store, or a Public Key
Certificate Standard #12 (PKCS12) file for your client certificates. There
is a feature of the JSSE libraries that require you to have at least a six character
password on your key (at least for the keytool utility that comes with your
JDK).
</p>
<p>
To select the client certificate, choose <span class="menuchoice"><span class="guimenuitem">Options</span>&nbsp;&rarr;&nbsp;<span class="guimenuitem">SSL Manager</span></span> from the menu bar.
You will be presented with a file finder that looks for PKCS12 files by default.
Your PKCS12 file must have the extension '<span class="code">.p12</span>' for SSL Manager to recognize it
as a PKCS12 file. Any other file will be treated like an average JKS key store.
If JSSE is correctly installed, you will be prompted for the password. The text
box does not hide the characters you type at this point -- so make sure no one is
looking over your shoulder. The current implementation assumes that the password
for the keystore is also the password for the private key of the client you want
to authenticate as.
</p>
<p>Or you can set the appropriate System properties - see the <span class="code">system.properties</span> file.</p>
<p>
The next time you run your test, the SSL Manager will examine your key store to
see if it has at least one key available to it. If there is only one key, SSL
Manager will select it for you. If there is more than one key, it currently selects the first key.
There is currently no way to select other entries in the keystore, so the desired key must be the first.
</p>
<b>Things to Look Out For</b>
<p>
You must have your Certificate Authority (CA) certificate installed properly
if it is not signed by one of the five CA certificates that ships with your
JDK. One method to install it is to import your CA certificate into a JKS
file, and name the JKS file "<span class="code">jssecacerts</span>". Place the file in your JRE's
<span class="code">lib/security</span> folder. This file will be read before the "<span class="code">cacerts</span>" file in
the same directory. Keep in mind that as long as the "<span class="code">jssecacerts</span>" file
exists, the certificates installed in "<span class="code">cacerts</span>" will not be used. This may
cause problems for you. If you don't mind importing your CA certificate into
the "<span class="code">cacerts</span>" file, then you can authenticate against all of the CA certificates
installed.
</p>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="HTTP(S)_Test_Script_Recorder">HTTP(S) Test Script Recorder<a name="HTTP_Proxy_Server">
(was:
HTTP Proxy Server
)
</a><a class="sectionlink" href="#HTTP(S)_Test_Script_Recorder" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>The HTTP(S) Test Script Recorder allows JMeter to intercept and record your actions while you browse your web application
with your normal browser. JMeter will create test sample objects and store them
directly into your test plan as you go (so you can view samples interactively while you make them).<br>
Ensure you read this <a href="https://cwiki.apache.org/confluence/display/JMETER/TestRecording210">wiki page</a> to setup correctly JMeter.
</p>
<p>To use the recorder, <i>add</i> the HTTP(S) Test Script Recorder element.
Right-click on the Test Plan element to get the Add menu:
(<span class="menuchoice"><span class="guimenuitem">Add</span>&nbsp;&rarr;&nbsp;<span class="guimenuitem">Non-Test Elements</span>&nbsp;&rarr;&nbsp;<span class="guimenuitem">HTTP(S) Test Script Recorder</span></span>
).
</p>
<p>
The recorder is implemented as an HTTP(S) proxy server.
You need to set up your browser use the proxy for all HTTP and HTTPS requests.
<div class="clear"></div>
<div class="note">Do not use JMeter as the proxy for any other request types - FTP, etc. - as JMeter cannot handle them.</div>
<div class="clear"></div>
</p>
<p>
Ideally use private browsing mode when recording the session.
This should ensure that the browser starts with no stored cookies, and prevents certain changes from being saved.
For example, Firefox does not allow certificate overrides to be saved permanently.
</p>
<h4>HTTPS recording and certificates</h4>
<p>
HTTPS connections use certificates to authenticate the connection between the browser and the web server.
When connecting via HTTPS, the server presents the certificate to the browser.
To authenticate the certificate, the browser checks that the server certificate is signed
by a Certificate Authority (CA) that is linked to one of its in-built root CAs.
<div class="clear"></div>
<div class="note">Browsers also check that the certificate is for the correct host or domain, and that it is valid and not expired.</div>
<div class="clear"></div>
If any of the browser checks fail, it will prompt the user who can then decide whether to allow the connection to proceed.
</p>
<p>
JMeter needs to use its own certificate to enable it to intercept the HTTPS connection from
the browser. Effectively JMeter has to pretend to be the target server.
</p>
<p>
JMeter will generate its own certificate(s).
These are generated with a validity period defined by the property <span class="code">proxy.cert.validity</span>, default 7 days, and random passwords.
If JMeter detects that it is running under Java 8 or later, it will generate certificates for each target server as necessary (dynamic mode)
unless the following property is defined: <span class="code">proxy.cert.dynamic_keys=false</span>.
When using dynamic mode, the certificate will be for the correct host name, and will be signed by a JMeter-generated CA certificate.
By default, this CA certificate won't be trusted by the browser, however it can be installed as a trusted certificate.
Once this is done, the generated server certificates will be accepted by the browser.
This has the advantage that even embedded HTTPS resources can be intercepted, and there is no need to override the browser checks for each new server.
<div class="clear"></div>
<div class="note">Browsers don't prompt for embedded resources. So with earlier versions, embedded resources would only be downloaded for servers that were already 'known' to the browser</div>
<div class="clear"></div>
</p>
<p>Unless a keystore is provided (and you define the property <span class="code">proxy.cert.alias</span>),
JMeter needs to use the keytool application to create the keystore entries.
JMeter includes code to check that keytool is available by looking in various standard places.
If JMeter is unable to find the keytool application, it will report an error.
If necessary, the system property <span class="code">keytool.directory</span> can be used to tell JMeter where to find keytool.
This should be defined in the file <span class="code">system.properties</span>.
</p>
<p>
The JMeter certificates are generated (if necessary) when the <span class="code">Start</span> button is pressed.
<div class="clear"></div>
<div class="note">Certificate generation can take some while, during which time the GUI will be unresponsive.</div>
<div class="clear"></div>
The cursor is changed to an hour-glass whilst this is happening.
When certificate generation is complete, the GUI will display a pop-up dialogue containing the details of the certificate for the root CA.
This certificate needs to be installed by the browser in order for it to accept the host certificates generated by JMeter; see <a href="#install_cert">below</a> for details.
</p>
<p>
If necessary, you can force JMeter to regenerate the keystore (and the exported certificates - <span class="code">ApacheJMeterTemporaryRootCA[.usr|.crt]</span>) by deleting the keystore file <span class="code">proxyserver.jks</span> from the JMeter directory.
</p>
<p>
This certificate is not one of the certificates that browsers normally trust, and will not be for the
correct host.<br>
As a consequence:
</p>
<ul>
<li>The browser should display a dialogue asking if you want to accept the certificate or not. For example:
<pre class="source">
1) The server's name "<span class="code">www.example.com</span>" does not match the certificate's name
"<span class="code">JMeter Proxy (DO NOT TRUST)</span>". Somebody may be trying to eavesdrop on you.
2) The certificate for "<span class="code">JMeter Proxy (DO NOT TRUST)</span>" is signed by the unknown Certificate Authority
"<span class="code">JMeter Proxy (DO NOT TRUST)</span>". It is not possible to verify that this is a valid certificate.
</pre>
You will need to accept the certificate in order to allow the JMeter Proxy to intercept the SSL traffic in order to
record it.
However, do not accept this certificate permanently; it should only be accepted temporarily.
Browsers only prompt this dialogue for the certificate of the main URL, not for the resources loaded in the page, such as images, CSS or JavaScript files hosted on a secured external CDN.
If you have such resources (gmail has for example), you'll have to first browse manually to these other domains in order to accept JMeter's certificate for them.
Check in <span class="code">jmeter.log</span> for secure domains that you need to register certificate for.
</li>
<li>If the browser has already registered a validated certificate for this domain, the browser will detect JMeter as a security breach and will refuse to load the page. If so, you have to remove the trusted certificate from your browser's keystore.
</li>
</ul>
<p>
Versions of JMeter from 2.10 onwards still support this method, and will continue to do so if you define the following property:
<span class="code">proxy.cert.alias</span>
The following properties can be used to change the certificate that is used:
</p>
<ul>
<li>
<span class="code">proxy.cert.directory</span> - the directory in which to find the certificate (default = JMeter <span class="code">bin/</span>)</li>
<li>
<span class="code">proxy.cert.file</span> - name of the keystore file (default "<span class="code">proxyserver.jks</span>")</li>
<li>
<span class="code">proxy.cert.keystorepass</span> - keystore password (default "<span class="code">password</span>") [Ignored if using JMeter certificate]</li>
<li>
<span class="code">proxy.cert.keypassword</span> - certificate key password (default "<span class="code">password</span>") [Ignored if using JMeter certificate]</li>
<li>
<span class="code">proxy.cert.type</span> - the certificate type (default "<span class="code">JKS</span>") [Ignored if using JMeter certificate]</li>
<li>
<span class="code">proxy.cert.factory</span> - the factory (default "<span class="code">SunX509</span>") [Ignored if using JMeter certificate]</li>
<li>
<span class="code">proxy.cert.alias</span> - the alias for the key to be used. If this is defined, JMeter does not attempt to generate its own certificate(s).</li>
<li>
<span class="code">proxy.ssl.protocol</span> - the protocol to be used (default "<span class="code">SSLv3</span>")</li>
</ul>
<div class="clear"></div>
<div class="note">
If your browser currently uses a proxy (e.g. a company intranet may route all external requests via a proxy),
then you need to <a href="get-started.html#proxy_server">tell JMeter to use that proxy</a> before starting JMeter,
using the <a href="get-started.html#options">command-line options</a> <span class="code">-H</span> and <span class="code">-P</span>.
This setting will also be needed when running the generated test plan.
</div>
<div class="clear"></div>
<a name="install_cert"></a>
<h4>Installing the JMeter CA certificate for HTTPS recording</h4>
<p>
As mentioned above, when run under Java 8, JMeter can generate certificates for each server.
For this to work smoothly, the root CA signing certificate used by JMeter needs to be trusted by the browser.
The first time that the recorder is started, it will generate the certificates if necessary.
The root CA certificate is exported into a file with the name <span class="code">ApacheJMeterTemporaryRootCA</span> in the current launch directory.
When the certificates have been set up, JMeter will show a dialog with the current certificate details.
At this point, the certificate can be imported into the browser, as per the instructions below.
</p>
<p>
Note that once the root CA certificate has been installed as a trusted CA, the browser will trust any certificates signed by it.
Until such time as the certificate expires or the certificate is removed from the browser, it will not warn the user that the certificate is being relied upon.
So anyone that can get hold of the keystore and password can use the certificate to generate certificates which will be accepted
by any browsers that trust the JMeter root CA certificate.
For this reason, the password for the keystore and private keys are randomly generated and a short validity period used.
The passwords are stored in the local preferences area.
Please ensure that only trusted users have access to the host with the keystore.
</p>
<div class="clear"></div>
<div class="note">
The popup that displays once you start the Recorder is an informational popup:
<figure>
<a href="../images/screenshots/recorder_popup_info.png"><img src="../images/screenshots/recorder_popup_info.png" width="1024" height="749" alt="Recorder Install Certificate Popup"></a>
<figcaption>Recorder Install Certificate Popup</figcaption>
</figure>
Just click ok and proceed further.
</div>
<div class="clear"></div>
<h5>Installing the certificate in Firefox</h5>
<p>
Choose the following options:
</p>
<ul>
<li>
<span class="code">Tools / Options</span>
</li>
<li>
<span class="code">Advanced / Certificates</span>
</li>
<li>
<span class="code">View Certificates</span>
</li>
<li>
<span class="code">Authorities</span>
</li>
<li>
<span class="code">Import &hellip;</span>
</li>
<li>Browse to the JMeter launch directory, and click on the file <span class="code">ApacheJMeterTemporaryRootCA.crt</span>, press <span class="code">Open</span>
</li>
<li>Click <span class="code">View</span> and check that the certificate details agree with the ones displayed by the JMeter Test Script Recorder</li>
<li>If OK, select "<span class="code">Trust this CA to identify web sites</span>", and press <span class="code">OK</span>
</li>
<li>Close dialogs by pressing <span class="code">OK</span> as necessary</li>
</ul>
<h5>Installing the certificate in Chrome or Internet Explorer</h5>
<p>
Both Chrome and Internet Explorer use the same trust store for certificates.
</p>
<ul>
<li>Browse to the JMeter launch directory, and click on the file <span class="code">ApacheJMeterTemporaryRootCA.crt</span>, and open it</li>
<li>Click on the "<span class="code">Details</span>" tab and check that the certificate details agree with the ones displayed by the JMeter Test Script Recorder</li>
<li>If OK, go back to the "<span class="code">General</span>" tab, and click on "<span class="code">Install Certificate &hellip;</span>" and follow the Wizard prompts</li>
</ul>
<h5>Installing the certificate in Opera</h5>
<ul>
<li>
<span class="code">Tools / Preferences / Advanced / Security</span>
</li>
<li>
<span class="code">Manage Certificates &hellip;</span>
</li>
<li>Select "<span class="code">Intermediate</span>" tab, click "<span class="code">Import &hellip;</span>"</li>
<li>Browse to the JMeter launch directory, and click on the file <span class="code">ApacheJMeterTemporaryRootCA.usr</span>, and open it</li>
<li></li>
</ul>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/proxy_control.png"><img src="../images/screenshots/proxy_control.png" width="1052" height="694" alt="Screenshot for Control-Panel of HTTP(S) Test Script Recorder"></a>
<figcaption>Screenshot of Control-Panel of HTTP(S) Test Script Recorder</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="HTTP(S)_Test_Script_Recorder_parms1">
Parameters
<a class="sectionlink" href="#HTTP(S)_Test_Script_Recorder_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-false">Descriptive name for this element that is shown in the tree.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Port</div>
<div class="description req-true">The port that the HTTP(S) Test Script Recorder listens to. <span class="code">8888</span> is the default, but you can change it.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">HTTPS Domains</div>
<div class="description req-false">List of domain (or host) names for HTTPS. Use this to pre-generate certificates for all servers you wish to record.
<br>
For example, <span class="code">*.example.com,*.subdomain.example.com</span>
<br>
Note that wildcard domains only apply to one level,
i.e. <span class="code">abc.subdomain.example.com</span> matches <span class="code">*.subdomain.example.com</span> but not <span class="code">*.example.com</span>
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Target Controller</div>
<div class="description req-true">The controller where the proxy will store the generated samples. By default, it will look for a Recording Controller and store them there wherever it is.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Grouping</div>
<div class="description req-true">Whether to group samplers for requests from a single "click" (requests received without significant time separation), and how to represent that grouping in the recording:
<ul>
<li>
<span class="code">Do not group samplers</span> - store all recorded samplers sequentially, without any grouping.</li>
<li>
<span class="code">Add separators between groups</span> - add a controller named "<span class="code">--------------</span>" to create a visual separation between the groups. Otherwise the samplers are all stored sequentially.</li>
<li>
<span class="code">Put each group in a new controller</span> - create a new <a href="../usermanual/component_reference.html#Simple_Controller">Simple Controller</a> for each group, and store all samplers for that group in it.</li>
<li>
<span class="code">Store 1<sup>st</sup> sampler of each group only</span> - only the first request in each group will be recorded. The "<span class="code">Follow Redirects</span>" and "<span class="code">Retrieve All Embedded Resources &hellip;</span>" flags will be turned on in those samplers.</li>
<li>
<span class="code">Put each group in a new transaction controller</span> - create a new <a href="../usermanual/component_reference.html#Transaction_Controller">Transaction Controller</a> for each group, and store all samplers for that group in it.</li>
</ul>
The property <span class="code">proxy.pause</span> determines the minimum gap that JMeter needs between requests
to treat them as separate "clicks". The default is <span class="code">5000</span> (milliseconds) i.e. 5 seconds.
If you are using grouping, please ensure that you leave the required gap between clicks.
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Capture HTTP Headers</div>
<div class="description req-true">Should headers be added to the plan?
If specified, a Header Manager will be added to each HTTP Sampler.
The Proxy server always removes Cookie and Authorization headers from the generated Header Managers.
By default it also removes <span class="code">If-Modified-Since</span> and <span class="code">If-None-Match</span> headers.
These are used to determine if the browser cache items are up to date;
when recording one normally wants to download all the content.
To change which additional headers are removed, define the JMeter property <span class="code">proxy.headers.remove</span>
as a comma-separated list of headers.
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Add Assertions</div>
<div class="description req-true">Add a blank assertion to each sampler?</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Regex Matching</div>
<div class="description req-true">Use Regex Matching when replacing variables? If checked replacement will use word boundaries, i.e. it will only replace word matching values of variable, not part of a word. A word boundary follows Perl5 definition and is equivalent to <span class="code">\b</span>. More information below in the paragraph about "<span class="code">User Defined Variable replacement</span>".</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Prefix/Transaction name</div>
<div class="description req-false">Add a prefix to sampler name during recording (Prefix mode). Or replace sampler name by user chosen name (Transaction name)</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">Create new transaction after request (ms)</div>
<div class="description req-true">Inactivity time between two requests needed to consider them in two separate groups.</div>
<div class="required req-true">
No
</div>
</div>
<div class="property">
<div class="name req-true">Type</div>
<div class="description req-true">Which type of sampler to generate (the HTTPClient default or Java)</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Redirect Automatically</div>
<div class="description req-true">Set Redirect Automatically in the generated samplers?</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Follow Redirects</div>
<div class="description req-true">Set Follow Redirects in the generated samplers?<br>
<div class="clear"></div>
<div class="note">Note: see "Recording and redirects" section below for important information.</div>
<div class="clear"></div>
</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Use Keep-Alive</div>
<div class="description req-true">Set Use Keep-Alive in the generated samplers?</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Retrieve all Embedded Resources</div>
<div class="description req-true">Set Retrieve all Embedded Resources in the generated samplers?</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Content Type filter</div>
<div class="description req-false">
Filter the requests based on the <span class="code">content-type</span> - e.g. "<span class="code">text/html [;charset=utf-8 ]</span>".
The fields are regular expressions which are checked to see if they are contained in the <span class="code">content-type</span>.
[Does not have to match the entire field].
The include filter is checked first, then the exclude filter.
Samples which are filtered out will not be stored.
<div class="clear"></div>
<div class="note">Note: this filtering is applied to the content type of the response</div>
<div class="clear"></div>
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Patterns to Include</div>
<div class="description req-false">Regular expressions that are matched against the full URL that is sampled. Allows filtering of requests that are recorded. All requests pass through, but only
those that meet the requirements of the <span class="code">Include</span>/<span class="code">Exclude</span> fields are <em>recorded</em>. If both <span class="code">Include</span> and <span class="code">Exclude</span> are
left empty, then everything is recorded (which can result in dozens of samples recorded for each page, as images, stylesheets,
etc. are recorded). <div class="clear"></div>
<div class="note">If there is at least one entry in the <span class="code">Include</span> field, then only requests that match one or more <span class="code">Include</span> patterns are
recorded</div>
<div class="clear"></div>.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Patterns to Exclude</div>
<div class="description req-false">Regular expressions that are matched against the URL that is sampled.
<div class="clear"></div>
<div class="note">Any requests that match one or more <span class="code">Exclude</span> pattern are <em>not</em> recorded</div>
<div class="clear"></div>.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Notify Child Listeners of filtered samplers</div>
<div class="description req-false">Notify Child Listeners of filtered samplers
<div class="clear"></div>
<div class="note">Any response that match one or more <span class="code">Exclude</span> pattern is <em>not</em> delivered to Child Listeners (View Results Tree)</div>
<div class="clear"></div>.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Start Button</div>
<div class="description req-false">Start the proxy server. JMeter writes the following message to the console once the proxy server has started up and is ready to take requests: "<span class="code">Proxy up and running!</span>".</div>
<div class="required req-false">N/A</div>
</div>
<div class="property">
<div class="name req-false">Stop Button</div>
<div class="description req-false">Stop the proxy server.</div>
<div class="required req-false">N/A</div>
</div>
<div class="property">
<div class="name req-false">Restart Button</div>
<div class="description req-false">Stops and restarts the proxy server. This is
useful when you change/add/delete an include/exclude filter expression.</div>
<div class="required req-false">N/A</div>
</div>
</div>
<h4>Recording and redirects</h4>
<p>
During recording, the browser will follow a redirect response and generate an additional request.
The Proxy will record both the original request and the redirected request
(subject to whatever exclusions are configured).
The generated samples have "<span class="code">Follow Redirects</span>" selected by default, because that is generally better.
<div class="clear"></div>
<div class="note">Redirects may depend on the original request, so repeating the originally recorded sample may not always work.</div>
<div class="clear"></div>
</p>
<p>
Now if JMeter is set to follow the redirect during replay, it will issue the original request,
and then replay the redirect request that was recorded.
To avoid this duplicate replay, JMeter tries to detect when a sample is the result of a previous
redirect. If the current response is a redirect, JMeter will save the redirect URL.
When the next request is received, it is compared with the saved redirect URL and if there is a match,
JMeter will disable the generated sample. It also adds comments to the redirect chain.
This assumes that all the requests in a redirect chain will follow each other without any intervening requests.
To disable the redirect detection, set the property <span class="code">proxy.redirect.disabling=false</span>
</p>
<h4>Includes and Excludes</h4>
<p>The <b>include and exclude patterns</b> are treated as regular expressions (using Jakarta ORO).
They will be matched against the host name, port (actual or implied), path and query (if any) of each browser request.
If the URL you are browsing is <br>
"<span class="code">http://localhost/jmeter/index.html?username=xxxx</span>",<br>
then the regular expression will be tested against the string:<br>
"<span class="code">localhost:80/jmeter/index.html?username=xxxx</span>".<br>
Thus, if you want to include all <span class="code">.html</span> files, your regular expression might look like: <br>
"<span class="code">.*\.html(\?.*)?</span>" - or "<span class="code">.*\.html</span>
if you know that there is no query string or you only want html pages without query strings.
</p>
<p>
If there are any include patterns, then the URL <b>must match at least one</b> of the patterns
, otherwise it will not be recorded.
If there are any exclude patterns, then the URL <b>must not match any</b> of the patterns
, otherwise it will not be recorded.
Using a combination of includes and excludes,
you should be able to record what you are interested in and skip what you are not.
</p>
<div class="clear"></div>
<div class="note">
N.B. the string that is matched by the regular expression must be the same as the <b>whole</b> host+path string.<br>Thus "<span class="code">\.html</span>" will <b>not</b> match <span class="code">localhost:80/index.html</span>
</div>
<div class="clear"></div>
<h4>Capturing binary POST data</h4>
<p>
JMeter is able to capture binary POST data.
To configure which <span class="code">content-types</span> are treated as binary, update the JMeter property <span class="code">proxy.binary.types</span>.
The default settings are as follows:
</p>
<pre class="source">
# These content-types will be handled by saving the request in a file:
proxy.binary.types=application/x-amf,application/x-java-serialized-object
# The files will be saved in this directory:
proxy.binary.directory=user.dir
# The files will be created with this file filesuffix:
proxy.binary.filesuffix=.binary
</pre>
<h4>Adding timers</h4>
<p>It is also possible to have the proxy add timers to the recorded script. To
do this, create a timer directly within the HTTP(S) Test Script Recorder component.
The proxy will place a copy of this timer into each sample it records, or into
the first sample of each group if you're using grouping. This copy will then be
scanned for occurrences of variable <span class="code">${T}</span> in its properties, and any such
occurrences will be replaced by the time gap from the previous sampler
recorded (in milliseconds).</p>
<p>When you are ready to begin, hit "<span class="code">start</span>".</p>
<div class="clear"></div>
<div class="note">You will need to edit the proxy settings of your browser to point at the
appropriate server and port, where the server is the machine JMeter is running on, and
the port # is from the Proxy Control Panel shown above.</div>
<div class="clear"></div>
<h4>Where Do Samples Get Recorded?</h4>
<p>JMeter places the recorded samples in the Target Controller you choose. If you choose the default option
"<span class="code">Use Recording Controller</span>", they will be stored in the first Recording Controller found in the test object tree (so be
sure to add a Recording Controller before you start recording).</p>
<p>
If the Proxy does not seem to record any samples, this could be because the browser is not actually using the proxy.
To check if this is the case, try stopping the proxy.
If the browser still downloads pages, then it was not sending requests via the proxy.
Double-check the browser options.
If you are trying to record from a server running on the same host,
then check that the browser is not set to "<span class="code">Bypass proxy server for local addresses</span>"
(this example is from IE7, but there will be similar options for other browsers).
If JMeter does not record browser URLs such as <span class="code">http://localhost/</span> or <span class="code">http://127.0.0.1/</span>,
try using the non-loopback hostname or IP address, e.g. <span class="code">http://myhost/</span> or <span class="code">http://192.168.0.2/</span>.
</p>
<h4>Handling of HTTP Request Defaults</h4>
<p>If the HTTP(S) Test Script Recorder finds enabled <a href="../usermanual/component_reference.html#HTTP_Request_Defaults">HTTP Request Defaults</a> directly within the
controller where samples are being stored, or directly within any of its parent controllers, the recorded samples
will have empty fields for the default values you specified. You may further control this behaviour by placing an
HTTP Request Defaults element directly within the HTTP(S) Test Script Recorder, whose non-blank values will override
those in the other HTTP Request Defaults. See <a href="best-practices.html#proxy_server"> Best
Practices with the HTTP(S) Test Script Recorder</a> for more info.</p>
<h4>User Defined Variable replacement</h4>
<p>Similarly, if the HTTP(S) Test Script Recorder finds <a href="../usermanual/component_reference.html#User_Defined_Variables">User Defined Variables</a> (UDV) directly within the
controller where samples are being stored, or directly within any of its parent controllers, the recorded samples
will have any occurrences of the values of those variables replaced by the corresponding variable. Again, you can
place User Defined Variables directly within the HTTP(S) Test Script Recorder to override the values to be replaced. See
<a href="best-practices.html#proxy_server"> Best Practices with the Test Script Recorder</a> for more info.</p>
<div class="clear"></div>
<div class="note">Please note that matching is case-sensitive.</div>
<div class="clear"></div>
<p>Replacement by Variables: by default, the Proxy server looks for all occurrences of UDV values.
If you define the variable <span class="code">WEB</span> with the value <span class="code">www</span>, for example,
the string <span class="code">www</span> will be replaced by <span class="code">${WEB}</span> wherever it is found.
To avoid this happening everywhere, set the "<span class="code">Regex Matching</span>" check-box.
This tells the proxy server to treat values as Regexes (using the perl5 compatible regex matchers provided by ORO).</p>
<p>If "<span class="code">Regex Matching</span>" is selected every variable will be compiled into a perl compatible regex enclosed in
<span class="code">\b(</span> and <span class="code">)\b</span>. That way each match will start and end at a word boundary.</p>
<div class="clear"></div>
<div class="note">Note that the boundary characters are not part of the matching group, e.g. <span class="code">n.*</span> to match <span class="code">name</span> out
of <span class="code">You can call me 'name'</span>.</div>
<div class="clear"></div>
<p>If you don't want your regex to be enclosed with those boundary matchers, you have to enclose your
regex within parens, e.g <span class="code">('.*?')</span> to match <span class="code">'name'</span> out of <span class="code">You can call me 'name'</span>.</p>
<div class="clear"></div>
<div class="note">
The variables will be checked in random order. So ensure, that the potential matches don't overlap.
Overlapping matchers would be <span class="code">.*</span> (which matches anything) and <span class="code">www</span> (which
matches <span class="code">www</span> only). Non-overlapping matchers would be <span class="code">a+</span> (matches a sequence
of <span class="code">a</span>'s) and <span class="code">b+</span> (matches a sequence of <span class="code">b</span>'s).
</div>
<div class="clear"></div>
<p>If you want to match a whole string only, enclose it in <span class="code">(^</span> and <span class="code">$)</span>, e.g. <span class="code">(^thus$)</span>.
The parens are necessary, since the normally added boundary characters will prevent <span class="code">^</span> and
<span class="code">$</span> to match.</p>
<p>If you want to match <span class="code">/images</span> at the start of a string only, use the value <span class="code">(^/images)</span>.
Jakarta ORO also supports zero-width look-ahead, so one can match <span class="code">/images/&hellip;</span>
but retain the trailing <span class="code">/</span> in the output by using <span class="code">(^/images(?=/))</span>.</p>
<div class="clear"></div>
<div class="note">
Note that the current version of Jakarta ORO does not support look-behind - i.e. <span class="code">(?&lt;=&hellip;)</span> or <span class="code">(?&lt;!&hellip;)</span>.
</div>
<div class="clear"></div>
<p>Look out for overlapping matchers. For example the value <span class="code">.*</span> as a regex in a variable named
<span class="code">regex</span> will partly match a previous replaced variable, which will result in something like
<span class="code">${{regex}</span>, which is most probably not the desired result.</p>
<p>If there are any problems interpreting any variables as patterns, these are reported in <span class="code">jmeter.log</span>,
so be sure to check this if UDVs are not working as expected.</p>
<p>When you are done recording your test samples, stop the proxy server (hit the "<span class="code">stop</span>" button). Remember to reset
your browser's proxy settings. Now, you may want to sort and re-order the test script, add timers, listeners, a
cookie manager, etc.</p>
<h4>How can I record the server's responses too?</h4>
<p>Just place a <a href="../usermanual/component_reference.html#View_Results_Tree">View Results Tree</a> listener as a child of the HTTP(S) Test Script Recorder and the responses will be displayed.
You can also add a <a href="../usermanual/component_reference.html#Save_Responses_to_a_file">Save Responses to a file</a> Post-Processor which will save the responses to files.
</p>
<h4>Associating requests with responses</h4>
<p>
If you define the property <span class="code">proxy.number.requests=true</span>
JMeter will add a number to each sampler and each response.
Note that there may be more responses than samplers if excludes or includes have been used.
Responses that have been excluded will have labels enclosed in <span class="code">[</span> and <span class="code">],</span> for example <span class="code">[23 /favicon.ico]</span>
</p>
<h4>Cookie Manager</h4>
<p>
If the server you are testing against uses cookies, remember to add an <a href="../usermanual/component_reference.html#HTTP_Cookie_Manager">HTTP Cookie Manager</a> to the test plan
when you have finished recording it.
During recording, the browser handles any cookies, but JMeter needs a Cookie Manager
to do the cookie handling during a test run.
The JMeter Proxy server passes on all cookies sent by the browser during recording, but does not save them to the test
plan because they are likely to change between runs.
</p>
<h4>Authorization Manager</h4>
<p>
The HTTP(S) Test Script Recorder grabs "<span class="code">Authentication</span>" header, tries to compute the Auth Policy. If Authorization Manager was added to target
controller manually, HTTP(S) Test Script Recorder will find it and add authorization (matching ones will be removed). Otherwise
Authorization Manager will be added to target controller with authorization object.
You may have to fix automatically computed values after recording.
</p>
<h4>Uploading files</h4>
<p>
Some browsers (e.g. Firefox and Opera) don't include the full name of a file when uploading files.
This can cause the JMeter proxy server to fail.
One solution is to ensure that any files to be uploaded are in the JMeter working directory,
either by copying the files there or by starting JMeter in the directory containing the files.
</p>
<h4>Recording HTTP Based Non Textual Protocols not natively available in JMeter</h4>
<p>
You may have to record an HTTP protocol that is not handled by default by JMeter (Custom Binary Protocol, Adobe Flex, Microsoft Silverlight, &hellip; ).
Although JMeter does not provide a native proxy implementation to record these protocols, you have the ability to
record these protocols by implementing a custom <span class="code">SamplerCreator</span>. This Sampler Creator will translate the binary format into a <span class="code">HTTPSamplerBase</span> subclass
that can be added to the JMeter Test Case.
For more details see "Extending JMeter".
</p>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="HTTP_Mirror_Server">HTTP Mirror Server<a class="sectionlink" href="#HTTP_Mirror_Server" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>
The HTTP Mirror Server is a very simple HTTP server - it simply mirrors the data sent to it.
This is useful for checking the content of HTTP requests.
</p>
<p>
It uses default port <span class="code">8081</span>.
</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/mirrorserver.png"><img src="../images/screenshots/mirrorserver.png" width="794" height="157" alt="Screenshot for Control-Panel of HTTP Mirror Server"></a>
<figcaption>Screenshot of Control-Panel of HTTP Mirror Server</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="HTTP_Mirror_Server_parms1">
Parameters
<a class="sectionlink" href="#HTTP_Mirror_Server_parms1" title="Link to here">&para;</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">Port</div>
<div class="description req-true">Port on which Mirror server listens, defaults to <span class="code">8081</span>.</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-false">Max Number of threads</div>
<div class="description req-false">If set to a value &gt; <span class="code">0</span>, number of threads serving requests will be limited to the configured number, if set to a value &le; <span class="code">0</span>
a new thread will be created to serve each incoming request. Defaults to <span class="code">0</span>
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">Max Queue size</div>
<div class="description req-false">Size of queue used for holding tasks before they are executed by Thread Pool, when Thread pool is exceeded, incoming requests will
be held in this queue and discarded when this queue is full. This parameter is only used if Max Number of Threads is greater than <span class="code">0</span>. Defaults to <span class="code">25</span>
</div>
<div class="required req-false">No</div>
</div>
</div>
<div class="clear"></div>
<div class="note">
Note that you can get more control over the responses by adding an HTTP Header Manager with the following name/value pairs:
</div>
<div class="clear"></div>
<div class="properties">
<h3 id="HTTP_Mirror_Server_parms2">
Parameters
<a class="sectionlink" href="#HTTP_Mirror_Server_parms2" title="Link to here">&para;</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">X-Sleep</div>
<div class="description req-false">Time to sleep in ms before sending response</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">X-SetCookie</div>
<div class="description req-false">Cookies to be set on response</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">X-ResponseStatus</div>
<div class="description req-false">Response status, see <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html">HTTP Status responses</a>, example 200 OK, 500 Internal Server Error, &hellip;.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">X-ResponseLength</div>
<div class="description req-false">Size of response, this trims the response to the requested size if that is less than the total size</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">X-SetHeaders</div>
<div class="description req-false">Pipe separated list of headers, example:<br>
<span class="code">headerA=valueA|headerB=valueB</span> would set <span class="code">headerA</span> to <span class="code">valueA</span> and <span class="code">headerB</span> to <span class="code">valueB</span>.
</div>
<div class="required req-false">No</div>
</div>
</div>
<p>
You can also use the following query parameters:
</p>
<div class="properties">
<h3 id="HTTP_Mirror_Server_parms3">
Parameters
<a class="sectionlink" href="#HTTP_Mirror_Server_parms3" title="Link to here">&para;</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">redirect</div>
<div class="description req-false">Generates a 302 (Temporary Redirect) with the provided location.
e.g. <span class="code">?redirect=/path</span>
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">status</div>
<div class="description req-false">Overrides the default status return. e.g. <span class="code">?status=404 Not Found</span>
</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-false">v</div>
<div class="description req-false">Verbose flag, writes some details to standard output. e.g. first line and redirect location if specified</div>
<div class="required req-false">No</div>
</div>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="Property_Display">Property Display<a class="sectionlink" href="#Property_Display" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>
The Property Display shows the values of System or JMeter properties.
Values can be changed by entering new text in the Value column.
</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/property_display.png"><img src="../images/screenshots/property_display.png" width="804" height="508" alt="Screenshot for Control-Panel of Property Display"></a>
<figcaption>Screenshot of Control-Panel of Property Display</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="Property_Display_parms1">
Parameters
<a class="sectionlink" href="#Property_Display_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-false">Descriptive name for this element that is shown in the tree.</div>
<div class="required req-false">No</div>
</div>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="Debug_Sampler">Debug Sampler<a class="sectionlink" href="#Debug_Sampler" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>
The Debug Sampler generates a sample containing the values of all JMeter variables and/or properties.
</p>
<p>
The values can be seen in the <a href="../usermanual/component_reference.html#View_Results_Tree">View Results Tree</a> Listener Response Data pane.
</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/debug_sampler.png"><img src="../images/screenshots/debug_sampler.png" width="431" height="172" alt="Screenshot for Control-Panel of Debug Sampler"></a>
<figcaption>Screenshot of Control-Panel of Debug Sampler</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="Debug_Sampler_parms1">
Parameters
<a class="sectionlink" href="#Debug_Sampler_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-false">Descriptive name for this element that is shown in the tree.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">JMeter Properties</div>
<div class="description req-true">Include JMeter properties?</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">JMeter Variables</div>
<div class="description req-true">Include JMeter variables?</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">System Properties</div>
<div class="description req-true">Include System properties?</div>
<div class="required req-true">Yes</div>
</div>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="Debug_PostProcessor">Debug PostProcessor<a class="sectionlink" href="#Debug_PostProcessor" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>
The Debug PostProcessor creates a subSample with the details of the previous Sampler properties,
JMeter variables, properties and/or System Properties.
</p>
<p>
The values can be seen in the <a href="../usermanual/component_reference.html#View_Results_Tree">View Results Tree</a> Listener Response Data pane.
</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/debug_postprocessor.png"><img src="../images/screenshots/debug_postprocessor.png" width="344" height="193" alt="Screenshot for Control-Panel of Debug PostProcessor"></a>
<figcaption>Screenshot of Control-Panel of Debug PostProcessor</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="Debug_PostProcessor_parms1">
Parameters
<a class="sectionlink" href="#Debug_PostProcessor_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-false">Descriptive name for this element that is shown in the tree.</div>
<div class="required req-false">No</div>
</div>
<div class="property">
<div class="name req-true">JMeter Properties</div>
<div class="description req-true">Whether to show JMeter properties (default <span class="code">false</span>).</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">JMeter Variables</div>
<div class="description req-true">Whether to show JMeter variables (default <span class="code">false</span>).</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">Sampler Properties</div>
<div class="description req-true">Whether to show Sampler properties (default <span class="code">true</span>).</div>
<div class="required req-true">Yes</div>
</div>
<div class="property">
<div class="name req-true">System Properties</div>
<div class="description req-true">Whether to show System properties (default <span class="code">false</span>).</div>
<div class="required req-true">Yes</div>
</div>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="Test_Fragment">Test Fragment<a class="sectionlink" href="#Test_Fragment" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>
The Test Fragment is used in conjunction with the <a href="../usermanual/component_reference.html#Include_Controller">Include Controller</a> and <a href="../usermanual/component_reference.html#Module_Controller">Module Controller</a>.
</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/test_fragment.png"><img src="../images/screenshots/test_fragment.png" width="236" height="94" alt="Screenshot for Control-Panel of Test Fragment"></a>
<figcaption>Screenshot of Control-Panel of Test Fragment</figcaption>
</figure>
</div>
<div class="properties">
<h3 id="Test_Fragment_parms1">
Parameters
<a class="sectionlink" href="#Test_Fragment_parms1" title="Link to here">&para;</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">Name</div>
<div class="description req-true">Descriptive name for this element that is shown in the tree.</div>
<div class="required req-true">Yes</div>
</div>
</div>
<div class="clear"></div>
<div class="note">
When using Test Fragment with <a href="../usermanual/component_reference.html#Module_Controller">Module Controller</a>, ensure you disable the Test Fragment to avoid the execution of Test Fragment itself.
This is done by default since JMeter 2.13.
</div>
<div class="clear"></div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="setUp_Thread_Group">setUp Thread Group<a class="sectionlink" href="#setUp_Thread_Group" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>
A special type of ThreadGroup that can be utilized to perform Pre-Test Actions. The behavior of these threads
is exactly like a normal <a href="../usermanual/component_reference.html#Thread_Group">Thread Group</a> element. The difference is that these type of threads
execute before the test proceeds to the executing of regular Thread Groups.
</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/setup_thread_group.png"><img src="../images/screenshots/setup_thread_group.png" width="1252" height="828" alt="Screenshot for Control-Panel of setUp Thread Group"></a>
<figcaption>Screenshot of Control-Panel of setUp Thread Group</figcaption>
</figure>
</div>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<div class="component">
<h2 id="tearDown_Thread_Group">tearDown Thread Group<a class="sectionlink" href="#tearDown_Thread_Group" title="Link to here">&para;</a>
</h2>
<div class="description">
<p>
A special type of ThreadGroup that can be utilized to perform Post-Test Actions. The behavior of these threads
is exactly like a normal <a href="../usermanual/component_reference.html#Thread_Group">Thread Group</a> element. The difference is that these type of threads
execute after the test has finished executing its regular Thread Groups.
</p>
</div>
<div class="screenshot">
<figure>
<a href="../images/screenshots/teardown_thread_group.png"><img src="../images/screenshots/teardown_thread_group.png" width="1248" height="824" alt="Screenshot for Control-Panel of tearDown Thread Group"></a>
<figcaption>Screenshot of Control-Panel of tearDown Thread Group</figcaption>
</figure>
</div>
<div class="clear"></div>
<div class="note">
Note that by default it won't run if Test is gracefully shutdown, if you want to make it run in this case,
ensure you check option "<span class="code">Run tearDown Thread Groups after shutdown of main threads</span>" on Test Plan element.
If Test Plan is stopped, tearDown will not run even if option is checked.
</div>
<div class="clear"></div>
<figure>
<a href="../images/screenshots/tear_down_on_shutdown.png"><img src="../images/screenshots/tear_down_on_shutdown.png" width="1130" height="486" alt="Figure 1 - Run tearDown Thread Groups after shutdown of main threads"></a>
<figcaption>Figure 1 - Run tearDown Thread Groups after shutdown of main threads</figcaption>
</figure>
<div class="go-top">
<a href="#">^</a>
</div>
</div>
<a href="#">^</a>
</div>
<ul class="pagelinks">
<li>
<a href="boss.html">&lt; Prev</a>
</li>
<li>
<a href="../index.html">Index</a>
</li>
<li>
<a href="properties_reference.html">Next &gt;</a>
</li>
</ul>
<div class="share-links">
Share this page:
<ul>
<li class="fb">
<a data-social-url="https://facebook.com/sharer/sharer.php?u=" title="Share on facebook"><i class="fa fa-facebook" aria-hidden="true"></i>share</a>
</li>
<li class="twitter">
<a data-social-url="https://twitter.com/intent/tweet?url=" title="Tweet on twitter"><i class="fa fa-twitter" aria-hidden="true"></i>tweet</a>
</li>
</ul>
</div>
<a href="#top" id="topButton">Go to top</a>
</div>
<div class="footer">
<div class="copyright">
Copyright &copy;
1999 &ndash;
2020
, 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>
<script>(function(){
"use strict";
// enable 'go to top' button functionality
document.addEventListener('scroll', function() {
if (document.body.scrollTop > 500 || document.documentElement.scrollTop > 500) {
document.getElementById("topButton").style.display = "block";
} else {
document.getElementById("topButton").style.display = "none";
}
});
// fill in the current location into social links on this page.
var as = document.getElementsByTagName('a');
var loc = document.location.href;
if (!loc.toLowerCase().startsWith('http')) {
return;
}
for (var i=0; i<as.length; i++) {
var href = as[i].getAttribute('data-social-url');
if (href !== null) {
as[i].href = href + encodeURIComponent(loc);
}
}
})();</script>
</body>
</html>