Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
5499 lines (5147 sloc) 324 KB
<?xml version="1.0"?>
<!--
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*
-->
<!DOCTYPE document
[
<!ENTITY sect-num '18'>
]>
<document index="yes" index-level-2="yes" index-numbers="no" colbreak="&sect-num;.4"
prev="boss.html" next="functions.html" id="$Id: component_reference.xml 1341969 2012-05-23 18:24:47Z pmouawad $">
<properties>
<title>User's Manual: Component Reference</title>
</properties>
<body>
<!--
Because this is an XML document, all tags must be properly closed, including ones
which are passed unchanged into the HTML output, e.g. <br/>, not just <br>.
Unfortunately Java does not currently allow for this - it outputs the trailing > -
which messes up the Help display.
To avoid these artefacts, use the form <br></br>, which Java does seem to handle OK.
-->
<section name="&sect-num;.0 Introduction" anchor="introduction">
<description>
<p>
</p>
<note>
Several test elements use JMeter properties to control their behaviour.
These properties are normally resolved when the class is loaded.
This generally occurs before the test plan starts, so it's not possible to change the settings by using the __setProperty() function.
</note>
<p>
</p>
</description>
</section>
<section name="&sect-num;.1 Samplers" anchor="samplers">
<description>
<p>
Samplers perform the actual work of JMeter.
Each sampler (except Test Action) generates one or more sample results.
The sample results have various attributes (success/fail, elapsed time, data size etc) and can be viewed in the various listeners.
</p>
</description>
<component name="FTP Request" index="&sect-num;.1.1" width="519" height="289" screenshot="ftptest/ftp-request.png">
<description>
This controller lets you send an FTP "retrieve file" or "upload file" request to an FTP server.
If you are going to send multiple requests to the same FTP server, consider
using a <complink name="FTP Request Defaults"/> Configuration
Element so you do not have to enter the same information for each FTP Request Generative
Controller. When downloading a file, it can be stored on disk (Local File) or in the Response Data, or both.
<p>
Latency is set to the time it takes to login (versions of JMeter after 2.3.1).
</p>
</description>
<properties>
<property name="Name" required="No">Descriptive name for this controller that is shown in the tree.</property>
<property name="Server Name or IP" required="Yes">Domain name or IP address of the FTP server.</property>
<property name="Port" required="No">Port to use. If this is >0, then this specific port is used, otherwise JMeter uses the default FTP port.</property>
<property name="Remote File:" required="Yes">File to retrieve or name of destination file to upload.</property>
<property name="Local File:" required="Yes, if uploading (*)">File to upload, or destination for downloads (defaults to remote file name).</property>
<property name="Local File Contents:" required="Yes, if uploading (*)">Provides the contents for the upload, overrides the Local File property.</property>
<property name="get(RETR) / put(STOR)" required="Yes">Whether to retrieve or upload a file.</property>
<property name="Use Binary mode ?" required="Yes">Check this to use Binary mode (default Ascii)</property>
<property name="Save File in Response ?" required="Yes, if downloading">
Whether to store contents of retrieved file in response data.
If the mode is Ascii, then the contents will be visible in the Tree View Listener.
</property>
<property name="Username" required="Usually">FTP account username.</property>
<property name="Password" required="Usually">FTP account password. N.B. This will be visible in the test plan.</property>
</properties>
<links>
<link href="test_plan.html#assertions">Assertions</link>
<complink name="FTP Request Defaults"/>
<link href="build-ftp-test-plan.html">Building an FTP Test Plan</link>
</links>
</component>
<component name="HTTP Request" index="&sect-num;.1.2" width="907" height="674" screenshot="http-request.png">
<description>
<p>This sampler lets you send an HTTP/HTTPS request to a web server. It
also lets you control whether or not JMeter parses HTML files for images and
other embedded resources and sends HTTP requests to retrieve them.
The following types of embedded resource are retrieved:</p>
<ul>
<li>images</li>
<li>applets</li>
<li>stylesheets</li>
<li>external scripts</li>
<li>frames, iframes</li>
<li>background images (body, table, TD, TR)</li>
<li>background sound</li>
</ul>
<p>
The default parser is htmlparser.
This can be changed by using the property "htmlparser.classname" - see jmeter.properties for details.
</p>
<p>If you are going to send multiple requests to the same web server, consider
using an <complink name="HTTP Request Defaults"/>
Configuration Element so you do not have to enter the same information for each
HTTP Request.</p>
<p>Or, instead of manually adding HTTP Requests, you may want to use
JMeter's <complink name="HTTP Proxy Server"/> to create
them. This can save you time if you have a lot of HTTP requests or requests with many
parameters.</p>
<p><b>There are two different screens for defining the samplers:</b>
<ul>
<li>AJP/1.3 Sampler - uses the Tomcat mod_jk protocol (allows testing of Tomcat in AJP mode without needing Apache httpd)
The AJP Sampler does not support multiple file upload; only the first file will be used.
</li>
<li>HTTP Request - this has an implementation drop-down box, which selects the HTTP protocol implementation to be used:</li>
<ul>
<li>Java - uses the HTTP implementation provided by the JVM.
This has some limitations in comparison with the HttpClient implementations - see below.</li>
<li>HTTPClient3.1 - uses Apache Commons HttpClient 3.1.
This is no longer being developed, and support for this may be dropped in a future JMeter release.</li>
<li>HTTPClient4 - uses Apache HttpComponents HttpClient 4.x.</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 (e.g. proxy)
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>
</ul>
<p>Note: the FILE protocol is intended for testing puposes 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 <complink name="HTTP Authorization Manager"/> 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
<complink name="HTTP Cookie Manager"/>. You can
add either of these elements to the Thread Group or the HTTP Request. If you have
more than one HTTP Request that needs authorizations or cookies, then add the
elements to the Thread Group. That way, all HTTP Request controllers will share the
same Authorization Manager and Cookie Manager elements.</p>
<p>If the request uses a technique called "URL Rewriting" to maintain sessions,
then see section
<a href="build-adv-web-test-plan.html#session_url_rewriting">6.1 Handling User Sessions With URL Rewriting</a>
for additional configuration steps.</p>
</description>
<properties>
<property name="Name" required="No">Descriptive name for this controller that is shown in the tree.</property>
<property name="Server" required="Yes, unless provided by HTTP Request Defaults">
Domain name or IP address of the web server. e.g. www.example.com. [Do not include the http:// prefix.]
Note: in JMeter 2.5 (and later) if the "Host" header is defined in a Header Manager, then this will be used
as the virtual host name.
</property>
<property name="Port" required="No">Port the web server is listening to. Default: 80</property>
<property name="Connect Timeout" required="No">Connection Timeout. Number of milliseconds to wait for a connection to open.</property>
<property name="Response Timeout" required="No">Response Timeout. Number of milliseconds to wait for a response.</property>
<property name="Server (proxy)" required="No">Hostname or IP address of a proxy server to perform request. [Do not include the http:// prefix.]</property>
<property name="Port" required="No, unless proxy hostname is specified">Port the proxy server is listening to.</property>
<property name="Username" required="No">(Optional) username for proxy server.</property>
<property name="Password" required="No">(Optional) password for proxy server. (N.B. this is stored unencrypted in the test plan)</property>
<property name="Implementation" required="No">Java, HttpClient3.1, HttpClient4.
If not specified (and not defined by HTTP Request Defaults), the default depends on the value of the JMeter property
<code>jmeter.httpsampler</code>, failing that, the Java implementation is used.</property>
<property name="Protocol" required="No">HTTP, HTTPS or FILE. Default: HTTP</property>
<property name="Method" required="Yes">GET, POST, HEAD, TRACE, OPTIONS, PUT, DELETE</property>
<property name="Content Encoding" required="No">Content encoding to be used (for POST and FILE)</property>
<property name="Redirect Automatically" required="No">
Sets the underlying http protocol handler to automatically follow redirects,
so they are not seen by JMeter, and thus will not appear as samples.
Should only be used for GET and HEAD requests.
The HttpClient sampler will reject attempts to use it for POST or PUT.
<b>Warning: see below for information on cookie and header handling.</b>
</property>
<property name="Follow Redirects" required="No">
This only has any effect if "Redirect Automatically" is not enabled.
If set, the JMeter sampler will check if the response is a redirect and follow it if so.
The initial redirect and further responses will appear as additional samples.
The URL and data fields of the parent sample will be taken from the final (non-redirected)
sample, but the parent byte count and elapsed time include all samples.
The latency is taken from the initial response (versions of JMeter after 2.3.4 - previously it was zero).
Note that the HttpClient sampler may log the following message:<br/>
"Redirect requested but followRedirects is disabled"<br/>
This can be ignored.
<br/>
In versions after 2.3.4, JMeter will collapse paths of the form '/../segment' in
both absolute and relative redirect URLs. For example http://host/one/../two => http://host/two.
If necessary, this behaviour can be suppressed by setting the JMeter property
<code>httpsampler.redirect.removeslashdotdot=false</code>
</property>
<property name="Use KeepAlive" required="No">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.</property>
<property name="Use multipart/form-data for HTTP POST" required="No">
Use a multipart/form-data or application/x-www-form-urlencoded post request
</property>
<property name="Browser-compatible headers" required="No">
When using multipart/form-data, this suppresses the Content-Type and
Content-Transfer-Encoding headers; only the Content-Disposition header is sent.
</property>
<property name="Path" required="Yes">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.
<b>
As a special case, if the path starts with "http://" or "https://" then this is used as the full URL.
</b>
In this case, the server, port and protocol are ignored; parameters are also ignored for GET and DELETE methods.
</property>
<property name="Send Parameters With the Request" required="No">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 options to encode the parameter, and an option to include or exclude an equals sign (some applications
don't expect an equals when the value is the empty string). The query string will be generated in the correct fashion, depending on
the choice of "Method" you made (ie if you chose GET or DELETE, the query string will be
appended to the URL, if POST or PUT, then it will be sent separately). Also, if you are
sending a file using a multipart form, the query string will be created using the
multipart form specifications.
<b>See below for some further information on parameter handling.</b>
<p>
Additionally, you can specify whether each parameter should be URL encoded. If you are not sure what this
means, it is probably best to select it. If your values contain characters such as &amp;amp; or spaces, or
question marks, then encoding is usually required.</p></property>
<property name="File Path:" required="No">Name of the file to send. If left blank, JMeter
does not send a file, if filled in, JMeter automatically sends the request as
a multipart form request.
<p>
If it is a POST or PUT request and there is a single file whose 'name' attribute (below) is omitted,
then the file is sent as the entire body
of the request, i.e. no wrappers are added. This allows arbitrary bodies to be sent. This functionality is present for POST requests
after version 2.2, and also for PUT requests after version 2.3.
<b>See below for some further information on parameter handling.</b>
</p>
</property>
<property name="Parameter name:" required="No">Value of the "name" web request parameter.</property>
<property name="MIME Type" required="No">MIME type (for example, text/plain).
If it is a POST or PUT request and either the 'name' atribute (below) are omitted or the request body is
constructed from parameter values only, then the value of this field is used as the value of the
content-type request header.
</property>
<property name="Retrieve All Embedded Resources from HTML Files" required="No">Tell JMeter to parse the HTML file
and send HTTP/HTTPS requests for all images, Java applets, JavaScript files, CSSs, etc. referenced in the file.
See below for more details.
</property>
<property name="Use as monitor" required="No">For use with the <complink name="Monitor Results"/> listener.</property>
<property name="Save response as MD5 hash?" required="No">
If this is selected, then the response is not stored in the sample result.
Instead, the 32 character MD5 hash of the data is calculated and stored instead.
This is intended for testing large amounts of data.
</property>
<property name="Embedded URLs must match:" required="No">
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:
http://example\.com/.*
</property>
<property name="Use concurrent pool" required="No">Use a pool of concurrent connections to get embedded resources.</property>
<property name="Size" required="No">Pool size for concurrent connections used to get embedded resources.</property>
<property name="Source IP address:" required="No">
[Only for HTTP Request HTTPClient]
Override the default local IP address for this sample.
The JMeter host must have multiple IP addresses (i.e. IP aliases or network interfaces).
If the property <b>httpclient.localaddress</b> is defined, that is used for all HttpClient requests.
</property>
</properties>
<p>
<b>N.B.</b> when using Automatic Redirection, cookies are only sent for the initial URL.
This can cause unexpected behaviour for web-sites that redirect to a local server.
E.g. if www.example.com redirects to www.example.co.uk.
In this case the server will probably return cookies for both URLs, but JMeter will only see the cookies for the last
host, i.e. www.example.co.uk. If the next request in the test plan uses www.example.com,
rather than www.example.co.uk, it will not get the correct cookies.
Likewise, Headers are sent for the initial request, and won't be sent for the redirect.
This is generally only a problem for manually created test plans,
as a test plan created using a recorder would continue from the redirected URL.
</p>
<p>
<b>Parameter Handling:</b><br></br>
For the POST and PUT method, if there is no file to send, and the name(s) of the parameter(s) are omitted,
then the body is created by concatenating all the value(s) of the parameters.
Note that the values are concatenated without adding any end-of-line characters.
These can be added by using the __char() function in the value fields.
This allows arbitrary bodies to be sent.
The values are encoded if the encoding flag is set (versions of JMeter after 2.3).
See also the MIME Type above how you can control the content-type request header that is sent.
<br></br>
For other methods, if the name of the parameter is missing,
then the parameter is ignored. This allows the use of optional parameters defined by variables.
(versions of JMeter after 2.3)
</p>
<br/>
<p>Since JMeter 2.6, you have the option to switch to Post Body when a request has only unnamed parameters
(or no parameters at all).
This option is useful in the following cases (amongst others):
<ul>
<li>GWT RPC HTTP Request</li>
<li>JSON REST HTTP Request</li>
<li>XML REST HTTP Request</li>
<li>SOAP HTTP Request</li>
</ul>
Note that once you leave the Tree node, you cannot switch back to the parameter tab unless you clear the Post Body tab of data.
</p>
<p>
In Post Body mode, each line will be sent with CRLF appended, apart from the last line.
To send a CRLF after the last line of data, just ensure that there is an empty line following it.
(This cannot be seen, except by noting whether the cursor can be placed on the subsequent line.)
</p>
<figure width="902" height="421" image="http-request-raw-single-parameter.png">Figure 1 - HTTP Request with one unnamed parameter</figure>
<figure width="908" height="212" image="http-request-confirm-raw-body.png">Figure 2 - Confirm dialog to switch</figure>
<figure width="905" height="423" image="http-request-raw-body.png">Figure 3 - HTTP Request using RAW Post body</figure>
<p>
<b>Method Handling:</b><br></br>
The POST and PUT request methods work similarly, except that the PUT method does not support multipart requests.
The PUT method body must be provided as one of the following:
<ul>
<li>define the body as a file</li>
<li>define the body as parameter value(s) with no name</li>
</ul>
If you define any parameters with a name in either the sampler or Http
defaults then nothing is sent.
The GET and DELETE request methods work similarly to each other.
</p>
<p>Upto and including JMeter 2.1.1, only responses with the content-type "text/html" were scanned for
embedded resources. Other content-types were assumed to be something other than HTML.
JMeter 2.1.2 introduces the a new property <b>HTTPResponse.parsers</b>, which is a list of parser ids,
e.g. <b>htmlParser</b> and <b>wmlParser</b>. For each id found, JMeter checks two further properties:</p>
<ul>
<li>id.types - a list of content types</li>
<li>id.className - the parser to be used to extract the embedded resources</li>
</ul>
<p>See jmeter.properties file for the details of the settings.
If the HTTPResponse.parser property is not set, JMeter reverts to the previous behaviour,
i.e. only text/html responses will be scanned</p>
<b>Emulating slow connections (HttpClient only):</b><br></br>
The HttpClient version of the sampler supports emulation of slow connections; see the following entries in jmeter.properties:
<pre>
# Define characters per second > 0 to emulate slow connections
#httpclient.socket.http.cps=0
#httpclient.socket.https.cps=0
</pre>
<p><b>Response size calculation</b><br></br>
Optional properties to allow change the method to get response size:<br></br>
<ul><li>Gets the real network size in bytes for the body response
<pre>sampleresult.getbytes.body_real_size=true</pre></li>
<li>Add HTTP headers to full response size
<pre>sampleresult.getbytes.headers_size=true</pre></li></ul>
<note>
The Java and HttpClient3 inplementations do not include transport overhead such as
chunk headers in the response body size.<br></br>
The HttpClient4 implementation does include the overhead in the response body size,
so the value may be greater than the number of bytes in the response content.
</note>
<note>Versions of JMeter before 2.5 returns only data response size (uncompressed if request uses gzip/defate mode).
<br></br>To return to settings before version 2.5, set the two properties to false.</note>
</p>
<p>
<b>Retry handling</b><br></br>
In version 2.5 of JMeter, the HttpClient4 and Commons HttpClient 3.1 samplers used the default retry count, which was 3.
In later versions, the retry count has been set to 1, which is what the Java implementation appears to do.
The retry count can be overridden by setting the relevant JMeter property, for example:
<pre>
httpclient4.retrycount=3
httpclient3.retrycount=3
</pre>
</p>
<links>
<link href="test_plan.html#assertions">Assertion</link>
<link href="build-web-test-plan.html">Building a Web Test Plan</link>
<link href="build-adv-web-test-plan.html">Building an Advanced Web Test Plan</link>
<complink name="HTTP Authorization Manager"/>
<complink name="HTTP Cookie Manager"/>
<complink name="HTTP Header Manager"/>
<complink name="HTML Link Parser"/>
<complink name="HTTP Proxy Server"/>
<complink name="HTTP Request Defaults"/>
<link href="build-adv-web-test-plan.html#session_url_rewriting">HTTP Requests and Session ID's: URL Rewriting</link>
</links>
</component>
<component name="JDBC Request" index="&sect-num;.1.3" width="466" height="334" screenshot="jdbctest/jdbc-request.png">
<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
<complink name="JDBC Connection Configuration"/> Configuration element
</p>
<p>
If the Variable Names list is provided, then for each row returned by a Select statement, the variables are set up
with the value of the corresponding column (if a variable name is provided), and the count of rows is also set up.
For example, if the Select statement returns 2 rows of 3 columns, and the variable list is <code>A,,C</code>,
then the following variables will be set up:
<pre>
A_#=2 (number of rows)
A_1=column 1, row 1
A_2=column 1, row 2
C_#=2 (number of rows)
C_1=column 3, row 1
C_2=column 3, row 2
</pre>
If the Select statement returns zero rows, then the A_# and C_# variables would be set to 0, and no other variables would be set.
</p>
<p>
Old variables are cleared if necessary - e.g. if the first select retrieves 6 rows and a second select returns only 3 rows,
the additional variables for rows 4, 5 and 6 will be removed.
</p>
<p>
<b>Note:</b> The latency time is set from the time it took to acquire a connection.
</p>
</description>
<properties>
<property name="Name" required="No">Descriptive name for this controller that is shown in the tree.</property>
<property name="Variable Name" required="Yes">
Name of the JMeter variable that the connection pool is bound to.
This must agree with the 'Variable Name' field of a JDBC Connection Configuration.
</property>
<property name="Query Type" required="Yes">Set this according to the statement type:
<ul>
<li>Select Statement</li>
<li>Update Statement - use this for Inserts as well</li>
<li>Callable Statement</li>
<li>Prepared Select Statement</li>
<li>Prepared Update Statement - use this for Inserts as well</li>
<li>Commit</li>
<li>Rollback</li>
<li>Autocommit(false)</li>
<li>Autocommit(true)</li>
<li>Edit - this should be a variable reference that evaluates to one of the above</li>
</ul>
</property>
<property name="SQL Query" required="Yes">
SQL query.
Do not enter a trailing semi-colon.
There is generally no need to use { and } to enclose Callable statements;
however they mey be used if the database uses a non-standard syntax.
[The JDBC driver automatically converts the statement if necessary when it is enclosed in {}].
For example:
<ul>
<li>select * from t_customers where id=23</li>
<li>CALL SYSCS_UTIL.SYSCS_EXPORT_TABLE (null,?, ?, null, null, null)
<ul>
<li>Parameter values: tablename,filename</li>
<li>Parameter types: VARCHAR,VARCHAR</li>
</ul>
</li>
The second example assumes you are using Apache Derby.
</ul>
</property>
<property name="Parameter values" required="Yes, if a prepared or callable statement has parameters">
Comma-separated list of parameter values. Use ]NULL[ to indicate a NULL parameter.
(If required, the null string can be changed by defining the property "jdbcsampler.nullmarker".)
<br></br>
The list must be enclosed in double-quotes if any of the values contain a comma or double-quote,
and any embedded double-quotes must be doubled-up, for example:
<pre>"Dbl-Quote: "" and Comma: ,"</pre>
There must be as many values as there are placeholders in the statement.
</property>
<property name="Parameter types" required="Yes, if a prepared or callable statement has parameters">
Comma-separated list of SQL parameter types (e.g. INTEGER, DATE, VARCHAR, DOUBLE).
These are defined as fields in the class java.sql.Types, see for example:
<a href="http://download.oracle.com/javase/1.5.0/docs/api/java/sql/Types.html">Javadoc for java.sql.Types</a>.
[Note: JMeter will use whatever types are defined by the runtime JVM,
so if you are running on a different JVM, be sure to check the appropriate document]
If the callable statement has INOUT or OUT parameters, then these must be indicated by prefixing the
appropriate parameter types, e.g. instead of "INTEGER", use "INOUT INTEGER".
If not specified, "IN" is assumed, i.e. "DATE" is the same as "IN DATE".
<br></br>
If the type is not one of the fields found in java.sql.Types, versions of JMeter after 2.3.2 also
accept the corresponding integer number, e.g. since INTEGER == 4, you can use "INOUT 4".
<br></br>
There must be as many types as there are placeholders in the statement.
</property>
<property name="Variable Names" required="No">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.
If more variable names than OUT parameters exist, the additional variables will be ignored</property>
<property name="Result Variable Name" required="No">
If specified, this will create an Object variable containing a list of row maps.
Each map contains the column name as the key and the column data as the value. Usage:<br></br>
<code>columnValue = vars.getObject("resultObject").get(0).get("Column Name");</code>
</property>
</properties>
<links>
<link href="build-db-test-plan.html">Building a Database Test Plan</link>
<complink name="JDBC Connection Configuration"/>
</links>
<note>Versions of JMeter after 2.3.2 use UTF-8 as the character encoding. Previously the platform default was used.</note>
</component>
<component name="Java Request" index="&sect-num;.1.4" width="563" height="347" screenshot="java_request.png">
<description><p>This sampler lets you control a java class that implements the
<b><code>org.apache.jmeter.protocol.java.sampler.JavaSamplerClient</code></b> interface.
By writing your own implementation of this interface,
you can use JMeter to harness multiple threads, input parameter control, and
data collection.</p>
<p>The pull-down menu provides the list of all such implementations found by
JMeter in its classpath. The parameters can then be specified in the
table below - as defined by your implementation. Two simple examples (JavaTest and SleepTest) are provided.
</p>
<p>
The JavaTest example sampler can be useful for checking test plans, because it allows one to set
values in almost all the fields. These can then be used by Assertions, etc.
The fields allow variables to be used, so the values of these can readily be seen.
</p>
</description>
<note>The Add/Delete buttons don't serve any purpose at present.</note>
<properties>
<property name="Name" required="No">Descriptive name for this sampler
that is shown in the tree.</property>
<property name="Classname" required="Yes">The specific implementation of
the JavaSamplerClient interface to be sampled.</property>
<property name="Send Parameters with Request" required="No">A list of
arguments that will be passed to the sampled class. All arguments
are sent as Strings.</property>
</properties>
</component>
<p>The sleep time is calculated as follows:</p>
<pre>
SleepTime is in milliseconds
SleepMask is used to add a "random" element to the time:
totalSleepTime = SleepTime + (System.currentTimeMillis() % SleepMask)
</pre>
<component name="SOAP/XML-RPC Request" index="&sect-num;.1.5" width="426" height="276" screenshot="soap_sampler.png">
<description><p>This sampler lets you send a SOAP request to a webservice. It can also be
used to send XML-RPC over HTTP. It creates an HTTP POST request, with the specified XML as the
POST content.
To change the "Content-type" from the default of "text/xml", use a HeaderManager.
Note that the sampler will use all the headers from the HeaderManager.
If a SOAP action is specified, that will override any SOAPaction in the HeaderManager.
The primary difference between the soap sampler and
webservice sampler, is the soap sampler uses raw post and does not require conformance to
SOAP 1.1.</p>
<note>For versions of JMeter later than 2.2, the sampler no longer uses chunked encoding by default.<br/>
For screen input, it now always uses the size of the data.<br/>
File input uses the file length as determined by Java.<br/>
On some OSes this may not work for all files, in which case add a child Header Manager
with Content-Length set to the actual length of the file.<br/>
Or set Content-Length to -1 to force chunked encoding.
</note>
</description>
<properties>
<property name="Name" required="No">Descriptive name for this sampler
that is shown in the tree.</property>
<property name="URL" required="Yes">The URL to direct the SOAP request to.</property>
<property name="Send SOAP action" required="No">Send a SOAP action header? (overrides the Header Manager)</property>
<property name="Use KeepAlive" required="No">If set, sends Connection: keep-alive, else sends Connection: close</property>
<property name="Soap/XML-RPC Data" required="No">The Soap XML message, or XML-RPC instructions.
Not used if the filename is provided.
</property>
<property name="Filename" required="No">If specified, then the contents of the file are sent, and the Data field is ignored</property>
</properties>
</component>
<component name="WebService(SOAP) Request" index="&sect-num;.1.6" width="943" height="648" screenshot="webservice_sampler.png">
<description><p>This sampler has been tested with IIS Webservice running .NET 1.0 and .NET 1.1.
It has been tested with SUN JWSDP, IBM webservices, Axis and gSoap toolkit for C/C++.
The sampler uses Apache SOAP driver to serialize the message and set the header
with the correct SOAPAction. Right now the sampler doesn't support automatic WSDL
handling, since Apache SOAP currently does not provide support for it. Both IBM
and SUN provide WSDL drivers. There are 3 options for the post data: text area,
external file, or directory. If you want the sampler to randomly select a message,
use the directory. Otherwise, use the text area or a file. The if either the
file or path are set, it will not use the message in the text area. If you need
to test a soap service that uses different encoding, use the file or path. If you
paste the message in to text area, it will not retain the encoding and will result
in errors. Save your message to a file with the proper encoding, and the sampler
will read it as java.io.FileInputStream.</p>
<p>An important note on the sampler is it will automatically use the proxy host
and port passed to JMeter from command line, if those fields in the sampler are
left blank. If a sampler has values in the proxy host and port text field, it
will use the ones provided by the user. This behavior may not be what users
expect.</p>
<p>By default, the webservice sampler sets SOAPHTTPConnection.setMaintainSession
(true). If you need to maintain the session, add a blank Header Manager. The
sampler uses the Header Manager to store the SOAPHTTPConnection object, since
the version of apache soap does not provide a easy way to get and set the cookies.</p>
<p><b>Note:</b> If you are using CSVDataSet, do not check "Memory Cache". If memory
cache is checked, it will not iterate to the next value. That means all the requests
will use the first value.</p>
<p>Make sure you use &amp;lt;soap:Envelope rather than &amp;lt;Envelope. For example:</p>
<pre>
&amp;lt;?xml version="1.0" encoding="utf-8"?>
&amp;lt;soap:Envelope
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
&amp;lt;soap:Body>
&amp;lt;foo xmlns="http://clients-xlmns"/>
&amp;lt;/soap:Body>
&amp;lt;/soap:Envelope>
</pre>
<note>The SOAP library that is used does not support SOAP 1.2, only SOAP 1.1.
Also the library does not provide access to the HTTP response code (e.g. 200) or message (e.g. OK).
To get round this, versions of JMeter after 2.3.2 check the returned message length.
If this is zero, then the request is marked as failed.
</note>
</description>
<properties>
<property name="Name" required="No">Descriptive name for this sampler
that is shown in the tree.</property>
<property name="WSDL URL" required="No">The WSDL URL with the service description.
Versions of JMeter after 2.3.1 support the file: protocol for local WSDL files.
</property>
<property name="Web Methods" required="No">Will be populated from the WSDL when the Load WSDL button is pressed.
Select one of the methods and press the Configure button to populate the Protocol, Server, Port, Path and SOAPAction fields.
</property>
<property name="Protocol" required="Yes">HTTP or HTTPS are acceptable protocol.</property>
<property name="Server Name or IP" required="Yes">The hostname or IP address.</property>
<property name="Port Number" required="Yes">Port Number.</property>
<property name="Timeout" required="No">Connection timeout.</property>
<property name="Path" required="Yes">Path for the webservice.</property>
<property name="SOAPAction" required="Yes">The SOAPAction defined in the webservice description or WSDL.</property>
<property name="Soap/XML-RPC Data" required="Yes">The Soap XML message</property>
<property name="Soap file" required="No">File containing soap message</property>
<property name="Message(s) Folder" required="No">Folder containing soap files. Files are choose randomly during test.</property>
<property name="Memory cache" required="Yes">
When using external files, setting this causes the file to be processed once and caches the result.
This may use a lot of memory if there are many different large files.
</property>
<property name="Read SOAP Response" required="No">Read the SOAP reponse (consumes performance). Permit to have assertions or post-processors</property>
<property name="Use HTTP Proxy" required="No">Check box if http proxy should be used</property>
<property name="Server Name or IP" required="No">Proxy hostname</property>
<property name="Port Number" required="No">Proxy host port</property>
</properties>
</component>
<component name="LDAP Request" index="&sect-num;.1.7" width="621" height="462" screenshot="ldap_request.png">
<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 <complink name="LDAP Request Defaults"/>
Configuration Element so you do not have to enter the same information for each
LDAP Request.</p> The same way the <complink name="Login Config Element"/> also using for Login and password.
</description>
<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
the execution time. After execution of the test, the created entry will be
deleted from the LDAP
Server.</p></li>
<li>User defined test :
<p>This will add the entry in the LDAP Server. User has to enter all the
attributes in the table.The entries are collected from the table to add. The
execution time is calculated. The created entry will not be deleted after the
test.</p></li></ol>
<li>Modify Test</li>
<ol><li>Inbuilt test :
<p>This will create a pre-defined entry first, then will modify the
created entry in the LDAP Server.And calculate the execution time. After
execution
of the test, the created entry will be deleted from the LDAP Server.</p></li>
<li>User defined test
<p>This will modify the entry in the LDAP Server. User has to enter all the
attributes in the table. The entries are collected from the table to modify.
The execution time is calculated. The entry will not be deleted from the LDAP
Server.</p></li></ol>
<li>Search Test</li>
<ol><li>Inbuilt test :
<p>This will create the entry first, then will search if the attributes
are available. It calculates the execution time of the search query. At the
end of the execution,created entry will be deleted from the LDAP Server.</p></li>
<li>User defined test
<p>This will search the user defined entry(Search filter) in the Search
base (again, defined by the user). The entries should be available in the LDAP
Server. The execution time is calculated.</p></li></ol>
<li>Delete Test</li>
<ol><li>Inbuilt test :
<p>This will create a pre-defined entry first, then it will be deleted
from the LDAP Server. The execution time is calculated.</p></li>
<li>User defined test
<p>This will delete the user-defined entry in the LDAP Server. The entries
should be available in the LDAP Server. The execution time is calculated.</p></li></ol></ol>
<properties>
<property name="Name" required="No">Descriptive name for this controller that is shown in the tree.</property>
<property name="Server Name or IP" required="Yes">Domain name or IP address of the LDAP server.
JMeter assumes the LDAP server is listening on the default port(389).</property>
<property name="Port" required="Yes">default port(389).</property>
<property name="root DN" required="Yes">DN for the server to communicate</property>
<property name="Username" required="Usually">LDAP server username.</property>
<property name="Password" required="Usually">LDAP server password. (N.B. this is stored unencrypted in the test plan)</property>
<property name="Entry DN" required="Yes">the name of the context to create or Modify; may not be empty Example: do you want to add cn=apache,ou=test
you have to add in table name=cn, value=apache
</property>
<property name="Delete" required="Yes">the name of the context to Delete; may not be empty</property>
<property name="Search base" required="Yes">the name of the context or object to search</property>
<property name="Search filter" required="Yes"> the filter expression to use for the search; may not be null</property>
<property name="add test" required="Yes"> this name, value pair to added in the given context object</property>
<property name="modify test" required="Yes"> this name, value pair to add or modify in the given context object</property>
</properties>
<links>
<link href="build-ldap-test-plan.html">Building an Ldap Test Plan</link>
<complink name="LDAP Request Defaults"/>
</links>
</component>
<component name="LDAP Extended Request" index="&sect-num;.1.8" width="619" height="371" screenshot="ldapext_request.png">
<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 <complink name="LDAP Extended Request Defaults"/>
Configuration Element so you do not have to enter the same information for each
LDAP Request.</p> </description>
<p>There are nine test operations defined. These operations are given below:</p>
<ol>
<li><b>Thread bind</b></li>
<p>Any LDAP request is part of an LDAP session, so the first thing that should be done is starting a session to the LDAP server.
For starting this session a thread bind is used, which is equal to the LDAP "bind" operation.
The user is requested to give a username (Distinguished name) and password,
which will be used to initiate a session.
When no password, or the wrong password is specified, an anonymous session is started. Take care,
omitting the password will not fail this test, a wrong password will.
(N.B. this is stored unencrypted in the test plan)</p>
<properties>
<property name="Name" required="No">Descriptive name for this sampler that is shown in the tree.</property>
<property name="Servername" required="Yes">The name (or IP-address) of the LDAP server.</property>
<property name="Port" required="No">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).</property>
<property name="DN" required="No">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!</property>
<property name="Username" required="No">Full distinguished name of the user as which you want to bind.</property>
<property name="Password" required="No">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)</property>
</properties>
<br />
<li><b>Thread unbind</b></li>
<p>This is simply the operation to end a session.
It is equal to the LDAP "unbind" operation.</p>
<properties>
<property name="Name" required="No">Descriptive name for this sampler that is shown in the tree.</property>
</properties>
<br />
<li><b>Single bind/unbind</b></li>
<p> This is a combination of the LDAP "bind" and "unbind" operations.
It can be used for an authentication request/password check for any user. It will open an new session, just to
check the validity of the user/password combination, and end the session again.</p>
<properties>
<property name="Name" required="No">Descriptive name for this sampler that is shown in the tree.</property>
<property name="Username" required="Yes">Full distinguished name of the user as which you want to bind.</property>
<property name="Password" required="No">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)</property>
</properties>
<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
the LDAP tree. </p>
<properties>
<property name="Name" required="No">Descriptive name for this sampler that is shown in the tree.</property>
<property name="Old entry name" required="Yes">The current distinguished name of the object you want to rename or move,
relative to the given DN in the thread bind operation.</property>
<property name="New distinguished name" required="Yes">The new distinguished name of the object you want to rename or move,
relative to the given DN in the thread bind operation.</property>
</properties>
<br />
<li><b>Add test</b></li>
<p>This is the ldap "add" operation. It can be used to add any kind of
object to the LDAP server. </p>
<properties>
<property name="Name" required="No">Descriptive name for this sampler that is shown in the tree.</property>
<property name="Entry DN" required="Yes">Distinguished name of the object you want to add, relative to the given DN in the thread bind operation.</property>
<property name="Add test" required="Yes">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.</property>
</properties>
<br />
<li><b>Delete test</b></li>
<p> This is the LDAP "delete" operation, it can be used to delete an
object from the LDAP tree </p>
<properties>
<property name="Name" required="No">Descriptive name for this sampler that is shown in the tree.</property>
<property name="Delete" required="Yes">Distinguished name of the object you want to delete, relative to the given DN in the thread bind operation.</property>
</properties>
<br />
<li><b>Search test</b></li>
<p>This is the LDAP "search" operation, and will be used for defining searches. </p>
<properties>
<property name="Name" required="No">Descriptive name for this sampler that is shown in the tree.</property>
<property name="Search base" required="No">Distinguished name of the subtree you want your
search to look in, relative to the given DN in the thread bind operation.</property>
<property name="Search Filter" required="Yes">searchfilter, must be specified in LDAP syntax.</property>
<property name="Scope" required="No">Use 0 for baseobject-, 1 for onelevel- and 2 for a subtree search. (Default=0)</property>
<property name="Size Limit" required="No">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</property>
<property name="Time Limit" required="No">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)</property>
<property name="Attributes" required="No">Specify the attributes you want to have returned, seperated by a semicolon. An empty field will return all attributes</property>
<property name="Return object" required="No">Whether the object will be returned (true) or not (false). Default=false</property>
<property name="Dereference aliases" required="No">If true, it will dereference aliases, if false, it will not follow them (default=false)</property>
</properties>
<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>
<properties>
<property name="Name" required="No">Descriptive name for this sampler that is shown in the tree.</property>
<property name="Entry name" required="Yes">Distinguished name of the object you want to modify, relative
to the given DN in the thread bind operation</property>
<property name="Modification test" required="Yes">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.</property>
</properties>
<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>
<properties>
<property name="Name" required="No">Descriptive name for this sampler that is shown in the tree.</property>
<property name="Entry DN" required="Yes">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.</property>
<property name="Compare filter" required="Yes">In the form "attribute=value"</property>
</properties>
</ol>
<links>
<link href="build-ldapext-test-plan.html">Building an LDAP Test Plan</link>
<complink name="LDAP Extended Request Defaults"/>
</links>
</component>
<component name="Access Log Sampler" index="&sect-num;.1.9" width="613" height="318" screenshot="accesslogsampler.png">
<center><h2>(Alpha Code)</h2></center>
<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 the every image and 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
like this:</p>
<p>127.0.0.1 - - [21/Oct/2003:05:37:21 -0500] "GET /index.jsp?%2Findex.jsp= HTTP/1.1" 200 8343</p>
<p>The current implemenation of the parser only looks at the text within the quotes.
Everything else is stripped out and igored. For example, the response code is completely
ignored by the parser. 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
are two interfaces you have to implement.</p>
<p>org.apache.jmeter.protocol.http.util.accesslog.LogParser</p>
<p>org.apache.jmeter.protocol.http.util.accesslog.Generator</p>
<p>The current implementation of AccessLogSampler uses the generator to create a new
HTTPSampler. The servername, port and get images are set by AccessLogSampler. Next,
the parser is called with integer 1, telling it to parse one entry. After that,
HTTPSampler.sample() is called to make the request.
<code>
<pre>
samp = (HTTPSampler) GENERATOR.generateRequest();
samp.setDomain(this.getDomain());
samp.setPort(this.getPort());
samp.setImageParser(this.isImageParser());
PARSER.parse(1);
res = samp.sample();
res.setSampleLabel(samp.toString());
</pre>
</code>
The required methods in LogParser are: setGenerator(Generator) and parse(int).
Classes implementing Generator interface should provide concrete implementation
for all the methods. For an example of how to implement either interface, refer to
StandardGenerator and TCLogParser.
</p>
</description>
<properties>
<property name="Name" required="No">Descriptive name for this controller that is shown in the tree.</property>
<property name="Server" required="Yes">Domain name or IP address of the web server.</property>
<property name="Port" required="No (defaults to 80)">Port the web server is listening to.</property>
<property name="Log parser class" required="Yes (default provided)">The log parser class is responsible for parsing the logs.</property>
<property name="Filter" required="No">The filter class is used to filter out certain lines.</property>
<property name="Location of log file" required="Yes">The location of the access log file.</property>
</properties>
<p>
The TCLogParser processes the access log independently for each thread.
The SharedTCLogParser and OrderPreservingLogParser share access to the file,
i.e. each thread gets the next entry in the log.
</p>
<p>
The SessionFilter is intended to handle Cookies across threads.
It does not filter out any entries, but modifies the cookie manager so that the cookies for a given IP are
processed by a single thread at a time. If two threads try to process samples from the same client IP address,
then one will be forced to wait until the other has completed.
</p>
<p>
The LogFilter is intended to allow access log entries to be filtered by filename and regex,
as well as allowing for the replacement of file extensions. However, it is not currently possible
to configure this via the GUI, so it cannot really be used.
</p>
</component>
<component name="BeanShell Sampler" index="&sect-num;.1.10" width="1034" height="505" screenshot="beanshellsampler.png">
<description><p>This sampler allows you to write a sampler using the BeanShell scripting language.
</p><p>
<b>For full details on using BeanShell, please see the <a href="http://www.beanshell.org/">BeanShell website.</a></b>
</p>
<p>
The test element supports the ThreadListener and TestListener interface methods.
These must be defined in the initialisation file.
See the file BeanShellListeners.bshrc for example definitions.
</p>
<p>
From JMeter version 2.5.1, the BeanShell sampler also supports the Interruptible interface.
The interrupt() method can be defined in the script or the init file.
</p>
</description>
<properties>
<property name="Name" required="No">Descriptive name for this controller that is shown in the tree.
The name is stored in the script variable Label</property>
<property name="Reset bsh.Interpreter before each call" required="Yes">
If this option is selected, then the interpreter will be recreated for each sample.
This may be necessary for some long running scripts.
For further information, see <a href="best-practices#bsh_scripting">Best Practices - BeanShell scripting</a>.
</property>
<property name="Parameters" required="No">Parameters to pass to the BeanShell script.
This is intended for use with script files; for scripts defined in the GUI, you can use whatever
variable and function references you need within the script itself.
The parameters are stored in the following variables:
<ul>
<li>Parameters - string containing the parameters as a single variable</li>
<li>bsh.args - String array containing parameters, split on white-space</li>
</ul></property>
<property name="Script file" required="No">A file containing the BeanShell script to run.
The file name is stored in the script variable FileName</property>
<property name="Script" required="Yes (unless script file is provided)">The BeanShell script to run.
The return value (if not null) is stored as the sampler result.</property>
</properties>
<p>
N.B. Each Sampler instance has its own BeanShell interpeter,
and Samplers are only called from a single thread
</p><p>
If the property "beanshell.sampler.init" is defined, it is passed to the Interpreter
as the name of a sourced file.
This can be used to define common methods and variables.
There is a sample init file in the bin directory: BeanShellSampler.bshrc.
</p><p>
If a script file is supplied, that will be used, otherwise the script will be used.</p>
<p>Before invoking the script, some variables are set up in the BeanShell interpreter:
</p>
<p>The contents of the Parameters field is put into the variable "Parameters".
The string is also split into separate tokens using a single space as the separator, and the resulting list
is stored in the String array bsh.args.</p>
<p>The full list of BeanShell variables that is set up is as follows:</p>
<ul>
<li>log - the Logger</li>
<li>Label - the Sampler label</li>
<li>FileName - the file name, if any</li>
<li>Parameters - text from the Parameters field</li>
<li>bsh.args - the parameters, split as described above</li>
<li>SampleResult - pointer to the current SampleResult</li>
<li>ResponseCode = 200</li>
<li>ResponseMessage = "OK"</li>
<li>IsSuccess = true</li>
<li>ctx - JMeterContext</li>
<li>vars - <a href="../../docs/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 SampleResult:</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
setStopThread(boolean) and setStopTest(boolean).
Here is a simple (not very useful!) example script:</p>
<pre>
if (bsh.args[0].equalsIgnoreCase("StopThread")) {
log.info("Stop Thread detected!");
SampleResult.setStopThread(true);
}
return "Data from sample with Label "+Label;
//or, since version 2.1.2
SampleResult.setResponseData("My data");
return null;
</pre>
<p>Another example:<br></br> ensure that the property <b>beanshell.sampler.init=BeanShellSampler.bshrc</b> is defined in jmeter.properties.
The following script will show the values of all the variables in the ResponseData field:
</p>
<pre>
return getVariables();
</pre>
<p>
For details on the methods available for the various classes (JMeterVariables, SampleResult etc) please check the Javadoc or the source code.
Beware however that misuse of any methods can cause subtle faults that may be difficult to find ...
</p>
</component>
<component name="BSF Sampler" index="&sect-num;.1.11" width="1228" height="407" screenshot="bsfsampler.png">
<description><p>This sampler allows you to write a sampler using a BSF scripting language.<br></br>
See the <a href="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>
<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>
<note>Unlike the BeanShell sampler, the interpreter is not saved between invocations.</note>
</description>
<properties>
<property name="Name" required="No">Descriptive name for this controller that is shown in the tree.</property>
<property name="Scripting Language" required="Yes">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.
</property>
<property name="Script File" required="No">Name of a file to be used as a BSF script</property>
<property name="Parameters" required="No">List of parameters to be passed to the script file or the script.</property>
<property name="Script" required="Yes (unless script file is provided)">Script to be passed to BSF language</property>
</properties>
<p>
If a script file is supplied, that will be used, otherwise the script will be used.</p>
<p>
Before invoking the script, some variables are set up.
Note that these are BSF variables - i.e. they can be used directly in the script.
</p>
<ul>
<li>log - the Logger</li>
<li>Label - the Sampler label</li>
<li>FileName - the file name, if any</li>
<li>Parameters - text from the Parameters field</li>
<li>args - the parameters, split as described above</li>
<li>SampleResult - pointer to the current SampleResult</li>
<li>sampler - pointer to current Sampler</li>
<li>ctx - JMeterContext</li>
<li>vars - <a href="../../docs/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>
<li>OUT - System.out - e.g. OUT.println("message")</li>
</ul>
<p>
The SampleResult ResponseData is set from the return value of the script.
If the script returns null, it can set the response directly, by using the method
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
setStopThread(boolean) and setStopTest(boolean).
</p>
<p>
Unlike the Beanshell Sampler, the BSF Sampler does not set the ResponseCode, ResponseMessage and sample status via script variables.
Currently the only way to changes these is via the SampleResult methods:
<ul>
<li>SampleResult.setSuccessful(true/false)</li>
<li>SampleResult.setResponseCode("code")</li>
<li>SampleResult.setResponseMessage("message")</li>
</ul>
</p>
</component>
<component name="JSR223 Sampler" index="&sect-num;.1.11.1">
<description>
<p>
The JSR223 Sampler allows JSR223 script code to be used to perform a sample.
For details, see <complink name="BSF Sampler"/>.
</p>
<note>Unlike the BeanShell sampler, the interpreter is not saved between invocations.</note>
</description>
</component>
<component name="TCP Sampler" index="&sect-num;.1.12" width="743" height="357" screenshot="tcpsampler.png">
<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></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.
<br></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></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></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></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></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></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></br>
For example, if the prefix = "[" and the suffix = "]", then the following repsonse:
<br></br>
[J28] XI123,23,GBP,CR
<br></br>
would have the response code J28.
<br></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>
<note>The login name/password are not used by the supplied TCP implementations.</note>
<br></br>
Sockets are disconnected at the end of a test run.
</description>
<properties>
<property name="Name" required="">Descriptive name for this element that is shown in the tree.</property>
<property name="TCPClient classname" required="No">Name of the TCPClient class. Defaults to the property tcp.handler, failing that TCPClientImpl.</property>
<property name="ServerName or IP" required="Yes">Name or IP of TCP server</property>
<property name="Port Number" required="Yes">Port to be used</property>
<property name="Re-use connection" required="Yes">If selected, the connection is kept open. Otherwise it is closed when the data has been read.</property>
<property name="Connect Timeout" required="No">Connect Timeout (milliseconds, 0 disables).</property>
<property name="Response Timeout" required="No">Response Timeout (milliseconds, 0 disables).</property>
<property name="Set Nodelay" required="Yes">See java.net.Socket.setTcpNoDelay().
If selected, this will disable Nagle's algorithm, otherwise Nagle's algorithm will be used.</property>
<property name="Text to Send" required="Yes">Text to be sent</property>
<property name="Login User" required="No">User Name - not used by default implementation</property>
<property name="Password" required="No">Password - not used by default implementation (N.B. this is stored unencrypted in the test plan)</property>
</properties>
</component>
<component name="JMS Publisher" index="&sect-num;.1.13" width="802" height="735" screenshot="jmspublisher.png">
<note>BETA CODE - the code is still subject to change</note>
<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></br>
<note>JMeter does not include any JMS implementation jar; this must be downloaded from the JMS provider and put in the lib directory</note>
</description>
<properties>
<property name="Name" required="">Descriptive name for this element that is shown in the tree.</property>
<property name="use JNDI properties file" required="Yes">use jndi.properties.
Note that the file must be on the classpath - e.g. by updating the user.classpath JMeter property.
If this option is not selected, JMeter uses the "JNDI Initial Context Factory" and "Provider URL" fields
to create the connection.
</property>
<property name="JNDI Initial Context Factory" required="No">Name of the context factory</property>
<property name="Provider URL" required="Yes, unless using jndi.properties">The URL for the jms provider</property>
<property name="Destination" required="Yes">The message destination (topic or queue name)</property>
<property name="Setup" required="Yes">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)</property>
<property name="Authentication" required="Yes">Authentication requirement for the JMS provider</property>
<property name="User" required="No">User Name</property>
<property name="Password" required="No">Password (N.B. this is stored unencrypted in the test plan)</property>
<property name="Number of samples to aggregate" required="Yes">Number of samples to aggregate</property>
<property name="Message source" required="Yes">Where to obtain the message</property>
<property name="Message type" required="Yes">Text, Map or Object message</property>
<property name="Use non-persistent delivery mode?" required="No">
Whether to set DeliveryMode.NON_PERSISTENT (defaults to false)
</property>
<property name="JMS Properties" required="No">
The JMS Properties are properties specific for the underlying messaging system.
For example: for WebSphere 5.1 web services you will need to set the JMS Property targetService to test
webservices through JMS.
</property>
</properties>
<p>
For the MapMessage type, JMeter reads the source as lines of text.
Each line must have 3 fields, delimited by commas.
The fields are:
<ul>
<li>Name of entry</li>
<li>Object class name, e.g. "String" (assumes java.lang package if not specified)</li>
<li>Object string value</li>
</ul>
For each entry, JMeter adds an Object with the given name.
The value is derived by creating an instance of the class, and using the valueOf(String) method to convert the value if necessary.
For example:
<pre>
name,String,Example
size,Integer,1234
</pre>
This is a very simple implementation; it is not intended to support all possible object types.
</p>
<p>
<note>
The Object message is implemented since 2.7 and works as follow:
<ul>
<li>Put the JAR that contain you object and its dependencies in jmeter_home/lib/ folder </li>
<li>Serialize your object as XML using XStream</li>
<li>Either put result in a file suffixed with .txt or .obj or put XML content direclty in Text Area</li>
</ul>
Note that if message is in an file, replacement of properties will not occur while it will happen if you use Text Area.
</note>
</p>
<p>
The following table shows some values which may be useful when configuring JMS:
<table>
<tr>
<!-- Anakia does not like th cell without any text -->
<th>Apache <a href="http://activemq.apache.org/">ActiveMQ</a></th>
<th>Value(s)</th>
<th>Comment</th>
</tr>
<tr><td>Context Factory</td><td>org.apache.activemq.jndi.ActiveMQInitialContextFactory</td><td>.</td></tr>
<tr><td>Provider URL</td><td>vm://localhost</td><td></td></tr>
<tr><td>Provider URL</td><td>vm:(broker:(vm://localhost)?persistent=false)</td><td>Disable persistence</td></tr>
<tr><td>Queue Reference</td><td>dynamicQueues/QUEUENAME</td>
<td><a href="http://activemq.apache.org/jndi-support.html#JNDISupport-Dynamicallycreatingdestinations">Dynamically define</a> the QUEUENAME to JNDI</td></tr>
<tr><td>Topic Reference</td><td>dynamicTopics/TOPICNAME</td>
<td><a href="http://activemq.apache.org/jndi-support.html#JNDISupport-Dynamicallycreatingdestinations">Dynamically define</a> the TOPICNAME to JNDI</td></tr>
</table>
</p>
</component>
<component name="JMS Subscriber" index="&sect-num;.1.14" width="709" height="498" screenshot="jmssubscriber.png">
<note>BETA CODE - the code is still subject to change</note>
<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></br>
<note>JMeter does not include any JMS implementation jar; this must be downloaded from the JMS provider and put in the lib directory</note>
</description>
<properties>
<property name="Name" required="">Descriptive name for this element that is shown in the tree.</property>
<property name="use JNDI properties file" required="Yes">use jndi.properties.
Note that the file must be on the classpath - e.g. by updating the user.classpath JMeter property.
If this option is not selected, JMeter uses the "JNDI Initial Context Factory" and "Provider URL" fields
to create the connection.
</property>
<property name="JNDI Initial Context Factory" required="No">Name of the context factory</property>
<property name="Provider URL" required="No">The URL for the jms provider</property>
<property name="Destination" required="Yes">the message destination (topic or queue name)</property>
<property name="Durable Subscription ID" required="No">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.</property>
<property name="Client ID" required="No">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.</property>
<property name="JMS Selector" required="No">Message Selector as defined by JMS specification to extract only
messages that respect the Selector condition. Syntax uses subpart of SQL 92.</property>
<property name="Setup" required="Yes">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)</property>
<property name="Authentication" required="Yes">Authentication requirement for the JMS provider</property>
<property name="User" required="No">User Name</property>
<property name="Password" required="No">Password (N.B. this is stored unencrypted in the test plan)</property>
<property name="Number of samples to aggregate" required="Yes">number of samples to aggregate</property>
<property name="Read response" required="Yes">should the sampler read the response. If not, only the response length is returned.</property>
<property name="Timeout" required="Yes">Specify the timeout to be applied, in milliseconds. 0=none.
This is the overall aggregate timeout, not per sample.</property>
<property name="Client" required="Yes">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.
This is best suited to Topic subscriptions.</li>
</ul>
</property>
<property name="Stop between samples?" required="Yes">
If selected, then JMeter calls Connection.stop() at the end of each sample (and calls start() before each sample).
This may be useful in some cases where multiple samples/threads have connections to the same queue.
If not selected, JMeter calls Connection.start() at the start of the thread, and does not call stop() until the end of the thread.
</property>
<property name="Separator" required="No">
Separator used to separate messages when there is more than one (related to setting Number of samples to aggregate).
Note that \n, \r, \t are accepted.
</property>
</properties>
<p>
<b>NOTE:</b> JMeter 2.3.4 and earlier used a different strategy for the MessageConsumer.receive() client.
Previously this started a background thread which polled for messages. This thread continued when the sampler
completed, so the net effect was similar to the MessageListener.onMessage() strategy.
</p>
</component>
<component name="JMS Point-to-Point" index="&sect-num;.1.15" width="746" height="662" screenshot="jms/JMS_Point-to-Point.png">
<note>BETA CODE - the code is still subject to change</note>
<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>
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></br>
<note>JMeter does not include any JMS implementation jar; this must be downloaded from the JMS provider and put in the lib directory</note>
</description>
<properties>
<property name="Name" required="">Descriptive name for this element that is shown in the tree.</property>
<property name="QueueConnection Factory" required="Yes">
The JNDI name of the queue connection factory to use for connecting to the messaging system.
</property>
<property name="JNDI Name Request queue" required="Yes">
This is the JNDI name of the queue to which the messages are sent.
</property>
<property name="JNDI Name Reply queue" required="No">
The JNDI name of the receiving queue. If a value is provided here and the communication style is Request Response
this queue will be monitored for responses to the requests sent.
</property>
<property name="JMS Selector" required="No">
Message Selector as defined by JMS specification to extract only
messages that respect the Selector condition. Syntax uses subpart of SQL 92.
</property>
<property name="Communication style" required="Yes">
The Communication style can be Request Only (also known as Fire and Forget) or Request Reply.
Request Only will only sent messages and will not monitor replies. As such it can be used to put load on a system.
Request Reply will sent messages and monitor the replies it receives. Behaviour is depended on the value of the JNDI Name Reply Queue.
If JNDI Name Reply Queue has a value, this queue is used to monitor the results. Matching of request and reply is done with
the message id of the request with the correlation id of the reply. If the JNDI Name Reply Queue is empty, then
temporary queues will be used for the communication between the requestor and the server. This is very different from
the fixed reply queue. With temporary queues the diffent threads will block until the reply message has been received.
</property>
<property name="Use alternate fields for message correlation" required="Yes">
These check-boxes select the fields which will be used for matching the response message with the original request.
<ul>
<li>Use Request Message Id - if selected, the request JMSMessageID will be used,
otherwise the request JMSCorrelationID will be used.
In the latter case the correlation id must be specified in the request.</li>
<li>Use Response Message Id - if selected, the response JMSMessageID will be used,
otherwise the response JMSCorrelationID will be used.
</li>
</ul>
There are two frequently used JMS Correlation patterns:
<ul>
<li>JMS Correlation ID Pattern -
i.e. match request and response on their correlation Ids
=> deselect both checkboxes, and provide a correlation id.</li>
<li>JMS Message ID Pattern -
i.e. match request message id with response correlation id
=> select "Use Request Message Id" only.
</li>
</ul>
In both cases the JMS application is responsible for populating the correlation ID as necessary.
<b>Note:</b> if the same queue is used to send and receive messages,
then the response message will be the same as the request message.
In which case, either provide a correlation id and clear both checkboxes;
or select both checkboxes to use the message Id for correlation.
This can be useful for checking raw JMS throughput.
</property>
<property name="Timeout" required="Yes">
The timeout in milliseconds for the reply-messages. If a reply has not been received within the specified
time, the specific testcase failes and the specific reply message received after the timeout is discarded.
</property>
<property name="Use non-persistent delivery mode?" required="Yes">
Whether to set DeliveryMode.NON_PERSISTENT.
</property>
<property name="Content" required="No">
The content of the message.
</property>
<property name="JMS Properties" required="No">
The JMS Properties are properties specific for the underlying messaging system.
For example: for WebSphere 5.1 web services you will need to set the JMS Property targetService to test
webservices through JMS.
</property>
<property name="Initial Context Factory" required="No">
The Initial Context Factory is the factory to be used to look up the JMS Resources.
</property>
<property name="JNDI properties" required="No">
The JNDI Properties are the specific properties for the underlying JNDI implementation.
</property>
<property name="Provider URL" required="No">
The URL for the jms provider.
</property>
</properties>
</component>
<component name="JUnit Request" index="&sect-num;.1.16" width="397" height="536" screenshot="junit_sampler.png">
<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.
<br></br>1. 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.
<br></br>2. 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.
<br></br>3. Junit sampler does not use name/value pairs for configuration like the JavaSampler. The sampler assumes setUp and tearDown will configure the test correctly.
<br></br>4. The sampler measures the elapsed time only for the test method and does not include setUp and tearDown.
<br></br>5. Each time the test method is called, Jmeter will pass the result to the listeners.
<br></br>6. 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.
<br></br>7. 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".<br></br>
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:&lt;br>
&lt;br>
Empty Constructor:&lt;br>
public class myTestCase {&lt;br>
public myTestCase() {}&lt;br>
}&lt;br>
&lt;br>
String Constructor:&lt;br>
public class myTestCase {&lt;br>
public myTestCase(String text) {&lt;br>
super(text);&lt;br>
}&lt;br>
}&lt;br>
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.&lt;br>
General Guidelines<br></br>
If you use setUp and tearDown, make sure the methods are declared public. If you do not, the test may not run properly.
<br></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.&lt;br>
&lt;br>
1. Write the setUp and tearDown methods so they are thread safe. This generally means avoid using static memebers.&lt;br>
2. 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.&lt;br>
3. 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.&lt;br>
4. If a test method is configurable, be careful about where the properties are stored. Reading the properties from the Jar file is recommended.&lt;br>
5. Each sampler creates an instance of the test class, so write your test so the setup happens in oneTimeSetUp and oneTimeTearDown.
</description>
<properties>
<property name="Name" required="">Descriptive name for this element that is shown in the tree.</property>
<property name="Search for JUnit4 annotations" required="Yes">Select this to search for JUnit 4 tests (@Test annotations)</property>
<property name="Package filter" required="">Comma separated list of packages to show. Example, org.apache.jmeter,junit.framework.</property>
<property name="Class name" required="Yes">Fully qualified name of the JUnit test class.</property>
<property name="Constructor string" required="">String pass to the string constructor. If a string is set, the sampler will use the
string constructor instead of the empty constructor.</property>
<property name="Test method" required="Yes">The method to test.</property>
<property name="Success message" required="">A descriptive message indicating what success means.</property>
<property name="Success code" required="">An unique code indicating the test was successful.</property>
<property name="Failure message" required="">A descriptive message indicating what failure means.</property>
<property name="Failure code" required="">An unique code indicating the test failed.</property>
<property name="Error message" required="">A description for errors.</property>
<property name="Error code" required="">Some code for errors. Does not need to be unique.</property>
<property name="Do not call setUp and tearDown" required="Yes">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.</property>
<property name="Append assertion errors" required="Yes">Whether or not to append assertion errors to the response message.</property>
<property name="Append runtime exceptions" required="Yes">Whether or not to append runtime exceptions to the response message. Only applies if "Append assertion errors" is not selected.</property>
<property name="Create a new Instance per sample" required="Yes">Whether or not to create a new JUnit instance for each sample. Defaults to false, meaning JUnit TestCase is created one and reused.</property>
</properties>
<p>
The following JUnit4 annotations are recognised:
<ul>
<li>@Test - used to find test methods and classes. The "expected" and "timeout" attributes are supported.</li>
<li>@Before - treated the same as setUp() in JUnit3</li>
<li>@After - treated the same as tearDown() in JUnit3</li>
<li>@BeforeClass, @AfterClass - treated as test methods so they can be run independently as required</li>
</ul>
</p>
<p>
Note that JMeter currently runs the test methods directly, rather than leaving it to JUnit.
This is to allow the setUp/tearDown methods to be excluded from the sample time.
</p>
</component>
<component name="Mail Reader Sampler" index="&sect-num;.1.17" width="547" height="409" screenshot="mailreader_sampler.png">
<description>
<p>
The Mail Reader Sampler can read (and optionally delete) mail messages using POP3(S) or IMAP(S) protocols.
</p>
</description>
<properties>
<property name="Name" required="">Descriptive name for this element that is shown in the tree.</property>
<property name="Server Type" required="Yes">The protocol used by the provider: e.g. pop3, pop3s, imap, imaps.
or another string representing the server protocol.
For example <code>file</code> for use with the read-only mail file provider.
The actual provider names for POP3 and IMAP are <code>pop3</code> and <code>imap</code>
</property>
<property name="Server" required="Yes">Hostname or IP address of the server. See below for use with <code>file</code> protocol.</property>
<property name="Port" required="No">Port to be used to connect to the server (optional)</property>
<property name="Username" required="">User login name</property>
<property name="Password" required="">User login password (N.B. this is stored unencrypted in the test plan)</property>
<property name="Folder" required="Yes, if using IMAP(S)">The IMAP(S) folder to use. See below for use with <code>file</code> protocol.</property>
<property name="Number of messages to retrieve" required="Yes">Set this to retrieve all or some messages</property>
<property name="Delete messages from the server" required="Yes">If set, messages will be deleted after retrieval</property>
<property name="Store the message using MIME" required="Yes">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.
</property>
<property name="Use no security features" required="">Indicates that the connection to the server does not use any security protocol.</property>
<property name="Use SSL" required="">Indicates that the connection to the server must use the SSL protocol.</property>
<property name="Use StartTLS" required="">Indicates that the connection to the server should attempt to start the TLS protocol.</property>
<property name="Enforce StartTLS" required="">If the server does not start the TLS protocol the connection will be terminated.</property>
<property name="Trust All Certificates" required="">When selected it will accept all certificates independent of the CA.</property>
<property name="Use local truststore" required="">When selected it will only accept certificates that are locally trusted.</property>
<property name="Local truststore" required="">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).
</property>
</properties>
<p>
Messages are stored as subsamples of the main sampler.
In versions of JMeter after 2.3.4, multipart message parts are stored as subsamples of the message.
</p>
<p>
<b>Special handling for "file" protocol:</b><br></br>
The <code>file</code> JavaMail provider can be used to read raw messages from files.
The <code>server</code> field is used to specify the path to the parent of the <code>folder</code>.
Individual message files should be stored with the name <code>n.msg</code>,
where <code>n</code> is the message number.
Alternatively, the <code>server</code> field can be the name of a file which contains a single message.
The current implementation is quite basic, and is mainly intended for debugging purposes.
</p>
</component>
<component name="Test Action" index="&sect-num;.1.18" width="467" height="184" screenshot="test_action.png">
<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>
<p>
The "Stop" action stops the thread or test after completing any samples that are in progress.
The "Stop Now" action stops the test without waiting for samples to complete; it will interrupt any active samples.
If some threads fail to stop within the 5 second time-limit, a message will be displayed in GUI mode.
You can try using the Stop command to see if this will stop the threads, but if not, you should exit JMeter.
In non-GUI mode, JMeter will exit if some threads fail to stop within the 5 second time limit.
[This can be changed using the JMeter property <code>jmeterengine.threadstop.wait</code>]
</p>
</description>
<properties>
<property name="Name" required="">Descriptive name for this element that is shown in the tree.</property>
<property name="Target" required="Yes">Current Thread / All Threads (ignored for Pause)</property>
<property name="Action" required="Yes">Pause / Stop / Stop Now</property>
<property name="Duration" required="Yes, if Pause is selected">How long to pause for (milliseconds)</property>
</properties>
</component>
<component name="SMTP Sampler" index="&sect-num;.1.19" width="713" height="802" screenshot="smtp_sampler.png">
<description>
<p>
The SMTP Sampler can send mail messages using SMTP/SMTPS protocol.
It is possible to set security propocols for the connection (SSL and TLS), as well as user authentication.
If a security protocol is used a verification on the server certificate will occur. <br></br>
Two alternatives to handle this verification are available:<br></br>
<ul>
<li>Trust all certificates. This will ignore certificate chain verification</li>
<li>Use a local truststore. With this option the certificate chain will be validated against the local truststore file.</li>
</ul>
</p>
</description>
<properties>
<property name="Server" required="Yes">Hostname or IP address of the server. See below for use with <code>file</code> protocol.</property>
<property name="Port" required="No">Port to be used to connect to the server.
Defaults are: SMTP=25, SSL=465, StartTLS=587
</property>
<property name="Address From" required="Yes">The from address that will appear in the e-mail</property>
<property name="Address To" required="Yes, unless CC or BCC is specified">The destination e-mail address (multiple values separated by ";")</property>
<property name="Address To CC" required="No">Carbon copy destinations e-mail address (multiple values separated by ";")</property>
<property name="Address To BCC" required="No">Blind carbon copy destinations e-mail address (multiple values separated by ";")</property>
<property name="Address Reply-To" required="No">Alternate Reply-To address (multiple values separated by ";")</property>
<property name="Use Auth" required="">Indicates if the SMTP server requires user authentication</property>
<property name="Username" required="">User login name</property>
<property name="Password" required="">User login password (N.B. this is stored unencrypted in the test plan)</property>
<property name="Use no security features" required="">Indicates that the connection to the SMTP server does not use any security protocol.</property>
<property name="Use SSL" required="">Indicates that the connection to the SMTP server must use the SSL protocol.</property>
<property name="Use StartTLS" required="">Indicates that the connection to the SMTP server should attempt to start the TLS protocol.</property>
<property name="Enforce StartTLS" required="">If the server does not start the TLS protocol the connection will be terminated.</property>
<property name="Trust All Certificates" required="">When selected it will accept all certificates independent of the CA.</property>
<property name="Use local truststore" required="">When selected it will only accept certificates that are locally trusted.</property>
<property name="Local truststore" required="">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).
</property>
<property name="Subject" required="">The e-mail message subject.</property>
<property name="Suppress Subject Header" required="">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.</property>
<property name="Include timestamp in subject" required="">Includes the System.currentTimemilis() in the subject line.</property>
<property name="Add Header" required="No">Additional headers can be defined using this button.</property>
<property name="Message" required="">The message body.</property>
<property name="Send plain body (i.e. not multipart/mixed)">
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.
</property>
<property name="Attach files" required="">Files to be attached to the message.</property>
<property name="Send .eml" required="">If set, the .eml file will be sent instead of the entries in the Subject, Message, and Attached files</property>
<property name="Calculate message size" required="">Calculates the message size and stores it in the sample result.</property>
<property name="Enable debug logging?" required="">If set, then the "mail.debug" property is set to "true"</property>
</properties>
</component>
<component name="OS Process Sampler" index="&sect-num;.1.20" width="656" height="465" screenshot="os_process_sampler.png">
<description>
<p>
The OS Process Sampler is a sampler that can be used to execute commands on the local machine.<br></br>
It should allow execution of any command that can be run from the command line.<br></br>
Validation of the return code can be enabled, and the expected return code can be specified.<br></br>
</p>
<p>
Note that OS shells generally provide command-line parsing.
This varies between OSes, but generally the shell will split parameters on white-space.
Some shells expand wild-card file names; some don't.
The quoting mechanism also varies between OSes.
The sampler deliberately does not do any parsing or quote handling.
The command and its parameters must be provided in the form expected by the executable.
This means that the sampler settings will not be portable between OSes.
</p>
<p>
Many OSes have some built-in commands which are not provided as separate executables.
For example the Windows DIR command is part of the command interpreter (CMD.EXE).
These built-ins cannot be run as independent programs, but have to be provided as arguments to the appropriate command interpreter.
<br/>
For example, the Windows command-line: <b><code>DIR C:\TEMP</code></b> needs to be specified as follows:
<pre>
command: CMD
Param 1: /C
Param 2: DIR
Param 3: C:\TEMP
</pre>
</p>
</description>
<properties>
<property name="Check Return Code" required="No">If checked, sampler will compare return code with Expected Return Code.</property>
<property name="Expected Return Code" required="No">Expected return code for System Call, required if "Check Return Code" is checked.</property>
<property name="Directory" required="No">Directory from which command will be executed, defaults to folder referenced by "user.dir" System property</property>
<property name="Command" required="Yes">The System command or shell to execute.</property>
<property name="OS Process Parameters" required="No">Parameters passed to process.</property>
<property name="Environment Parameters" required="No">Key/Value pairs added to environment when running command.</property>
</properties>
</component>
<a href="#">^</a>
</section>
<section name="&sect-num;.2 Logic Controllers" anchor="logic_controllers">
<description>
<br>Logic Controllers determine the order in which Samplers are processed.</br>
</description>
<component name="Simple Controller" index="&sect-num;.2.1" anchor="simple_controller" width="330" height="77" screenshot="logic-controller/simple-controller.png">
<description>
<p>The Simple Logic Controller lets you organize your Samplers and other
Logic Controllers. Unlike other Logic Controllers, this controller provides no functionality beyond that of a
storage device.</p>
</description>
<properties>
<property name="Name" required="No">Descriptive name for this controller that is shown in the tree.</property>
</properties>
<example title="Using the Simple Controller" anchor="simple_controller_example">
<p><a href="../demos/SimpleTestPlan.jmx">Download</a> this example (see Figure 6).
In this example, we created a Test Plan that sends two Ant HTTP requests and two
Log4J HTTP requests. We grouped the Ant and Log4J requests by placing them inside
Simple Logic Controllers. Remember, the Simple Logic Controller has no effect on how JMeter
processes the controller(s) you add to it. So, in this example, JMeter sends the requests in the
following order: Ant Home Page, Ant News Page, Log4J Home Page, Log4J History Page.
Note, the File Reporter
is configured to store the results in a file named "simple-test.dat" in the current directory.</p>
<figure width="546" height="222" image="logic-controller/simple-example.png">Figure 6 Simple Controller Example</figure>
</example>
</component>
<component name="Loop Controller" index="&sect-num;.2.2" anchor="loop" width="326" height="114" screenshot="logic-controller/loop-controller.png">
<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.
</p></description>
<properties>
<property name="Name" required="No">Descriptive name for this controller that is shown in the tree.</property>
<property name="Loop Count" required="Yes, unless &quot;Forever&quot; is checked">
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 <a href="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></property>
</properties>
<example title="Looping Example" anchor="loop_example">
<p><a href="../demos/LoopTestPlan.jmx">Download</a> this example (see Figure 4).
In this example, we created a Test Plan that sends a particular HTTP Request
only once and sends another HTTP Request five times.</p>
<figure width="548" height="160" image="logic-controller/loop-example.png">Figure 4 - Loop Controller Example</figure>
<p>We configured the Thread Group for a single thread and a loop count value of
one. Instead of letting the Thread Group control the looping, we used a Loop
Controller. You can see that we added one HTTP Request to the Thread Group and
another HTTP Request to a Loop Controller. We configured the Loop Controller
with a loop count value of five.</p>
<p>JMeter will send the requests in the following order: Home Page, News Page,
News Page, News Page, News Page, and News Page. Note, the File Reporter
is configured to store the results in a file named "loop-test.dat" in the current directory.</p>
</example>
</component>
<component name="Once Only Controller" index="&sect-num;.2.3" anchor="once_only_controller" width="330" height="78" screenshot="logic-controller/once-only-controller.png">
<description>
<p>The Once Only Logic Controller tells JMeter to process the controller(s) inside it only once, 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), but now the user has more flexibility in the use of the Once Only Controller.</p>
<p>For testing that requires a login, consider placing the login request in this controller since each thread only needs
to login once to establish a session.</p>
</description>
<properties>
<property name="Name" required="No">Descriptive name for this controller that is shown in the tree.</property>
</properties>
<example title="Once Only Example" anchor="once_only_example">
<p><a href="../demos/OnceOnlyTestPlan.jmx">Download</a> this example (see Figure 5).
In this example, we created a Test Plan that has two threads that send HTTP request.
Each thread sends one request to the Home Page, followed by three requests to the Bug Page.
Although we configured the Thread Group to iterate three times, each JMeter thread only
sends one request to the Home Page because this request lives inside a Once Only Controller.</p>
<figure width="348" height="131" image="logic-controller/once-only-example.png">Figure 5. Once Only Controller Example</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>
</example>
<note>The behaviour of the Once Only controller under anything other than the
Thread Group or a Loop Controller is not currently defined. Odd things may happen.</note>
</component>
<component name="Interleave Controller" index="&sect-num;.2.4" width="329" height="104" screenshot="logic-controller/interleave-controller.png">
<description><p>If you add Generative or Logic Controllers to an Interleave Controller, JMeter will alternate among each of the
other controllers for each loop iteration. </p>
</description>
<properties>
<property name="name" required="No">Descriptive name for this controller that is shown in the tree.</property>
<property name="ignore sub-controller blocks" required="No">If checked, the interleave controller will treat sub-controllers like single request elements and only allow one request per controller at a time. </property>
</properties>
<!--
For example, if you
add three HTTP Requests to an Interleave Controller and configure the Thread
Group to loop, here is the sequence in which JMeter sends the requests:
</p>
<table border="1" cellspacing="0" cellpadding="4">
<tr valign="top"><th>Loop Iteration</th><th>Description</th></tr>
<tr valign="top"><td>1</td><td>JMeter sends the first HTTP Request.</td></tr>
<tr valign="top"><td>2</td><td>JMeter sends the second HTTP Request.</td></tr>
<tr valign="top"><td>3</td><td>JMeter sends the third HTTP Request.</td></tr>
<tr valign="top"><td>4</td><td>Because there are no more requests in controller, JMeter start over and sends the first HTTP Request.</td></tr>
<tr valign="top"><td>5</td><td>JMeter sends the second HTTP Request.</td></tr>
<tr valign="top"><td>(and so on)</td><td>...</td></tr>
</table>
-->
<example title="Simple Interleave Example" anchor="simple_interleave_example">
<p><a href="../demos/InterleaveTestPlan.jmx">Download</a> this example (see Figure 1). In this example,
we configured the Thread Group to have two threads and a loop count of five, for a total of ten
requests per thread. See the table below for the sequence JMeter sends the HTTP Requests.</p>
<figure width="336" height="153" image="logic-controller/interleave.png">Figure 1 - Interleave Controller Example 1</figure>
<table border="1" cellspacing="0" cellpadding="4">
<tr valign="top"><th>Loop Iteration</th><th>Each JMeter Thread Sends These HTTP Requests</th></tr>
<tr valign="top"><td>1</td><td>News Page</td></tr>
<tr valign="top"><td>1</td><td>Log Page</td></tr>
<tr valign="top"><td>2</td><td>FAQ Page</td></tr>
<tr valign="top"><td>2</td><td>Log Page</td></tr>
<tr valign="top"><td>3</td><td>Gump Page</td></tr>
<tr valign="top"><td>3</td><td>Log Page</td></tr>
<tr valign="top"><td>4</td><td>Because there are no more requests in the controller,<br> </br> JMeter starts over and sends the first HTTP Request, which is the News Page.</td></tr>
<tr valign="top"><td>4</td><td>Log Page</td></tr>
<tr valign="top"><td>5</td><td>FAQ Page</td></tr>
<tr valign="top"><td>5</td><td>Log Page</td></tr>
</table>
</example>
<example title="Useful Interleave Example" anchor="useful_interleave_example">
<p><a href="../demos/InterleaveTestPlan2.jmx">Download</a> another example (see Figure 2). In this
example, we configured the Thread Group
to have a single thread and a loop count of eight. Notice that the Test Plan has an outer Interleave Controller with
two Interleave Controllers inside of it.</p>
<figure width="207" height="249" image="logic-controller/interleave2.png">
Figure 2 - Interleave Controller Example 2
</figure>
<p>The outer Interleave Controller alternates between the
two inner ones. Then, each inner Interleave Controller alternates between each of the HTTP Requests. Each JMeter
thread will send the requests in the following order: Home Page, Interleaved, Bug Page, Interleaved, CVS Page, Interleaved, and FAQ Page, Interleaved.
Note, the File Reporter is configured to store the results in a file named "interleave-test2.dat" in the current directory.</p>
<figure width="204" height="247" image="logic-controller/interleave3.png">
Figure 3 - Interleave Controller Example 3
</figure>
<p>If the two interleave controllers under the main interleave controller were instead simple controllers, then the order would be: Home Page, CVS Page, Interleaved, Bug Page, FAQ Page, Interleaved. 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>
</example>
</component>
<component name="Random Controller" index="&sect-num;.2.5" width="328" height="100" screenshot="logic-controller/random-controller.png">
<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>
<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</note>
</description>
<properties>
<property name="Name" required="No">Descriptive name for this controller that is shown in the tree.</property>
</properties>
</component>
<component name="Random Order Controller" index="&sect-num;.2.6" width="328" height="76" screenshot="randomordercontroller.png">
<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>
</description>
<properties>
<property name="Name" required="No">Descriptive name for this controller that is shown in the tree.</property>
</properties>
</component>
<component name="Throughput Controller" index="&sect-num;.2.7" width="329" height="167" screenshot="throughput_controller.png">
<description>
<p>
<b>This controller is badly named, as it does not control throughput.</b>
Please refer to the <complink name="Constant Throughput Timer"/> 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>
</description>
<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).</note>
<properties>
<property name="Name" required="No">Descriptive name for this controller that is shown in the tree.</property>
<property name="Execution Style" required="Yes">Whether the controller will run in percent executions or total executions mode.</property>
<property name="Throughput" required="Yes">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.</property>
<property name="Per User" required="No">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.</property>
</properties>
</component>
<component name="Runtime Controller" index="&sect-num;.2.8" width="328" height="100" screenshot="runtimecontroller.png">
<description>
<p>The Runtime Controller controls how long its children are allowed to run.
</p>
</description>
<properties>
<property name="Name" required="Yes">Descriptive name for this controller that is shown in the tree, and used to name the transaction.</property>
<property name="Runtime (seconds)" required="Yes">Desired runtime in seconds</property>
</properties>
</component>
<component name="If Controller" index="&sect-num;.2.9" width="497" height="131" screenshot="ifcontroller.png">
<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:
<code>${__jexl(${VAR} == 23)}</code> 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>
<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.
</note>
</description>
<properties>
<property name="Name" required="No">Descriptive name for this controller that is shown in the tree.</property>
<property name="Condition (default Javascript)" required="Yes">By default the condition is interpreted as <b>Javascript</b> code that returns "true" or "false",
but this can be overriden (see below)</property>
<property name="Interpret Condition as Variable Expression?" required="Yes">If this is selected, then the condition must be an expression that evaluates to "true" (case is ignored).
For example, <code>${FOUND}</code> or <code>${__jexl(${VAR} > 100)}</code>.
Unlike the Javascript case, the condition is only checked to see if it matches "true" (case is ignored).
</property>
<property name="Evaluate for all children" required="Yes">
Should condition be evaluated for all children?
If not checked, then the condition is only evaluated on entry.
</property>
</properties>
<p><b>Examples (Javascript):</b>
<ul>
<li>${COUNT} &lt; 10</li>
<li>"${VAR}" == "abcd"</li>
<li>${JMeterThread.last_sample_ok} (check if last sample succeeded)</li>
</ul>
If there is an error interpreting the code, the condition is assumed to be false, and a message is logged in jmeter.log.
</p>
<p><b>Examples (Variable Expression):</b>
<ul>
<li>${__jexl(${COUNT} &lt; 10)}</li>
<li>${RESULT}</li>
</ul>
</p>
</component>
<component name="While Controller" index="&sect-num;.2.10" width="362" height="102" screenshot="whilecontroller.png">
<description>
<p>
The While Controller runs its children until the condition is "false".
</p>
<p>Possible condition values:</p>
<ul>
<li>blank - exit loop when last sample in loop fails</li>
<li>LAST - exit loop when last sample in loop fails.
If the last sample just before the loop failed, don't enter loop.</li>
<li>Otherwise - exit (or don't enter) the loop when the condition is equal to the string "false"</li>
</ul>
<note>
The condition can be any variable or function that eventually evaluates to the string "false".
This allows the use of JavaScript, BeanShell, properties or variables as needed.
</note>
<br></br>
<note>
Note that the is evaluated twice, once before starting sampling children and once at end of children sampling, so putting
non idempotent functions in Condition (like __counter) can introduce issues.
</note>
<br></br>
For example:
<ul>
<li>${VAR} - where VAR is set to false by some other test element</li>
<li>${__javaScript(${C}==10)}</li>
<li>${__javaScript("${VAR2}"=="abcd")}</li>
<li>${_P(property)} - where property is set to "false" somewhere else</li>
</ul>
</description>
<properties>
<property name="Name" required="Yes">Descriptive name for this controller that is shown in the tree, and used to name the transaction.</property>
<property name="Condition" required="Yes">blank, LAST, or variable/function</property>
</properties>
</component>
<component name="Switch Controller" index="&sect-num;.2.11" width="361" height="106" screenshot="switchcontroller.png">
<description>
<p>
The Switch Controller acts like the <complink name="Interleave Controller"/>
in that it runs one of the subordinate elements on each iteration, but rather than
run them in sequence, the controller runs the element defined by the switch value.
</p>
<p>
Note: In versions of JMeter after 2.3.1, the switch value can also be a name.
</p>
<p>If the switch value is out of range, it will run the zeroth element,
which therefore acts as the default for the numeric case.
It also runs the zeroth element if the value is the empty string.</p>
<p>
If the value is non-numeric (and non-empty), then the Switch Controller looks for the
element with the same name (case is significant).
If none of the names match, then the element named "default" (case not significant) is selected.
If there is no default, then no element is selected, and the controller will not run anything.
</p>
</description>
<properties>
<property name="Name" required="Yes">Descriptive name for this controller that is shown in the tree, and used to name the transaction.</property>
<property name="Switch Value" required="Yes">The number (or name) of the subordinate element to be invoked. Elements are numbered from 0.</property>
</properties>
</component>
<component name="ForEach Controller" index="&sect-num;.2.12" anchor="loop" width="380" height="152" screenshot="logic-controller/foreach-controller.png">
<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>
<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.</note>
</description>
<properties>
<property name="Name" required="No">Descriptive name for this controller that is shown in the tree.</property>
<property name="Input variable prefix" required="Yes">Prefix for the variable names to be used as input.</property>
<property name="Output variable" required="Yes">
The name of the variable which can be used in the loop for replacement in the samplers</property>
<property required="Yes" name="Use Separator">If not checked, the "_" separator is omitted.</property>
</properties>
<example title="ForEach Example" anchor="foreach_example">
<p><a href="../demos/forEachTestPlan.jmx">Download</a> this example (see Figure 7).
In this example, we created a Test Plan that sends a particular HTTP Request
only once and sends another HTTP Request to every link that can be found on the page.</p>
<figure width="246" height="154" image="logic-controller/foreach-example.png">Figure 7 - ForEach Controller Example</figure>
<p>We configured the Thread Group for a single thread and a loop count value of
one. You can see that we added one HTTP Request to the Thread Group and
another HTTP Request to the ForEach Controller.</p>
<p>After the first HTTP request, a regular expression extractor is added, which extracts all the html links
out of the return page and puts them in the inputVar variable</p>
<p>In the ForEach loop, a HTTP sampler is added which requests all the links that were extracted from the first returned HTML page.
</p></example>
<example title="ForEach Example" anchor="foreach_example2">
<p>Here is <a href="../demos/ForEachTest2.jmx">another example</a> you can download.
This has two Regular Expressions and ForEach Controllers.
The first RE matches, but the second does not match,
so no samples are run by the second ForEach Controller</p>
<figure width="198" height="253" image="logic-controller/foreach-example2.png">Figure 8 - ForEach Controller Example 2</figure>
<p>The Thread Group has a single thread and a loop count of two.
</p><p>
Sample 1 uses the JavaTest Sampler to return the string "a b c d".
</p><p>The Regex Extractor uses the expression <b>(\w)\s</b> which matches a letter followed by a space,
and returns the letter (not the space). Any matches are prefixed with the string "inputVar".
</p><p>The ForEach Controller extracts all variables with the prefix "inputVar_", and executes its
sample, passing the value in the variable "returnVar". In this case it will set the variable to the values "a" "b" and "c" in turn.
</p><p>The For 1 Sampler is another Java Sampler which uses the return variable "returnVar" as part of the sample Label
and as the sampler Data.
</p><p>Sample 2, Regex 2 and For 2 are almost identical, except that the Regex has been changed to "(\w)\sx",
which clearly won't match. Thus the For 2 Sampler will not be run.
</p>
</example>
</component>
<component name="Module Controller" index="&sect-num;.2.13" width="504" height="217" screenshot="module_controller.png">
<description>
<p>
The Module Controller provides a mechanism for substituting test plan fragments into the current test plan at run-time.
</p>
<p>
A test plan fragment consists of a Controller and all the test elements (samplers etc) contained in it.
The fragment can be located in any Thread Group, or on the <complink name="WorkBench" />.
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>
</description>
<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.</note>
<properties>
<property name="Name" required="No">Descriptive name for this controller that is shown in the tree.</property>
<property name="Module to Run" required="Yes">The module controller provides a list of all controllers loaded into the gui. Select
the one you want to substitute in at runtime.</property>
</properties>
</component>
<component name="Include Controller" index="&sect-num;.2.14" width="417" height="130" screenshot="includecontroller.png">
<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.
</p>
<note>
This element does not support variables/functions in the filename field.<br></br>
However, if the property <b>includecontroller.prefix</b> is defined,
the contents are used to prefix the pathname.
</note>
<note>
When using IncludeController and including the same JMX file, ensure you name the IncludeController differently to avoid facing known issue 50898.
</note>
<p>
If the file cannot be found at the location given by prefix+filename, then the controller
attempts to open the fileName relative to the JMX launch directory (versions of JMeter after 2.3.4).
</p>
</description>
<properties>
<property name="Filename" required="Yes">The file to include.</property>
</properties>
</component>
<component name="Transaction Controller" index="&sect-num;.2.15" width="378" height="129" screenshot="transactioncontroller.png">
<description>
<p>
The Transaction Controller generates an additional
sample which measures the overall time taken to perform the nested test elements.
Note that this time by default includes all processing within the controller scope, not just
the samples, this can be changed by unchecking "Include duration of timer and pre-post processors in generated sample".
</p>
<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>
<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.
</note>
</description>
<properties>
<property name="Name" required="Yes">Descriptive name for this controller that is shown in the tree, and used to name the transaction.</property>
<property name="Generate Parent Sample" required="Yes">
If checked, then the sample is generated as a parent of the other samples,
otherwise the sample is generated as an independent sample.
</property>
<property name="Include duration of timer and pre-post processors in generated sample" required="Yes">
Whether to include timer, pre- and post-processing delays in the generated sample.
Default is true to be compatible with the behaviour in previous versions of JMeter.
Setting it to false is a better option to get only response time of the sample.
</property>
</properties>
</component>
<component name="Recording Controller" index="&sect-num;.2.16" width="420" height="79" screenshot="logic-controller/recording-controller.png">
<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 <complink name="HTTP Proxy Server" />, all recorded samples will by default
be saved under the Recording Controller.</p>
</description>
<properties>
<property name="Name" required="No">Descriptive name for this controller that is shown in the tree.</property>
</properties>
</component>
<a href="#">^</a>
</section>
<section name="&sect-num;.3 Listeners" anchor="listeners">
<description>
<br></br>
Most of the listeners perform several roles in addition to "listening"
to the test results.
They also provide means to view, save, and read saved test results.
<p>Note that Listeners are processed at the end of the scope in which they are found.</p>
<p>
The saving and reading of test results is generic. The various
listeners have a panel whereby one can specify the file to
which the results will be written (or read from).
By default, the results are stored as XML
files, typically with a ".jtl" extension.
Storing as CSV is the most efficient option, but is less detailed than XML (the other available option).
</p>
<p>
<b>Listeners do <i>not</i> process sample data in non-GUI mode, but the raw data will be saved if an output
file has been configured.</b>
In order to analyse the data generated by a non-GUI test run, you need to load the file into the appropriate
Listener.
</p>
<note>
To read existing results and display them, use the file panel Browse button to open the file.
</note>
<p>
Versions of JMeter up to 2.3.2 <b>used to clear any current data</b> before loading the new file.<br></br>
This is no longer done, thus <b>allowing files to be merged</b>.
If the previous behaviour is required,
use the menu item Run/Clear (Ctrl+Shift+E) or Run/Clear All (Ctrl+E) before loading the file.
</p>
<p>Results can be read from XML or CSV format files.
When reading from CSV results files, the header (if present) is used to determine which fields are present.
<b>In order to interpret a header-less CSV file correctly, the appropriate properties must be set in jmeter.properties.</b>
</p>
<note>
The file name can contain function and/or variable references.
However variable references do not work in client-server mode (functions work OK).
</note>
<p><b>Listeners can use a lot of memory if there are a lot of samples.</b>
Most of the listeners currently keep a copy of every sample in their scope, apart from:
</p>
<ul>
<li>Simple Data Writer</li>
<li>BeanShell/BSF Listener</li>
<li>Mailer Visualizer</li>
<li>Monitor Results</li>
<li>Summary Report</li>
</ul>
<p>
The following Listeners no longer need to keep copies of every single sample.
Instead, samples with the same elapsed time are aggregated.
Less memory is now needed, especially if most samples only take a second or two at most.
</p>
<ul>
<li>Aggregate Report</li>
<li>Aggregate Graph</li>
<li>Distribution Graph</li>
</ul>
<p>To minimise the amount of memory needed, use the Simple Data Writer, and use the CSV format.</p>
<p>
<note>
Versions of JMeter after 2.3.1 allow JMeter variables to be saved to the output files.
This can only be specified using a property.
See the <a href="listeners.html#sample_variables">Listener Sample Variables</a> for details
</note>
For full details on setting up the default items to be saved
see the <a href="listeners.html#defaults">Listener Default Configuration</a> documentation.
For details of the contents of the output files,
see the <a href="listeners.html#csvlogformat">CSV log</a> format or
the <a href="listeners.html#xmlformat2.1">XML log</a> format.
</p>
<note>The entries in jmeter.properties are used to define the defaults;
these can be overriden for individual listeners by using the Configure button,
as shown below.
The settings in jmeter.properties also apply to the listener that is added
by using the -l command-line flag.
</note>
<p>
The figure below shows an example of the result file configuration panel
<figure width="741" height="141" image="simpledatawriter.png">Result file configuration panel</figure>
</p>
<properties>
<property name="Filename" required="No">Name of the file containing sample results.
The file name can be specified using either a relative or an absolute path name.
Relative paths are resolved relative to the current working directory (which defaults to the 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.
</property>
<property name="Browse..." required="No">File Browse Button</property>
<property name="Errors" required="No">Select this to write/read only results with errors</property>
<property name="Successes" required="No">Select this to write/read only results without errors.
If neither Errors nor Successes is selected, then all results are processed.</property>
<property name="Configure" required="No">Configure Button, see below</property>
</properties>
</description>
<component name="Sample Result Save Configuration" index="&sect-num;.3.1" width="629" height="300" screenshot="sample_result_config.png">
<description>
<p>
Listeners can be configured to save different items to the result log files (JTL) by using the Config popup as shown below.
The defaults are defined as described in the <a href="listeners.html#defaults">Listener Default Configuration</a> documentation.
Items with (CSV) after the name only apply to the CSV format; items with (XML) only apply to XML format.
CSV format cannot currently be used to save any items that include line-breaks.
</p>
<p>
Note that cookies, method and the query string are saved as part of the "Sampler Data" option.
</p>
</description>
</component>
<component name="Graph Results" index="&sect-num;.3.3" width="915" height="686" screenshot="graph_results.png">
<description><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></description>
<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 <a href="glossary.html#Median">Median</a> (midway value)</li>
<li>Deviation - plot the <a href="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>
</component>
<component name="Spline Visualizer" index="&sect-num;.3.4" width="581" height="440" screenshot="spline_visualizer.png">
<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.
</p>
</description>
</component>
<component name="Assertion Results" index="&sect-num;.3.5" width="658" height="277" screenshot="assertion_results.png">
<description><p>The Assertion Results visualizer shows the Label of each sample taken.
It also reports failures of any <a href="test_plan.html#assertions">Assertions</a> that
are part of the test plan.</p></description>
<links>
<complink name="Response Assertion"/>
</links>
</component>
<component name="View Results Tree" index="&sect-num;.3.6" width="869" height="654" screenshot="view_results_tree.png">
<description>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>
<ul>
<li>HTML</li>
<li>HTML (download resources)</li>
<li>JSON</li>
<li>Regexp Tester</li>
<li>Text</li>
<li>XML</li>
</ul>
<p>Scroll automatically? option permit to have last node display in tree selection</p>
<p>
Additional renderers can be created.
The class must implement the interface <code>org.apache.jmeter.visualizers.ResultRenderer</code>
and/or extend the abstract class <code>org.apache.jmeter.visualizers.SamplerResultTab</code>, and the
compiled code must be available to JMeter (e.g. by adding it to the lib/ext directory).
</p>
<p>
The default "Text" view shows all of the text contained in the response.
Note that this will only work if the response content-type is considered to be text.
If the content-type begins with any of the following, it is considered as binary,
otherwise it is considered to be text.
<pre>
image/
audio/
video/
</pre>
If there is no content-type provided, then the content
will not be displayed in the any of the Response Data panels.
You can use <complink name="Save Responses to a file"/> to save the data in this case.
Note that the response data will still be available in the sample result,
so can still be accessed using Post-Processors.
</p>
<p>If the response data is larger than 200K, then it won't be displayed.
To change this limit, set the JMeter property <b>view.results.tree.max_size</b>.
You can also use save the entire response to a file using
<complink name="Save Responses to a file"/>.
</p>
<p>The HTML view attempts to render the response as
HTML. The rendered HTML is likely to compare poorly to the view one
would get in any web browser; however, it does provide a quick
approximation that is helpful for initial result evaluation.
No images etc are downloaded.
If the HTML (download embedded resources) option is selected, the renderer
may download images and style-sheets etc referenced by the HTML.
</p>
<p>The XML view will show response in tree style.
Any DTD nodes or Prolog nodes will not show up in tree; however, response may contain those nodes.
</p>
<p>The JSON view will show the response in tree style (also handles JSON embedded in JavaScript).</p>
<p>
Most of the views also allow the displayed data to be searched; the result of the search will be high-lighted
in the display above. For example the Control panel screenshot below shows one result of searching for "Java".
Note that the search operates on the visible text, so you may get different results when searching
the Text and HTML views.
</p>
<p>The "Regexp Tester" view only works for text responses. It shows the plain text in the upper panel.
The "Test" button allows the user to apply the Regular Expression to the upper panel and the results
will be displayed in the lower panel.
For example, the RE <b>(JMeter\w*).*</b> applied to the current JMeter home page gives the following output:
</p>
<pre>
Match count: 26
Match[1][0]=JMeter - Apache JMeter&amp;lt;/title>
Match[1][1]=JMeter
Match[2][0]=JMeter" title="JMeter" border="0"/>&amp;lt;/a>
Match[2][1]=JMeter
Match[3][0]=JMeterCommitters">Contributors&amp;lt;/a>
Match[3][1]=JMeterCommitters
... and so on ...
</pre>
<p>
The first number in [] is the match number; the second number is the group.
Group [0] is whatever matched the whole RE.
Group [1] is whatever matched the 1st group, i.e. (JMeter\w*) in this case.
See Figure 9b (below).
</p>
</description>
<p>
The Control Panel (above) shows an example of an HTML display.
Figure 9 (below) shows an example of an XML display.
<figure width="873" height="653" image="view_results_tree_xml.png">Figure 9 Sample XML display</figure>
<figure width="858" height="643" image="view_results_tree_regex.png">Figure 9a Sample Regexp Test display</figure>
</p>
</component>
<component name="Aggregate Report" index="&sect-num;.3.7" width="784" height="287" screenshot="aggregate_report.png">
<description>The aggregate report creates a table row for each differently named request in your
test. For each request, it totals the response information and provides request count, min, max,
average, error rate, approximate throughput (request/second) and Kilobytes per second throughput.
Once the test is done, the throughput is the actual through for the duration of the entire test.
<p>
The 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 names correctly to get the best results from
the Aggregate Report.
</p>
<p>
Calculation of the <a href="glossary.html#Median">Median</a> and 90% Line (90<sup>th</sup> <a href="glossary.html#Percentile">percentile</a>) values requires additional memory.
For JMeter 2.3.4 and earlier, details of each sample were saved separately, which meant a lot of memory was needed.
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.
See the <complink name="Summary Report"/> for a similar Listener that does not store individual samples and so needs constant memory.
</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.
</li>
<li># Samples - The number of samples with the same label</li>
<li>Average - The average time of a set of results</li>
<li>Median - The <a href="glossary.html#Median">median</a> is the time in the middle of a set of results.
50% of the samples took no more than this time; the remainder took at least as long.</li>
<li>90% Line - 90% of the samples took no more than this time.
The remaining samples at least as long as this. (90<sup>th</sup> <a href="glossary.html#Percentile">percentile</a>)</li>
<li>Min - The shortest time for the samples with the same label</li>
<li>Max - The longest time for the samples with the same label</li>
<li>Error % - Percent of requests with errors</li>
<li>Throughput - the <a href="glossary.html#Throughput">Throughput</a> is measured in requests per second/minute/hour.
The time unit is chosen so that the displayed rate is at least 1.0.
When the throughput is saved to a CSV file, it is expressed in requests/second,
i.e. 30.0 requests/minute is saved as 0.5.
</li>
<li>Kb/sec - The throughput measured in Kilobytes per second</li>
</ul>
<p>Times are in milliseconds.</p>
</description>
<div align="center">
<p>
The figure below shows an example of selecting the "Include group name" checkbox.
<figure width="784" height="287" image="aggregate_report_grouped.png">Sample "Include group name" display</figure>
</p>
</div>
</component>
<component name="View Results in Table" index="&sect-num;.3.8" width="658" height="700" screenshot="table_results.png">
<description>This visualizer creates a row for every sample result.
Like the <complink name="View Results Tree"/>, this visualizer uses a lot of memory.
<p>
By default, it only displays the main (parent) samples; it does not display the sub-samples (child samples).
Versions of JMeter after 2.5.1 have a "Child Samples?" check-box.
If this is selected, then the sub-samples are displayed instead of the main samples.
</p>
</description>
</component>
<component name="Simple Data Writer" index="&sect-num;.3.9" width="786" height="145" screenshot="simpledatawriter.png">
<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.
See the jmeter.properties file for details.
</description>
</component>
<component name="Monitor Results" index="&sect-num;.3.10" width="762" height="757" screenshot="monitor_screencap.png">
<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>
<note>
The monitor requires Tomcat 5 or above.
Use a browser to check that you can access the Tomcat status servlet OK.
</note>
<p>
For a detailed description of how to use the monitor, please refer to
<a href="build-monitor-test-plan.html">Building a Monitor Test Plan</a>
</p>
</description>
</component>
<component name="Distribution Graph (alpha)" index="&sect-num;.3.11" width="819" height="626" screenshot="distribution_graph.png">
<description>
<p>The distribution graph will display a bar for every unique response time. Since the
granularity of System.currentTimeMillis() is 10 milliseconds, the 90% threshold should be
within the width of the graph. The graph will draw two threshold lines: 50% and 90%.
What this means is 50% of the response times finished between 0 and the line. The same
is true of 90% line. Several tests with Tomcat were performed using 30 threads for 600K
requests. The graph was able to display the distribution without any problems and both
the 50% and 90% line were within the width of the graph. A performant application will
generally produce results that clump together. A poorly written application that has
memory leaks may result in wild fluctuations. In those situations, the threshold lines
may be beyond the width of the graph. The recommended solution to this specific problem
is fix the webapp so it performs well. If your test plan produces distribution graphs
with no apparent clumping or pattern, it may indicate a memory leak. The only way to
know for sure is to use a profiling tool.</p>
</description>
</component>
<component name="Aggregate Graph" index="&sect-num;.3.12" width="914" height="684" screenshot="aggregate_graph.png">
<description>The aggregate graph is similar to the aggregate report. The primary
difference is the aggregate graph provides an easy way to generate bar graphs and save
the graph as a PNG file.</description>
<div align="center">
<p>
The figure below shows an example of settings to draw this graph.
<figure width="913" height="443" image="aggregate_graph_settings.png">Aggregate graph settings</figure>
</p>
</div>
</component>
<component name="Mailer Visualizer" index="&sect-num;.3.13" width="860" height="463" screenshot="mailervisualizer.png">
<description><p>The mailer visualizer can be set up to send email if a test run receives too many
failed responses from the server.</p></description>
<properties>
<property name="Name" required="No">Descriptive name for this element that is shown in the tree.</property>
<property name="From" required="Yes">Email address to send messages from.</property>
<property name="Addressee(s)" required="Yes">Email address to send messages to, comma-separated.</property>
<property name="Success Subject" required="No">Email subject line for success messages.</property>
<property name="Success Limit" required="Yes">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.</property>
<property name="Failure Subject" required="No">Email subject line for fail messages.</property>
<property name="Failure Limit" required="Yes">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.</property>
<property name="Host" required="No">IP address or host name of SMTP server (email redirector)
server.</property>
<property name="Port" required="No">Port of SMTP server (defaults to 25).</property>
<property name="Login" required="No">Login used to authenticate.</property>
<property name="Password" required="No">Password used to authenticate.</property>
<property name="Connection security" required="No">Type of encryption for SMTP authentication (SSL, TLS or none).</property>
<property name="Test Mail" required="No">Press this button to send a test mail</property>
<property name="Failures" required="No">A field that keeps a running total of number
of failures so far received.</property>
</properties>
</component>
<component name="BeanShell Listener" index="&sect-num;.3.14" width="553" height="382" screenshot="beanshell_listener.png">
<description>
<p>
The BeanShell Listener allows the use of BeanShell for processing samples for saving etc.
</p>
<p>
<b>For full details on using BeanShell, please see the <a href="http://www.beanshell.org/">BeanShell website.</a></b>
</p>
<p>
The test element supports the ThreadListener and TestListener methods.
These should be defined in the initialisation file.
See the file BeanShellListeners.bshrc for example definitions.
</p>
</description>
<properties>
<property name="Name" required="">Descriptive name for this element that is shown in the tree.
The name is stored in the script variable Label</property>
<property name="Reset bsh.Interpreter before each call" required="Yes">
If this option is selected, then the interpreter will be recreated for each sample.
This may be necessary for some long running scripts.
For further information, see <a href="best-practices#bsh_scripting">Best Practices - BeanShell scripting</a>.
</property>
<property name="Parameters" required="No">Parameters to pass to the BeanShell script.
The parameters are stored in the following variables:
<ul>
<li>Parameters - string containing the parameters as a single variable</li>
<li>bsh.args - String array containing parameters, split on white-space</li>
</ul></property>
<property name="Script file" required="No">A file containing the BeanShell script to run.
The file name is stored in the script variable FileName</property>
<property name="Script" required="Yes (unless script file is provided)">The BeanShell script to run. The return value is ignored.</property>
</properties>
<p>Before invoking the script, some variables are set up in the BeanShell interpreter:</p>
<ul>
<li>log - (Logger) - can be used to write to the log file</li>
<li>ctx - (JMeterContext) - gives access to the context</li>
<li>vars - (<a href="../../docs/api/org/apache/jmeter/threads/JMeterVariables.html">JMeterVariables</a>) - gives read/write access to variables: vars.get(key); vars.put(key,val); vars.putObject("OBJ1",new Object());</li>
<li>props - (JMeterProperties - class java.util.Properties) - e.g. props.get("START.HMS"); props.put("PROP1","1234");</li>
<li>sampleResult, prev - (SampleResult) - gives access to the previous SampleResult</li>
<li>sampleEvent (SampleEvent) 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>
</component>
<component name="Summary Report" index="&sect-num;.3.15" width="784" height="287" screenshot="summary_report.png">
<description>The summary report creates a table row for each differently named request in your
test. This is similar to the <complink name="Aggregate Report"/> , 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.
</li>
<li># Samples - The number of samples with the same label</li>
<li>Average - The average elapsed time of a set of results</li>
<li>Min - The lowest elapsed time for the samples with the same label</li>
<li>Max - The longest elapsed time for the samples with the same label</li>
<li>Std. Dev. - the <a href="glossary.html#StandardDeviation">Standard Deviation</a> of the sample elapsed time</li>
<li>Error % - Percent of requests with errors</li>
<li>Throughput - the <a href="glossary.html#Throughput">Throughput</a> is measured in requests per second/minute/hour.
The time unit is chosen so that the displayed rate is at least 1.0.
When the throughput is saved to a CSV file, it is expressed in requests/second,
i.e. 30.0 requests/minute is saved as 0.5.
</li>
<li>Kb/sec - The throughput measured in Kilobytes per second</li>
<li>Avg. Bytes - average size of the sample response in bytes. (in JMeter 2.2 it wrongly showed the value in kB)</li>
</ul>
<p>Times are in milliseconds.</p>
</description>
<div align="center">
<p>
The figure below shows an example of selecting the "Include group name" checkbox.
<figure width="784" height="287" image="summary_report_grouped.png">Sample "Include group name" display</figure>
</p>
</div>
</component>
<component name="Save Responses to a file" index="&sect-num;.3.16" width="358" height="225" screenshot="savetofile.png">
<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
<complink name="View Results Tree"/> Listener.
The file name is created from the specified prefix, plus a number (unless this is disabled, see below).
The file extension is created from the document type, if known.
If not known, the file extension is set to 'unknown'.
If numbering is disabled, and adding a suffix is disabled, then the file prefix is
taken as the entire file name. This allows a fixed file name to be generated if required.
The generated file name is stored in the sample response, and can be saved
in the test log output file if required.
</p>
<p>
The current sample is saved first, followed by any sub-samples (child samples).
If a variable name is provided, then the names of the files are saved in the order
that the sub-samples appear. See below.
</p>
</description>
<properties>
<property name="Name" required="No">Descriptive name for this element that is shown in the tree.</property>
<property name="Filename Prefix" required="Yes">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.
</property>
<property name="Variable Name" required="No">
Name of a variable in which to save the generated file name (so it can be used later in the test plan).
If there are sub-samples then a numeric suffix is added to the variable name.
E.g. if the variable name is FILENAME, then the parent sample file name is saved in the variable FILENAME,
and the filenames for the child samplers are saved in FILENAME1, FILENAME2 etc.
</property>
<property name="Save Failed Responses only" required="Yes">If selected, then only failed responses are saved</property>
<property name="Save Successful Responses only" required="Yes">If selected, then only successful responses are saved</property>
<property name="Don't add number to prefix" required="Yes">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.</property>
<property name="Don't add suffix" required="Yes">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.</property>
</properties>
</component>
<component name="BSF Listener" index="&sect-num;.3.17" width="736" height="369" screenshot="bsf_listener.png">
<description>
<p>
The BSF Listener allows BSF script code to be applied to sample results.
</p>
</description>
<properties>
<property name="Name" required="No">Descriptive name for this element that is shown in the tree.</property>
<property name="Language" required="Yes">The BSF language to be used</property>
<property name="Parameters" required="No">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>
</ul></property>
<property name="Script file" required="No">A file containing the script to run.</property>
<property name="Script" required="Yes (unless script file is provided)">The script to run.</property>
</properties>
<p>
The script (or file) is processed using the BSFEngine.exec() method, which does not return a value.
</p>
<p>
Before invoking the script, some variables are set up.
Note that these are BSF variables - i.e. they can be used directly in 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 - (JMeterContext) - gives access to the context</li>
<li>vars - (<a href="../../docs/api/org/apache/jmeter/threads/JMeterVariables.html">JMeterVariables</a>) - gives read/write access to variables: vars.get(key); vars.put(key,val); vars.putObject("OBJ1",new Object()); vars.getObject("OBJ2");</li>
<li>props - (JMeterProperties - class java.util.Properties) - e.g. props.get("START.HMS"); props.put("PROP1","1234");</li>
<li>sampleResult, prev - (SampleResult) - gives access to the SampleResult</li>
<li>sampleEvent - (SampleEvent) - gives access to the SampleEvent</li>
<li>sampler - (Sampler)- gives access to the last sampler</li>
<li>OUT - System.out - e.g. OUT.println("message")</li>
</ul>
<p>For details of all the methods available on each of the above variables, please check the Javadoc</p>
</component>
<component name="JSR223 Listener" index="&sect-num;.3.18.1">
<description>
<p>
The JSR223 Listener allows JSR223 script code to be applied to sample results.
For details, see <complink name="BSF Listener"/>.
</p>
</description>
</component>
<component name="Generate Summary Results" index="&sect-num;.3.18" width="358" height="131" screenshot="summary.png">
<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 3 minutes) 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=180
#
# 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 output looks like the following:
<pre>
label + 171 in 20.3s = 8.4/s Avg: 1129 Min: 1000 Max: 1250 Err: 0 (0.00%)
label + 263 in 31.3s = 8.4/s Avg: 1138 Min: 1000 Max: 1250 Err: 0 (0.00%)
label = 434 in 50.4s = 8.6/s Avg: 1135 Min: 1000 Max: 1250 Err: 0 (0.00%)
label + 263 in 31.0s = 8.5/s Avg: 1138 Min: 1000 Max: 1250 Err: 0 (0.00%)
label = 697 in 80.3s = 8.7/s Avg: 1136 Min: 1000 Max: 1250 Err: 0 (0.00%)
label + 109 in 12.4s = 8.8/s Avg: 1092 Min: 47 Max: 1250 Err: 0 (0.00%)
label = 806 in 91.6s = 8.8/s Avg: 1130 Min: 47 Max: 1250 Err: 0 (0.00%)
</pre>
The "label" is the the name of the element.
The "+" means that the line is a delta line, i.e. shows the changes since the last output.
The "=" means that the line is a totals line, i.e. it shows the running total.
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.
The Avg (Average), Min(imum) and Max(imum) times are in milliseconds.
"Err" means number of errors (also shown as percentage).
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 synchronises 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>
</description>
<properties>
<property name="Name" required="Yes">Descriptive name for this element that is shown in the tree.
It appears as the "label" in the output. Details for all elements with the same label will be added together.
</property>
</properties>
</component>
<component name="Comparison Assertion Visualizer" index="&sect-num;.3.19" width="777" height="266" screenshot="comparison_assertion_visualizer.png">
<description>
The Comparison Assertion Visualizer shows the results of any <complink name="Compare Assertion"/> elements.
</description>
<properties>
<property name="Name" required="Yes">Descriptive name for this element that is shown in the tree.
</property>
</properties>
</component>
<a href="#">^</a>
</section>
<section name="&sect-num;.4 Configuration Elements" anchor="config_elements">
<description>
<br></br>
Configuration elements can be used to set up defaults and variables for later use by samplers.
Note that these elements are processed at the start of the scope in which they are found,
i.e. before any samplers in the same scope.
<br></br>
</description>
<component name="CSV Data Set Config" index="&sect-num;.4.1" width="433" height="281" screenshot="csvdatasetconfig.png">
<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>
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
<code>test${__threadNum}.csv</code> and set the "Sharing mode" to "Current thread".
</p>
<note>CSV Dataset variables are defined at the start of each test iteration.
As this is after configuration processing is completed,
they cannot be used for some configuration items - such as JDBC Config -
that process their contents at configuration time (see <a href="http://issues.apache.org/bugzilla/show_bug.cgi?id=40934">Bug 40394 </a>)
However the variables do work in the HTTP Auth Manager, as the username etc are processed at run-time.
</note>
<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>&amp;lt;EOF&gt;</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.
</p>
</description>
<properties>
<property name="Name" required="">Descriptive name for this element that is shown in the tree.</property>
<property name="Filename" required="Yes">Name of the file to be read.
<b>Relative file names are resolved with respect to the path of the active test plan.</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.
</property>
<property name="File Encoding" required="No">The encoding to be used to read the file, if not the platform default.</property>
<property name="Variable Names" required="Yes">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.
</property>
<property name="Delimiter" required="Yes">Delimiter to be used to split the records in the file.
If there are fewer values on the line than there are variables the remaining variables are not updated -
so they will retain their previous value (if any).</property>
<property name="Allow quoted data?" required="Yes">Should the CSV file allow values to be quoted?
If enabled, then values can be enclosed in <code>"</code> - double-quote - allowing values to contain a delimeter.
</property>
<property name="Recycle on EOF?" required="Yes">Should the file be re-read from the beginning on reaching EOF? (default is true)</property>
<property name="Stop thread on EOF?" required="Yes">Should the thread be stopped on EOF, if Recycle is false? (default is false)</property>
<property name="Sharing mode" required="Yes">
<ul>
<li>All threads - (the default) the file is shared between all the threads.</li>
<li>Current thread group - each file is opened once for each thread group in which the element appears</li>
<li>Current thread - each file is opened separately for each thread</li>
<li>Identifier - all threads sharing the same identifier share the same file.
So for example if you have 4 thread groups, you could use a common id for two or more of the groups
to share the file between them.
Or you could use the thread number to share the file between the same thread numbers in different thread groups.
</li>
</ul>
</property>
</properties>
</component>
<component name="FTP Request Defaults" index="&sect-num;.4.2" width="520" height="202" screenshot="ftp-config/ftp-request-defaults.png">
<description></description>
</component>
<component name="HTTP Authorization Manager" index="&sect-num;.4.3" width="439" height="238" screenshot="http-config/http-auth-manager.png">
<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.</note>
<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 are not shown in the Tree View Listener.
</p>
<p>
In versions of JMeter after 2.2, the HttpClient sampler defaults to pre-emptive authentication
if the setting has not been defined. To disable this, set the values as below, in which case
authentication will only be performed in response to a challenge.
<pre>
jmeter.properties:
httpclient.parameters.file=httpclient.parameters
httpclient.parameters:
http.authentication.preemptive$Boolean=false
</pre>
Note: the above settings only apply to the HttpClient sampler (and the SOAP samplers, which use Httpclient).
</p>
<note>
When looking for a match against a URL, JMeter checks each entry in turn, and stops when it finds the first match.
Thus the most specific URLs should appear first in the list, followed by less specific ones.
Duplicate URLs will be ignored.
If you want to use different usernames/passwords for different threads, you can use variables.
These can be set up using a <complink name="CSV Data Set Config"/> Element (for example).
</note>
</description>
<properties>
<property name="Name" required="No">Descriptive name for this element that is shown in the tree. </property>
<property name="Base URL" required="Yes">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&q