<divclass="component"><h2id="FTP_Request">FTP Request<aclass="sectionlink"href="#FTP_Request"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/ftptest/ftp-request.png"><imgsrc="../images/screenshots/ftptest/ftp-request.png"width="861"height="278"alt="Screenshot for FTP Request"></a></div>
<aclass="sectionlink"href="#FTP_Request_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-false">Name</div><divclass="description req-false">Descriptive name for this sampler that is shown in the tree.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Server Name or IP</div><divclass="description req-true">Domain name or IP address of the FTP server.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-false">Port</div><divclass="description req-false">Port to use. If this is >0, then this specific port is used, otherwise JMeter uses the default FTP port.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Remote File:</div><divclass="description req-true">File to retrieve or name of destination file to upload.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Local File:</div><divclass="description req-true">File to upload, or destination for downloads (defaults to remote file name).</div><divclass="required req-true">Yes, if uploading (*)</div></div>
<divclass="property"><divclass="name req-true">Local File Contents:</div><divclass="description req-true">Provides the contents for the upload, overrides the Local File property.</div><divclass="required req-true">Yes, if uploading (*)</div></div>
<divclass="property"><divclass="name req-true">get(RETR) / put(STOR)</div><divclass="description req-true">Whether to retrieve or upload a file.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Use Binary mode ?</div><divclass="description req-true">Check this to use Binary mode (default Ascii)</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Save File in Response ?</div><divclass="description req-true">
<divclass="property"><divclass="name req-false">Password</div><divclass="description req-false">FTP account password. N.B. This will be visible in the test plan.</div><divclass="required req-false">Usually</div></div>
</div>
<divclass="links"><divclass="title">See also:</div><ulclass="links"><li><ahref="test_plan.html#assertions">Assertions</a></li><li><ahref="../usermanual/component_reference.html#FTP_Request_Defaults">FTP Request Defaults</a></li><li><ahref="build-ftp-test-plan.html">Building an FTP Test Plan</a></li></ul></div>
<divclass="component"><h2id="HTTP_Request">HTTP Request<aclass="sectionlink"href="#HTTP_Request"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/http-request.png"><imgsrc="../images/screenshots/http-request.png"width="900"height="686"alt="Screenshot for HTTP Request"></a></div>
<li>Blank Value - does not set implementation on HTTP Samplers, so relies on HTTP Request Defaults if present or on jmeter.httpsampler property defined in jmeter.properties</li>
</ul>
</ul>
</p>
<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>There is a bug in the handling of HTTPS via a Proxy (the CONNECT is not handled correctly).
See Java bugs 6226610 and 6208335.
</li>
<li>It does not support virtual hosts.</li>
<li>It does not support the following methods: COPY, LOCK, MKCOL, MOVE, PATCH, PROPFIND, PROPPATCH, UNLOCK, REPORT, MKCALENDAR.</li>
<li>It does not support client based certificate testing with Keystore Config.</li>
</ul>
<p>Note: the FILE protocol is intended for testing purposes only.
It is handled by the same code regardless of which HTTP Sampler is used.</p>
<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 <ahref="../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 POST)
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>
In versions of JMeter up to 2.2, only a single SSL context was used for all threads and samplers.
This did not generate the proper load for multiple users.
A separate SSL context is now used for each thread.
To revert to the original behaviour, set the JMeter property:
<pre>
https.sessioncontext.shared=true
</pre>
By default, the SSL context is retained for the duration of the test.
In versions of JMeter from 2.5.1, the SSL session can be optionally reset for each test iteration.
To enable this, set the JMeter property:
<pre>
https.use.cached.ssl.context=false
</pre>
Note: this does not apply to the Java HTTP implementation.
</p>
<p>
JMeter defaults to the SSL protocol level TLS.
If the server needs a different level, e.g. SSLv3, change the JMeter property, for example:
<pre>
https.default.protocol=SSLv3
</pre>
</p>
<p>
JMeter also allows one to enable additional protocols, by changing the property <tt>https.socket.protocols</tt>.
</p>
<p>If the request uses cookies, then you will also need an
<ahref="../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>
<aclass="sectionlink"href="#HTTP_Request_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-false">Name</div><divclass="description req-false">Descriptive name for this sampler that is shown in the tree.</div><divclass="required req-false">No</div></div>
</div><divclass="required req-true">Yes, unless provided by HTTP Request Defaults</div></div>
<divclass="property"><divclass="name req-false">Port</div><divclass="description req-false">Port the web server is listening to. Default: 80</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Connect Timeout</div><divclass="description req-false">Connection Timeout. Number of milliseconds to wait for a connection to open.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Response Timeout</div><divclass="description req-false">Response Timeout. Number of milliseconds to wait for a response.
A <ahref="../usermanual/component_reference.html#Duration_Assertion">Duration Assertion</a> can be used to detect responses that take too long to complete.
<divclass="property"><divclass="name req-false">Server (proxy)</div><divclass="description req-false">Hostname or IP address of a proxy server to perform request. [Do not include the http:// prefix.]</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Port</div><divclass="description req-false">Port the proxy server is listening to.</div><divclass="required req-false">No, unless proxy hostname is specified</div></div>
<divclass="property"><divclass="name req-false">Username</div><divclass="description req-false">(Optional) username for proxy server.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Password</div><divclass="description req-false">(Optional) password for proxy server. (N.B. this is stored unencrypted in the test plan)</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Use KeepAlive</div><divclass="description req-false">JMeter sets the Connection: keep-alive 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><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Use multipart/form-data for HTTP POST</div><divclass="description req-false">
<divclass="property"><divclass="name req-true">Path</div><divclass="description req-true">The path to resource (for example, /servlets/myServlet). If the
<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 : '$', '&', '+', ',' , '/', ':', ';', '=', '?', '@'</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 : ' ', '<', '>', '#', '%', ...</li>
<divclass="property"><divclass="name req-false">Parameter name:</div><divclass="description req-false">Value of the "name" web request parameter.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">MIME Type</div><divclass="description req-false">MIME type (for example, text/plain).
<divclass="property"><divclass="name req-false">Retrieve All Embedded Resources from HTML Files</div><divclass="description req-false">Tell JMeter to parse the HTML file
<divclass="property"><divclass="name req-false">Use as monitor</div><divclass="description req-false">For use with the <ahref="../usermanual/component_reference.html#Monitor_Results">Monitor Results</a> listener.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Save response as MD5 hash?</div><divclass="description req-false">
<divclass="property"><divclass="name req-false">Use concurrent pool</div><divclass="description req-false">Use a pool of concurrent connections to get embedded resources.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Size</div><divclass="description req-false">Pool size for concurrent connections used to get embedded resources.</div><divclass="required req-false">No</div></div>
<figure><ahref="../images/screenshots/http-request-raw-single-parameter.png"><imgsrc="../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><ahref="../images/screenshots/http-request-confirm-raw-body.png"><imgsrc="../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><ahref="../images/screenshots/http-request-raw-body.png"><imgsrc="../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>
<divclass="clear"></div><divclass="note">Versions of JMeter before 2.5 returns only data response size (uncompressed if request uses gzip/defate mode).
<br>To return to settings before version 2.5, set the two properties to false.</div><divclass="clear"></div>
<divclass="links"><divclass="title">See also:</div><ulclass="links"><li><ahref="test_plan.html#assertions">Assertion</a></li><li><ahref="build-web-test-plan.html">Building a Web Test Plan</a></li><li><ahref="build-adv-web-test-plan.html">Building an Advanced Web Test Plan</a></li><li><ahref="../usermanual/component_reference.html#HTTP_Authorization_Manager">HTTP Authorization Manager</a></li><li><ahref="../usermanual/component_reference.html#HTTP_Cookie_Manager">HTTP Cookie Manager</a></li><li><ahref="../usermanual/component_reference.html#HTTP_Header_Manager">HTTP Header Manager</a></li><li><ahref="../usermanual/component_reference.html#HTML_Link_Parser">HTML Link Parser</a></li><li><ahref="../usermanual/component_reference.html#HTTP(S)_Test_Script_Recorder">HTTP(S) Test Script Recorder</a></li><li><ahref="../usermanual/component_reference.html#HTTP_Request_Defaults">HTTP Request Defaults</a></li><li><ahref="build-adv-web-test-plan.html#session_url_rewriting">HTTP Requests and Session ID's: URL Rewriting</a></li></ul></div>
<divclass="component"><h2id="JDBC_Request">JDBC Request<aclass="sectionlink"href="#JDBC_Request"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/jdbctest/jdbc-request.png"><imgsrc="../images/screenshots/jdbctest/jdbc-request.png"width="466"height="334"alt="Screenshot for JDBC Request"></a></div>
<divclass="description"><p>This sampler lets you send an JDBC Request (an SQL query) to a database.</p>
<p>Before using this you need to set up a
<ahref="../usermanual/component_reference.html#JDBC_Connection_Configuration">JDBC Connection Configuration</a> Configuration element
<aclass="sectionlink"href="#JDBC_Request_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-false">Name</div><divclass="description req-false">Descriptive name for this sampler that is shown in the tree.</div><divclass="required req-false">No</div></div>
When "Prepared Select Statement", "Prepared Update Statement" or "Callable Statement" types are selected, a Statement Cache per connection is used by JDBC Request.
It stores by default up to 100 PreparedStatements per connection, this can impact your database (Open Cursors).
<divclass="clear"></div><divclass="note">There must be as many values as there are placeholders in the statement even if your parameters are OUT ones, be sure to set a value even if the value will not be used (for example in a CallableStatement).</div><divclass="clear"></div>
</div><divclass="required req-true">Yes, if a prepared or callable statement has parameters</div></div>
Comma-separated list of SQL parameter types (e.g. INTEGER, DATE, VARCHAR, DOUBLE) or integer values of Constants when for example you use custom database types proposed by driver (-10 for OracleTypes.CURSOR for example).<br>
These are defined as fields in the class java.sql.Types, see for example:<br>
<ahref="http://docs.oracle.com/javase/6/docs/api/java/sql/Types.html">Javadoc for java.sql.Types</a>.<br>
</div><divclass="required req-true">Yes, if a prepared or callable statement has parameters</div></div>
<divclass="property"><divclass="name req-false">Variable Names</div><divclass="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 OUT parameters returned by the call.
If there are less variable names than OUT parameters only as many results shall be stored in the thread-context variables as variable names were supplied.
<divclass="property"><divclass="name req-false">Handle ResultSet</div><divclass="description req-false">Defines how ResultSet returned from callable statements be handled:
<ul>
<li>Store As String (default) - All variables on Variable Names list are stored as strings, will not iterate through a ResultSets when present on the list.</li>
<li>Store As Object - Variables of ResultSet 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 ResultSet </li>
<li>Count Records - Variables of ResultSet types will be iterated through showing the count of records as result. Variables will be stored as Strings.</li>
<divclass="links"><divclass="title">See also:</div><ulclass="links"><li><ahref="build-db-test-plan.html">Building a Database Test Plan</a></li><li><ahref="../usermanual/component_reference.html#JDBC_Connection_Configuration">JDBC Connection Configuration</a></li></ul></div>
<divclass="clear"></div><divclass="note">Versions of JMeter after 2.3.2 use UTF-8 as the character encoding. Previously the platform default was used.</div><divclass="clear"></div>
<divclass="clear"></div><divclass="note">Ensure Variable Name is unique accross Test Plan.</div><divclass="clear"></div>
<divclass="component"><h2id="Java_Request">Java Request<aclass="sectionlink"href="#Java_Request"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/java_request.png"><imgsrc="../images/screenshots/java_request.png"width="563"height="347"alt="Screenshot for Java Request"></a></div>
<divclass="clear"></div><divclass="note">Since JMeter 2.8, if the method teardownTest is not overriden by a subclass of AbstractJavaSamplerClient, its teardownTest method will not be called.
<aclass="sectionlink"href="#Java_Request_parms2"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-true">Sleep_time</div><divclass="description req-true">How long to sleep for (ms)</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Sleep_mask</div><divclass="description req-true">How much "randomness" to add:<br>
<aclass="sectionlink"href="#Java_Request_parms3"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-false">Label</div><divclass="description req-false">The label to use. If provided, overrides Name</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">ResponseCode</div><divclass="description req-false">If provided, sets the SampleResult ResponseCode.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">ResponseMessage</div><divclass="description req-false">If provided, sets the SampleResult ResponseMessage.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Status</div><divclass="description req-false">If provided, sets the SampleResult Status. If this equals "OK" (ignoring case) then the status is set to success, otherwise the sample is marked as failed.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">SamplerData</div><divclass="description req-false">If provided, sets the SampleResult SamplerData.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">ResultData</div><divclass="description req-false">If provided, sets the SampleResult ResultData.</div><divclass="required req-false">No</div></div>
</div>
<divclass="go-top"><ahref="#">^</a></div></div>
<divclass="component"><h2id="SOAP/XML-RPC_Request">SOAP/XML-RPC Request<aclass="sectionlink"href="#SOAP/XML-RPC_Request"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/soap_sampler.png"><imgsrc="../images/screenshots/soap_sampler.png"width="426"height="276"alt="Screenshot for SOAP/XML-RPC Request"></a></div>
<divclass="description"><p>This sampler lets you send a SOAP request to a webservice. It can also be
<aclass="sectionlink"href="#SOAP/XML-RPC_Request_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-false">Name</div><divclass="description req-false">Descriptive name for this sampler
that is shown in the tree.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">URL</div><divclass="description req-true">The URL to direct the SOAP request to.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-false">Send SOAP action</div><divclass="description req-false">Send a SOAP action header? (overrides the Header Manager)</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Soap/XML-RPC Data</div><divclass="description req-false">The Soap XML message, or XML-RPC instructions.
<divclass="property"><divclass="name req-false">Filename</div><divclass="description req-false">If specified, then the contents of the file are sent, and the Data field is ignored</div><divclass="required req-false">No</div></div>
</div>
<divclass="go-top"><ahref="#">^</a></div></div>
<divclass="component"><h2id="WebService(SOAP)_Request_(DEPRECATED)">WebService(SOAP) Request (DEPRECATED)<aclass="sectionlink"href="#WebService(SOAP)_Request_(DEPRECATED)"title="Link to here">¶</a></h2><divclass="deprecated">
</div><divclass="screenshot"><ahref="../images/screenshots/webservice_sampler.png"><imgsrc="../images/screenshots/webservice_sampler.png"width="943"height="648"alt="Screenshot for WebService(SOAP) Request (DEPRECATED)"></a></div>
<divclass="description"><p>This sampler has been tested with IIS Webservice running .NET 1.0 and .NET 1.1.
<divclass="property"><divclass="name req-false">Web Methods</div><divclass="description req-false">Will be populated from the WSDL when the Load WSDL button is pressed.
<divclass="property"><divclass="name req-true">Protocol</div><divclass="description req-true">HTTP or HTTPS are acceptable protocol.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Server Name or IP</div><divclass="description req-true">The hostname or IP address.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Path</div><divclass="description req-true">Path for the webservice.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">SOAPAction</div><divclass="description req-true">The SOAPAction defined in the webservice description or WSDL.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Soap/XML-RPC Data</div><divclass="description req-true">The Soap XML message</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-false">Read SOAP Response</div><divclass="description req-false">Read the SOAP reponse (consumes performance). Permit to have assertions or post-processors</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Use HTTP Proxy</div><divclass="description req-false">Check box if http proxy should be used</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Server Name or IP</div><divclass="description req-false">Proxy hostname</div><divclass="required req-false">No</div></div>
<divclass="component"><h2id="LDAP_Request">LDAP Request<aclass="sectionlink"href="#LDAP_Request"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/ldap_request.png"><imgsrc="../images/screenshots/ldap_request.png"width="621"height="462"alt="Screenshot for LDAP Request"></a></div>
<divclass="description">This Sampler lets you send a different Ldap request(Add, Modify, Delete and Search) to an LDAP server.
<p>If you are going to send multiple requests to the same LDAP server, consider
using an <ahref="../usermanual/component_reference.html#LDAP_Request_Defaults">LDAP Request Defaults</a>
LDAP Request.</p> The same way the <ahref="../usermanual/component_reference.html#Login_Config_Element">Login Config Element</a> also using for Login and password.
</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</li>
<ol><li>Inbuilt test :
<p>This will add a pre-defined entry in the LDAP Server and calculate
<aclass="sectionlink"href="#LDAP_Request_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-false">Name</div><divclass="description req-false">Descriptive name for this sampler that is shown in the tree.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Server Name or IP</div><divclass="description req-true">Domain name or IP address of the LDAP server.
JMeter assumes the LDAP server is listening on the default port(389).</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">root DN</div><divclass="description req-true">DN for the server to communicate</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-false">Username</div><divclass="description req-false">LDAP server username.</div><divclass="required req-false">Usually</div></div>
<divclass="property"><divclass="name req-false">Password</div><divclass="description req-false">LDAP server password. (N.B. this is stored unencrypted in the test plan)</div><divclass="required req-false">Usually</div></div>
<divclass="property"><divclass="name req-true">Entry DN</div><divclass="description req-true">the name of the context to create or Modify; may not be empty Example: do you want to add cn=apache,ou=test
<divclass="property"><divclass="name req-true">Delete</div><divclass="description req-true">the name of the context to Delete; may not be empty</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Search base</div><divclass="description req-true">the name of the context or object to search</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Search filter</div><divclass="description req-true"> the filter expression to use for the search; may not be null</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">add test</div><divclass="description req-true"> this name, value pair to added in the given context object</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">modify test</div><divclass="description req-true"> this name, value pair to add or modify in the given context object</div><divclass="required req-true">Yes</div></div>
<divclass="links"><divclass="title">See also:</div><ulclass="links"><li><ahref="build-ldap-test-plan.html">Building an Ldap Test Plan</a></li><li><ahref="../usermanual/component_reference.html#LDAP_Request_Defaults">LDAP Request Defaults</a></li></ul></div>
<divclass="component"><h2id="LDAP_Extended_Request">LDAP Extended Request<aclass="sectionlink"href="#LDAP_Extended_Request"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/ldapext_request.png"><imgsrc="../images/screenshots/ldapext_request.png"width="619"height="371"alt="Screenshot for LDAP Extended Request"></a></div>
<divclass="description">This Sampler can send all 8 different LDAP request 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 <ahref="../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
<divclass="property"><divclass="name req-false">Name</div><divclass="description req-false">Descriptive name for this sampler that is shown in the tree.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Servername</div><divclass="description req-true">The name (or IP-address) of the LDAP server.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-false">Port</div><divclass="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><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">DN</div><divclass="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><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Username</div><divclass="description req-false">Full distinguished name of the user as which you want to bind.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Password</div><divclass="description req-false">Password for the above user. If omitted it will result in an anonymous bind.
If is 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><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Name</div><divclass="description req-false">Descriptive name for this sampler that is shown in the tree.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Name</div><divclass="description req-false">Descriptive name for this sampler that is shown in the tree.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Username</div><divclass="description req-true">Full distinguished name of the user as which you want to bind.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-false">Password</div><divclass="description req-false">Password for the above user. If omitted it will result in an anonymous bind.
If is is incorrect, the sampler will return an error. (N.B. this is stored unencrypted in the test plan)</div><divclass="required req-false">No</div></div>
</div>
<br>
<li><b>Rename entry</b></li>
<p>This is the LDAP "moddn" operation. It can be used to rename an entry, but
also for moving an entry or a complete subtree to a different place in
<divclass="property"><divclass="name req-false">Name</div><divclass="description req-false">Descriptive name for this sampler that is shown in the tree.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Old entry name</div><divclass="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><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">New distinguished name</div><divclass="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><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-false">Name</div><divclass="description req-false">Descriptive name for this sampler that is shown in the tree.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Entry DN</div><divclass="description req-true">Distinguished name of the object you want to add, relative to the given DN in the thread bind operation.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Add test</div><divclass="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><divclass="required req-true">Yes</div></div>
</div>
<br>
<li><b>Delete test</b></li>
<p> This is the LDAP "delete" operation, it can be used to delete an
<divclass="property"><divclass="name req-false">Name</div><divclass="description req-false">Descriptive name for this sampler that is shown in the tree.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Delete</div><divclass="description req-true">Distinguished name of the object you want to delete, relative to the given DN in the thread bind operation.</div><divclass="required req-true">Yes</div></div>
</div>
<br>
<li><b>Search test</b></li>
<p>This is the LDAP "search" operation, and will be used for defining searches. </p>
<divclass="property"><divclass="name req-false">Name</div><divclass="description req-false">Descriptive name for this sampler that is shown in the tree.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Search base</div><divclass="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><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Search Filter</div><divclass="description req-true">searchfilter, must be specified in LDAP syntax.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-false">Scope</div><divclass="description req-false">Use 0 for baseobject-, 1 for onelevel- and 2 for a subtree search. (Default=0)</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Size Limit</div><divclass="description req-false">Specify the maximum number of results you want back from the server. (default=0, which means no limit.) When the sampler hits the maximum number of results, it will fail with errorcode 4</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Time Limit</div><divclass="description req-false">Specify the maximum amount of (cpu)time (in miliseconds) that the server can spend on your search. Take care, this does not say anything about the responsetime. (default is 0, which means no limit)</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Attributes</div><divclass="description req-false">Specify the attributes you want to have returned, seperated by a semicolon. An empty field will return all attributes</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Return object</div><divclass="description req-false">Whether the object will be returned (true) or not (false). Default=false</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Dereference aliases</div><divclass="description req-false">If true, it will dereference aliases, if false, it will not follow them (default=false)</div><divclass="required req-false">No</div></div>
</div>
<br>
<li><b>Modification test</b></li>
<p>This is the LDAP "modify" operation. It can be used to modify an object. It
can be used to add, delete or replace values of an attribute. </p>
<divclass="property"><divclass="name req-false">Name</div><divclass="description req-false">Descriptive name for this sampler that is shown in the tree.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Entry name</div><divclass="description req-true">Distinguished name of the object you want to modify, relative
to the given DN in the thread bind operation</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Modification test</div><divclass="description req-true">The attribute-value-opCode triples. The opCode can be any
valid LDAP operationCode (add, delete/remove or replace). If you don't specify a value with a delete operation,
all values of the given attribute will be deleted. If you do specify a value in a delete operation, only
the given value will be deleted. If this value is non-existent, the sampler will fail the test.</div><divclass="required req-true">Yes</div></div>
</div>
<br>
<li><b>Compare</b></li>
<p>This is the LDAP "compare" 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 "member" of an object of the type groupOfNames.
If the compare operation fails, this test fails with errorcode 49.</p>
<divclass="property"><divclass="name req-false">Name</div><divclass="description req-false">Descriptive name for this sampler that is shown in the tree.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Entry DN</div><divclass="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><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Compare filter</div><divclass="description req-true">In the form "attribute=value"</div><divclass="required req-true">Yes</div></div>
</div>
</ol>
<divclass="links"><divclass="title">See also:</div><ulclass="links"><li><ahref="build-ldapext-test-plan.html">Building an LDAP Test Plan</a></li><li><ahref="../usermanual/component_reference.html#LDAP_Extended_Request_Defaults">LDAP Extended Request Defaults</a></li></ul></div>
<divclass="component"><h2id="Access_Log_Sampler">Access Log Sampler<aclass="sectionlink"href="#Access_Log_Sampler"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/accesslogsampler.png"><imgsrc="../images/screenshots/accesslogsampler.png"width="613"height="318"alt="Screenshot for Access Log Sampler"></a></div>
<center><h2>(Beta Code)</h2></center>
<divclass="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....
The current implementation is complete, but some features have not been enabled.
There is a filter for the access log parser, but I haven't figured out how to link to the pre-processor.
Once I do, changes to the sampler will be made to enable that functionality.</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
<divclass="clear"></div><divclass="note">The current implementation of the parser only looks at the text within the quotes that contains one of the HTTP protocol methods (GET, PUT, POST, DELETE...).
Everything else is stripped out and ignored. For example, the response code is completely
ignored by the parser. </div><divclass="clear"></div>
<p>For the future, it might be nice to filter out entries that
do not have a response code of 200. Extending the sampler should be fairly simple. There
<aclass="sectionlink"href="#Access_Log_Sampler_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-false">Name</div><divclass="description req-false">Descriptive name for this sampler that is shown in the tree.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Server</div><divclass="description req-true">Domain name or IP address of the web server.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-false">Port</div><divclass="description req-false">Port the web server is listening to.</div><divclass="required req-false">No (defaults to 80)</div></div>
<divclass="property"><divclass="name req-true">Log parser class</div><divclass="description req-true">The log parser class is responsible for parsing the logs.</div><divclass="required req-true">Yes (default provided)</div></div>
<divclass="property"><divclass="name req-false">Filter</div><divclass="description req-false">The filter class is used to filter out certain lines.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Location of log file</div><divclass="description req-true">The location of the access log file.</div><divclass="required req-true">Yes</div></div>
<divclass="component"><h2id="BeanShell_Sampler">BeanShell Sampler<aclass="sectionlink"href="#BeanShell_Sampler"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/beanshellsampler.png"><imgsrc="../images/screenshots/beanshellsampler.png"width="848"height="566"alt="Screenshot for BeanShell Sampler"></a></div>
<divclass="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 <ahref="http://www.beanshell.org/">BeanShell website.</a></b>
<aclass="sectionlink"href="#BeanShell_Sampler_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-false">Name</div><divclass="description req-false">Descriptive name for this sampler that is shown in the tree.
The name is stored in the script variable Label</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Reset bsh.Interpreter before each call</div><divclass="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 <ahref="best-practices#bsh_scripting">Best Practices - BeanShell scripting</a>.
<li>vars - <ahref="../api/org/apache/jmeter/threads/JMeterVariables.html">JMeterVariables</a> - e.g. vars.get("VAR1"); vars.put("VAR2","value"); vars.remove("VAR3"); vars.putObject("OBJ1",new Object());</li>
<li>props - JMeterProperties (class java.util.Properties)- e.g. props.get("START.HMS"); props.put("PROP1","1234");</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 <ahref="../api/org/apache/jmeter/samplers/SampleResult.html">SampleResult</a>:</p>
<ul>
<li>ResponseCode - for example 200</li>
<li>ResponseMessage - for example "OK"</li>
<li>IsSuccess - true/false</li>
</ul>
<p>The SampleResult ResponseData is set from the return value of the script.
Since version 2.1.2, if the script returns null, it can set the response directly, by using the method
SampleResult.setResponseData(data), where data is either a String or a byte array.
The data type defaults to "text", but can be set to binary by using the method
SampleResult.setDataType(SampleResult.BINARY).
</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
For details on the methods available for the various classes (<ahref="../api/org/apache/jmeter/threads/JMeterVariables.html">JMeterVariables</a>, <ahref="../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 ...
<divclass="component"><h2id="BSF_Sampler">BSF Sampler<aclass="sectionlink"href="#BSF_Sampler"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/bsfsampler.png"><imgsrc="../images/screenshots/bsfsampler.png"width="848"height="590"alt="Screenshot for BSF Sampler"></a></div>
<divclass="description"><p>This sampler allows you to write a sampler using a BSF scripting language.<br>
See the <ahref="http://commons.apache.org/bsf/index.html">Apache Bean Scripting Framework</a>
website for details of the languages supported.
You may need to download the appropriate jars for the language; they should be put in the JMeter <b>lib</b> directory.
</p>
<divclass="clear"></div><divclass="note">
The BSF API has been largely superseded by JSR-223, which is included in Java 6 onwards.
Most scripting languages now include support for JSR-223; please use the JSR223 Sampler instead.
The BSF Sampler should only be needed for supporting legacy languages/test scripts.
</div><divclass="clear"></div>
<p>By default, JMeter supports the following languages:</p>
<ul>
<li>javascript</li>
<li>jexl (JMeter version 2.3.2 and later)</li>
<li>xslt</li>
</ul>
<divclass="clear"></div><divclass="note">Unlike the BeanShell sampler, the interpreter is not saved between invocations.</div><divclass="clear"></div>
<aclass="sectionlink"href="#BSF_Sampler_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-false">Name</div><divclass="description req-false">Descriptive name for this sampler that is shown in the tree.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Scripting Language</div><divclass="description req-true">Name of the BSF scripting language to be used.
N.B. Not all the languages in the drop-down list are supported by default.
The following are supported: jexl, javascript, xslt.
Others may be available if the appropriate jar is installed in the JMeter lib directory.
<divclass="property"><divclass="name req-false">Script File</div><divclass="description req-false">Name of a file to be used as a BSF script, if a relative file path is used, then it will be relative to directory referenced by "user.dir" System property</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Parameters</div><divclass="description req-false">List of parameters to be passed to the script file or the script.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Script</div><divclass="description req-true">Script to be passed to BSF language</div><divclass="required req-true">Yes (unless script file is provided)</div></div>
<divclass="component"><h2id="JSR223_Sampler">JSR223 Sampler<aclass="sectionlink"href="#JSR223_Sampler"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/jsr223-sampler.png"><imgsrc="../images/screenshots/jsr223-sampler.png"width="846"height="630"alt="Screenshot for JSR223 Sampler"></a></div>
The JSR223 test elements have a feature (compilation) that can significantly increase performance.
To benefit from this feature:
<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 fill in script cache key property, ensure it is unique across Test Plan as JMeter will use it to cache result of compilation.
<divclass="clear"></div><divclass="note">When using this feature, ensure you script code does not use JMeter variables directly in script code as caching would only cache first replacement. Instead use script parameters.</div><divclass="clear"></div>
<divclass="clear"></div><divclass="note">To benefit fomr Caching and compilation, language engine used for scripting must implement JSR223 Compilable interface (Groovy is one of these, java, beanshell and javascript are not)</div><divclass="clear"></div>
</li>
</ul>
Cache size is controlled by the following jmeter property (jmeter.properties):
<ul>
<li>jsr223.compiled_scripts_cache_size=100</li>
</ul>
For details, see <ahref="../usermanual/component_reference.html#BSF_Sampler">BSF Sampler</a>.
<divclass="clear"></div><divclass="note">Unlike the BeanShell sampler, the interpreter is not saved between invocations.</div><divclass="clear"></div>
<divclass="clear"></div><divclass="note">
Since JMeter 2.8, JSR223 Test Elements using Script file or Script text + cache key are now Compiled if ScriptEngine supports this feature, this enables great performance enhancements.
</div><divclass="clear"></div>
</div>
<divclass="clear"></div><divclass="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. props.get("START.HMS"); props.put("PROP1","1234");
<divclass="component"><h2id="TCP_Sampler">TCP Sampler<aclass="sectionlink"href="#TCP_Sampler"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/tcpsampler.png"><imgsrc="../images/screenshots/tcpsampler.png"width="827"height="521"alt="Screenshot for TCP Sampler"></a></div>
<divclass="description">
<p>
The TCP Sampler opens a TCP/IP connection to the specified server.
It then sends the text, and waits for a response.
<br>
If "Re-use connection" 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 "Re-use connection" and "Close connection" 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.
<br>
If an error is detected - or "Re-use connection" is not selected - the socket is closed.
Another socket will be reopened on the next sample.
<br>
The following properties can be used to control its operation:
</p>
<ul>
<li>tcp.status.prefix - text that precedes a status number</li>
<li>tcp.status.suffix - text that follows a status number</li>
<li>tcp.status.properties - name of property file to convert status codes to messages</li>
<li>tcp.handler - Name of TCP Handler class (default TCPClientImpl) - only used if not specified on the GUI</li>
</ul>
The class that handles the connection is defined by the GUI, failing that the property tcp.handler.
If not found, the class is then searched for in the package org.apache.jmeter.protocol.tcp.sampler.
<p>
Users can provide their own implementation.
The class must extend org.apache.jmeter.protocol.tcp.sampler.TCPClient.
</p>
<p>
The following implementations are currently provided.
<ul>
<li>TCPClientImpl</li>
<li>BinaryTCPClientImpl</li>
<li>LengthPrefixedBinaryTCPClientImpl</li>
</ul>
The implementations behave as follows:
</p>
<p><b>TCPClientImpl</b><br>
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 <b>tcp.eolByte</b>, otherwise until the end of the input stream.
You can control charset encoding by setting <b>tcp.charset</b>, which will default to Platform default encoding.
</p>
<p><b>BinaryTCPClientImpl</b><br>
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 <b>tcp.BinaryTCPClient.eomByte</b>, otherwise until the end of the input stream.
</p>
<p><b>LengthPrefixedBinaryTCPClientImpl</b><br>
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 <b>tcp.binarylength.prefix.length</b>.
</p>
<p><b>Timeout handling</b>
If the timeout is set, the read will be terminated when this expires.
So if you are using an eolByte/eomByte, make sure the timeout is sufficiently long,
otherwise the read will be terminated early.
</p>
<p><b>Response handling</b>
<br>
If tcp.status.prefix 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).
<br>
For example, if the prefix = "[" and the suffix = "]", then the following repsonse:
<br>
[J28] XI123,23,GBP,CR
<br>
would have the response code J28.
<br>
Response codes in the range "400"-"499" and "500"-"599" are currently regarded as failures;
all others are successful. [This needs to be made configurable!]
</p>
<divclass="clear"></div><divclass="note">The login name/password are not used by the supplied TCP implementations.</div><divclass="clear"></div>
<br>
Sockets are disconnected at the end of a test run.
<aclass="sectionlink"href="#TCP_Sampler_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-true">Name</div><divclass="description req-true">Descriptive name for this element that is shown in the tree.</div><divclass="required req-true"></div></div>
<divclass="property"><divclass="name req-false">TCPClient classname</div><divclass="description req-false">Name of the TCPClient class. Defaults to the property tcp.handler, failing that TCPClientImpl.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">ServerName or IP</div><divclass="description req-true">Name or IP of TCP server</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Port Number</div><divclass="description req-true">Port to be used</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Re-use connection</div><divclass="description req-true">If selected, the connection is kept open. Otherwise it is closed when the data has been read.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Close connection</div><divclass="description req-true">If selected, the connection will be closed after running the sampler.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-false">SO_LINGER</div><divclass="description req-false">Enable/disable SO_LINGER with the specified linger time in seconds when a socket is created. If you set "SO_LINGER" value as 0, you may prevent large numbers of sockets sitting around with a TIME_WAIT status.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">End of line(EOL) byte value</div><divclass="description req-false">Byte value for end of line, set this to a value outside the range -128 to +127 to skip eol checking. You may set this in jmeter.properties file as well with eolByte property. If you set this in TCP Sampler Config and in jmeter.properties file at the same time, the setting value in the TCP Sampler Config will be used.</div><divclass="required req-false">No</div></div>
If selected, this will disable Nagle's algorithm, otherwise Nagle's algorithm will be used.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Text to Send</div><divclass="description req-true">Text to be sent</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-false">Login User</div><divclass="description req-false">User Name - not used by default implementation</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Password</div><divclass="description req-false">Password - not used by default implementation (N.B. this is stored unencrypted in the test plan)</div><divclass="required req-false">No</div></div>
<divclass="component"><h2id="JMS_Publisher">JMS Publisher<aclass="sectionlink"href="#JMS_Publisher"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/jmspublisher.png"><imgsrc="../images/screenshots/jmspublisher.png"width="854"height="796"alt="Screenshot for JMS Publisher"></a></div>
<divclass="clear"></div><divclass="note">BETA CODE - the code is still subject to change</div><divclass="clear"></div>
<divclass="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>
<divclass="clear"></div><divclass="note">JMeter does not include any JMS implementation jar; this must be downloaded from the JMS provider and put in the lib directory</div><divclass="clear"></div>
<aclass="sectionlink"href="#JMS_Publisher_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-true">Name</div><divclass="description req-true">Descriptive name for this element that is shown in the tree.</div><divclass="required req-true"></div></div>
<divclass="property"><divclass="name req-false">JNDI Initial Context Factory</div><divclass="description req-false">Name of the context factory</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Provider URL</div><divclass="description req-true">The URL for the jms provider</div><divclass="required req-true">Yes, unless using jndi.properties</div></div>
<divclass="property"><divclass="name req-true">Destination</div><divclass="description req-true">The message destination (topic or queue name)</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Setup</div><divclass="description req-true">The destination setup type. With At startup, the destination name is static (i.e. always same name during the test), with Each sample, the destination name is dynamic and is evaluate at each sample (i.e. the destination name may be a variable)</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Authentication</div><divclass="description req-true">Authentication requirement for the JMS provider</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-false">Password</div><divclass="description req-false">Password (N.B. this is stored unencrypted in the test plan)</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Number of samples to aggregate</div><divclass="description req-true">Number of samples to aggregate</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Message source</div><divclass="description req-true">Where to obtain the message:
<ul>
<li>From File : means the referenced file will be read and reused by all samples</li>
<li>Random File from folder specified below : means a random file will be selected from folder specified below, this folder must contain either files with extension .dat for Bytes Messages, or files with extension .txt or .obj for Object or Text messages</li>
<li>Text area : The Message to use either for Text or Object message</li>
<td><ahref="http://activemq.apache.org/jndi-support.html#JNDISupport-Dynamicallycreatingdestinations">Dynamically define</a> the QUEUENAME to JNDI</td></tr>
<td><ahref="http://activemq.apache.org/jndi-support.html#JNDISupport-Dynamicallycreatingdestinations">Dynamically define</a> the TOPICNAME to JNDI</td></tr>
<divclass="component"><h2id="JMS_Subscriber">JMS Subscriber<aclass="sectionlink"href="#JMS_Subscriber"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/jmssubscriber.png"><imgsrc="../images/screenshots/jmssubscriber.png"width="709"height="498"alt="Screenshot for JMS Subscriber"></a></div>
<divclass="clear"></div><divclass="note">BETA CODE - the code is still subject to change</div><divclass="clear"></div>
<divclass="description">
<p>
JMS Publisher 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>
<divclass="clear"></div><divclass="note">JMeter does not include any JMS implementation jar; this must be downloaded from the JMS provider and put in the lib directory</div><divclass="clear"></div>
<aclass="sectionlink"href="#JMS_Subscriber_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-true">Name</div><divclass="description req-true">Descriptive name for this element that is shown in the tree.</div><divclass="required req-true"></div></div>
<divclass="property"><divclass="name req-false">JNDI Initial Context Factory</div><divclass="description req-false">Name of the context factory</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Provider URL</div><divclass="description req-false">The URL for the jms provider</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Destination</div><divclass="description req-true">the message destination (topic or queue name)</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-false">Durable Subscription ID</div><divclass="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><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Client ID</div><divclass="description req-false">The Client ID to use when you you use a durable subscription.
Be sure to add a variable like ${__threadNum} when you have more than one Thread.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">JMS Selector</div><divclass="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><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Setup</div><divclass="description req-true">The destination setup type. With At startup, the destination name is static (i.e. always same name during the test), with Each sample, the destination name is dynamic and is evaluate at each sample (i.e. the destination name may be a variable)</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Authentication</div><divclass="description req-true">Authentication requirement for the JMS provider</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-false">Password</div><divclass="description req-false">Password (N.B. this is stored unencrypted in the test plan)</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Number of samples to aggregate</div><divclass="description req-true">number of samples to aggregate</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Read response</div><divclass="description req-true">should the sampler read the response. If not, only the response length is returned.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Timeout</div><divclass="description req-true">Specify the timeout to be applied, in milliseconds. 0=none.
This is the overall aggregate timeout, not per sample.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Client</div><divclass="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:
<ul>
<li>MessageConsumer.receive() - calls receive() 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.
</li>
<li>MessageListener.onMessage() - establishes a Listener that stores all incoming messages on a queue.
The listener remains active after the sampler completes.
<divclass="component"><h2id="JMS_Point-to-Point">JMS Point-to-Point<aclass="sectionlink"href="#JMS_Point-to-Point"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/jms/JMS_Point-to-Point.png"><imgsrc="../images/screenshots/jms/JMS_Point-to-Point.png"width="882"height="804"alt="Screenshot for JMS Point-to-Point"></a></div>
<divclass="clear"></div><divclass="note">BETA CODE - the code is still subject to change</div><divclass="clear"></div>
<divclass="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>
<b>Request Only</b> will typically used to put load on a JMS System.<br>
<b>Request Response</b> 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>
</p>
<p>
Versions of JMeter after 2.3.2 use the properties java.naming.security.[principal|credentials] - if present -
when creating the Queue Connection. If this behaviour is not desired, set the JMeter property
<b>JMSSampler.useSecurity.properties=false</b>
</p>
<br>
<divclass="clear"></div><divclass="note">JMeter does not include any JMS implementation jar; this must be downloaded from the JMS provider and put in the lib directory</div><divclass="clear"></div>
<aclass="sectionlink"href="#JMS_Point-to-Point_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-true">Name</div><divclass="description req-true">Descriptive name for this element that is shown in the tree.</div><divclass="required req-true"></div></div>
<divclass="component"><h2id="JUnit_Request">JUnit Request<aclass="sectionlink"href="#JUnit_Request"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/junit_sampler.png"><imgsrc="../images/screenshots/junit_sampler.png"width="397"height="536"alt="Screenshot for JUnit Request"></a></div>
<divclass="description">
The current implementation supports standard Junit convention and extensions. It also
includes extensions like oneTimeSetUp and oneTimeTearDown. The sampler works like the
JavaSampler with some differences.
<ul>
<li>rather than use Jmeter's test interface, it scans the jar files for classes extending junit's TestCase class. That includes any class or subclass.</li>
<li>Junit test jar files should be placed in jmeter/lib/junit instead of /lib directory.
In versions of JMeter after 2.3.1, you can also use the "user.classpath" property to specify where to look for TestCase classes.</li>
<li>Junit sampler does not use name/value pairs for configuration like the JavaSampler. The sampler assumes setUp and tearDown will configure the test correctly.</li>
<li>The sampler measures the elapsed time only for the test method and does not include setUp and tearDown.</li>
<li>Each time the test method is called, Jmeter will pass the result to the listeners.</li>
<li>Support for oneTimeSetUp and oneTimeTearDown is done as a method. Since Jmeter is multi-threaded, we cannot call oneTimeSetUp/oneTimeTearDown 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 "Create a new instance per sample".</li>
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:
<divclass="example"><divclass="title">Junit Constructors<aclass="sectionlink"href="#junit_constructor_example"title="Link to here">¶</a></div>
Empty Constructor:
<pre>
public class myTestCase {
public myTestCase() {}
}
</pre>
String Constructor:
<pre>
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.
<divclass="clear"></div><divclass="note">
<h3>General Guidelines</h3>
If you use setUp and tearDown, 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 setUp and tearDown methods so they are thread safe. This generally means avoid using static memebers.</li>
<li>Make the test methods discrete units of work and not long sequences of actions. By keeping the test method to a descrete 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 oneTimeSetUp and oneTimeTearDown.</li>
<aclass="sectionlink"href="#JUnit_Request_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-true">Name</div><divclass="description req-true">Descriptive name for this element that is shown in the tree.</div><divclass="required req-true"></div></div>
<divclass="property"><divclass="name req-true">Search for JUnit4 annotations</div><divclass="description req-true">Select this to search for JUnit 4 tests (@Test annotations)</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Package filter</div><divclass="description req-true">Comma separated list of packages to show. Example, org.apache.jmeter,junit.framework.</div><divclass="required req-true"></div></div>
<divclass="property"><divclass="name req-true">Class name</div><divclass="description req-true">Fully qualified name of the JUnit test class.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Constructor string</div><divclass="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><divclass="required req-true"></div></div>
<divclass="property"><divclass="name req-true">Test method</div><divclass="description req-true">The method to test.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Success code</div><divclass="description req-true">An unique code indicating the test was successful.</div><divclass="required req-true"></div></div>
<divclass="property"><divclass="name req-true">Failure code</div><divclass="description req-true">An unique code indicating the test failed.</div><divclass="required req-true"></div></div>
<divclass="property"><divclass="name req-true">Error message</div><divclass="description req-true">A description for errors.</div><divclass="required req-true"></div></div>
<divclass="property"><divclass="name req-true">Error code</div><divclass="description req-true">Some code for errors. Does not need to be unique.</div><divclass="required req-true"></div></div>
<divclass="property"><divclass="name req-true">Do not call setUp and tearDown</div><divclass="description req-true">Set the sampler not to call setUp and tearDown.
By default, setUp and tearDown should be called. Not calling those methods could affect the test and make it inaccurate.
This option should only be used with calling oneTimeSetUp and oneTimeTearDown. If the selected method is oneTimeSetUp or oneTimeTearDown,
this option should be checked.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Append assertion errors</div><divclass="description req-true">Whether or not to append assertion errors to the response message.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Append runtime exceptions</div><divclass="description req-true">Whether or not to append runtime exceptions to the response message. Only applies if "Append assertion errors" is not selected.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Create a new Instance per sample</div><divclass="description req-true">Whether or not to create a new JUnit instance for each sample. Defaults to false, meaning JUnit TestCase is created one and reused.</div><divclass="required req-true">Yes</div></div>
<divclass="component"><h2id="Mail_Reader_Sampler">Mail Reader Sampler<aclass="sectionlink"href="#Mail_Reader_Sampler"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/mailreader_sampler.png"><imgsrc="../images/screenshots/mailreader_sampler.png"width="547"height="409"alt="Screenshot for Mail Reader Sampler"></a></div>
<aclass="sectionlink"href="#Mail_Reader_Sampler_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-true">Name</div><divclass="description req-true">Descriptive name for this element that is shown in the tree.</div><divclass="required req-true"></div></div>
<divclass="property"><divclass="name req-true">Server Type</div><divclass="description req-true">The protocol used by the provider: e.g. pop3, pop3s, imap, imaps.
or another string representing the server protocol.
For example <spanclass="code">file</span> for use with the read-only mail file provider.
The actual provider names for POP3 and IMAP are <spanclass="code">pop3</span> and <spanclass="code">imap</span>
<divclass="property"><divclass="name req-true">Server</div><divclass="description req-true">Hostname or IP address of the server. See below for use with <spanclass="code">file</span> protocol.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-false">Port</div><divclass="description req-false">Port to be used to connect to the server (optional)</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Password</div><divclass="description req-true">User login password (N.B. this is stored unencrypted in the test plan)</div><divclass="required req-true"></div></div>
<divclass="property"><divclass="name req-true">Folder</div><divclass="description req-true">The IMAP(S) folder to use. See below for use with <spanclass="code">file</span> protocol.</div><divclass="required req-true">Yes, if using IMAP(S)</div></div>
<divclass="property"><divclass="name req-true">Number of messages to retrieve</div><divclass="description req-true">Set this to retrieve all or some messages</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Fetch headers only</div><divclass="description req-true">If selected, only the message headers will be retrieved.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Delete messages from the server</div><divclass="description req-true">If set, messages will be deleted after retrieval</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Store the message using MIME</div><divclass="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 (Date, To, From, Subject) in the body.
<divclass="property"><divclass="name req-true">Use no security features</div><divclass="description req-true">Indicates that the connection to the server does not use any security protocol.</div><divclass="required req-true"></div></div>
<divclass="property"><divclass="name req-true">Use SSL</div><divclass="description req-true">Indicates that the connection to the server must use the SSL protocol.</div><divclass="required req-true"></div></div>
<divclass="property"><divclass="name req-true">Use StartTLS</div><divclass="description req-true">Indicates that the connection to the server should attempt to start the TLS protocol.</div><divclass="required req-true"></div></div>
<divclass="property"><divclass="name req-true">Enforce StartTLS</div><divclass="description req-true">If the server does not start the TLS protocol the connection will be terminated.</div><divclass="required req-true"></div></div>
<divclass="property"><divclass="name req-true">Trust All Certificates</div><divclass="description req-true">When selected it will accept all certificates independent of the CA.</div><divclass="required req-true"></div></div>
<divclass="property"><divclass="name req-true">Use local truststore</div><divclass="description req-true">When selected it will only accept certificates that are locally trusted.</div><divclass="required req-true"></div></div>
<divclass="property"><divclass="name req-true">Local truststore</div><divclass="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).
<divclass="component"><h2id="Test_Action">Test Action<aclass="sectionlink"href="#Test_Action"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/test_action.png"><imgsrc="../images/screenshots/test_action.png"width="467"height="184"alt="Screenshot for Test Action"></a></div>
<divclass="description">
The Test Action sampler is a sampler that is intended for use in a conditional controller.
Rather than generate a sample, the test element eithers 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>
<aclass="sectionlink"href="#Test_Action_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-true">Name</div><divclass="description req-true">Descriptive name for this element that is shown in the tree.</div><divclass="required req-true"></div></div>
<divclass="property"><divclass="name req-true">Target</div><divclass="description req-true">Current Thread / All Threads (ignored for Pause)</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Action</div><divclass="description req-true">Pause / Stop / Stop Now / Go to next loop iteration</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Duration</div><divclass="description req-true">How long to pause for (milliseconds)</div><divclass="required req-true">Yes, if Pause is selected</div></div>
<divclass="component"><h2id="SMTP_Sampler">SMTP Sampler<aclass="sectionlink"href="#SMTP_Sampler"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/smtp_sampler.png"><imgsrc="../images/screenshots/smtp_sampler.png"width="825"height="728"alt="Screenshot for SMTP Sampler"></a></div>
<aclass="sectionlink"href="#SMTP_Sampler_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-true">Server</div><divclass="description req-true">Hostname or IP address of the server. See below for use with <spanclass="code">file</span> protocol.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-false">Port</div><divclass="description req-false">Port to be used to connect to the server.
<divclass="property"><divclass="name req-false">Connection timeout</div><divclass="description req-false">Connection timeout value in milliseconds (socket level). Default is infinite timeout.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Read timeout</div><divclass="description req-false">Read timeout value in milliseconds (socket level). Default is infinite timeout.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Address From</div><divclass="description req-true">The from address that will appear in the e-mail</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Address To</div><divclass="description req-true">The destination e-mail address (multiple values separated by ";")</div><divclass="required req-true">Yes, unless CC or BCC is specified</div></div>
<divclass="property"><divclass="name req-false">Address To CC</div><divclass="description req-false">Carbon copy destinations e-mail address (multiple values separated by ";")</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Address To BCC</div><divclass="description req-false">Blind carbon copy destinations e-mail address (multiple values separated by ";")</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Use Auth</div><divclass="description req-true">Indicates if the SMTP server requires user authentication</div><divclass="required req-true"></div></div>
<divclass="property"><divclass="name req-true">Password</div><divclass="description req-true">User login password (N.B. this is stored unencrypted in the test plan)</div><divclass="required req-true"></div></div>
<divclass="property"><divclass="name req-true">Use no security features</div><divclass="description req-true">Indicates that the connection to the SMTP server does not use any security protocol.</div><divclass="required req-true"></div></div>
<divclass="property"><divclass="name req-true">Use SSL</div><divclass="description req-true">Indicates that the connection to the SMTP server must use the SSL protocol.</div><divclass="required req-true"></div></div>
<divclass="property"><divclass="name req-true">Use StartTLS</div><divclass="description req-true">Indicates that the connection to the SMTP server should attempt to start the TLS protocol.</div><divclass="required req-true"></div></div>
<divclass="property"><divclass="name req-true">Enforce StartTLS</div><divclass="description req-true">If the server does not start the TLS protocol the connection will be terminated.</div><divclass="required req-true"></div></div>
<divclass="property"><divclass="name req-true">Trust All Certificates</div><divclass="description req-true">When selected it will accept all certificates independent of the CA.</div><divclass="required req-true"></div></div>
<divclass="property"><divclass="name req-true">Use local truststore</div><divclass="description req-true">When selected it will only accept certificates that are locally trusted.</div><divclass="required req-true"></div></div>
<divclass="property"><divclass="name req-true">Local truststore</div><divclass="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).
<divclass="property"><divclass="name req-true">Suppress Subject Header</div><divclass="description req-true">If selected, the "Subject:" header is omitted from the mail that is sent.
This is different from sending an empty "Subject:" header, though some e-mail clients may display it identically.</div><divclass="required req-true"></div></div>
<divclass="property"><divclass="name req-true">Include timestamp in subject</div><divclass="description req-true">Includes the System.currentTimemilis() in the subject line.</div><divclass="required req-true"></div></div>
<divclass="property"><divclass="name req-false">Add Header</div><divclass="description req-false">Additional headers can be defined using this button.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Send plain body (i.e. not multipart/mixed)</div><divclass="description req-true">
If selected, then send the body as a plain message, i.e. not multipart/mixed, if possible.
If the message body is empty and there is a single file, then send the file contents as the message body.
Note: If the message body is not empty, and there is at least one attached file, then the body is sent as multipart/mixed.
</div><divclass="required req-true">
No
</div></div>
<divclass="property"><divclass="name req-true">Attach files</div><divclass="description req-true">Files to be attached to the message.</div><divclass="required req-true"></div></div>
<divclass="property"><divclass="name req-true">Send .eml</div><divclass="description req-true">If set, the .eml file will be sent instead of the entries in the Subject, Message, and Attached files</div><divclass="required req-true"></div></div>
<divclass="property"><divclass="name req-true">Calculate message size</div><divclass="description req-true">Calculates the message size and stores it in the sample result.</div><divclass="required req-true"></div></div>
<divclass="property"><divclass="name req-true">Enable debug logging?</div><divclass="description req-true">If set, then the "mail.debug" property is set to "true"</div><divclass="required req-true"></div></div>
<divclass="component"><h2id="OS_Process_Sampler">OS Process Sampler<aclass="sectionlink"href="#OS_Process_Sampler"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/os_process_sampler.png"><imgsrc="../images/screenshots/os_process_sampler.png"width="683"height="582"alt="Screenshot for OS Process Sampler"></a></div>
<aclass="sectionlink"href="#OS_Process_Sampler_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-true">Command</div><divclass="description req-true">The program name to execute.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-false">Working directory</div><divclass="description req-false">Directory from which command will be executed, defaults to folder referenced by "user.dir" System property</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Command Parameters</div><divclass="description req-false">Parameters passed to the program name.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Environment Parameters</div><divclass="description req-false">Key/Value pairs added to environment when running command.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Standard input (stdin)</div><divclass="description req-false">Name of file from which input is to be taken (STDIN).</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Standard output (stdout</div><divclass="description req-false">Name of output file for standard output (STDOUT).
If omitted, output is captured and returned as the response data.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Standard error (stderr)</div><divclass="description req-false">Name of output file for standard error (STDERR).
If omitted, output is captured and returned as the response data.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Check Return Code</div><divclass="description req-false">If checked, sampler will compare return code with Expected Return Code.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Expected Return Code</div><divclass="description req-false">Expected return code for System Call, required if "Check Return Code" is checked.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Timeout</div><divclass="description req-false">Timeout for command in milliseconds, defaults to 0, which means NO timeout.
If the timeout expires before the command finishes, JMeter will attempt to kill the OS process.
<divclass="component"><h2id="MongoDB_Script">MongoDB Script<aclass="sectionlink"href="#MongoDB_Script"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/mongodb-script.png"><imgsrc="../images/screenshots/mongodb-script.png"width="847"height="635"alt="Screenshot for MongoDB Script"></a></div>
<divclass="description"><p>This sampler lets you send an Request to a MongoDB.</p>
<p>Before using this you need to set up a
<ahref="../usermanual/component_reference.html#MongoDB_Source_Config">MongoDB Source Config</a> Configuration element
</p>
<divclass="clear"></div><divclass="note">This Element currently uses com.mongodb.DB#eval which takes a global write lock causing a performance impact on the database, see <ahref="http://docs.mongodb.org/manual/reference/method/db.eval/">db.eval()</a>.
So it is better to avoid using this element for load testing and use JSR223+Groovy scripting using <ahref="../api/org/apache/jmeter/protocol/mongodb/config/MongoDBHolder.html">MongoDBHolder</a> instead.
MongoDB Script is more suitable for functionnal testing or test setup (setup/teardown threads)</div><divclass="clear"></div>
<aclass="sectionlink"href="#MongoDB_Script_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-false">Name</div><divclass="description req-false">Descriptive name for this sampler that is shown in the tree.</div><divclass="required req-false">No</div></div>
</div><divclass="section"><h1id="logic_controllers">18.2 Logic Controllers<aclass="sectionlink"href="#logic_controllers"title="Link to here">¶</a></h1>
<divclass="description">
<br>Logic Controllers determine the order in which Samplers are processed.
<divclass="component"><h2id="Simple_Controller">Simple Controller<aclass="sectionlink"href="#Simple_Controller"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/logic-controller/simple-controller.png"><imgsrc="../images/screenshots/logic-controller/simple-controller.png"width="330"height="77"alt="Screenshot for Simple Controller"></a></div>
<divclass="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
<aclass="sectionlink"href="#Simple_Controller_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-false">Name</div><divclass="description req-false">Descriptive name for this controller that is shown in the tree.</div><divclass="required req-false">No</div></div>
<divclass="example"><divclass="title">Using the Simple Controller<aclass="sectionlink"href="#simple_controller_example"title="Link to here">¶</a></div>
<p><ahref="../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.
Note, the File Reporter
is configured to store the results in a file named "simple-test.dat" in the current directory.</p>
<divclass="component"><h2id="Loop_Controller">Loop Controller<aclass="sectionlink"href="#Loop_Controller"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/logic-controller/loop-controller.png"><imgsrc="../images/screenshots/logic-controller/loop-controller.png"width="326"height="114"alt="Screenshot for Loop Controller"></a></div>
<divclass="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 2 * 3 = 6 HTTP Requests.
<aclass="sectionlink"href="#Loop_Controller_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-false">Name</div><divclass="description req-false">Descriptive name for this controller that is shown in the tree.</div><divclass="required req-false">No</div></div>
The number of times the subelements of this controller will be iterated each time
through a test run.
<p><b>Special Case:</b> The Loop Controller embedded in the <ahref="test_plan.html#thread_group">Thread Group</a>
element behaves slightly differently. Unless set to forever, it stops the test after
the given number of iterations have been done.</p>
<divclass="clear"></div><divclass="note">When using a function in this field, be aware it may be evaluated multiple times.
Example using __Random will evaluate it to a different value for each child samplers of Loop Controller and result into unwanted behaviour.</div><divclass="clear"></div></div><divclass="required req-true">Yes, unless "Forever" is checked</div></div>
<divclass="component"><h2id="Once_Only_Controller">Once Only Controller<aclass="sectionlink"href="#Once_Only_Controller"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/logic-controller/once-only-controller.png"><imgsrc="../images/screenshots/logic-controller/once-only-controller.png"width="330"height="78"alt="Screenshot for Once Only Controller"></a></div>
<divclass="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
(ie, every 5 times).
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>
<aclass="sectionlink"href="#Once_Only_Controller_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-false">Name</div><divclass="description req-false">Descriptive name for this controller that is shown in the tree.</div><divclass="required req-false">No</div></div>
<divclass="example"><divclass="title">Once Only Example<aclass="sectionlink"href="#once_only_example"title="Link to here">¶</a></div>
<p><ahref="../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><ahref="../images/screenshots/logic-controller/once-only-example.png"><imgsrc="../images/screenshots/logic-controller/once-only-example.png"width="348"height="131"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. Note, the File Reporter is configured to store the results in a file named "loop-test.dat" in the current directory.</p>
<divclass="component"><h2id="Interleave_Controller">Interleave Controller<aclass="sectionlink"href="#Interleave_Controller"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/logic-controller/interleave-controller.png"><imgsrc="../images/screenshots/logic-controller/interleave-controller.png"width="329"height="104"alt="Screenshot for Interleave Controller"></a></div>
<divclass="description"><p>If you add Generative or Logic Controllers to an Interleave Controller, JMeter will alternate among each of the
<aclass="sectionlink"href="#Interleave_Controller_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-false">name</div><divclass="description req-false">Descriptive name for this controller that is shown in the tree.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">ignore sub-controller blocks</div><divclass="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><divclass="required req-false">No</div></div>
<divclass="example"><divclass="title">Simple Interleave Example<aclass="sectionlink"href="#simple_interleave_example"title="Link to here">¶</a></div>
<trvalign="top"><th>Loop Iteration</th><th>Each JMeter Thread Sends These HTTP Requests</th></tr>
<trvalign="top"><td>1</td><td>News Page</td></tr>
<trvalign="top"><td>1</td><td>Log Page</td></tr>
<trvalign="top"><td>2</td><td>FAQ Page</td></tr>
<trvalign="top"><td>2</td><td>Log Page</td></tr>
<trvalign="top"><td>3</td><td>Gump Page</td></tr>
<trvalign="top"><td>3</td><td>Log Page</td></tr>
<trvalign="top"><td>4</td><td>Because there are no more requests in the controller,<br> JMeter starts over and sends the first HTTP Request, which is the News Page.</td></tr>
<divclass="example"><divclass="title">Useful Interleave Example<aclass="sectionlink"href="#useful_interleave_example"title="Link to here">¶</a></div>
<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. However, if "ignore sub-controller blocks" 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>
<divclass="component"><h2id="Random_Controller">Random Controller<aclass="sectionlink"href="#Random_Controller"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/logic-controller/random-controller.png"><imgsrc="../images/screenshots/logic-controller/random-controller.png"width="328"height="100"alt="Screenshot for Random Controller"></a></div>
<divclass="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>
<divclass="clear"></div><divclass="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><divclass="clear"></div>
<aclass="sectionlink"href="#Random_Controller_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-false">Name</div><divclass="description req-false">Descriptive name for this controller that is shown in the tree.</div><divclass="required req-false">No</div></div>
<divclass="component"><h2id="Random_Order_Controller">Random Order Controller<aclass="sectionlink"href="#Random_Order_Controller"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/randomordercontroller.png"><imgsrc="../images/screenshots/randomordercontroller.png"width="328"height="76"alt="Screenshot for Random Order Controller"></a></div>
<divclass="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>
<aclass="sectionlink"href="#Random_Order_Controller_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-false">Name</div><divclass="description req-false">Descriptive name for this controller that is shown in the tree.</div><divclass="required req-false">No</div></div>
<divclass="component"><h2id="Throughput_Controller">Throughput Controller<aclass="sectionlink"href="#Throughput_Controller"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/throughput_controller.png"><imgsrc="../images/screenshots/throughput_controller.png"width="329"height="167"alt="Screenshot for Throughput Controller"></a></div>
<divclass="description">
<p>
<b>This controller is badly named, as it does not control throughput.</b>
Please refer to the <ahref="../usermanual/component_reference.html#Constant_Throughput_Timer">Constant Throughput Timer</a> for an element that can be used to adjust the throughput.
</p>
<p>The Throughput Controller allows the user to control how often it is executed. There are two modes - percent execution and total executions. Percent executions causes the controller to execute a certain percentage of the iterations through the test plan. Total
executions causes the controller to stop executing after a certain number of executions have occurred. Like the Once Only Controller, this
setting is reset when a parent Loop Controller restarts.
</p>
</div>
<divclass="clear"></div><divclass="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><divclass="clear"></div>
<aclass="sectionlink"href="#Throughput_Controller_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-false">Name</div><divclass="description req-false">Descriptive name for this controller that is shown in the tree.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Execution Style</div><divclass="description req-true">Whether the controller will run in percent executions or total executions mode.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Throughput</div><divclass="description req-true">A number. for percent execution mode, a number from 0-100 that indicates the percentage of times the controller will execute. "50" means the controller will execute during half the iterations throught the test plan. for total execution mode, the number indicates the total number of times the controller will execute.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-false">Per User</div><divclass="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 "per user", then the number given for throughput will be the total number of executions made. if "per user" is checked, then the total number of executions would be the number of users times the number given for throughput.</div><divclass="required req-false">No</div></div>
<divclass="component"><h2id="Runtime_Controller">Runtime Controller<aclass="sectionlink"href="#Runtime_Controller"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/runtimecontroller.png"><imgsrc="../images/screenshots/runtimecontroller.png"width="328"height="100"alt="Screenshot for Runtime Controller"></a></div>
<divclass="description">
<p>The Runtime Controller controls how long its children are allowed to run.
<aclass="sectionlink"href="#Runtime_Controller_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-true">Name</div><divclass="description req-true">Descriptive name for this controller that is shown in the tree, and used to name the transaction.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Runtime (seconds)</div><divclass="description req-true">Desired runtime in seconds</div><divclass="required req-true">Yes</div></div>
<divclass="component"><h2id="If_Controller">If Controller<aclass="sectionlink"href="#If_Controller"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/ifcontroller.png"><imgsrc="../images/screenshots/ifcontroller.png"width="497"height="131"alt="Screenshot for If Controller"></a></div>
<divclass="description">
<p>The If Controller allows the user to control whether the test elements below it (its children) are run or not.</p>
<p>
Prior to JMeter 2.3RC3, the condition was evaluated for every runnable element contained in the controller.
This sometimes caused unexpected behaviour, so 2.3RC3 was changed to evaluate the condition only once on initial entry.
However, the original behaviour is also useful, so versions of JMeter after 2.3RC4 have an additional
option to select the original behaviour.
</p>
<p>
Versions of JMeter after 2.3.2 allow the script to be processed as a variable expression, rather than requiring Javascript.
It was always possible to use functions and variables in the Javascript condition, so long as they evaluated to "true" or "false";
now this can be done without the overhead of using Javascript as well. For example, previously one could use the condition:
<spanclass="code">${__jexl(${VAR} == 23)}</span> and this would be evaluated as true/false, the result would then be passed to Javascript
which would then return true/false. If the Variable Expression option is selected, then the expression is evaluated
and compared with "true", without needing to use Javascript.
Also, variable expressions can return any value, whereas the
Javascript condition must return "true"/"false" or an error is logged.
</p>
<divclass="clear"></div><divclass="note">
No variables are made available to the script when the condition is interpreted as Javascript.
If you need access to such variables, then select "Interpret Condition as Variable Expression?" and use
a __javaScript() function call. You can then use the objects "vars", "log", "ctx" etc. in the script.
</div><divclass="clear"></div>
<divclass="clear"></div><divclass="note">
To test if a variable is undefined (or null) do the following, suppose var is named myVar, expression will be:
<aclass="sectionlink"href="#If_Controller_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-false">Name</div><divclass="description req-false">Descriptive name for this controller that is shown in the tree.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Condition (default Javascript)</div><divclass="description req-true">By default the condition is interpreted as <b>Javascript</b> code that returns "true" or "false",
but this can be overriden (see below)</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Interpret Condition as Variable Expression?</div><divclass="description req-true">If this is selected, then the condition must be an expression that evaluates to "true" (case is ignored).
For example, <spanclass="code">${FOUND}</span> or <spanclass="code">${__jexl(${VAR} > 100)}</span>.
Unlike the Javascript case, the condition is only checked to see if it matches "true" (case is ignored).
<divclass="component"><h2id="While_Controller">While Controller<aclass="sectionlink"href="#While_Controller"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/whilecontroller.png"><imgsrc="../images/screenshots/whilecontroller.png"width="362"height="102"alt="Screenshot for While Controller"></a></div>
<divclass="description">
<p>
The While Controller runs its children until the condition is "false".
<aclass="sectionlink"href="#While_Controller_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-true">Name</div><divclass="description req-true">Descriptive name for this controller that is shown in the tree, and used to name the transaction.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Condition</div><divclass="description req-true">blank, LAST, or variable/function</div><divclass="required req-true">Yes</div></div>
<divclass="component"><h2id="Switch_Controller">Switch Controller<aclass="sectionlink"href="#Switch_Controller"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/switchcontroller.png"><imgsrc="../images/screenshots/switchcontroller.png"width="361"height="106"alt="Screenshot for Switch Controller"></a></div>
<aclass="sectionlink"href="#Switch_Controller_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-true">Name</div><divclass="description req-true">Descriptive name for this controller that is shown in the tree, and used to name the transaction.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Switch Value</div><divclass="description req-true">The number (or name) of the subordinate element to be invoked. Elements are numbered from 0.</div><divclass="required req-true">Yes</div></div>
<divclass="component"><h2id="ForEach_Controller">ForEach Controller<aclass="sectionlink"href="#ForEach_Controller"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/logic-controller/foreach-controller.png"><imgsrc="../images/screenshots/logic-controller/foreach-controller.png"width="342"height="193"alt="Screenshot for ForEach Controller"></a></div>
<divclass="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 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 inputVar, the following variables should have been defined:
<ul>
<li>inputVar_1 = wendy</li>
<li>inputVar_2 = charles</li>
<li>inputVar_3 = peter</li>
<li>inputVar_4 = john</li>
</ul>
<p>Note: the "_" separator is now optional.</p>
When the return variable is given as "returnVar", the collection of samplers and controllers under the ForEach controller will be executed 4 consecutive times,
with the return variable having the respective above values, which can then be used in the samplers.
</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 "_" separator, the ForEach Controller can be used to loop through the groups by using
the input variable refName_g, and can also loop through all the groups in all the matches
by using an input variable of the form refName_${C}_g, where C is a counter variable.
</p>
<divclass="clear"></div><divclass="note">The ForEach Controller does not run any samples if inputVar_1 is null.
This would be the case if the Regular Expression returned no matches.</div><divclass="clear"></div>
<aclass="sectionlink"href="#ForEach_Controller_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-false">Name</div><divclass="description req-false">Descriptive name for this controller that is shown in the tree.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Input variable prefix</div><divclass="description req-true">Prefix for the variable names to be used as input.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-false">Start index for loop</div><divclass="description req-false">Start index (exclusive) for loop over variables (first element is at start index + 1)</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">End index for loop</div><divclass="description req-false">End index (inclusive) for loop over variables</div><divclass="required req-false">No</div></div>
The name of the variable which can be used in the loop for replacement in the samplers</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Use Separator</div><divclass="description req-true">If not checked, the "_" separator is omitted.</div><divclass="required req-true">Yes</div></div>
<divclass="component"><h2id="Module_Controller">Module Controller<aclass="sectionlink"href="#Module_Controller"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/module_controller.png"><imgsrc="../images/screenshots/module_controller.png"width="504"height="217"alt="Screenshot for Module Controller"></a></div>
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, or on the <ahref="../usermanual/component_reference.html#WorkBench">WorkBench</a>.
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:
<pre>
Test Plan / Protocol: JDBC / Control / Interleave Controller (Module1)
</pre>
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>
<divclass="clear"></div><divclass="note">The Module Controller should not be used with remote testing or non-gui testing in conjunction with Workbench components since the Workbench test elements are not part of test plan .jmx files. Any such test will fail.</div><divclass="clear"></div>
<aclass="sectionlink"href="#Module_Controller_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-false">Name</div><divclass="description req-false">Descriptive name for this controller that is shown in the tree.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Module to Run</div><divclass="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><divclass="required req-true">Yes</div></div>
<divclass="component"><h2id="Include_Controller">Include Controller<aclass="sectionlink"href="#Include_Controller"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/includecontroller.png"><imgsrc="../images/screenshots/includecontroller.png"width="417"height="130"alt="Screenshot for Include Controller"></a></div>
<divclass="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 Thread Group can also be added in the external JMX file for debugging purposes.
A Module Controller can be used to reference the Test Fragment. The Thread Group 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.
This element does not support variables/functions in the filename field.<br>
However, if the property <b>includecontroller.prefix</b> is defined,
the contents are used to prefix the pathname.
</div><divclass="clear"></div>
<divclass="clear"></div><divclass="note">
When using IncludeController and including the same JMX file, ensure you name the IncludeController differently to avoid facing known issue <ahref="http://bz.apache.org/bugzilla/show_bug.cgi?id=50898">
<divclass="component"><h2id="Transaction_Controller">Transaction Controller<aclass="sectionlink"href="#Transaction_Controller"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/transactioncontroller.png"><imgsrc="../images/screenshots/transactioncontroller.png"width="622"height="140"alt="Screenshot for Transaction Controller"></a></div>
<divclass="description">
<p>
The Transaction Controller generates an additional
sample which measures the overall time taken to perform the nested test elements.
</p>
<divclass="clear"></div><divclass="note">
Note: when the check box "Include duration of timer and pre-post processors in generated sample" is checked,
the time includes all processing within the controller scope, not just the samples.
</div><divclass="clear"></div>
<p>
For JMeter versions after 2.3, there are two modes of operation
<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>
<p>
The generated sample time includes all the times for the nested samplers, <b>and any timers etc.</b>
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>
<divclass="clear"></div><divclass="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.
<aclass="sectionlink"href="#Transaction_Controller_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-true">Name</div><divclass="description req-true">Descriptive name for this controller that is shown in the tree, and used to name the transaction.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Include duration of timer and pre-post processors in generated sample</div><divclass="description req-true">
Whether to include timer, pre- and post-processing delays in the generated sample.
Default is false (since JMeter 2.11, in previous versions the default value is true).
<divclass="component"><h2id="Recording_Controller">Recording Controller<aclass="sectionlink"href="#Recording_Controller"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/logic-controller/recording-controller.png"><imgsrc="../images/screenshots/logic-controller/recording-controller.png"width="420"height="79"alt="Screenshot for Recording Controller"></a></div>
<divclass="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 <ahref="../usermanual/component_reference.html#HTTP(S)_Test_Script_Recorder">HTTP(S) Test Script Recorder</a>, all recorded samples will by default
<aclass="sectionlink"href="#Recording_Controller_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-false">Name</div><divclass="description req-false">Descriptive name for this controller that is shown in the tree.</div><divclass="required req-false">No</div></div>
<divclass="component"><h2id="Critical_Section_Controller">Critical Section Controller<aclass="sectionlink"href="#Critical_Section_Controller"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/logic-controller/critical-section-controller.png"><imgsrc="../images/screenshots/logic-controller/critical-section-controller.png"width="469"height="129"alt="Screenshot for Critical Section Controller"></a></div>
<divclass="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>
The figure below shows an example of using Critical Section Controller, in the figure below 2 Critical Section Controllers ensure
that:
<ul>
<li>DS2-${__threadNum} is executed only by one thread at a time</li>
<li>DS4-${__threadNum} is executed only by one thread at a time</li>
</ul>
<figure><ahref="../images/screenshots/logic-controller/critical-section-controller-tp.png"><imgsrc="../images/screenshots/logic-controller/critical-section-controller-tp.png"width="248"height="241"alt="Test Plan using Critical Section Controller"></a><figcaption>Test Plan using Critical Section Controller</figcaption></figure>
<aclass="sectionlink"href="#Critical_Section_Controller_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-true">Lock Name</div><divclass="description req-true">Lock that will be taken by controller, ensure you use different lock names for unrelated sections</div><divclass="required req-true">Yes</div></div>
</div>
<divclass="clear"></div><divclass="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.
<divclass="property"><divclass="name req-false">Errors</div><divclass="description req-false">Select this to write/read only results with errors</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Successes</div><divclass="description req-false">Select this to write/read only results without errors.
If neither Errors nor Successes is selected, then all results are processed.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Configure</div><divclass="description req-false">Configure Button, see below</div><divclass="required req-false">No</div></div>
<divclass="component"><h2id="Sample_Result_Save_Configuration">Sample Result Save Configuration<aclass="sectionlink"href="#Sample_Result_Save_Configuration"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/sample_result_config.png"><imgsrc="../images/screenshots/sample_result_config.png"width="629"height="300"alt="Screenshot for Sample Result Save Configuration"></a></div>
<divclass="component"><h2id="Graph_Results">Graph Results<aclass="sectionlink"href="#Graph_Results"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/graph_results.png"><imgsrc="../images/screenshots/graph_results.png"width="915"height="686"alt="Screenshot for Graph Results"></a></div>
<divclass="description">
<divclass="clear"></div><divclass="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><divclass="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>
<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>Data - plot the actual data values</li>
<li>Average - plot the Average</li>
<li>Median - plot the <ahref="glossary.html#Median">Median</a> (midway value)</li>
<li>Deviation - plot the <ahref="glossary.html#StandardDeviation">Standard Deviation</a> (a measure of the variation)</li>
<li>Throughput - 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.
"Latest Sample" is the current elapsed sample time, shown on the graph as "Data".</p>
<p>The value displayed on the top left of graph is the max of 90th percentile of response time.</p>
<divclass="go-top"><ahref="#">^</a></div></div>
<divclass="component"><h2id="Spline_Visualizer">Spline Visualizer<aclass="sectionlink"href="#Spline_Visualizer"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/spline_visualizer.png"><imgsrc="../images/screenshots/spline_visualizer.png"width="737"height="489"alt="Screenshot for Spline Visualizer"></a></div>
<divclass="clear"></div><divclass="note">
Spline Visualizer 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><divclass="clear"></div>
<divclass="description">
<p>
The Spline Visualizer provides a view of all sample times from the start
of the test till the end, regardless of how many samples have been taken. The spline
has 10 points, each representing 10% of the samples, and connected using spline
logic to show a single continuous line.
</p>
<p>
The graph is automatically scaled to fit within the window.
This needs to be borne in mind when comparing graphs.
<divclass="component"><h2id="Assertion_Results">Assertion Results<aclass="sectionlink"href="#Assertion_Results"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/assertion_results.png"><imgsrc="../images/screenshots/assertion_results.png"width="954"height="365"alt="Screenshot for Assertion Results"></a></div>
<divclass="description">
<divclass="clear"></div><divclass="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><divclass="clear"></div>
<p>The Assertion Results visualizer shows the Label of each sample taken.
It also reports failures of any <ahref="test_plan.html#assertions">Assertions</a> that
<divclass="component"><h2id="View_Results_Tree">View Results Tree<aclass="sectionlink"href="#View_Results_Tree"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/view_results_tree.png"><imgsrc="../images/screenshots/view_results_tree.png"width="901"height="646"alt="Screenshot for View Results Tree"></a></div>
<divclass="description">
<divclass="clear"></div><divclass="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><divclass="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 Host) 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>
<td>The <i>CSS/JQuery Tester</i> only works for text responses. It shows the plain text in the upper panel.
The "Test" 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 engine of CSS/JQuery expression can be JSoup or Jodd, syntax of these 2 implementation differs slightly.<br>
For example, the Selector <b>a[class=sectionlink]</b> with attribute <b>href</b> applied to the current JMeter functions page gives the following output:
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 an Regexp tester display.<br>
Figure 9b (below) shows an example of an Document display.<br>
<divalign="center">
<figure><ahref="../images/screenshots/view_results_tree_xml.png"><imgsrc="../images/screenshots/view_results_tree_xml.png"width="873"height="653"alt="Figure 9 Sample XML display"></a><figcaption>Figure 9 Sample XML display</figcaption></figure>
<figure><ahref="../images/screenshots/view_results_tree_regex.png"><imgsrc="../images/screenshots/view_results_tree_regex.png"width="858"height="643"alt="Figure 9a Sample Regexp Test display"></a><figcaption>Figure 9a Sample Regexp Test display</figcaption></figure>
<divclass="component"><h2id="Aggregate_Report">Aggregate Report<aclass="sectionlink"href="#Aggregate_Report"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/aggregate_report.png"><imgsrc="../images/screenshots/aggregate_report.png"width="1140"height="266"alt="Screenshot for Aggregate Report"></a></div>
<divclass="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.
Calculation of the <ahref="glossary.html#Median">Median</a> and 90% Line (90<sup>th</sup><ahref="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 <ahref="../usermanual/component_reference.html#Summary_Report">Summary Report</a> for a similar Listener that does not store individual samples and so needs constant memory.
The figure below shows an example of selecting the "Include group name" checkbox.
<figure><ahref="../images/screenshots/aggregate_report_grouped.png"><imgsrc="../images/screenshots/aggregate_report_grouped.png"width="1140"height="276"alt="Sample "Include group name" display"></a><figcaption>Sample "Include group name" display</figcaption></figure>
<divclass="component"><h2id="View_Results_in_Table">View Results in Table<aclass="sectionlink"href="#View_Results_in_Table"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/table_results.png"><imgsrc="../images/screenshots/table_results.png"width="966"height="683"alt="Screenshot for View Results in Table"></a></div>
<divclass="description">This visualizer creates a row for every sample result.
Like the <ahref="../usermanual/component_reference.html#View_Results_Tree">View Results Tree</a>, this visualizer uses a lot of memory.
<divclass="component"><h2id="Simple_Data_Writer">Simple Data Writer<aclass="sectionlink"href="#Simple_Data_Writer"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/simpledatawriter.png"><imgsrc="../images/screenshots/simpledatawriter.png"width="741"height="141"alt="Screenshot for Simple Data Writer"></a></div>
<divclass="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 non-GUI mode, the -l flag can be used to create a data file.
The fields to save are defined by JMeter properties.
<divclass="component"><h2id="Monitor_Results">Monitor Results<aclass="sectionlink"href="#Monitor_Results"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/monitor_screencap.png"><imgsrc="../images/screenshots/monitor_screencap.png"width="762"height="757"alt="Screenshot for Monitor Results"></a></div>
<divclass="description">
<p>Monitor Results is a new Visualizer for displaying server
status. It is designed for Tomcat 5, but any servlet container
can port the status servlet and use this monitor. There are two primary
tabs for the monitor. The first is the "Health" tab, which will show the
status of one or more servers. The second tab labled "Performance" shows
the performance for one server for the last 1000 samples. The equations
used for the load calculation is included in the Visualizer.</p>
<p>Currently, the primary limitation of the monitor is system memory. A
quick benchmark of memory usage indicates a buffer of 1000 data points for
100 servers would take roughly 10Mb of RAM. On a 1.4Ghz centrino
laptop with 1Gb of ram, the monitor should be able to handle several
hundred servers.</p>
<p>As a general rule, monitoring production systems should take care to
set an appropriate interval. Intervals shorter than 5 seconds are too
aggressive and have a potential of impacting the server. With a buffer of
1000 data points at 5 second intervals, the monitor would check the server
status 12 times a minute or 720 times a hour. This means the buffer shows
the performance history of each machine for the last hour.</p>
<divclass="clear"></div><divclass="note">
The monitor requires Tomcat 5 or above.
Use a browser to check that you can access the Tomcat status servlet OK.
<divclass="component"><h2id="Distribution_Graph_(alpha)">Distribution Graph (alpha)<aclass="sectionlink"href="#Distribution_Graph_(alpha)"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/distribution_graph.png"><imgsrc="../images/screenshots/distribution_graph.png"width="819"height="626"alt="Screenshot for Distribution Graph (alpha)"></a></div>
<divclass="description">
<divclass="clear"></div><divclass="note">
Distribution Graph 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
<divclass="component"><h2id="Aggregate_Graph">Aggregate Graph<aclass="sectionlink"href="#Aggregate_Graph"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/aggregate_graph.png"><imgsrc="../images/screenshots/aggregate_graph.png"width="1132"height="872"alt="Screenshot for Aggregate Graph"></a></div>
<divclass="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
<li><u>Columns to display:</u> Choose the column(s) to display in graph.</li>
<li><u>Rectangles color:</u> Clic on right color rectangle open a popup dialog to choose a custom color for column.</li>
<li><u>Foreground color</u> Allow to change the value text color.</li>
<li><u>Value font:</u> Allow to define font settings for the text.</li>
<li><u>Draw outlines bar?</u> To draw or not the border line on bar chart</li>
<li><u>Show number grouping?</u> Show or not the number grouping in Y Axis labels.</li>
<li><u>Value labels vertical?</u> Change orientation for value label. (Default is horizontal)</li>
<li><u>Column label selection:</u> Filter by result label. A regular expression can be used, example: <i>.*Transaction.*</i>
<br>Before display the graph, click on <b>Apply filter</b> button to refresh internal data.</li></ul></div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-false">Title</div><divclass="description req-false">Define the graph's title on the head of chart. Empty value is the default value : "Aggregate Graph".
The button <b>Synchronize with name</b> define the title with the label of the listener. And define font settings for graph title</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Graph size</div><divclass="description req-false">Compute the graph size by the width and height depending of the current JMeter's window size.
Use Width and Height fields to define a custom size. The unit is pixel. </div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">X Axis settings</div><divclass="description req-false">Define the max length of X Axis label (in pixel).</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Y Axis settings</div><divclass="description req-false">Define a custom maximum value for Y Axis.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Legend</div><divclass="description req-true">Define the placement and font settings for chart legend</div><divclass="required req-true">Yes</div></div>
<divclass="component"><h2id="Response_Time_Graph">Response Time Graph<aclass="sectionlink"href="#Response_Time_Graph"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/response_time_graph.png"><imgsrc="../images/screenshots/response_time_graph.png"width="921"height="616"alt="Screenshot for Response Time Graph"></a></div>
<divclass="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>
<divalign="center">
<p>
The figure below shows an example of settings to draw this graph.
<figure><ahref="../images/screenshots/response_time_graph_settings.png"><imgsrc="../images/screenshots/response_time_graph_settings.png"width="919"height="481"alt="Response time graph settings"></a><figcaption>Response time graph settings</figcaption></figure>
</p>
</div>
<p><i>Please note: All this parameters are saved in JMeter .jmx file.</i></p>
<aclass="sectionlink"href="#Response_Time_Graph_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-true">Interval (ms)</div><divclass="description req-true">The time in milli-seconds for X axis interval. Samples are grouped according to this value.
Before display the graph, click on <b>Apply interval</b> button to refresh internal data.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-false">Sampler label selection</div><divclass="description req-false">Filter by result label. A regular expression can be used, ex.<i>.*Transaction.*</i>.
Before display the graph, click on <b>Apply filter</b> button to refresh internal data.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Title</div><divclass="description req-false">Define the graph's title on the head of chart. Empty value is the default value : "Response Time Graph".
The button <b>Synchronize with name</b> define the title with the label of the listener. And define font settings for graph title</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Line settings</div><divclass="description req-true">Define the width of the line. Define the type of each value point. Choose <i>none</i> to have a line without mark</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-false">Graph size</div><divclass="description req-false">Compute the graph size by the width and height depending of the current JMeter's window size.
Use Width and Height fields to define a custom size. The unit is pixel. </div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">X Axis settings</div><divclass="description req-false">Customize the date format of X axis label.
The syntax is the Java <ahref="http://docs.oracle.com/javase/6/docs/api/java/text/SimpleDateFormat.html">SimpleDateFormat API</a>.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Y Axis settings</div><divclass="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><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Legend</div><divclass="description req-true">Define the placement and font settings for chart legend</div><divclass="required req-true">Yes</div></div>
</div>
<divclass="go-top"><ahref="#">^</a></div></div>
<divclass="component"><h2id="Mailer_Visualizer">Mailer Visualizer<aclass="sectionlink"href="#Mailer_Visualizer"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/mailervisualizer.png"><imgsrc="../images/screenshots/mailervisualizer.png"width="860"height="403"alt="Screenshot for Mailer Visualizer"></a></div>
<divclass="description"><p>The mailer visualizer can be set up to send email if a test run receives too many
<aclass="sectionlink"href="#Mailer_Visualizer_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-false">Name</div><divclass="description req-false">Descriptive name for this element that is shown in the tree.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">From</div><divclass="description req-true">Email address to send messages from.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Addressee(s)</div><divclass="description req-true">Email address to send messages to, comma-separated.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-false">Success Subject</div><divclass="description req-false">Email subject line for success messages.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Success Limit</div><divclass="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><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-false">Failure Subject</div><divclass="description req-false">Email subject line for fail messages.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Failure Limit</div><divclass="description req-true">Once this number of failed responses is exceeded, a failure
email is sent - i.e. set the count to 0 to send an e-mail on the first failure.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-false">Host</div><divclass="description req-false">IP address or host name of SMTP server (email redirector)
<divclass="property"><divclass="name req-false">Port</div><divclass="description req-false">Port of SMTP server (defaults to 25).</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Login</div><divclass="description req-false">Login used to authenticate.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Password</div><divclass="description req-false">Password used to authenticate.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Connection security</div><divclass="description req-false">Type of encryption for SMTP authentication (SSL, TLS or none).</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Test Mail</div><divclass="description req-false">Press this button to send a test mail</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Failures</div><divclass="description req-false">A field that keeps a running total of number
of failures so far received.</div><divclass="required req-false">No</div></div>
<divclass="component"><h2id="BeanShell_Listener">BeanShell Listener<aclass="sectionlink"href="#BeanShell_Listener"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/beanshell_listener.png"><imgsrc="../images/screenshots/beanshell_listener.png"width="844"height="633"alt="Screenshot for BeanShell Listener"></a></div>
<divclass="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 <ahref="http://www.beanshell.org/">BeanShell website.</a></b>
<divclass="property"><divclass="name req-false">Script file</div><divclass="description req-false">A file containing the BeanShell script to run.
The file name is stored in the script variable FileName</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Script</div><divclass="description req-true">The BeanShell script to run. The return value is ignored.</div><divclass="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>
<li>props - (JMeterProperties - class java.util.Properties) - e.g. props.get("START.HMS"); props.put("PROP1","1234");</li>
<li>sampleResult, prev - (<ahref="../api/org/apache/jmeter/samplers/SampleResult.html">SampleResult</a>) - gives access to the previous <ahref="../api/org/apache/jmeter/samplers/SampleResult.html">SampleResult</a></li>
<li>sampleEvent (<ahref="../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 <b>beanshell.listener.init</b> 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>
<divclass="component"><h2id="Summary_Report">Summary Report<aclass="sectionlink"href="#Summary_Report"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/summary_report.png"><imgsrc="../images/screenshots/summary_report.png"width="926"height="324"alt="Screenshot for Summary Report"></a></div>
<divclass="description">The summary report creates a table row for each differently named request in your
test. This is similar to the <ahref="../usermanual/component_reference.html#Aggregate_Report">Aggregate Report</a> , except that it uses less memory.
<p>
The thoughput 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>Label - The label of the sample.
If "Include group name in label?" 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.
The figure below shows an example of selecting the "Include group name" checkbox.
<figure><ahref="../images/screenshots/summary_report_grouped.png"><imgsrc="../images/screenshots/summary_report_grouped.png"width="923"height="325"alt="Sample "Include group name" display"></a><figcaption>Sample "Include group name" display</figcaption></figure>
<divclass="component"><h2id="Save_Responses_to_a_file">Save Responses to a file<aclass="sectionlink"href="#Save_Responses_to_a_file"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/savetofile.png"><imgsrc="../images/screenshots/savetofile.png"width="358"height="225"alt="Screenshot for Save Responses to a file"></a></div>
<divclass="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
<aclass="sectionlink"href="#Save_Responses_to_a_file_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-false">Name</div><divclass="description req-false">Descriptive name for this element that is shown in the tree.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Filename Prefix</div><divclass="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 bin/ directory).
Versions of JMeter after 2.4 also support paths relative to the directory containing the current test plan (JMX file).
If the path name begins with "~/" (or whatever is in the jmeter.save.saveservice.base_prefix JMeter property),
then the path is assumed to be relative to the JMX file location.
<divclass="property"><divclass="name req-true">Save Failed Responses only</div><divclass="description req-true">If selected, then only failed responses are saved</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Save Successful Responses only</div><divclass="description req-true">If selected, then only successful responses are saved</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Don't add number to prefix</div><divclass="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><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Don't add suffix</div><divclass="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><divclass="required req-true">Yes</div></div>
<divclass="component"><h2id="BSF_Listener">BSF Listener<aclass="sectionlink"href="#BSF_Listener"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/bsf_listener.png"><imgsrc="../images/screenshots/bsf_listener.png"width="847"height="634"alt="Screenshot for BSF Listener"></a></div>
<aclass="sectionlink"href="#BSF_Listener_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-false">Name</div><divclass="description req-false">Descriptive name for this element that is shown in the tree.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Language</div><divclass="description req-true">The BSF language to be used</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-false">Parameters</div><divclass="description req-false">Parameters to pass to the script.
The parameters are stored in the following variables:
<ul>
<li>Parameters - string containing the parameters as a single variable</li>
<li>args - String array containing parameters, split on white-space</li>
<divclass="property"><divclass="name req-false">Script file</div><divclass="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 "user.dir" System property</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Script</div><divclass="description req-true">The script to run.</div><divclass="required req-true">Yes (unless script file is provided)</div></div>
<divclass="component"><h2id="Generate_Summary_Results">Generate Summary Results<aclass="sectionlink"href="#Generate_Summary_Results"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/summary.png"><imgsrc="../images/screenshots/summary.png"width="358"height="131"alt="Screenshot for Generate Summary Results"></a></div>
<divclass="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 n seconds (default 30 seconds) on the appropriate
time boundary, so that multiple test runs on the same time will be synchronised.
See jmeter.properties file for the summariser configuration items:
<pre>
# Define the following property to automatically start a summariser with that name
# (applies to non-GUI 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 (non-GUI) runs.
The "+" means that the line is a delta line, i.e. shows the changes since the last output.<br>
The "=" means that the line is a totals line, i.e. it shows the running total.<br>
Entries in the jmeter log file also include time-stamps.
The example "806 in 91.6s = 8.8/s" means that there were 806 samples recorded in 91.6 seconds,
and that works out at 8.8 samples per second.<br>
The Avg (Average), Min(imum) and Max(imum) times are in milliseconds.<br>
"Err" 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>
<divclass="clear"></div><divclass="note">
In Non-GUI mode by default a Generate Summary Results listener named "summariser" 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).
This is not a bug but a design choice allowing to summarize across thread groups.
<divclass="component"><h2id="Comparison_Assertion_Visualizer">Comparison Assertion Visualizer<aclass="sectionlink"href="#Comparison_Assertion_Visualizer"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/comparison_assertion_visualizer.png"><imgsrc="../images/screenshots/comparison_assertion_visualizer.png"width="777"height="266"alt="Screenshot for Comparison Assertion Visualizer"></a></div>
<divclass="description">
The Comparison Assertion Visualizer shows the results of any <ahref="../usermanual/component_reference.html#Compare_Assertion">Compare Assertion</a> elements.
<divclass="component"><h2id="Backend_Listener">Backend Listener<aclass="sectionlink"href="#Backend_Listener"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/backend_listener.png"><imgsrc="../images/screenshots/backend_listener.png"width="902"height="341"alt="Screenshot for Backend Listener"></a></div>
<divclass="description">
The backend listener is an Asynchronous listener that enables you to plug custom implementations of <ahref="../api/org/apache/jmeter/visualizers/backend/BackendListenerClient.html">BackendListenerClient</a>.
By default, a Graphite implementation is provided.
<aclass="sectionlink"href="#Backend_Listener_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-true">Name</div><divclass="description req-true">Descriptive name for this element that is shown in the tree.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Backend Listener implementation</div><divclass="description req-true">Class of the BackendListenerClient implementation.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Async Queue size</div><divclass="description req-true">Size of the queue that holds the SampleResults while they are processed asynchronously.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Parameters</div><divclass="description req-true">Parameters of the BackendListenerClient implementation.</div><divclass="required req-true">Yes</div></div>
</div>
<p>The following parameters apply to the <b>GraphiteBackendListenerClient</b> implementation:</p>
<aclass="sectionlink"href="#Backend_Listener_parms2"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-true">graphiteMetricsSender</div><divclass="description req-true">org.apache.jmeter.visualizers.backend.graphite.TextGraphiteMetricsSender or org.apache.jmeter.visualizers.backend.graphite.PickleGraphiteMetricsSender</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">graphiteHost</div><divclass="description req-true">Graphite or InfluxDB (with Graphite plugin enabled) server host</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">graphitePort</div><divclass="description req-true">Graphite or InfluxDB (with Graphite plugin enabled) server port, defaults to 2003. Note PickleGraphiteMetricsSender (port 2004) can only talk to Graphite server.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">rootMetricsPrefix</div><divclass="description req-true">Prefix of metrics sent to backend. Defaults to "jmeter."</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">summaryOnly</div><divclass="description req-true">Only send a summary with no detail. Defaults to true.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">samplersList</div><divclass="description req-true">Semicolon separated list of samplers for which you want to report metrics to backend.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">percentiles</div><divclass="description req-true">The percentiles you want to send to backend. List must be semicolon separated.</div><divclass="required req-true">Yes</div></div>
</div>
<p>Read <ahref="realtime-results.html">this</a> for more details.</p>
</div><divclass="section"><h1id="config_elements">18.4 Configuration Elements<aclass="sectionlink"href="#config_elements"title="Link to here">¶</a></h1>
<divclass="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,
<divclass="component"><h2id="CSV_Data_Set_Config">CSV Data Set Config<aclass="sectionlink"href="#CSV_Data_Set_Config"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/csvdatasetconfig.png"><imgsrc="../images/screenshots/csvdatasetconfig.png"width="433"height="281"alt="Screenshot for CSV Data Set Config"></a></div>
<divclass="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 __CSVRead() and _StringFromFile() functions.
It is well suited to handling large numbers of variables, and is also useful for tesing with
"random" and unique values.
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>
Versions of JMeter after 2.3.1 allow values to be quoted; this allows the value to contain a delimiter.
Previously it was necessary to choose a delimiter that was not used in any values.
If "allow quoted data" 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:<pre>
1,"2,3","4""5" =>
1
2,3
4"5
</pre>
</p>
<p>
Versions of JMeter after 2.3.4 support CSV files which have a header line defining the column names.
To enable this, leave the "Variable Names" field empty. The correct delimiter must be provided.
</p>
<p>
Versions of JMeter after 2.7 support 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 (JMeter 2.3.2+).
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 test1.csv, test2.csv,... testn.csv. Use the filename
<spanclass="code">test${__threadNum}.csv</span> and set the "Sharing mode" to "Current thread".
</p>
<divclass="clear"></div><divclass="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 <ahref="http://bz.apache.org/bugzilla/show_bug.cgi?id=40394">
Bug
40394</a>)
However the variables do work in the HTTP Auth Manager, as the username etc are processed at run-time.
</div><divclass="clear"></div>
<p>
As a special case, the string "\t" (without quotes) in the delimiter field is treated as a Tab.
</p>
<p>
When the end of file (EOF) is reached, and the recycle option is true, reading starts again with the first line of the file.
</p>
<p>
If the recycle option is false, and stopThread is false, then all the variables are set to <b><EOF></b> when the end of file is reached.
This value can be changed by setting the JMeter property <b>csvdataset.eofstring</b>.
</p>
<p>
If the Recycle option is false, and Stop Thread is true, then reaching EOF will cause the thread to be stopped.
<aclass="sectionlink"href="#CSV_Data_Set_Config_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-true">Name</div><divclass="description req-true">Descriptive name for this element that is shown in the tree.</div><divclass="required req-true"></div></div>
<divclass="property"><divclass="name req-true">Filename</div><divclass="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. csvdata.txt and ./csvdata.txt -
then these are treated as different files.
If the OS does not distinguish between upper and lower case, csvData.TXT would also be opened separately.
<divclass="property"><divclass="name req-false">File Encoding</div><divclass="description req-false">The encoding to be used to read the file, if not the platform default.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Variable Names</div><divclass="description req-true">List of variable names (comma-delimited).
Versions of JMeter after 2.3.4 support 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.
The names must be separated by the delimiter character. They can be quoted using double-quotes.
<divclass="property"><divclass="name req-true">Recycle on EOF?</div><divclass="description req-true">Should the file be re-read from the beginning on reaching EOF? (default is true)</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Stop thread on EOF?</div><divclass="description req-true">Should the thread be stopped on EOF, if Recycle is false? (default is false)</div><divclass="required req-true">Yes</div></div>
<divclass="component"><h2id="FTP_Request_Defaults">FTP Request Defaults<aclass="sectionlink"href="#FTP_Request_Defaults"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/ftp-config/ftp-request-defaults.png"><imgsrc="../images/screenshots/ftp-config/ftp-request-defaults.png"width="520"height="202"alt="Screenshot for FTP Request Defaults"></a></div>
<divclass="component"><h2id="DNS_Cache_Manager">DNS Cache Manager<aclass="sectionlink"href="#DNS_Cache_Manager"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/dns-cache-manager.png"><imgsrc="../images/screenshots/dns-cache-manager.png"width="712"height="387"alt="Screenshot for DNS Cache Manager"></a></div>
<divclass="clear"></div><divclass="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><divclass="clear"></div>
<divclass="clear"></div><divclass="note">DNS Cache Manager working only with the HTTP request using HTTPClient4 implementation.</div><divclass="clear"></div>
<divclass="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 name for each thread separately each iteration and
saves results of resolving to its internal DNS Cache, which independent from both JVM and OS DNS caches.
<aclass="sectionlink"href="#DNS_Cache_Manager_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-false">Name</div><divclass="description req-false">Descriptive name for this element that is shown in the tree. </div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Clear cache each Iteration</div><divclass="description req-false">If selected, DNS cache of every Thread is cleared each time new iteration is started.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Use system DNS resolver</div><divclass="description req-false">System DNS resolver will be used. For correct work edit
$JAVA_HOME/jre/lib/security/java.security and add <pre>networkaddress.cache.ttl=0</pre>
<divclass="property"><divclass="name req-false">Use custom DNS resolver</div><divclass="description req-false">Custom DNS resolver(from dnsjava library) will be used.</div><divclass="required req-false">N/A</div></div>
<divclass="property"><divclass="name req-false">Hostname or IP address</div><divclass="description req-false">List of DNS servers to use. If empty, network configuration DNS will used.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Add Button</div><divclass="description req-false">Add an entry to the DNS servers table.</div><divclass="required req-false">N/A</div></div>
<divclass="property"><divclass="name req-false">Delete Button</div><divclass="description req-false">Delete the currently selected table entry.</div><divclass="required req-false">N/A</div></div>
</div>
<divclass="go-top"><ahref="#">^</a></div></div>
<divclass="component"><h2id="HTTP_Authorization_Manager">HTTP Authorization Manager<aclass="sectionlink"href="#HTTP_Authorization_Manager"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/http-config/http-auth-manager.png"><imgsrc="../images/screenshots/http-config/http-auth-manager.png"width="538"height="340"alt="Screenshot for HTTP Authorization Manager"></a></div>
<divclass="clear"></div><divclass="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><divclass="clear"></div>
<divclass="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 Authorisation headers may not be shown in the Tree View Listener "Request" tab.
The Java implementation does pre-emptive authentication, but it does not
return the Authorization header when JMeter fetches the headers.
The Commons HttpClient (3.1) implementation defaults to pre-emptive and the header will be shown.
The HttpComponents implementation does not do pre-emptive auth
(it is supported by the library but JMeter does not enable it)
<aclass="sectionlink"href="#HTTP_Authorization_Manager_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-false">Name</div><divclass="description req-false">Descriptive name for this element that is shown in the tree. </div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Clear auth on each iteration ?</div><divclass="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.
<divclass="property"><divclass="name req-true">Base URL</div><divclass="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 "http://jmeter.apache.org/restricted/" with a username of "jmeter" and
a password of "jmeter". If you send an HTTP request to the URL
"http://jmeter.apache.org/restricted/ant/myPage.html", the Authorization Manager sends the login
information for the user named, "jmeter".</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Username</div><divclass="description req-true">The username to authorize.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Password</div><divclass="description req-true">The password for the user. (N.B. this is stored unencrypted in the test plan)</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-false">Domain</div><divclass="description req-false">The domain to use for NTLM.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Realm</div><divclass="description req-false">The realm to use for NTLM.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Mechanism</div><divclass="description req-false">Type of authentication to perform. JMeter can perform different types of authentications based on used Http Samplers:
<p><ahref="../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, "secret", which contains two files, "index.html" and "index2.html". We created a login id named, "kevin",
which has a password of "spot". 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 "SecretPage1" and "SecretPage2" make requests
to "/secret/index.html" and "/secret/index2.html". The other HTTP request, named "NoSecretPage" makes a request to
<figure><ahref="../images/screenshots/http-config/auth-manager-example1a.gif"><imgsrc="../images/screenshots/http-config/auth-manager-example1a.gif"width="289"height="201"alt="Figure 10 - Test Plan"></a><figcaption>Figure 10 - Test Plan</figcaption></figure>
<figure><ahref="../images/screenshots/http-config/auth-manager-example1b.png"><imgsrc="../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>
<divclass="component"><h2id="HTTP_Cache_Manager">HTTP Cache Manager<aclass="sectionlink"href="#HTTP_Cache_Manager"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/http-config/http-cache-manager.png"><imgsrc="../images/screenshots/http-config/http-cache-manager.png"width="511"height="196"alt="Screenshot for HTTP Cache Manager"></a></div>
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 "maxSize" 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 -Xmx option accordingly.
<aclass="sectionlink"href="#HTTP_Cache_Manager_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-false">Name</div><divclass="description req-false">Descriptive name for this element that is shown in the tree. </div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Clear cache each iteration</div><divclass="description req-true">
If selected, then the cache is cleared at the start of the thread.
<divclass="property"><divclass="name req-true">Use Cache Control/Expires header when processing GET requests</div><divclass="description req-true">See description above.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Max Number of elements in cache</div><divclass="description req-true">See description above.</div><divclass="required req-true">Yes</div></div>
<divclass="component"><h2id="HTTP_Cookie_Manager">HTTP Cookie Manager<aclass="sectionlink"href="#HTTP_Cookie_Manager"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/http-config/http-cookie-manager.png"><imgsrc="../images/screenshots/http-config/http-cookie-manager.png"width="513"height="383"alt="Screenshot for HTTP Cookie Manager"></a></div>
<aclass="sectionlink"href="#HTTP_Cookie_Manager_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-false">Name</div><divclass="description req-false">Descriptive name for this element that is shown in the tree. </div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Clear Cookies each Iteration</div><divclass="description req-true">If selected, all server-defined cookies are cleared each time the main Thread Group loop is executed.
In JMeter versions after 2.3, any cookies defined in the GUI are not cleared.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Cookie Policy</div><divclass="description req-true">The cookie policy that will be used to manage the cookies.
"compatibility" is the default, and should work in most cases.
See http://hc.apache.org/httpclient-3.x/cookies.html and
<i>[Note: If you have a website to test with IPv6 address, choose HC4CookieHandler (IPv6 compliant)]</i></div><divclass="required req-true">Yes</div></div>
gives you the opportunity to use hardcoded cookies that will be used by all threads during the test execution.
<br>
The "domain" is the hostname of the server (without http://); the port is currently ignored.
</div><divclass="required req-false">No (discouraged, unless you know what you're doing)</div></div>
<divclass="property"><divclass="name req-false">Add Button</div><divclass="description req-false">Add an entry to the cookie table.</div><divclass="required req-false">N/A</div></div>
<divclass="property"><divclass="name req-false">Delete Button</div><divclass="description req-false">Delete the currently selected table entry.</div><divclass="required req-false">N/A</div></div>
<divclass="property"><divclass="name req-false">Load Button</div><divclass="description req-false">Load a previously saved cookie table and add the entries to the existing
<divclass="component"><h2id="HTTP_Request_Defaults">HTTP Request Defaults<aclass="sectionlink"href="#HTTP_Request_Defaults"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/http-config/http-request-defaults.png"><imgsrc="../images/screenshots/http-config/http-request-defaults.png"width="853"height="463"alt="Screenshot for HTTP Request Defaults"></a></div>
<divclass="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 "Server Name or IP" field filled in. Then, when
you add the 25 HTTP Request controllers, leave the "Server Name or IP" field empty. The controllers will inherit
this field value from the HTTP Request Defaults element.</p>
<divclass="clear"></div><divclass="note">
In JMeter 2.2 and earlier, port 80 was treated specially - it was ignored if the sampler used the https protocol.
JMeter 2.3 and later treat all port values equally; a sampler that does not specify a port will use the HTTP Request Defaults port, if one is provided.
<aclass="sectionlink"href="#HTTP_Request_Defaults_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-false">Name</div><divclass="description req-false">Descriptive name for this element that is shown in the tree.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Server</div><divclass="description req-false">Domain name or IP address of the web server. e.g. www.example.com. [Do not include the http:// prefix.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Port</div><divclass="description req-false">Port the web server is listening to.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Connect Timeout</div><divclass="description req-false">Connection Timeout. Number of milliseconds to wait for a connection to open.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Response Timeout</div><divclass="description req-false">Response Timeout. Number of milliseconds to wait for a response.</div><divclass="required req-false">No</div></div>
If not specified the default depends on the value of the JMeter property
<spanclass="code">jmeter.httpsampler</span>, failing that, the Java implementation is used.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Protocol</div><divclass="description req-false">HTTP or HTTPS.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Method</div><divclass="description req-false">HTTP GET or HTTP POST.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Path</div><divclass="description req-false">The path to resource (for example, /servlets/myServlet). If the
resource requires query string parameters, add them below in the "Send Parameters With the Request" section.
Note that the path is the default for the full path, not a prefix to be applied to paths
<divclass="property"><divclass="name req-false">Send Parameters With the Request</div><divclass="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 "Method" you made (ie if you chose GET, the query string will be
appended to the URL, if POST, 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><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Server (proxy)</div><divclass="description req-false">Hostname or IP address of a proxy server to perform request. [Do not include the http:// prefix.]</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Port</div><divclass="description req-false">Port the proxy server is listening to.</div><divclass="required req-false">No, unless proxy hostname is specified</div></div>
<divclass="property"><divclass="name req-false">Username</div><divclass="description req-false">(Optional) username for proxy server.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Password</div><divclass="description req-false">(Optional) password for proxy server. (N.B. this is stored unencrypted in the test plan)</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Retrieve All Embedded Resources from HTML Files</div><divclass="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.
<divclass="property"><divclass="name req-false">Use concurrent pool</div><divclass="description req-false">Use a pool of concurrent connections to get embedded resources.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Size</div><divclass="description req-false">Pool size for concurrent connections used to get embedded resources.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Embedded URLs must match:</div><divclass="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 http://example.com/, use the expression:
<divclass="component"><h2id="HTTP_Header_Manager">HTTP Header Manager<aclass="sectionlink"href="#HTTP_Header_Manager"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/http-config/http-header-manager.png"><imgsrc="../images/screenshots/http-config/http-header-manager.png"width="767"height="239"alt="Screenshot for HTTP Header Manager"></a></div>
<divclass="description">
<p>The Header Manager lets you add or override HTTP request headers.</p>
<p>
Versions of JMeter up to 2.3.2 supported only one Header Manager per sampler;
if there were more in scope, then only the last one would be used.
</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,
unless the entry value is empty, in which case any existing entry is removed.
This allows one to set up a default set of headers, and apply adjustments to particular samplers.
<aclass="sectionlink"href="#HTTP_Header_Manager_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-false">Name</div><divclass="description req-false">Descriptive name for this element that is shown in the tree. </div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Name (Header)</div><divclass="description req-false">Name of the request header.
Two common request headers you may want to experiment with
are "User-Agent" and "Referer".</div><divclass="required req-false">No (You should have at least one, however)</div></div>
<divclass="property"><divclass="name req-false">Value</div><divclass="description req-false">Request header value.</div><divclass="required req-false">No (You should have at least one, however)</div></div>
<divclass="property"><divclass="name req-false">Add Button</div><divclass="description req-false">Add an entry to the header table.</div><divclass="required req-false">N/A</div></div>
<divclass="property"><divclass="name req-false">Delete Button</div><divclass="description req-false">Delete the currently selected table entry.</div><divclass="required req-false">N/A</div></div>
<divclass="property"><divclass="name req-false">Load Button</div><divclass="description req-false">Load a previously saved header table and add the entries to the existing
<divclass="property"><divclass="name req-false">Save As Button</div><divclass="description req-false">Save the current header table to a file.</div><divclass="required req-false">N/A</div></div>
<figure><ahref="../images/screenshots/http-config/header-manager-example1a.gif"><imgsrc="../images/screenshots/http-config/header-manager-example1a.gif"width="203"height="141"alt="Figure 12 - Test Plan"></a><figcaption>Figure 12 - Test Plan</figcaption></figure>
<figure><ahref="../images/screenshots/http-config/header-manager-example1b.png"><imgsrc="../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>
<divclass="component"><h2id="Java_Request_Defaults">Java Request Defaults<aclass="sectionlink"href="#Java_Request_Defaults"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/java_defaults.png"><imgsrc="../images/screenshots/java_defaults.png"width="454"height="283"alt="Screenshot for Java Request Defaults"></a></div>
<divclass="description"><p>The Java Request Defaults component lets you set default values for Java testing. See the <ahref="../usermanual/component_reference.html#Java_Request">Java Request</a>.</p>
<divclass="component"><h2id="JDBC_Connection_Configuration">JDBC Connection Configuration<aclass="sectionlink"href="#JDBC_Connection_Configuration"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/jdbc-config/jdbc-conn-config.png"><imgsrc="../images/screenshots/jdbc-config/jdbc-conn-config.png"width="474"height="458"alt="Screenshot for JDBC Connection Configuration"></a></div>
<divclass="description">Creates a database connection (used by <ahref="../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
<aclass="sectionlink"href="#JDBC_Connection_Configuration_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-false">Name</div><divclass="description req-false">Descriptive name for the connection configuration that is shown in the tree.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Variable Name</div><divclass="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.
<b>Each name must be different. If there are two configuration elements using the same name,
only one will be saved. JMeter versions after 2.3 log a message if a duplicate name is detected.</b>
<divclass="property"><divclass="name req-true">Pool timeout</div><divclass="description req-true">Pool throws an error if the timeout period is exceeded in the
process of trying to retrieve a connection</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Idle Cleanup Interval (ms)</div><divclass="description req-true">This is used to specify how long idle connections will be maintained in the pool before being closed. For a complete explanation on how this works, see <ahref="http://excalibur.apache.org/apidocs/org/apache/avalon/excalibur/pool/ResourceLimitingPool.html#trim%28%29">ResourceLimitingPool.trim()</a> (Defaults to "60000", 1 minute)</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Auto Commit</div><divclass="description req-true">Turn auto commit on or off for the connections.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Keep-alive</div><divclass="description req-true">The keep-alive is used enable a mechanism to monitor the health of connections. If a connection has not been used for Max Connection Age (ms) then before returning the connection from a call to getConnection(), the connection is first used to ping the database to make sure that it is still alive.
Setting the age allows the 5 second age to be overridden. Validation Query will be used to test it.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Max Connection Age (ms)</div><divclass="description req-true">Controls the age mentionned in "Keep-Alive" property. It means connections not used for more than Max Connection Age will be tested</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Validation Query</div><divclass="description req-true">A simple query used to determine if the database is still
<divclass="property"><divclass="name req-true">Database URL</div><divclass="description req-true">JDBC Connection string for the database.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">JDBC Driver class</div><divclass="description req-true">Fully qualified name of driver class. (Must be in
JMeter's classpath - easiest to copy .jar file into JMeter's /lib directory).</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-false">Username</div><divclass="description req-false">Name of user to connect as.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Password</div><divclass="description req-false">Password to connect with. (N.B. this is stored unencrypted in the test plan)</div><divclass="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 <b>No suitable driver</b>, then this could mean either:
<ul>
<li>The driver class was not found. In this case, there will be a log message such as <tt>DataSourceElement: Could not load driver: {classname} java.lang.ClassNotFoundException: {classname}</tt></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 the wrong classname was used.</li>
</ul>
If the database server is not running or is not accessible, then JMeter will report a <b>java.net.ConnectException</b>.
<tr><td>SQL Server (MS JDBC driver)</td><td>com.microsoft.sqlserver.jdbc.SQLServerDriver</td><td>jdbc:sqlserver://host:port;DatabaseName=dbname</td></tr>
<divclass="clear"></div><divclass="note">The above may not be correct - please check the relevant JDBC driver documentation.</div><divclass="clear"></div>
<divclass="go-top"><ahref="#">^</a></div></div>
<divclass="component"><h2id="Keystore_Configuration">Keystore Configuration<aclass="sectionlink"href="#Keystore_Configuration"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/keystore_config.png"><imgsrc="../images/screenshots/keystore_config.png"width="441"height="189"alt="Screenshot for Keystore Configuration"></a></div>
<divclass="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:
<ol>
<li>Create your certificates either with Java keytool 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 2 JVM properties (or add them in system.properties):
preload.shortDescription=Preload Keystore before test. Setting is to true is usually the best option.
startIndex.displayName=Alias Start index (0-based)
startIndex.shortDescription=First index of Alias in Keystore
endIndex.displayName=Alias End index (0-based)
endIndex.shortDescription=Last index of Alias in Keystore. When using Variable name ensure it is large enough so that all keys are loaded at startup.
clientCertAliasVarName.displayName=Variable name holding certificate alias
clientCertAliasVarName.shortDescription=Variable name that will contain the alias to use for Cert authentication. Var content can come from CSV Data Set.
<aclass="sectionlink"href="#Keystore_Configuration_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-false">Name</div><divclass="description req-false">Descriptive name for this element that is shown in the tree. </div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Preload</div><divclass="description req-true">Wether or not to preload Keystore. Setting is to true is usually the best option.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-false">Variable name holding certificate alias</div><divclass="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, "certificat_ssl" will also be a variable in CSV Data Set.</div><divclass="required req-false">False</div></div>
<divclass="property"><divclass="name req-true">Alias Start Index</div><divclass="description req-true">The index of the first key to use in Keystore, 0-based.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Alias End Index</div><divclass="description req-true">The index of the last key to use in Keystore, 0-based. When using "Variable name holding certificate alias" ensure it is large enough so that all keys are loaded at startup.</div><divclass="required req-true">Yes</div></div>
</div>
<divclass="clear"></div><divclass="note">
To make JMeter use more than one certificate you need to ensure that:
<divclass="component"><h2id="Login_Config_Element">Login Config Element<aclass="sectionlink"href="#Login_Config_Element"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/login-config.png"><imgsrc="../images/screenshots/login-config.png"width="352"height="112"alt="Screenshot for Login Config Element"></a></div>
<divclass="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>
<aclass="sectionlink"href="#Login_Config_Element_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-false">Name</div><divclass="description req-false">Descriptive name for this element that is shown in the tree. </div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Username</div><divclass="description req-false">The default username to use.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Password</div><divclass="description req-false">The default password to use. (N.B. this is stored unencrypted in the test plan)</div><divclass="required req-false">No</div></div>
<divclass="component"><h2id="LDAP_Request_Defaults">LDAP Request Defaults<aclass="sectionlink"href="#LDAP_Request_Defaults"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/ldap_defaults.png"><imgsrc="../images/screenshots/ldap_defaults.png"width="689"height="232"alt="Screenshot for LDAP Request Defaults"></a></div>
<divclass="description"><p>The LDAP Request Defaults component lets you set default values for LDAP testing. See the <ahref="../usermanual/component_reference.html#LDAP_Request">LDAP Request</a>.</p>
<divclass="component"><h2id="LDAP_Extended_Request_Defaults">LDAP Extended Request Defaults<aclass="sectionlink"href="#LDAP_Extended_Request_Defaults"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/ldapext_defaults.png"><imgsrc="../images/screenshots/ldapext_defaults.png"width="686"height="184"alt="Screenshot for LDAP Extended Request Defaults"></a></div>
<divclass="description"><p>The LDAP Extended Request Defaults component lets you set default values for extended LDAP testing. See the <ahref="../usermanual/component_reference.html#LDAP_Extended_Request">LDAP Extended Request</a>.</p>
<divclass="component"><h2id="TCP_Sampler_Config">TCP Sampler Config<aclass="sectionlink"href="#TCP_Sampler_Config"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/tcpsamplerconfig.png"><imgsrc="../images/screenshots/tcpsamplerconfig.png"width="826"height="450"alt="Screenshot for TCP Sampler Config"></a></div>
<divclass="description">
<p>
The TCP Sampler Config provides default data for the TCP Sampler
<aclass="sectionlink"href="#TCP_Sampler_Config_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-true">Name</div><divclass="description req-true">Descriptive name for this element that is shown in the tree.</div><divclass="required req-true"></div></div>
<divclass="property"><divclass="name req-false">TCPClient classname</div><divclass="description req-false">Name of the TCPClient class. Defaults to the property tcp.handler, failing that TCPClientImpl.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">ServerName or IP</div><divclass="description req-true">Name or IP of TCP server</div><divclass="required req-true"></div></div>
<divclass="property"><divclass="name req-true">Port Number</div><divclass="description req-true">Port to be used</div><divclass="required req-true"></div></div>
<divclass="property"><divclass="name req-true">Re-use connection</div><divclass="description req-true">If selected, the connection is kept open. Otherwise it is closed when the data has been read.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Close connection</div><divclass="description req-true">If selected, the connection will be closed after running the sampler.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-false">SO_LINGER</div><divclass="description req-false">Enable/disable SO_LINGER with the specified linger time in seconds when a socket is created. If you set "SO_LINGER" value as 0, you may prevent large numbers of sockets sitting around with a TIME_WAIT status.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">End of line(EOL) byte value</div><divclass="description req-false">Byte value for end of line, set this to a value outside the range -128 to +127 to skip eol checking. You may set this in jmeter.properties file as well with eolByte property. If you set this in TCP Sampler Config and in jmeter.properties file at the same time, the setting value in the TCP Sampler Config will be used.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Set Nodelay</div><divclass="description req-true">Should the nodelay property be set?</div><divclass="required req-true"></div></div>
<divclass="property"><divclass="name req-true">Text to Send</div><divclass="description req-true">Text to be sent</div><divclass="required req-true"></div></div>
<divclass="component"><h2id="User_Defined_Variables">User Defined Variables<aclass="sectionlink"href="#User_Defined_Variables"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/user_defined_variables.png"><imgsrc="../images/screenshots/user_defined_variables.png"width="741"height="266"alt="Screenshot for User Defined Variables"></a></div>
<divclass="description"><p>The User Defined Variables element lets you define an <b>initial set of variables</b>, just as in the <ahref="../usermanual/component_reference.html#Test_Plan">Test Plan</a>.
<b>
Note that all the UDV elements in a test plan - no matter where they are - are processed at the start.
</b>
So you cannot reference variables which are defined as part of a test run, e.g. in a Post-Processor.
<aclass="sectionlink"href="#User_Defined_Variables_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-true">Name</div><divclass="description req-true">Descriptive name for this element that is shown in the tree.</div><divclass="required req-true"></div></div>
<divclass="property"><divclass="name req-true">User Defined Variables</div><divclass="description req-true">Variable name/value pairs. The string under the "Name"
column is what you'll need to place inside the brackets in ${...} constructs to use the variables later on. The
whole ${...} will then be replaced by the string in the "Value" column.</div><divclass="required req-true"></div></div>
<divclass="component"><h2id="Random_Variable">Random Variable<aclass="sectionlink"href="#Random_Variable"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/random_variable.png"><imgsrc="../images/screenshots/random_variable.png"width="495"height="286"alt="Screenshot for Random Variable"></a></div>
<divclass="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 <ahref="../usermanual/component_reference.html#User_Defined_Variables">User Defined Variables</a> together with the __Random() 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 <spanclass="code">minimum+Random.nextInt(maximum-minimum+1)</span>.
Random.nextInt() requires a positive integer.
This means that maximum-minimum - i.e. the range - must be less than 2147483647,
however the minimum and maximum values can be any long values so long as the range is OK.
<aclass="sectionlink"href="#Random_Variable_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-true">Name</div><divclass="description req-true">Descriptive name for this element that is shown in the tree.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Variable Name</div><divclass="description req-true">The name of the variable in which to store the random string.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-false">Format String</div><divclass="description req-false">The java.text.DecimalFormat format string to be used.
For example "000" which will generate numbers with at least 3 digits,
or "USER_000" which will generate output of the form USER_nnn.
If not specified, the default is to generate the number using Long.toString()</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Minimum Value</div><divclass="description req-true">The minimum value (long) of the generated random number.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Maximum Value</div><divclass="description req-true">The maximum value (long) of the generated random number.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-false">Random Seed</div><divclass="description req-false">The seed for the random number generator. Default is the current time in milliseconds.
If you use the same seed value with Per Thread set to true, you will get the same value for earch Thread as per
<divclass="property"><divclass="name req-true">Per Thread(User)?</div><divclass="description req-true">If False, the generator is shared between all threads in the thread group.
If True, then each thread has its own random generator.</div><divclass="required req-true">Yes</div></div>
<divclass="component"><h2id="Counter">Counter<aclass="sectionlink"href="#Counter"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/counter.png"><imgsrc="../images/screenshots/counter.png"width="404"height="262"alt="Screenshot for Counter"></a></div>
<divclass="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>From version 2.1.2, the counter now uses a long to store the value, so the range is from -2^63 to 2^63-1.</p>
</div>
<divclass="properties"><h3id="Counter_parms1">
Parameters
<aclass="sectionlink"href="#Counter_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-true">Name</div><divclass="description req-true">Descriptive name for this element that is shown in the tree.</div><divclass="required req-true"></div></div>
<divclass="property"><divclass="name req-true">Start</div><divclass="description req-true">The starting number for the counter. The counter will equal this
number during the first iteration.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Increment</div><divclass="description req-true">How much to increment the counter by after each
<divclass="property"><divclass="name req-false">Maximum</div><divclass="description req-false">If the counter exceeds the maximum, then it is reset to the Start value.
For versions after 2.2 the default is Long.MAX_VALUE (previously it was 0).
<divclass="property"><divclass="name req-true">Reference Name</div><divclass="description req-true">This controls how you refer to this value in other elements. Syntax is
as in <ahref="functions.html">user-defined values</a>: <spanclass="code">$(reference_name}</span>.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-false">Track Counter Independently for each User</div><divclass="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 (ie, user #1 will get value "1", and user #2 will get value "2" on
the first iteration). If checked, each user has an independent counter.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Reset counter on each Thread Group Iteration</div><divclass="description req-false">This option is only available when counter is tracked per User, if checked,
counter will be reset to Start value on each Thread Group iteration. This can be useful when Counter is inside a Loop Controller.</div><divclass="required req-false">No</div></div>
<divclass="component"><h2id="Simple_Config_Element">Simple Config Element<aclass="sectionlink"href="#Simple_Config_Element"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/simple_config_element.png"><imgsrc="../images/screenshots/simple_config_element.png"width="393"height="245"alt="Screenshot for Simple Config Element"></a></div>
<divclass="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>
<aclass="sectionlink"href="#Simple_Config_Element_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-true">Name</div><divclass="description req-true">Descriptive name for this element that is shown in the tree. </div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Parameter Name</div><divclass="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><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Parameter Value</div><divclass="description req-true">The value to apply to that parameter.</div><divclass="required req-true">Yes</div></div>
<divclass="component"><h2id="MongoDB_Source_Config">MongoDB Source Config<aclass="sectionlink"href="#MongoDB_Source_Config"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/mongodb-source-config.png"><imgsrc="../images/screenshots/mongodb-source-config.png"width="1233"height="618"alt="Screenshot for MongoDB Source Config"></a></div>
<divclass="description">Creates a MongoDB connection (used by <ahref="../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.
You can then access com.mongodb.DB object in Beanshell or JSR223 Test Elements through the element <ahref="../api/org/apache/jmeter/protocol/mongodb/config/MongoDBHolder.html">MongoDBHolder</a>
<aclass="sectionlink"href="#MongoDB_Source_Config_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-false">Name</div><divclass="description req-false">Descriptive name for the connection configuration that is shown in the tree.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Server Address List</div><divclass="description req-true">Mongo DB Servers</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">MongoDB Source</div><divclass="description req-true">The name of the variable the connection is tied to.
<divclass="clear"></div><divclass="note">Each name must be different. If there are two configuration elements using the same name, only one will be saved.</div><divclass="clear"></div>
If true, 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 also can be useful to smooth the transition to a new master (so that a new master is elected within the retry time).<br>
Note that when using this flag\:
<br>- for a replica set, the driver will trying to connect to the old master for that time, instead of failing over to the new one right away
<br>- this does not prevent exception from being thrown in read/write operations on the socket, which must be handled by application.<br>
Even if this flag is false, the driver already has mechanisms to automatically recreate broken connections and retry the read operations. <br>
The connection timeout in milliseconds.<br>It is used solely when establishing a new connection Socket.connect(java.net.SocketAddress, int)<br>Default is 0 and means no timeout.
The maximum amount of time in MS to spend retrying to open connection to the same server.<br>Default is 0, which means to use the default 15s if autoConnectRetry is on.
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 connectionsPerHost is 10 and threadsAllowedToBlockForConnectionMultiplier is 5, then up to 50 threads can wait for a connection.<br>
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>
<divclass="clear"></div><divclass="note">
The variable <b>JMeterThread.last_sample_ok</b> is updated to
"true" or "false" after all assertions for a sampler have been run.
</div><divclass="clear"></div>
</div>
<divclass="component"><h2id="Response_Assertion">Response Assertion<aclass="sectionlink"href="#Response_Assertion"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/assertion/assertion.png"><imgsrc="../images/screenshots/assertion/assertion.png"width="921"height="423"alt="Screenshot for Response Assertion"></a></div>
A summary of the pattern matching characters can be found at <ahref="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 <b>Price: \d+</b> not <b>/Price: \d+/</b>.
</p>
<p>
By default, the pattern is in multi-line mode, which means that the "." meta-character does not match newline.
In multi-line mode, "^" and "$" match the start or end of any line anywhere within the string
- not just the start and end of the entire string. Note that \s does match new-line.
Case is also significant. To override these settings, one can use the <i>extended regular expression</i> syntax.
<aclass="sectionlink"href="#Response_Assertion_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-false">Name</div><divclass="description req-false">Descriptive name for this element that is shown in the tree.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Response Field to Test</div><divclass="description req-true">Instructs JMeter which field of the Response to test.
<ul>
<li>Text Response - the response text from the server, i.e. the body, excluding any HTTP headers.</li>
<li>Document (text) - the extract text from various type of documents via Apache Tika (see <ahref="../usermanual/component_reference.html#View_Results_Tree">View Results Tree</a> Document view section).</li>
<li>URL sampled</li>
<li>Response Code - e.g. 200</li>
<li>Response Message - e.g. OK</li>
<li>Response Headers, including Set-Cookie headers (if any)</li>
<divclass="property"><divclass="name req-true">Ignore status</div><divclass="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 Ignore Status checkbox is selected, the Response status is forced
to successful before evaluating the Assertion.
</p>
HTTP Responses with statuses in the 4xx and 5xx ranges are normally
regarded as unsuccessful.
The "Ignore status" 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.
The pattern is a Perl5-style regular expression, but without the enclosing brackets.
</p>
<divclass="example"><divclass="title">Assertion Examples<aclass="sectionlink"href="#assertion_examples"title="Link to here">¶</a></div>
<center>
<figure><ahref="../images/screenshots/assertion/example1a.png"><imgsrc="../images/screenshots/assertion/example1a.png"width="242"height="123"alt="Figure 14 - Test Plan"></a><figcaption>Figure 14 - Test Plan</figcaption></figure>
<figure><ahref="../images/screenshots/assertion/example1b.png"><imgsrc="../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>
<divclass="component"><h2id="Duration_Assertion">Duration Assertion<aclass="sectionlink"href="#Duration_Assertion"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/duration_assertion.png"><imgsrc="../images/screenshots/duration_assertion.png"width="606"height="187"alt="Screenshot for Duration Assertion"></a></div>
<divclass="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
<aclass="sectionlink"href="#Duration_Assertion_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-true">Name</div><divclass="description req-true">Descriptive name for this element that is shown in the tree.</div><divclass="required req-true"></div></div>
<divclass="property"><divclass="name req-true">Duration in Milliseconds</div><divclass="description req-true">The maximum number of milliseconds
each response is allowed before being marked as failed.</div><divclass="required req-true">Yes</div></div>
<divclass="component"><h2id="Size_Assertion">Size Assertion<aclass="sectionlink"href="#Size_Assertion"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/size_assertion.png"><imgsrc="../images/screenshots/size_assertion.png"width="732"height="358"alt="Screenshot for Size Assertion"></a></div>
<divclass="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>
<divclass="clear"></div><divclass="note">Since JMeter 2.3RC3, an empty response is treated as being 0 bytes rather than reported as an error.</div><divclass="clear"></div>
<aclass="sectionlink"href="#Size_Assertion_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-true">Name</div><divclass="description req-true">Descriptive name for this element that is shown in the tree.</div><divclass="required req-true"></div></div>
<divclass="property"><divclass="name req-true">Size in bytes</div><divclass="description req-true">The number of bytes to use in testing the size of the response (or value of the JMeter variable).</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Type of Comparison</div><divclass="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><divclass="required req-true">Yes</div></div>
<divclass="component"><h2id="XML_Assertion">XML Assertion<aclass="sectionlink"href="#XML_Assertion"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/xml_assertion.png"><imgsrc="../images/screenshots/xml_assertion.png"width="470"height="85"alt="Screenshot for XML Assertion"></a></div>
<divclass="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>
<aclass="sectionlink"href="#XML_Assertion_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-true">Name</div><divclass="description req-true">Descriptive name for this element that is shown in the tree.</div><divclass="required req-true"></div></div>
<divclass="component"><h2id="BeanShell_Assertion">BeanShell Assertion<aclass="sectionlink"href="#BeanShell_Assertion"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/beanshell_assertion.png"><imgsrc="../images/screenshots/beanshell_assertion.png"width="849"height="633"alt="Screenshot for BeanShell Assertion"></a></div>
<divclass="description"><p>The BeanShell Assertion allows the user to perform assertion checking using a BeanShell script.
<divclass="property"><divclass="name req-false">Script file</div><divclass="description req-false">A file containing the BeanShell script to run. This overrides the script.
The file name is stored in the script variable FileName</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Script</div><divclass="description req-true">The BeanShell script to run. The return value is ignored.</div><divclass="required req-true">Yes (unless script file is provided)</div></div>
</div>
<p>There's a <ahref="../demos/BeanShellAssertion.bsh">sample script</a> you can try.</p>
<p>
Before invoking the script, some variables are set up in the BeanShell interpreter.
<li>vars - <ahref="../api/org/apache/jmeter/threads/JMeterVariables.html">JMeterVariables</a> - e.g. vars.get("VAR1"); vars.put("VAR2","value"); vars.putObject("OBJ1",new Object());</li>
<li>props - JMeterProperties (class java.util.Properties) - e.g. props.get("START.HMS"); props.put("PROP1","1234");</li>
</ul>
</p>
<p>The following methods of the Response object may be useful:
<ul>
<li>setStopThread(boolean)</li>
<li>setStopTest(boolean)</li>
<li>String getSampleLabel()</li>
<li>setSampleLabel(String)</li>
</ul></p>
<divclass="go-top"><ahref="#">^</a></div></div>
<divclass="component"><h2id="MD5Hex_Assertion">MD5Hex Assertion<aclass="sectionlink"href="#MD5Hex_Assertion"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/assertion/MD5HexAssertion.png"><imgsrc="../images/screenshots/assertion/MD5HexAssertion.png"width="411"height="149"alt="Screenshot for MD5Hex Assertion"></a></div>
<divclass="description"><p>The MD5Hex Assertion allows the user to check the MD5 hash of the response data.</p></div>
<aclass="sectionlink"href="#MD5Hex_Assertion_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-true">Name</div><divclass="description req-true">Descriptive name for this element that is shown in the tree.</div><divclass="required req-true"></div></div>
<divclass="property"><divclass="name req-true">MD5 sum</div><divclass="description req-true">32 hex digits representing the MD5 hash (case not significant)</div><divclass="required req-true">Yes</div></div>
<divclass="component"><h2id="HTML_Assertion">HTML Assertion<aclass="sectionlink"href="#HTML_Assertion"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/assertion/HTMLAssertion.png"><imgsrc="../images/screenshots/assertion/HTMLAssertion.png"width="464"height="384"alt="Screenshot for HTML Assertion"></a></div>
<divclass="description"><p>The HTML Assertion allows the user to check the HTML syntax of the response data using JTidy.</p></div>
<aclass="sectionlink"href="#HTML_Assertion_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-true">Name</div><divclass="description req-true">Descriptive name for this element that is shown in the tree.</div><divclass="required req-true"></div></div>
<divclass="property"><divclass="name req-true">Format</div><divclass="description req-true">HTML, XHTML or XML</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Errors only</div><divclass="description req-true">Only take note of errors?</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Error threshold</div><divclass="description req-true">Number of errors allowed before classing the response as failed</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Warning threshold</div><divclass="description req-true">Number of warnings allowed before classing the response as failed</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-false">Filename</div><divclass="description req-false">Name of file to which report is written</div><divclass="required req-false">No</div></div>
<divclass="component"><h2id="XPath_Assertion">XPath Assertion<aclass="sectionlink"href="#XPath_Assertion"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/xpath_assertion.png"><imgsrc="../images/screenshots/xpath_assertion.png"width="800"height="317"alt="Screenshot for XPath Assertion"></a></div>
<divclass="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 "/" will match any well-formed
document, and is the default XPath Expression.
The assertion also supports boolean expressions, such as "count(//*error)=2".
See <ahref="http://www.w3.org/TR/xpath">http://www.w3.org/TR/xpath</a> for more information
<aclass="sectionlink"href="#XPath_Assertion_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-false">Name</div><divclass="description req-false">Descriptive name for this element that is shown in the tree.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Use Tidy (tolerant parser)</div><divclass="description req-true">Use Tidy, i.e. be tolerant of XML/HTML errors</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-false">Quiet</div><divclass="description req-false">Sets the Tidy Quiet flag</div><divclass="required req-false">If Tidy is selected</div></div>
<divclass="property"><divclass="name req-false">Report Errors</div><divclass="description req-false">If a Tidy error occurs, then set the Assertion accordingly</div><divclass="required req-false">If Tidy is selected</div></div>
<divclass="property"><divclass="name req-false">Show warnings</div><divclass="description req-false">Sets the Tidy showWarnings option</div><divclass="required req-false">If Tidy is selected</div></div>
<divclass="property"><divclass="name req-false">Use Namespaces</div><divclass="description req-false">Should namespaces be honoured?</div><divclass="required req-false">If Tidy is not selected</div></div>
<divclass="property"><divclass="name req-false">Validate XML</div><divclass="description req-false">Check the document against its schema.</div><divclass="required req-false">If Tidy is not selected</div></div>
<divclass="property"><divclass="name req-false">Ignore Whitespace</div><divclass="description req-false">Ignore Element Whitespace.</div><divclass="required req-false">If Tidy is not selected</div></div>
<divclass="property"><divclass="name req-false">Fetch External DTDs</div><divclass="description req-false">If selected, external DTDs are fetched.</div><divclass="required req-false">If Tidy is not selected</div></div>
<divclass="property"><divclass="name req-true">XPath Assertion</div><divclass="description req-true">XPath to match in the document.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-false">True if nothing matches</div><divclass="description req-false">True if a XPath expression is not matched</div><divclass="required req-false">No</div></div>
</div>
<divclass="clear"></div><divclass="note">
The non-tolerant parser can be quite slow, as it may need to download the DTD etc.
</div><divclass="clear"></div>
<divclass="clear"></div><divclass="note">
As a work-round for namespace limitations of the Xalan XPath parser implementation on which JMeter is based,
you can provide a Properties file which contains mappings for the namespace prefixes:
<divclass="component"><h2id="XML_Schema_Assertion">XML Schema Assertion<aclass="sectionlink"href="#XML_Schema_Assertion"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/assertion/XMLSchemaAssertion.png"><imgsrc="../images/screenshots/assertion/XMLSchemaAssertion.png"width="472"height="132"alt="Screenshot for XML Schema Assertion"></a></div>
<divclass="description"><p>The XML Schema Assertion allows the user to validate a response against an XML Schema.</p></div>
<aclass="sectionlink"href="#XML_Schema_Assertion_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-true">Name</div><divclass="description req-true">Descriptive name for this element that is shown in the tree.</div><divclass="required req-true"></div></div>
<divclass="property"><divclass="name req-true">File Name</div><divclass="description req-true">Specify XML Schema File Name</div><divclass="required req-true">Yes</div></div>
<divclass="component"><h2id="BSF_Assertion">BSF Assertion<aclass="sectionlink"href="#BSF_Assertion"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/bsf_assertion.png"><imgsrc="../images/screenshots/bsf_assertion.png"width="847"height="634"alt="Screenshot for BSF Assertion"></a></div>
<divclass="description">
<p>
The BSF Assertion allows BSF script code to be used to check the status of the previous sample.
<aclass="sectionlink"href="#BSF_Assertion_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-false">Name</div><divclass="description req-false">Descriptive name for this element that is shown in the tree.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Language</div><divclass="description req-true">The BSF language to be used</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-false">Parameters</div><divclass="description req-false">Parameters to pass to the script.
The parameters are stored in the following variables:
<ul>
<li>Parameters - string containing the parameters as a single variable</li>
<li>args - String array containing parameters, split on white-space</li>
<divclass="property"><divclass="name req-false">Script file</div><divclass="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 "user.dir" System property</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Script</div><divclass="description req-true">The script to run.</div><divclass="required req-true">Yes (unless script file is provided)</div></div>
</div>
<p>
The script (or file) is processed using the BSFEngine.exec() method, which does not return a value.
</p>
<p>The following variables are set up for use by the script:</p>
<ul>
<li>log - (Logger) - can be used to write to the log file</li>
<li>Label - the String Label</li>
<li>Filename - the script file name (if any)</li>
<li>Parameters - the parameters (as a String)</li>
<li>args[] - the parameters as a String array (split on whitespace)</li>
<li>ctx - (<ahref="../api/org/apache/jmeter/threads/JMeterContext.html">JMeterContext</a>) - gives access to the context</li>
<divclass="component"><h2id="Compare_Assertion">Compare Assertion<aclass="sectionlink"href="#Compare_Assertion"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/assertion/compare.png"><imgsrc="../images/screenshots/assertion/compare.png"width="292"height="296"alt="Screenshot for Compare Assertion"></a></div>
<divclass="description">
<divclass="clear"></div><divclass="note">
Compare Assertion 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
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 <ahref="../usermanual/component_reference.html#Comparison_Assertion_Visualizer">Comparison Assertion Visualizer</a>.
<aclass="sectionlink"href="#Compare_Assertion_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-false">Name</div><divclass="description req-false">Descriptive name for this element that is shown in the tree.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Compare Content</div><divclass="description req-true">Whether or not to compare the content (response data)</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Compare Time</div><divclass="description req-true">If the value is >=0, then check if the response time difference is no greater than the value.
I.e. if the value is 0, then the response times must be exactly equal.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-false">Comparison Filters</div><divclass="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: "Time: \d\d:\d\d:\d\d" and replaced with a dummy fixed time "Time: HH:MM:SS".
<divclass="component"><h2id="SMIME_Assertion">SMIME Assertion<aclass="sectionlink"href="#SMIME_Assertion"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/assertion/smime.png"><imgsrc="../images/screenshots/assertion/smime.png"width="471"height="428"alt="Screenshot for SMIME Assertion"></a></div>
<divclass="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 JMETER_HOME/lib :<br>
<ul>
<li>bcmail-xxx.jar (BouncyCastle SMIME/CMS)</li>
<li>bcprov-xxx.jar (BouncyCastle Provider)</li>
</ul>
These need to be <ahref="http://www.bouncycastle.org/latest_releases.html">downloaded from BouncyCastle.</a>
<p>
If using the <ahref="../usermanual/component_reference.html#Mail_Reader_Sampler">Mail Reader Sampler</a>,
please ensure that you select "Store the message using MIME (raw)" otherwise the Assertion won't be able to process the message correctly.
<aclass="sectionlink"href="#SMIME_Assertion_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-false">Name</div><divclass="description req-false">Descriptive name for this element that is shown in the tree.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Verify Signature</div><divclass="description req-true">If selected, the asertion will verify if it is a valid signature according to the parameters defined in the Signer Certificate box.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Message not signed</div><divclass="description req-true">Whether or not to expect a signature in the message</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Signer Cerificate</div><divclass="description req-true">"No Check" means that it wil not perform signature verification. "Check values" is used to verify the signature against the inputs provided. And "Certificate file" will perform the verification against a specific certificate file.</div><divclass="required req-true">Yes</div></div>
</div><divclass="section"><h1id="timers">18.6 Timers<aclass="sectionlink"href="#timers"title="Link to here">¶</a></h1>
<divclass="description">
<br>
<p>
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 <ahref="../usermanual/component_reference.html#Test_Action">Test Action</a> Sampler.
</p>
</div>
<divclass="component"><h2id="Constant_Timer">Constant Timer<aclass="sectionlink"href="#Constant_Timer"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/timers/constant_timer.png"><imgsrc="../images/screenshots/timers/constant_timer.png"width="372"height="100"alt="Screenshot for Constant Timer"></a></div>
<divclass="description">
<p>If you want to have each thread pause for the same amount of time between
<aclass="sectionlink"href="#Constant_Timer_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-false">Name</div><divclass="description req-false">Descriptive name for this timer that is shown in the tree.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Thread Delay</div><divclass="description req-true">Number of milliseconds to pause.</div><divclass="required req-true">Yes</div></div>
<divclass="component"><h2id="Gaussian_Random_Timer">Gaussian Random Timer<aclass="sectionlink"href="#Gaussian_Random_Timer"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/timers/gauss_random_timer.png"><imgsrc="../images/screenshots/timers/gauss_random_timer.png"width="372"height="156"alt="Screenshot for Gaussian Random Timer"></a></div>
<aclass="sectionlink"href="#Gaussian_Random_Timer_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-false">Name</div><divclass="description req-false">Descriptive name for this timer that is shown in the tree</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Deviation</div><divclass="description req-true">Deviation in milliseconds.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Constant Delay Offset</div><divclass="description req-true">Number of milliseconds to pause in addition
to the random delay.</div><divclass="required req-true">Yes</div></div>
<divclass="component"><h2id="Uniform_Random_Timer">Uniform Random Timer<aclass="sectionlink"href="#Uniform_Random_Timer"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/timers/uniform_random_timer.png"><imgsrc="../images/screenshots/timers/uniform_random_timer.png"width="372"height="157"alt="Screenshot for Uniform Random Timer"></a></div>
<aclass="sectionlink"href="#Uniform_Random_Timer_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-false">Name</div><divclass="description req-false">Descriptive name for this timer that is shown in the tree. </div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Random Delay Maximum</div><divclass="description req-true">Maxium random number of milliseconds to
<divclass="component"><h2id="Constant_Throughput_Timer">Constant Throughput Timer<aclass="sectionlink"href="#Constant_Throughput_Timer"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/timers/constant_throughput_timer.png"><imgsrc="../images/screenshots/timers/constant_throughput_timer.png"width="636"height="146"alt="Screenshot for Constant Throughput Timer"></a></div>
<divclass="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>
<aclass="sectionlink"href="#Constant_Throughput_Timer_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-false">Name</div><divclass="description req-false">Descriptive name for this timer that is shown in the tree. </div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Target Throughput</div><divclass="description req-true">Throughput we want the timer to try to generate.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Calculate Throughput based on</div><divclass="description req-true">
<ul>
<li>this thread only - each thread will try to maintain the target throughput. The overall throughput will be proportional to the number of active threads.</li>
<li>all active threads in current thread group - 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>all active threads - 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>all active threads in current thread group (shared) - as above, but each thread is delayed based on when any thread in the group last ran.</li>
<li>all active threads (shared) - as above; each thread is delayed based on when any thread last ran.</li>
<divclass="component"><h2id="Synchronizing_Timer">Synchronizing Timer<aclass="sectionlink"href="#Synchronizing_Timer"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/timers/sync_timer.png"><imgsrc="../images/screenshots/timers/sync_timer.png"width="415"height="125"alt="Screenshot for Synchronizing Timer"></a></div>
<aclass="sectionlink"href="#Synchronizing_Timer_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-false">Name</div><divclass="description req-false">Descriptive name for this timer that is shown in the tree. </div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Number of Simultaneous Users to Group by</div><divclass="description req-true">Number of threads to release at once. Setting it to 0 is equivalent to setting it to Number of threads in Thread Group.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-false">Timeout in milliseconds</div><divclass="description req-false">If set to 0, Timer will wait for the number of threads to reach the value in "Number of Simultaneous Users to Group", if superior to 0, then timer will wait at max "Timeout in milliseconds" if number of Threads does not reach if ater the timeout interval the number of users waiting is not reached, timer will stop waiting. Defaults to 0</div><divclass="required req-false">No</div></div>
</div>
<divclass="clear"></div><divclass="note">
If timeout in milliseconds is set to 0 and number of threads never reaches "Number of Simultaneous Users to Group by" 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><divclass="clear"></div>
<divclass="clear"></div><divclass="note">
Synchronizing timer blocks only within one JVM, so if using Distributed testing ensure you never set "Number of Simultaneous Users to Group by" to a value superior to the number of users
of its containing Thread group considering 1 injector only.
<divclass="component"><h2id="BeanShell_Timer">BeanShell Timer<aclass="sectionlink"href="#BeanShell_Timer"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/timers/beanshell_timer.png"><imgsrc="../images/screenshots/timers/beanshell_timer.png"width="846"height="636"alt="Screenshot for BeanShell Timer"></a></div>
<aclass="sectionlink"href="#BeanShell_Timer_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-false">Name</div><divclass="description req-false">Descriptive name for this element that is shown in the tree.
The name is stored in the script variable Label</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Reset bsh.Interpreter before each call</div><divclass="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 <ahref="best-practices#bsh_scripting">Best Practices - BeanShell scripting</a>.
<li>props - (JMeterProperties - class java.util.Properties) - e.g. props.get("START.HMS"); props.put("PROP1","1234");</li>
<li>prev - (<ahref="../api/org/apache/jmeter/samplers/SampleResult.html">SampleResult</a>) - gives access to the previous SampleResult (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 <b>beanshell.timer.init</b> 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>
<divclass="component"><h2id="BSF_Timer">BSF Timer<aclass="sectionlink"href="#BSF_Timer"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/timers/bsf_timer.png"><imgsrc="../images/screenshots/timers/bsf_timer.png"width="844"height="636"alt="Screenshot for BSF Timer"></a></div>
<divclass="description">
<p>
The BSF Timer can be used to generate a delay using a BSF scripting language.
</p>
</div>
<divclass="properties"><h3id="BSF_Timer_parms1">
Parameters
<aclass="sectionlink"href="#BSF_Timer_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-false">Name</div><divclass="description req-false">Descriptive name for this element that is shown in the tree.</div><divclass="required req-false">No</div></div>
<divclass="component"><h2id="Poisson_Random_Timer">Poisson Random Timer<aclass="sectionlink"href="#Poisson_Random_Timer"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/timers/poisson_random_timer.png"><imgsrc="../images/screenshots/timers/poisson_random_timer.png"width="341"height="182"alt="Screenshot for Poisson Random Timer"></a></div>
<aclass="sectionlink"href="#Poisson_Random_Timer_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-false">Name</div><divclass="description req-false">Descriptive name for this timer that is shown in the tree</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Lambda</div><divclass="description req-true">Lambda value in milliseconds.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Constant Delay Offset</div><divclass="description req-true">Number of milliseconds to pause in addition
to the random delay.</div><divclass="required req-true">Yes</div></div>
</div><divclass="section"><h1id="preprocessors">18.7 Pre Processors<aclass="sectionlink"href="#preprocessors"title="Link to here">¶</a></h1>
<divclass="description">
<br>
Preprocessors are used to modify the Samplers in their scope.
<br>
</div>
<divclass="component"><h2id="HTML_Link_Parser">HTML Link Parser<aclass="sectionlink"href="#HTML_Link_Parser"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/html_link_parser.png"><imgsrc="../images/screenshots/html_link_parser.png"width="239"height="113"alt="Screenshot for HTML Link Parser"></a></div>
<divclass="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>
<divclass="clear"></div><divclass="note">
Matches are performed using protocol, host, path and parameter names.
The target sampler cannot contain parameters that are not in the response links.
</div><divclass="clear"></div>
<divclass="clear"></div><divclass="note">
If using distributed testing, ensure you switch mode (see jmeter.properties) so that it's not a stripping one, see <ahref="http://bz.apache.org/bugzilla/show_bug.cgi?id=56376">
Bug
56376</a>
</div><divclass="clear"></div>
<divclass="example"><divclass="title">Spidering Example<aclass="sectionlink"href="#spider_example"title="Link to here">¶</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 <ahref="../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 ".*", 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.
<aclass="sectionlink"href="#HTTP_URL_Re-writing_Modifier_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-false">Name</div><divclass="description req-false">Descriptive name given to this element in the test tree.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Session Argument Name</div><divclass="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><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-false">Path Extension</div><divclass="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><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Do not use equals in path extension</div><divclass="description req-false">Some web apps rewrite URLs without using an "=" sign between the parameter name and value (such as Intershop Enfinity).</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Do not use questionmark in path extension</div><divclass="description req-false">Prevents the query string to end up in the path extension (such as Intershop Enfinity).</div><divclass="required req-false">No</div></div>
If using distributed testing, ensure you switch mode (see jmeter.properties) so that it's not a stripping one, see <ahref="http://bz.apache.org/bugzilla/show_bug.cgi?id=56376">
</div><divclass="screenshot"><ahref="../images/screenshots/parameter_mask.png"><imgsrc="../images/screenshots/parameter_mask.png"width="624"height="209"alt="Screenshot for HTML Parameter Mask (DEPRECATED)"></a></div>
<divclass="description"><p>The HTML Parameter Mask is used to generate unique values for HTML arguments. By
specifying the name of the parameter, a value prefix and suffix, and counter parameters, this
modifier will generate values of the form "<spanclass="code">name=prefixcountersuffix</span>". Any HTTP
Request that it modifies, it will replace any parameter with the same name or add the appropriate
parameter to the requests list of arguments.</p>
<divclass="clear"></div><divclass="note">The value of the argument in your HTTP Request must be a '*' in order for the HTML Parameter Mask
Modifier to replace it.</div><divclass="clear"></div>
<p>As an example, the username for a login script could be modified to send a series of values
<aclass="sectionlink"href="#HTML_Parameter_Mask_(DEPRECATED)_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-false">Name</div><divclass="description req-false">Descriptive name given to this element in the test tree.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Name (second appearing)</div><divclass="description req-true">The name of the parameter to
modify or add to the HTTP Request.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-false">ID Prefix</div><divclass="description req-false">A string value to prefix to every generated value.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Lower Bound</div><divclass="description req-true">A number value to start the counter at.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Upper Bound</div><divclass="description req-true">A number value to end the counter, at which point it restarts
with the Lower Bound value.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Increment</div><divclass="description req-true">Value to increment the counter by each time through.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-false">ID Suffix</div><divclass="description req-false">A string value to add as suffix to every generated vaue.</div><divclass="required req-false">No</div></div>
<divclass="component"><h2id="User_Parameters">User Parameters<aclass="sectionlink"href="#User_Parameters"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/user_params.png"><imgsrc="../images/screenshots/user_params.png"width="703"height="303"alt="Screenshot for User Parameters"></a></div>
<divclass="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>Values can be accessed in any test component in the same thread group, using the <ahref="functions.html">function syntax</a>: ${variable}.</p>
<p>See also the <ahref="../usermanual/component_reference.html#CSV_Data_Set_Config">CSV Data Set Config</a> element, which is more suitable for large numbers of parameters</p>
<aclass="sectionlink"href="#User_Parameters_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-true">Name</div><divclass="description req-true">Descriptive name for this element that is shown in the tree.</div><divclass="required req-true"></div></div>
<divclass="property"><divclass="name req-true">Update Once Per Iteration</div><divclass="description req-true">A flag to indicate whether the User Paramters 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 <ahref="test_plan.html#scoping_rules">scope</a>.</div><divclass="required req-true">Yes</div></div>
<divclass="component"><h2id="BeanShell_PreProcessor">BeanShell PreProcessor<aclass="sectionlink"href="#BeanShell_PreProcessor"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/beanshell_preprocessor.png"><imgsrc="../images/screenshots/beanshell_preprocessor.png"width="845"height="633"alt="Screenshot for BeanShell PreProcessor"></a></div>
<divclass="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 <ahref="http://www.beanshell.org/">BeanShell website.</a></b>
<aclass="sectionlink"href="#BeanShell_PreProcessor_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-false">Name</div><divclass="description req-false">Descriptive name for this element that is shown in the tree.
The name is stored in the script variable Label</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Reset bsh.Interpreter before each call</div><divclass="description req-true">
<divclass="property"><divclass="name req-false">Script file</div><divclass="description req-false">A file containing the BeanShell script to run.
The file name is stored in the script variable FileName</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Script</div><divclass="description req-true">The BeanShell script. The return value is ignored.</div><divclass="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>
<p>For details of all the methods available on each of the above variables, please check the Javadoc</p>
<p>If the property <b>beanshell.preprocessor.init</b> 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>
<divclass="go-top"><ahref="#">^</a></div></div>
<divclass="component"><h2id="BSF_PreProcessor">BSF PreProcessor<aclass="sectionlink"href="#BSF_PreProcessor"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/bsf_preprocessor.png"><imgsrc="../images/screenshots/bsf_preprocessor.png"width="844"height="632"alt="Screenshot for BSF PreProcessor"></a></div>
<divclass="description">
<p>
The BSF PreProcessor allows BSF script code to be applied before taking a sample.
<aclass="sectionlink"href="#BSF_PreProcessor_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-false">Name</div><divclass="description req-false">Descriptive name for this element that is shown in the tree.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Language</div><divclass="description req-true">The BSF language to be used</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-false">Parameters</div><divclass="description req-false">Parameters to pass to the script.
The parameters are stored in the following variables:
<ul>
<li>Parameters - string containing the parameters as a single variable</li>
<li>args - String array containing parameters, split on white-space</li>
<divclass="property"><divclass="name req-false">Script file</div><divclass="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 "user.dir" System property</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Script</div><divclass="description req-true">The script to run.</div><divclass="required req-true">Yes (unless script file is provided)</div></div>
<divclass="component"><h2id="JSR223_PreProcessor">JSR223 PreProcessor<aclass="sectionlink"href="#JSR223_PreProcessor"title="Link to here">¶</a></h2>
<divclass="description">
<p>
The JSR223 PreProcessor allows JSR223 script code to be applied before taking a sample.
For details, see <ahref="../usermanual/component_reference.html#BSF_PreProcessor">BSF PreProcessor</a>.
<divclass="component"><h2id="JDBC_PreProcessor">JDBC PreProcessor<aclass="sectionlink"href="#JDBC_PreProcessor"title="Link to here">¶</a></h2>
<divclass="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 <ahref="../usermanual/component_reference.html#JDBC_Request">JDBC Request</a>.
</p>
<p>
See the following Test plan:
</p>
<divclass="links"><divclass="title">See also:</div><ulclass="links"><li><ahref="../demos/JDBC-Pre-Post-Processor.jmx">Test Plan using JDBC Pre/Post Processor</a></li></ul></div>
<p>
In the linked test plan,"Create Price Cut-Off" JDBC PreProcessor calls a stored procedure to create a Price Cut-Off in Database,
this one will be used by "Calculate Price cut off".
<divclass="component"><h2id="RegEx_User_Parameters">RegEx User Parameters<aclass="sectionlink"href="#RegEx_User_Parameters"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/regex_user_params.png"><imgsrc="../images/screenshots/regex_user_params.png"width="727"height="138"alt="Screenshot for RegEx User Parameters"></a></div>
<divclass="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>
<aclass="sectionlink"href="#RegEx_User_Parameters_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-true">Name</div><divclass="description req-true">Descriptive name for this element that is shown in the tree.</div><divclass="required req-true"></div></div>
<divclass="property"><divclass="name req-true">Regular Expression Reference Name</div><divclass="description req-true">Name of a reference to a regular expression</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Parameter names regexp group number</div><divclass="description req-true">Group number of regular expression used to extract parameter names</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Parameter values regex group number</div><divclass="description req-true">Group number of regular expression used to extract parameter values</div><divclass="required req-true">Yes</div></div>
</div>
<p>Example:</p>
<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>
<p>1. - Create Post Processor Regular Expression for first HTTP Request</p>
<ul>
<li>refName - set name of a regular expression Ex. (listParams)</li>
<li>regular expression - expression that will extract input names and input values attributes
<br>
Ex: input name="([^"]+?)" value="([^"]+?)"</li>
<li>template would be empty</li>
<li>match nr - -1 (in order to iterate through all the possible matches)</li>
</ul>
<p>2. - Create Pre Processor RegEx User Parameters for second HTTP Request</p>
<ul>
<li>refName - set the same reference name of a regular expression, would be listParams in our example</li>
<li>parameter names group number - group number of regular expression for parameter names, would be 1 in our example</li>
<li>parameter values group number - group number of regular expression for parameter values, would be 2 in our example</li>
</ul>
<p>See also the <ahref="../usermanual/component_reference.html#Regular_Expression_Extractor">Regular Expression Extractor</a> element, which is used to extract parametes names and values</p>
<divclass="go-top"><ahref="#">^</a></div></div>
<divclass="links"><divclass="title">See also:</div><ulclass="links"><li><ahref="../demos/RegEx-User-Parameters.jmx">Test Plan showing how to use RegEx User Parameters</a></li></ul></div>
<ahref="#">^</a>
</div><divclass="section"><h1id="postprocessors">18.8 Post-Processors<aclass="sectionlink"href="#postprocessors"title="Link to here">¶</a></h1>
<divclass="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>
<p>
Note: Unless documented otherwise, Post-Processors are not applied to sub-samples (child samples) -
only to the parent sample.
In the case of BSF and BeanShell post-processors, the script can retrieve sub-samples using the method
<spanclass="code">prev.getSubResults()</span> which returns an array of SampleResults.
The array will be empty if there are none.
</p>
<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 JMeterThread.last_sample_ok is set to "true" or "false"
after all Assertions have been run.
</p>
</div>
<divclass="component"><h2id="Regular_Expression_Extractor">Regular Expression Extractor<aclass="sectionlink"href="#Regular_Expression_Extractor"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/regex_extractor.png"><imgsrc="../images/screenshots/regex_extractor.png"width="790"height="276"alt="Screenshot for Regular Expression Extractor"></a></div>
<divclass="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>
<aclass="sectionlink"href="#Regular_Expression_Extractor_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-true">Name</div><divclass="description req-true">Descriptive name for this element that is shown in the tree.</div><divclass="required req-true"></div></div>
<divclass="property"><divclass="name req-true">Field to check</div><divclass="description req-true">
The following fields can be checked:
<ul>
<li>Body - the body of the response, e.g. the content of a web-page (excluding headers)</li>
<li>Body (unescaped) - 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.
<divclass="clear"></div><divclass="note">Note that this option highly impacts performances, so use it only when absolutely necessary and be aware of its impacts</div><divclass="clear"></div>
</li>
<li>Body as a Document - the extract text from various type of documents via Apache Tika (see <ahref="../usermanual/component_reference.html#View_Results_Tree">View Results Tree</a> Document view section).
<divclass="clear"></div><divclass="note">Note that the Body as a Document option can impact performances, so ensure it is Ok for your test</div><divclass="clear"></div>
</li>
<li>Request Headers - may not be present for non-HTTP samples</li>
<li>Response Headers - may not be present for non-HTTP samples</li>
<li>URL</li>
<li>Response Code - e.g. 200</li>
<li>Response Message - e.g. OK</li>
</ul>
Headers can be useful for HTTP samples; it may not be present for other sample types.
<divclass="property"><divclass="name req-true">Reference Name</div><divclass="description req-true">The name of the JMeter variable in which to store the result. Also note that each group is stored as [refname]_g#, where [refname] is the string you entered as the reference name, and # is the group number, where group 0 is the entire match, group 1 is the match from the first set of parentheses, etc.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Regular Expression</div><divclass="description req-true">The regular expression used to parse the response data.
This must contain at least one set of parentheses "()" to capture a portion of the string, unless using the group $0$.
Do not enclose the expression in / / - unless of course you want to match these characters as well.
<divclass="property"><divclass="name req-true">Template</div><divclass="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: '$1$' to refer to
group 1, '$2$' to refer to group 2, etc. $0$ refers to whatever the entire expression matches.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Match No.</div><divclass="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 nth match.</li>
<li> Negative numbers are used in conjunction with the ForEach controller - see below.</li>
<divclass="component"><h2id="CSS/JQuery_Extractor">CSS/JQuery Extractor<aclass="sectionlink"href="#CSS/JQuery_Extractor"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/css_extractor_attr.png"><imgsrc="../images/screenshots/css_extractor_attr.png"width="826"height="276"alt="Screenshot for CSS/JQuery Extractor"></a></div>
<divclass="description"><p>Allows the user to extract values from a server response using a CSS/JQuery selector like 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>
<aclass="sectionlink"href="#CSS/JQuery_Extractor_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-true">Name</div><divclass="description req-true">Descriptive name for this element that is shown in the tree.</div><divclass="required req-true"></div></div>
<divclass="property"><divclass="name req-true">Reference Name</div><divclass="description req-true">The name of the JMeter variable in which to store the result.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">CSS/JQuery expression</div><divclass="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>E[foo] an E element with a "foo" attribute</li>
<li>ancestor child:child elements that descend from ancestor, e.g. .body p finds p elements anywhere under a block with class "body"</li>
<li>:lt(n): find elements whose sibling index (i.e. its position in the DOM tree relative to its parent) is less than n; e.g. td:lt(3)</li>
<li>:contains(text): find elements that contain the given text. The search is case-insensitive; e.g. p:contains(jsoup)</li>
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 <ahref="http://jsoup.org/apidocs/org/jsoup/nodes/Node.html#attr%28java.lang.String%29">Element#attr(name)</a> function for JSoup if an atttribute is set.<br>
<figure><ahref="../images/screenshots/css_extractor_attr.png"><imgsrc="../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 <ahref="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><ahref="../images/screenshots/css_extractor_noattr.png"><imgsrc="../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>
<divclass="property"><divclass="name req-true">Match No.</div><divclass="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 N means to select the nth match.</li>
<li> Negative numbers are used in conjunction with the ForEach controller - see below.</li>
<divclass="component"><h2id="XPath_Extractor">XPath Extractor<aclass="sectionlink"href="#XPath_Extractor"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/xpath_extractor.png"><imgsrc="../images/screenshots/xpath_extractor.png"width="729"height="317"alt="Screenshot for XPath Extractor"></a></div>
<divclass="description">This test element allows the user to extract value(s) from
structured response - XML or (X)HTML - using XPath
<aclass="sectionlink"href="#XPath_Extractor_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-false">Name</div><divclass="description req-false">Descriptive name for this element that is shown in the tree.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Use Tidy (tolerant parser)</div><divclass="description req-true">If checked use Tidy to parse HTML response into XHTML.
<ul>
<li>"Use Tidy" should be checked on for HTML response. Such response is converted to valid XHTML (XML compatible HTML) using Tidy</li>
<li>"Use Tidy" should be unchecked for both XHTML or XML response (for example RSS)</li>
<divclass="property"><divclass="name req-false">Quiet</div><divclass="description req-false">Sets the Tidy Quiet flag</div><divclass="required req-false">If Tidy is selected</div></div>
<divclass="property"><divclass="name req-false">Report Errors</div><divclass="description req-false">If a Tidy error occurs, then set the Assertion accordingly</div><divclass="required req-false">If Tidy is selected</div></div>
<divclass="property"><divclass="name req-false">Show warnings</div><divclass="description req-false">Sets the Tidy showWarnings option</div><divclass="required req-false">If Tidy is selected</div></div>
If checked, then the XML parser will use namespace resolution.
Note that currently only namespaces declared on the root element will be recognised.
A later version of JMeter may support user-definition of additional workspace names.
Meanwhile, a work-round is to replace:
<br>
//mynamespace:tagname
<br>
by
<br>
//*[local-name()='tagname' and namespace-uri()='uri-for-namespace']
<br>
where "uri-for-namespace" is the uri for the "mynamespace" namespace.
(not applicable if Tidy is selected)
</div><divclass="required req-false">If Tidy is not selected</div></div>
<divclass="property"><divclass="name req-false">Validate XML</div><divclass="description req-false">Check the document against its schema.</div><divclass="required req-false">If Tidy is not selected</div></div>
<divclass="property"><divclass="name req-false">Ignore Whitespace</div><divclass="description req-false">Ignore Element Whitespace.</div><divclass="required req-false">If Tidy is not selected</div></div>
<divclass="property"><divclass="name req-false">Fetch External DTDs</div><divclass="description req-false">If selected, external DTDs are fetched.</div><divclass="required req-false">If Tidy is not selected</div></div>
<divclass="property"><divclass="name req-true">Return entire XPath fragment instead of text content?</div><divclass="description req-true">
If selected, the fragment will be returned rather than the text content.<br>
For example //title would return "<title>Apache JMeter</title>" rather than "Apache JMeter".<br>
In this case, //title/text() would return "Apache JMeter".
<divclass="property"><divclass="name req-true">Reference Name</div><divclass="description req-true">The name of the JMeter variable in which to store the result.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">XPath Query</div><divclass="description req-true">Element query in XPath language. Can return more than one match.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Default Value</div><divclass="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><divclass="required req-true"></div></div>
</div>
<p>To allow for use in a ForEach Controller, the following variables are set on return:</p>
<ul>
<li>refName - set to first (or only) match; if no match, then set to default</li>
<li>refName_matchNr - set to number of matches (may be 0)</li>
<li>refName_n - n=1,2,3 etc. Set to the 1st, 2nd 3rd match etc.
</li>
</ul>
<p>Note: The next refName_n variable is set to null - e.g. if there are 2 matches, then refName_3 is set to null,
and if there are no matches, then refName_1 is set to null.
</p>
<p>XPath is query language targeted primarily for XSLT transformations. However it is usefull as generic query language for structured data too. See
<ahref="http://www.topxml.com/xsl/xpathref.asp">XPath Reference</a> or <ahref="http://www.w3.org/TR/xpath">XPath specification</a> for more information. Here are few examples:
</p>
<dl>
<dt>/html/head/title</dt>
<dd>extracts title element from HTML response</dd>
<dd>extracts value attribute of option element that match text 'Czech Republic'
inside of select element with name attribute 'country' inside of
form with name attribute 'countryForm'</dd>
</dl>
<divclass="clear"></div><divclass="note">When "Use Tidy" 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) <spanclass="code">ul/font/li</span> becomes correct <spanclass="code">ul/li/font</span></li>
</ul>
See <ahref="http://jtidy.sf.net">Tidy homepage</a> for more information.
</div><divclass="clear"></div>
<divclass="go-top"><ahref="#">^</a></div></div>
<divclass="component"><h2id="Result_Status_Action_Handler">Result Status Action Handler<aclass="sectionlink"href="#Result_Status_Action_Handler"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/resultstatusactionhandler.png"><imgsrc="../images/screenshots/resultstatusactionhandler.png"width="613"height="133"alt="Screenshot for Result Status Action Handler"></a></div>
<divclass="description">This test element allows the user to stop the thread or the whole test if the relevant sampler failed.
<aclass="sectionlink"href="#Result_Status_Action_Handler_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-true">Name</div><divclass="description req-true">Descriptive name for this element that is shown in the tree.</div><divclass="required req-true"></div></div>
<divclass="property"><divclass="name req-true">Action to be taken after a Sampler error</div><divclass="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>Continue - ignore the error and continue with the test</li>
<li>Start next thread loop - does not execute samplers following the sampler in error for the current iteration and restarts the loop on next iteration</li>
<li>Stop Thread - current thread exits</li>
<li>Stop Test - the entire test is stopped at the end of any current samples.</li>
<li>Stop Test Now - the entire test is stopped abruptly. Any current samplers are interrupted if possible.</li>
</ul>
</div><divclass="required req-true">
No
</div></div>
</div>
<divclass="go-top"><ahref="#">^</a></div></div>
<divclass="component"><h2id="BeanShell_PostProcessor">BeanShell PostProcessor<aclass="sectionlink"href="#BeanShell_PostProcessor"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/beanshell_postprocessor.png"><imgsrc="../images/screenshots/beanshell_postprocessor.png"width="847"height="633"alt="Screenshot for BeanShell PostProcessor"></a></div>
<aclass="sectionlink"href="#BeanShell_PostProcessor_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-false">Name</div><divclass="description req-false">Descriptive name for this element that is shown in the tree.
The name is stored in the script variable Label</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Reset bsh.Interpreter before each call</div><divclass="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 <ahref="best-practices#bsh_scripting">Best Practices - BeanShell scripting</a>.
<divclass="property"><divclass="name req-false">Script file</div><divclass="description req-false">A file containing the BeanShell script to run.
The file name is stored in the script variable FileName</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Script</div><divclass="description req-true">The BeanShell script. The return value is ignored.</div><divclass="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>
<p>For details of all the methods available on each of the above variables, please check the Javadoc</p>
<p>If the property <b>beanshell.postprocessor.init</b> 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>
<divclass="go-top"><ahref="#">^</a></div></div>
<divclass="component"><h2id="BSF_PostProcessor">BSF PostProcessor<aclass="sectionlink"href="#BSF_PostProcessor"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/bsf_postprocessor.png"><imgsrc="../images/screenshots/bsf_postprocessor.png"width="844"height="633"alt="Screenshot for BSF PostProcessor"></a></div>
<divclass="description">
<p>
The BSF PostProcessor allows BSF script code to be applied after taking a sample.
<aclass="sectionlink"href="#BSF_PostProcessor_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-false">Name</div><divclass="description req-false">Descriptive name for this element that is shown in the tree.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Language</div><divclass="description req-true">The BSF language to be used</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-false">Parameters</div><divclass="description req-false">Parameters to pass to the script.
The parameters are stored in the following variables:
<ul>
<li>Parameters - string containing the parameters as a single variable</li>
<li>args - String array containing parameters, split on white-space</li>
<divclass="property"><divclass="name req-false">Script file</div><divclass="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 "user.dir" System property</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Script</div><divclass="description req-true">The script to run.</div><divclass="required req-true">Yes (unless script file is provided)</div></div>
<divclass="component"><h2id="JSR223_PostProcessor">JSR223 PostProcessor<aclass="sectionlink"href="#JSR223_PostProcessor"title="Link to here">¶</a></h2>
<divclass="links"><divclass="title">See also:</div><ulclass="links"><li><ahref="../demos/JDBC-Pre-Post-Processor.jmx">Test Plan using JDBC Pre/Post Processor</a></li></ul></div>
In the linked test plan,"JDBC PostProcessor" JDBC PostProcessor calls a stored procedure to delete from Database the Price Cut-Off that was created by PreProcessor.
</div><divclass="section"><h1id="Miscellaneous_Features">18.9 Miscellaneous Features<aclass="sectionlink"href="#Miscellaneous_Features"title="Link to here">¶</a></h1>
<divclass="description">
<br>
</div>
<divclass="component"><h2id="Test_Plan">Test Plan<aclass="sectionlink"href="#Test_Plan"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/testplan.png"><imgsrc="../images/screenshots/testplan.png"width="560"height="457"alt="Screenshot for Test Plan"></a></div>
<p>Also, an option exists here to instruct JMeter to run the <ahref="../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:
<divclass="component"><h2id="Thread_Group">Thread Group<aclass="sectionlink"href="#Thread_Group"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/threadgroup.png"><imgsrc="../images/screenshots/threadgroup.png"width="583"height="447"alt="Screenshot for Thread Group"></a></div>
<divclass="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 (num 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>
See also <ahref="../usermanual/component_reference.html#tearDown_Thread_Group">tearDown Thread Group</a> and <ahref="../usermanual/component_reference.html#setUp_Thread_Group">setUp Thread Group</a>.
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.
<aclass="sectionlink"href="#Thread_Group_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-true">Name</div><divclass="description req-true">Descriptive name for this element that is shown in the tree.</div><divclass="required req-true"></div></div>
<divclass="property"><divclass="name req-true">Action to be taken after a Sampler error</div><divclass="description req-true">
<li>Continue - ignore the error and continue with the test</li>
<li>Start Next Loop - ignore the error, start next loop and continue with the test</li>
<li>Stop Thread - current thread exits</li>
<li>Stop Test - the entire test is stopped at the end of any current samples.</li>
<li>Stop Test Now - the entire test is stopped abruptly. Any current samplers are interrupted if possible.</li>
</ul>
</div><divclass="required req-true">
No
</div></div>
<divclass="property"><divclass="name req-true">Number of Threads</div><divclass="description req-true">Number of users to simulate.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Ramp-up Period</div><divclass="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><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Loop Count</div><divclass="description req-true">Number of times to perform the test case. Alternatively, "forever" can be selected causing the test to run until manually stopped.</div><divclass="required req-true">Yes, unless forever is selected</div></div>
<divclass="property"><divclass="name req-true">Delay Thread creation until needed</div><divclass="description req-true">
<divclass="property"><divclass="name req-true">Scheduler</div><divclass="description req-true">If selected, enables the scheduler</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-false">Start Time</div><divclass="description req-false">If the scheduler checkbox is selected, one can choose an absolute start time. When you start your test, JMeter will wait until the specified start time to begin testing.
<divclass="property"><divclass="name req-false">End Time</div><divclass="description req-false">If the scheduler checkbox is selected, one can choose an absolute end time. When you start your test, JMeter will wait until the specified start time to begin testing, and it will stop at the specified end time.
Note: the Duration field over-rides this - see below.
<divclass="component"><h2id="WorkBench">WorkBench<aclass="sectionlink"href="#WorkBench"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/workbench.png"><imgsrc="../images/screenshots/workbench.png"width="384"height="103"alt="Screenshot for WorkBench"></a></div>
<divclass="description">
<p>The WorkBench simply provides a place to temporarily store test elements while not in use, for copy/paste purposes, or any other purpose you desire.
When you save your test plan, WorkBench items are not saved with it by default unless you check "Save Workbench" option.
Your WorkBench can be saved independently, if you like (right-click on WorkBench and choose Save).</p>
<p>Certain test elements are only available on the WorkBench:</p>
<ul>
<li><ahref="../usermanual/component_reference.html#HTTP(S)_Test_Script_Recorder">HTTP(S) Test Script Recorder</a></li>
<divclass="component"><h2id="HTTP(S)_Test_Script_Recorder">HTTP(S) Test Script Recorder<aname="HTTP_Proxy_Server">
(was:
HTTP Proxy Server
)
</a><aclass="sectionlink"href="#HTTP(S)_Test_Script_Recorder"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/proxy_control.png"><imgsrc="../images/screenshots/proxy_control.png"width="917"height="622"alt="Screenshot for HTTP(S) Test Script Recorder"></a></div>
<divclass="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 <ahref="https://wiki.apache.org/jmeter/TestRecording210">wiki page</a> to setup correctly JMeter.
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.
(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)
This certificate needs to be installed by the browser in order for it to accept the host certificates generated by JMeter; see <ahref="#install_cert">below</a> for details.
If necessary, you can force JMeter to regenerate the keystore (and the exported certificates - ApacheJMeterTemporaryRootCA[.usr|.crt]) by deleting the keystore file <spanclass="code">proxyserver.jks</span> from the JMeter directory.
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 jmeter.log for secure domains that you need to register certificate for.
<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.
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.
<aclass="sectionlink"href="#HTTP(S)_Test_Script_Recorder_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-false">Name</div><divclass="description req-false">Descriptive name for this element that is shown in the tree.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">Port</div><divclass="description req-true">The port that the HTTP(S) Test Script Recorder listens to. 8080 is the default, but you can change it.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-false">HTTPS Domains</div><divclass="description req-false">List of domain (or host) names for HTTPS. Use this to pre-generate certificates for all servers you wish to record.
<divclass="property"><divclass="name req-true">Target Controller</div><divclass="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><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Grouping</div><divclass="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>Do not group samplers: store all recorded samplers sequentially, without any grouping.</li>
<li>Add separators between groups: add a controller named "--------------" to create a visual separation between the groups. Otherwise the samplers are all stored sequentially.</li>
<li>Put each group in a new controller: create a new <ahref="../usermanual/component_reference.html#Simple_Controller">Simple Controller</a> for each group, and store all samplers for that group in it.</li>
<li>Store 1st sampler of each group only: only the first request in each group will be recorded. The "Follow Redirects" and "Retrieve All Embedded Resources..." flags will be turned on in those samplers.</li>
<li>Put each group in a new transaction controller: create a new <ahref="../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 <b>proxy.pause</b> determines the minimum gap that JMeter needs between requests
<divclass="property"><divclass="name req-true">Add Assertions</div><divclass="description req-true">Add a blank assertion to each sampler?</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Regex Matching</div><divclass="description req-true">Use Regex Matching when replacing variables? If checked replacement will use word boundaries, ie it will only replace word matching values of variable, not part of a word. A word boundary follows Perl5 definition and is equivalent to \b. More information below in the paragraph about "User Defined Variable replacement".</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Type</div><divclass="description req-true">Which type of sampler to generate (the Java default or HTTPClient)</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Redirect Automatically</div><divclass="description req-true">Set Redirect Automatically in the generated samplers?</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Follow Redirects</div><divclass="description req-true">Set Follow Redirects in the generated samplers?<br>
<b>Note:</b> see "Recording and redirects" section below for important information.
<divclass="property"><divclass="name req-true">Use Keep-Alive</div><divclass="description req-true">Set Use Keep-Alive in the generated samplers?</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Retrieve all Embedded Resources</div><divclass="description req-true">Set Retrieve all Embedded Resources in the generated samplers?</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-false">Content Type filter</div><divclass="description req-false">
<divclass="property"><divclass="name req-false">Patterns to Include</div><divclass="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 Include/Exclude fields are <i>recorded</i>. If both Include and Exclude are
<divclass="property"><divclass="name req-false">Patterns to Exclude</div><divclass="description req-false">Regular expressions that are matched against the URL that is sampled.
<b>Any requests that match one or more Exclude pattern are <i>not</i> recorded</b>.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Notify Child Listeners of filtered samplers</div><divclass="description req-false">Notify Child Listeners of filtered samplers
<b>Any response that match one or more Exclude pattern is <i>not</i> delivered to Child Listeners (View Results Tree)</b>.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Start Button</div><divclass="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: "Proxy up and running!".</div><divclass="required req-false">N/A</div></div>
<divclass="property"><divclass="name req-false">Stop Button</div><divclass="description req-false">Stop the proxy server.</div><divclass="required req-false">N/A</div></div>
<divclass="property"><divclass="name req-false">Restart Button</div><divclass="description req-false">Stops and restarts the proxy server. This is
useful when you change/add/delete an include/exclude filter expression.</div><divclass="required req-false">N/A</div></div>
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 <b>"\.html"</b> will <b>not</b> match <b>j.a.o/index.html</b>
<p>If the HTTP(S) Test Script Recorder finds enabled <ahref="../usermanual/component_reference.html#HTTP_Request_Defaults">HTTP Request Defaults</a> directly within the
those in the other HTTP Request Defaults. See <ahref="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 <ahref="../usermanual/component_reference.html#User_Defined_Variables">User Defined Variables</a> (UDV) directly within the
This tells the proxy server to treat values as Regexes (using the perl5 compatible regex matchers provided by ORO).</p>
<p>If "Regex Matching" is selected every variable will be compiled into a perl compatible regex enclosed in
<spanclass="code">\b(</span> and <spanclass="code">)\b</span>. That way each match will start and end at a word boundary.</p>
<divclass="clear"></div><divclass="note">Note that the boundary characters are not part of the matching group, e.g. <spanclass="code">n.*</span> to match <spanclass="code">name</span> out
of <spanclass="code">You can call me 'name'</span>.</div><divclass="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 <spanclass="code">('.*?')</span> to match <spanclass="code">'name'</span> out of <spanclass="code">You can call me 'name'</span>.</p>
<p>If you want to match a whole string only, enclose it in <spanclass="code">(^</span> and <spanclass="code">$)</span>, e.g. <spanclass="code">(^thus$)</span>.
The parens are neccessary, since the normally added boundary characters will prevent <spanclass="code">^</span> and
<p>If you want to match <spanclass="code">/images</span> at the start of a string only, use the value <spanclass="code">(^/images)</span>.
Jakarta ORO also supports zero-width look-ahead, so one can match <spanclass="code">/images/...</span>
but retain the trailing <spanclass="code">/</span> in the output by using <spanclass="code">(^/images(?=/))</span>".</p>
<divclass="clear"></div><divclass="note">
Note that the current version of Jakara ORO does not support look-behind - i.e. <spanclass="code">(?<=...)</span> or <spanclass="code">(?<!...)</span>.
</div><divclass="clear"></div>
<p>Look out for overlapping matchers. For example the value <spanclass="code">.*</span> as a regex in a variable named
<spanclass="code">regex</span> will partly match a previous replaced variable, which will result in something like
<spanclass="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 jmeter.log,
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 "stop" button). Remember to reset
<h4>How can I record the server's responses too?</h4>
<p>Just place a <ahref="../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 <ahref="../usermanual/component_reference.html#Save_Responses_to_a_file">Save Responses to a file</a> Post-Processor which will save the responses to files.
If the server you are testing against uses cookies, remember to add an <ahref="../usermanual/component_reference.html#HTTP_Cookie_Manager">HTTP Cookie Manager</a> to the test plan
<divclass="component"><h2id="HTTP_Mirror_Server">HTTP Mirror Server<aclass="sectionlink"href="#HTTP_Mirror_Server"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/mirrorserver.png"><imgsrc="../images/screenshots/mirrorserver.png"width="671"height="174"alt="Screenshot for HTTP Mirror Server"></a></div>
<aclass="sectionlink"href="#HTTP_Mirror_Server_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-true">Port</div><divclass="description req-true">Port on which Mirror server listens, defaults to 8081.</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-false">Max Number of threads</div><divclass="description req-false">If set to a value > 0, number of threads serving requests will be limited to the configured number, if set to a value <=0
a new thread will be created to serve each incoming request. Defaults to 0</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">Max Queue size</div><divclass="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 0. Defaults to 25</div><divclass="required req-false">No</div></div>
<aclass="sectionlink"href="#HTTP_Mirror_Server_parms2"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-false">X-Sleep</div><divclass="description req-false">Time to sleep in ms before sending response</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">X-SetCookie</div><divclass="description req-false">Cookies to be set on response</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">X-ResponseStatus</div><divclass="description req-false">Response status, see <ahref="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html">HTTP Status responses</a>, example 200 OK, 500 Internal Server Error ....</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">X-ResponseLength</div><divclass="description req-false">Size of response, this trims the response to the requested size if that is less than the total size</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">X-SetHeaders</div><divclass="description req-false">Pipe separated list of headers, example:<br>
<spanclass="code">headerA=valueA|headerB=valueB</span> would set headerA to valueA and headerB to valueB.
<aclass="sectionlink"href="#HTTP_Mirror_Server_parms3"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-false">redirect</div><divclass="description req-false">Generates a 302 (Temporary Redirect) with the provided location.
<divclass="property"><divclass="name req-false">status</div><divclass="description req-false">Overrides the default status return. e.g. ?status=404 Not Found</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-false">v</div><divclass="description req-false">Verbose flag, writes some details to standard output. e.g. first line and redirect location if specified</div><divclass="required req-false">No</div></div>
<divclass="component"><h2id="Property_Display">Property Display<aclass="sectionlink"href="#Property_Display"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/property_display.png"><imgsrc="../images/screenshots/property_display.png"width="804"height="508"alt="Screenshot for Property Display"></a></div>
<aclass="sectionlink"href="#Property_Display_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-false">Name</div><divclass="description req-false">Descriptive name for this element that is shown in the tree.</div><divclass="required req-false">No</div></div>
<divclass="component"><h2id="Debug_Sampler">Debug Sampler<aclass="sectionlink"href="#Debug_Sampler"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/debug_sampler.png"><imgsrc="../images/screenshots/debug_sampler.png"width="431"height="172"alt="Screenshot for Debug Sampler"></a></div>
<aclass="sectionlink"href="#Debug_Sampler_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-false">Name</div><divclass="description req-false">Descriptive name for this element that is shown in the tree.</div><divclass="required req-false">No</div></div>
<divclass="component"><h2id="Debug_PostProcessor">Debug PostProcessor<aclass="sectionlink"href="#Debug_PostProcessor"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/debug_postprocessor.png"><imgsrc="../images/screenshots/debug_postprocessor.png"width="344"height="193"alt="Screenshot for Debug PostProcessor"></a></div>
<aclass="sectionlink"href="#Debug_PostProcessor_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-false">Name</div><divclass="description req-false">Descriptive name for this element that is shown in the tree.</div><divclass="required req-false">No</div></div>
<divclass="property"><divclass="name req-true">JMeter Properties</div><divclass="description req-true">Whether to show JMeter properties (default false).</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">JMeter Variables</div><divclass="description req-true">Whether to show JMeter variables (default false).</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">Sampler Properties</div><divclass="description req-true">Whether to show Sampler properties (default true).</div><divclass="required req-true">Yes</div></div>
<divclass="property"><divclass="name req-true">System Properties</div><divclass="description req-true">Whether to show System properties (default false).</div><divclass="required req-true">Yes</div></div>
<divclass="component"><h2id="Test_Fragment">Test Fragment<aclass="sectionlink"href="#Test_Fragment"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/test_fragment.png"><imgsrc="../images/screenshots/test_fragment.png"width="236"height="94"alt="Screenshot for Test Fragment"></a></div>
The Test Fragment is used in conjunction with the <ahref="../usermanual/component_reference.html#Include_Controller">Include Controller</a> and <ahref="../usermanual/component_reference.html#Module_Controller">Module Controller</a>.
<aclass="sectionlink"href="#Test_Fragment_parms1"title="Link to here">¶</a></h3><divclass="property title"><divclass="name title">Attribute</div><divclass="description title">Description</div><divclass="required title">Required</div></div>
<divclass="property"><divclass="name req-true">Name</div><divclass="description req-true">Descriptive name for this element that is shown in the tree.</div><divclass="required req-true">Yes</div></div>
</div>
<divclass="clear"></div><divclass="note">
When using Test Fragment with <ahref="../usermanual/component_reference.html#Module_Controller">Module Controller</a>, ensure you disable the Test Fragment to avoid the execution of Test Fragment itself.
<divclass="component"><h2id="setUp_Thread_Group">setUp Thread Group<aclass="sectionlink"href="#setUp_Thread_Group"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/setup_thread_group.png"><imgsrc="../images/screenshots/setup_thread_group.png"width="537"height="289"alt="Screenshot for setUp Thread Group"></a></div>
is exactly like a normal <ahref="../usermanual/component_reference.html#Thread_Group">Thread Group</a> element. The difference is that these type of threads
<divclass="component"><h2id="tearDown_Thread_Group">tearDown Thread Group<aclass="sectionlink"href="#tearDown_Thread_Group"title="Link to here">¶</a></h2><divclass="screenshot"><ahref="../images/screenshots/teardown_thread_group.png"><imgsrc="../images/screenshots/teardown_thread_group.png"width="537"height="289"alt="Screenshot for tearDown Thread Group"></a></div>
is exactly like a normal <ahref="../usermanual/component_reference.html#Thread_Group">Thread Group</a> element. The difference is that these type of threads
<figure><ahref="../images/screenshots/tear_down_on_shutdown.png"><imgsrc="../images/screenshots/tear_down_on_shutdown.png"width="1081"height="570"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>
