Beruflich Dokumente
Kultur Dokumente
19 Introduction
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.
19.1 Samplers
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.
FTP Request
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 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.
Parameters
Attribute
Description
Page |2
Required
Name
Descriptive name for this sampler that is shown in the tree.
No
Server Name or IP
Domain name or IP address of the FTP server.
Yes
Port
Port to use. If this is >0, then this specific port is used, otherwise JMeter uses
the default FTP port.
No
Remote File:
File to retrieve or name of destination file to upload.
Yes
Local File:
File to upload, or destination for downloads (defaults to remote file name).
Yes, if uploading (*)
Local File Contents:
Provides the contents for the upload, overrides the Local File property.
Yes, if uploading (*)
get(RETR) / put(STOR)
Whether to retrieve or upload a file.
Yes
Use Binary mode?
Check this to use Binary mode (default ASCII)
Yes
Save File in Response?
Whether to store contents of retrieved file in response data. If the mode is
ASCII, then the contents will be visible in the View Results Tree.
Yes, if downloading
Username
FTP account username.
Usually
Password
FTP account password. N.B. This will be visible in the test plan.
Usually
See also:
Assertions
FTP Request Defaults
Building an FTP Test Plan
Page |3
HTTP Request
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:
images
applets
stylesheets (CSS) and resources referenced from those files
external scripts
frames, iframes
background images (body, table, TD, TR)
background sound
If you are going to send multiple requests to the same web server, consider
using an HTTP Request Defaults Configuration Element so you do not have to
enter the same information for each HTTP Request.
Or, instead of manually adding HTTP Requests, you may want to use
JMeter's HTTP(S) Test Script Recorder to create them. This can save you
time if you have a lot of HTTP requests or requests with many parameters.
There are two different test elements used to define the samplers:
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.
HTTP Request
this has an implementation drop-down box, which selects the HTTP
protocol implementation to be used:
Java
Page |4
uses the HTTP implementation provided by the JVM. This has some
limitations in comparison with the HttpClient implementations - see
below.
HTTPClient3.1
(DEPRECATED SINCE 3.0) uses Apache Commons HttpClient 3.1.
This is no longer being developed, and support for this will be dropped
in a future JMeter release.
HTTPClient4
uses Apache HttpComponents HttpClient 4.x.
Blank Value
does not set implementation on HTTP Samplers, so relies on HTTP
Request Defaults if present or on jmeter.httpsampler property
defined in jmeter.properties
Note: the FILE protocol is intended for testing purposes only. It is handled by
the same code regardless of which HTTP Sampler is used.
A separate SSL context is used for each thread. If you want to use a single
SSL context (not the standard behaviour of browsers), set the JMeter
property:
https.sessioncontext.shared=true
By default, the SSL context is retained for the duration of the test. The SSL
session can be optionally reset for each test iteration. To enable this, set the
JMeter property:
https.use.cached.ssl.context=false
Note: this does not apply to the Java HTTP implementation.
JMeter defaults to the SSL protocol level TLS. If the server needs a different
level, e.g. SSLv3, change the JMeter property, for example:
https.default.protocol=SSLv3
If the request uses cookies, then you will also need an 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.
Parameters
Attribute
Description
Required
Name
Descriptive name for this sampler that is shown in the tree.
No
Server
Page |7
A Duration Assertion can be used to detect responses that take too long to
complete.
No
Server (proxy)
Hostname or IP address of a proxy server to perform request. [Do not include
the http:// prefix.]
No
Port
Port the proxy server is listening to.
No, unless proxy hostname is specified
Username
(Optional) username for proxy server.
No
Password
(Optional) password for proxy server. (N.B. this is stored unencrypted in the
test plan)
No
Implementation
Java, HttpClient3.1 (DEPRECATED SINCE 3.0), HttpClient4. If not
specified (and not defined by HTTP Request Defaults), the default depends
on the value of the JMeter property jmeter.httpsampler, failing that, the
HttpClient4 implementation is used.
No
Protocol
HTTP, HTTPS or FILE. Default: HTTP
Page |8
No
Method
GET, POST, HEAD, TRACE, OPTIONS, PUT, DELETE, PATCH (not supported
for JAVA implementation). With HttpClient4, the following methods related
to WebDav are also
allowed: COPY, LOCK, MKCOL, MOVE, PROPFIND, PROPPATCH, UNLOCK, REPO
RT, MKCALENDAR, SEARCH.
More methods can be pre-defined for the HttpClient4 by using the JMeter
property httpsampler.user_defined_methods.
Yes
Content Encoding
Content encoding to be used (for POST, PUT, PATCH and FILE). This is the
character encoding to be used, and is not related to the Content-Encoding
HTTP header.
No
Redirect Automatically
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 HEADrequests. The HttpClient sampler will reject
attempts to use it for POST or PUT.
Warning: see below for information on cookie and header handling.
No
Follow Redirects
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. Note that
the HttpClient sampler may log the following message:
"Redirect requested but followRedirects is disabled"
This can be ignored.
JMeter will collapse paths of the form '/../segment' in both absolute and
relative redirect URLs. For example http://host/one/../two will be
collapsed into http://host/two. If necessary, this behaviour can be
suppressed by setting the JMeter
propertyhttpsampler.redirect.removeslashdotdot=false
No
Use KeepAlive
Page |9
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.
No
Use multipart/form-data for HTTP POST
Use a multipart/form-data or application/x-www-form-
urlencoded post request
No
Browser-compatible headers
When using multipart/form-data, this suppresses the Content-
Type and Content-Transfer-Encoding headers; only the Content-
Disposition header is sent.
No
Path
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.
As a special case, if the path starts with "http://" or "https://" then this
is used as the full URL.
In this case, the server, port and protocol fields are ignored; parameters are
also ignored for GET and DELETE methods. Also please note that the path is
not encoded - apart from replacing spaces with %20 - so unsafe characters
may need to be encoded to avoid errors such as URISyntaxException.
Yes
Send Parameters With the Request
The query string will be generated from the list of parameters you provide.
Each parameter has a name and value, the options to encode the parameter,
and an option to include or exclude an equals sign (some applications don't
expect an equals sign when the value is the empty string). The query string
will be generated in the correct fashion, depending on the choice of "Method"
you made (i.e. if you chose 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. See below for some further information on
parameter handling.
No
File Path:
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.
No
Parameter name:
Value of the "name" web request parameter.
No
MIME Type
MIME type (for example, text/plain). If it is
a POST or PUT or PATCH request and either the 'name' attribute (below) are
omitted or the request body is constructed from parameter values only, then
the value of this field is used as the value of the content-type request
header.
No
Retrieve All Embedded Resources from HTML Files
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.
No
Use as monitor
For use with the Monitor Results listener. DEPRECATED
No
P a g e | 11
No
Source address field
[Only for HTTP Request with HTTPClient implementation]
This property is used to enable IP Spoofing. It overrides the default local IP
address for this sample. The JMeter host must have multiple IP addresses
(i.e. IP aliases, network interfaces, devices). The value can be a host name,
IP address, or a network interface device such as "eth0" or "lo" or "wlan0".
If the property httpclient.localaddress is defined, that is used for all
HttpClient requests.
No
P a g e | 12
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.
Parameter Handling:
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. See also the MIME
Type above how you can control the content-type request header that is
sent.
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.
You have the option to switch to Body Data tab when a request has only
unnamed parameters (or no parameters at all). This option is useful in the
following cases (amongst others):
Note that once you leave the Tree node, you cannot switch back to the
parameter tab unless you clear the Body Datatab from its data.
In Body Data 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
P a g e | 13
an empty line following it. (This cannot be seen, except by noting whether the
cursor can be placed on the subsequent line.)
Figure
1 - HTTP Request with one unnamed parameter
Method Handling:
The GET, DELETE, POST, PUT and PATCH request methods work similarly,
except that as of 3.1, only POST method supports multipart requests or file
upload. The PUT and PATCH method body must be provided as one of the
following:
define the body as a file with empty Parameter name field; in which
case the MIME Type is used as the Content-Type
define the body as parameter value(s) with no name
use the Body Data tab
GETDELETEPOSTParameters
GET, DELETE, PUT and PATCH require a Content-Type. If not using a file,
attach a Header Manager to the sampler and define the Content-Type there.
Gets the real network size in bytes for the body response
sampleresult.getbytes.body_real_size=true
P a g e | 15
Retry handling
For HttpClient4 and Commons HttpClient 3.1 samplers, the retry count has
been set to 0, meaning not retry is attempted. Note that the Java
implementation appears to retry 1 time. The retry count can be overridden by
setting the relevant JMeter property, for example:
httpclient4.retrycount=3
httpclient3.retrycount=3
This error is related to increased security in Java 7 version u16 (MD2) and
version u40 (Certificate size lower than 1024 bits), and Java 8 too.
To allow you to perform your HTTPS request, you can downgrade the security
of your Java installation by editing the
Java jdk.certpath.disabledAlgorithms property. Remove the MD2
value or the constraint on size, depending on your case.
See also:
Assertion
Building a Web Test Plan
Building an Advanced Web Test Plan
HTTP Authorization Manager
HTTP Cookie Manager
HTTP Header Manager
HTML Link Parser
HTTP(S) Test Script Recorder
HTTP Request Defaults
HTTP Requests and Session ID's: URL Rewriting
JDBC Request
This sampler lets you send a JDBC Request (an SQL query) to a database.
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 A,,C, then the following variables will be set up:
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.
Old variables are cleared if necessary - e.g. if the first select retrieves six rows
and a second select returns only three rows, the additional variables for rows
four, five and six will be removed.
The latency time is set from the time it took to acquire a connection.
P a g e | 17
Parameters
Attribute
Description
Required
Name
Descriptive name for this sampler that is shown in the tree.
No
Variable Name
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.
Yes
Query Type
Set this according to the statement type:
Select Statement
Update Statement - use this for Inserts and Deletes as well
Callable Statement
Prepared Select Statement
Prepared Update Statement - use this for Inserts and Deletes as
well
P a g e | 18
Commit
Rollback
Autocommit(false)
Autocommit(true)
Edit - this should be a variable reference that evaluates to one of
the above
Yes
SQL Query
SQL query.
Do not enter a trailing semi-colon.
There is generally no need to use { and } to enclose Callable statements;
however they may 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:
select * from t_customers where id=23
CALL SYSCS_UTIL.SYSCS_EXPORT_TABLE (null, ?, ?,
null, null, null)
o Parameter values: tablename,filename
o Parameter types: VARCHAR,VARCHAR
Those integer values can be used, when you use custom database types
proposed by driver (For example OracleTypes.CURSORcould be
represented by its integer value -10).
These are defined as fields in the class java.sql.Types, see for example:
Javadoc for java.sql.Types.
Note: JMeter will use whatever types are defined by the runtime JVM, so if
you are running on a different JVM, be sure to check the appropriate
documentation
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".
If the type is not one of the fields found in java.sql.Types, JMeter also
accepts the corresponding integer number, e.g. since OracleTypes.CURSOR
== -10, you can use "INOUT -10".
There must be as many types as there are placeholders in the statement.
Yes, if a prepared or callable statement has parameters
Variable Names
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 OUTparameters 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
No
Result Variable Name
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:
No
See also:
Building
a Database Test Plan
JDBC Connection Configuration
Java Request
This sampler lets you control a java class that implements
theorg.apache.jmeter.protocol.java.sampler.JavaSamplerClie
nt interface. By writing your own implementation of this interface, you can use
JMeter to harness multiple threads, input parameter control, and data
collection.
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.
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
P a g e | 21
used by Assertions, etc. The fields allow variables to be used, so the values of
these can readily be seen.
Screenshot of
Control-Panel of Java Request
If the method teardownTest is not overridden by a subclass
of AbstractJavaSamplerClient, its teardownTestmethod will not be
called. This reduces JMeter memory requirements. This will not have any
impact on existing Test plans.
The Add/Delete buttons don't serve any purpose at present.
Parameters
Attribute
Description
Required
Name
Descriptive name for this sampler that is shown in the tree.
No
Classname
The specific implementation of the JavaSamplerClient interface to be
sampled.
Yes
Send Parameters with Request
A list of arguments that will be passed to the sampled class. All arguments are
sent as Strings. See below for specific settings.
No
P a g e | 22
Parameters
Attribute
Description
Required
Sleep_time
How long to sleep for (ms)
Yes
Sleep_mask
How much "randomness" to add:
The sleep time is calculated as follows:
totalSleepTime = SleepTime + (System.currentTimeMillis() % SleepMask)
Yes
Parameters
Attribute
Description
Required
Label
The label to use. If provided, overrides Name
No
ResponseCode
If provided, sets the SampleResult ResponseCode.
No
ResponseMessage
If provided, sets the SampleResult ResponseMessage.
No
Status
If provided, sets the SampleResult Status. If this equals "OK" (ignoring case)
then the status is set to success, otherwise the sample is marked as failed.
No
SamplerData
If provided, sets the SampleResult SamplerData.
No
ResultData
If provided, sets the SampleResult ResultData.
P a g e | 23
No
^
SOAP/XML-RPC Request
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 HTTP Header Manager. Note that the
sampler will use all the headers from the HTTP Header Manager. If a SOAP
action is specified, that will override any SOAPaction in the HTTP Header
Manager. 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.
Screenshot of Control-
Panel of SOAP/XML-RPC Request
See Building a WebService Test Plan for up to date way of test SOAP and
REST Webservices
Parameters
P a g e | 24
Attribute
Description
Required
Name
Descriptive name for this sampler that is shown in the tree.
No
URL
The URL to direct the SOAP request to.
Yes
Send SOAP action
Send a SOAP action header? (overrides the HTTP Header Manager)
No
Use KeepAlive
If set, sends Connection: keep-alive, else sends Connection:
close
No
Soap/XML-RPC Data
The Soap XML message, or XML-RPC instructions. Not used if the filename is
provided.
No
Filename
If specified, then the contents of the file are sent, and the Data field is ignored
No
^
LDAP Request
This Sampler lets you send a different Ldap
request(Add, Modify, Delete and Search) to an LDAP server.
If you are going to send multiple requests to the same LDAP server, consider
using an LDAP Request Defaults Configuration Element so you do not have to
enter the same information for each LDAP Request.
The same way the Login Config Element also using for Login and password.
P a g e | 25
Screenshot of
Control-Panel of LDAP Request
There are two ways to create test cases for testing an LDAP Server.
There are four test scenarios of testing LDAP. The tests are given below:
1. Add Test
1. Inbuilt test:
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.
2. Modify Test
1. Inbuilt test:
P a g e | 26
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.
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.
3. Search Test
1. Inbuilt test:
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.
4. Delete Test
1. Inbuilt test:
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.
Parameters
Attribute
Description
Required
P a g e | 27
Name
Descriptive name for this sampler that is shown in the tree.
No
Server Name or IP
Domain name or IP address of the LDAP server. JMeter assumes the LDAP
server is listening on the default port (389).
Yes
Port
Port to connect to (default is 389).
Yes
root DN
Base DN to use for ldap operations
Yes
Username
LDAP server username.
Usually
Password
LDAP server password. (N.B. this is stored unencrypted in the test plan)
Usually
Entry DN
the name of the context to create or Modify; may not be empty.
You have to set the right attributes of the object yourself. So if you want to
add cn=apache,ou=testyou have to add in the
table name and value to cnand apache.
Yes, if User Defined Test and Add Test or Modify Test is selected
Delete
the name of the context to Delete; may not be empty
Yes, if User Defined Test and Delete Test is selected
Search base
the name of the context or object to search
Yes, if User Defined Test and Search Test is selected
Search filter
the filter expression to use for the search; may not be null
Yes, if User Defined Test and Search Test is selected
add test
Use these name, value pairs for creation of the new object in the given
context
Yes, if User Defined Test and add Test is selected
modify test
Use these name, value pairs for modification of the given context object
Yes, if User Defined Test and Modify Test is selected
P a g e | 28
See also:
Building
an Ldap Test Plan
LDAP Request Defaults
If you are going to send multiple requests to the same LDAP server, consider
using an LDAP Extended Request DefaultsConfiguration Element so you do
not have to enter the same information for each LDAP Request.
There are nine test operations defined. These operations are given below:
Thread bind
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"
P a g e | 29
Parameters
Attribute
Description
Required
Name
Descriptive name for this sampler that is shown in the tree.
No
Servername
The name (or IP-address) of the LDAP server.
Yes
Port
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).
No
DN
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!
No
Username
Full distinguished name of the user as which you want to bind.
No
Password
Password for the above user. If omitted it will result in an
anonymous bind. If it is incorrect, the sampler will return an error
and revert to an anonymous bind. (N.B. this is stored unencrypted in
the test plan)
No
Thread unbind
P a g e | 30
Parameters
Attribute
Description
Required
Name
Descriptive name for this sampler that is shown in the tree.
No
Single bind/unbind
Parameters
Attribute
Description
Required
Name
Descriptive name for this sampler that is shown in the tree.
No
Username
Full distinguished name of the user as which you want to bind.
Yes
Password
Password for the above user. If omitted it will result in an
anonymous bind. If it is incorrect, the sampler will return an error.
(N.B. this is stored unencrypted in the test plan)
No
Rename entry
Parameters
P a g e | 31
Attribute
Description
Required
Name
Descriptive name for this sampler that is shown in the tree.
No
Old entry name
The current distinguished name of the object you want to rename or
move, relative to the given DN in the thread bind operation.
Yes
New distinguished name
The new distinguished name of the object you want to rename or
move, relative to the given DN in the thread bind operation.
Yes
Add test
This is the ldap "add" operation. It can be used to add any kind of
object to the LDAP server.
Parameters
Attribute
Description
Required
Name
Descriptive name for this sampler that is shown in the tree.
No
Entry DN
Distinguished name of the object you want to add, relative to the
given DN in the thread bind operation.
Yes
Add test
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.
Yes
Delete test
Parameters
Attribute
Description
Required
Name
Descriptive name for this sampler that is shown in the tree.
No
Delete
Distinguished name of the object you want to delete, relative to the
given DN in the thread bind operation.
Yes
Search test
This is the LDAP "search" operation, and will be used for defining
searches.
Parameters
Attribute
Description
Required
Name
Descriptive name for this sampler that is shown in the tree.
No
Search base
Distinguished name of the subtree you want your search to look in,
relative to the given DN in the thread bind operation.
No
Search Filter
searchfilter, must be specified in LDAP syntax.
Yes
Scope
Use 0 for baseobject-, 1 for onelevel- and 2 for a subtree search.
(Default=0)
No
Size Limit
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
No
Time Limit
P a g e | 33
Parameters
Attribute
Description
Required
Name
Descriptive name for this sampler that is shown in the tree.
No
Entry name
Distinguished name of the object you want to modify, relative to the
given DN in the thread bind operation
Yes
Modification test
P a g e | 34
Parameters
Attribute
Description
Required
Name
Descriptive name for this sampler that is shown in the tree.
No
Entry DN
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.
Yes
Compare filter
In the form "attribute=value"
Yes
See also:
Building
an LDAP Test Plan
LDAP Extended Request Defaults
^
P a g e | 35
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:
127.0.0.1 - - [21/Oct/2003:05:37:21 -0500] "GET /index.jsp?%2Findex.jsp=
HTTP/1.1" 200 8343
The current implementation of the parser only looks at the text within the
quotes that contains one of the HTTP protocol methods
(GET, PUT, POST, DELETE, …). Everything else is stripped out and ignored.
For example, the response code is completely ignored by the parser.
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:
org.apache.jmeter.protocol.http.util.accesslog.LogPar
ser
org.apache.jmeter.protocol.http.util.accesslog.Genera
tor
setGenerator(Generator)
parse(int)
(Beta Code)
Parameters
Attribute
Description
Required
Name
Descriptive name for this sampler that is shown in the tree.
No
Server
Domain name or IP address of the web server.
Yes
Protocol
Scheme
No (defaults to http
Port
Port the web server is listening to.
No (defaults to 80)
Log parser class
The log parser class is responsible for parsing the logs.
P a g e | 37
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.
BeanShell Sampler
This sampler allows you to write a sampler using the BeanShell scripting
language.
For full details on using BeanShell, please see the BeanShell website.
Parameters
Attribute
Description
Required
Name
Descriptive name for this sampler that is shown in the tree. The name is
stored in the script variable Label
No
Reset bsh.Interpreter before each call
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 Best Practices - BeanShell scripting.
Yes
Parameters
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:
Parameters
string containing the parameters as a single variable
P a g e | 39
bsh.args
String array containing parameters, split on white-space
No
Script file
A file containing the BeanShell script to run. The file name is stored in the
script variable FileName
No
Script
The BeanShell script to run. The return value (if not null) is stored as the
sampler result.
Yes (unless script file is provided)
N.B. Each Sampler instance has its own BeanShell interpreter, and Samplers
are only called from a single thread
If a script file is supplied, that will be used, otherwise the script will be used.
JMeter processes function and variable references before passing the script
field to the interpreter, so the references will only be resolved once. Variable
and function references in script files will be passed verbatim to the
interpreter, which is likely to cause a syntax error. In order to use runtime
variables, please use the appropriate props methods,
e.g.props.get("START.HMS"); props.put("PROP1","1234");
BeanShell does not currently support Java 5 syntax such as generics and the
enhanced for loop.
Before invoking the script, some variables are set up in the BeanShell
interpreter:
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.
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:
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).
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:
if (bsh.args[0].equalsIgnoreCase("StopThread")) {
log.info("Stop Thread detected!");
SampleResult.setStopThread(true);
}
P a g e | 41
Another example:
ensure that the
property beanshell.sampler.init=BeanShellSampler.bshrc is
defined in jmeter.properties. The following script will show the values of
all the variables in the ResponseData field:
return getVariables();
The BSF API has been largely superseded by JSR-223, which is included in
Java 6 onwards. Most scripting languages now include support for JSR-223;
please use the JSR223 Sampler instead. The BSF Sampler should only be
needed for supporting legacy languages/test scripts.
javascript
xslt
Parameters
Attribute
Description
Required
Name
Descriptive name for this sampler that is shown in the tree.
No
Scripting Language
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: javascript, xslt. Others may be available if the
appropriate jar is installed in the JMeter lib directory.
Yes
Script File
Name of a file to be used as a BSF script, if a relative file path is used, then it
will be relative to directory referenced by "user.dir" System property
No
Parameters
List of parameters to be passed to the script file or the script.
No
P a g e | 43
Script
Script to be passed to BSF language
Yes (unless script file is provided)
If a script file is supplied, that will be used, otherwise the script will be used.
JMeter processes function and variable references before passing the script
field to the interpreter, so the references will only be resolved once. Variable
and function references in script files will be passed verbatim to the
interpreter, which is likely to cause a syntax error. In order to use runtime
variables, please use the appropriate props methods,
e.g.props.get("START.HMS"); props.put("PROP1","1234");
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.
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
P a g e | 44
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).
Unlike the BeanShell Sampler, the BSF Sampler does not set
the ResponseCode, ResponseMessage and sample status via script
variables. Currently the only way to change these is via
the SampleResult methods:
SampleResult.setSuccessful(true/false)
SampleResult.setResponseCode("code")
SampleResult.setResponseMessage("message")
JSR223 Sampler
The JSR223 Sampler allows JSR223 script code to be used to perform a
sample.
The JSR223 test elements have a feature (compilation) that can significantly
increase performance. To benefit from this feature:
Use Script files instead of inlining them. This will make JMeter compile
them if this feature is available on ScriptEngine and cache them.
Or Use Script Text and check Cache compiled script if
available property.
When using this feature, ensure your script code does not use
JMeter variables directly in script code as caching would only cache
first replacement. Instead use script parameters.
o GROOVY-7683
o GROOVY-7591
o JDK-8136353
Parameters
Attribute
Description
Required
Name
Descriptive name for this sampler that is shown in the tree.
No
Scripting Language
Name of the JSR223 scripting language to be used.
There are other languages supported than those that appear in the drop-down
list. Others may be available if the appropriate jar is installed in the JMeter lib
directory.
Yes
Script File
Name of a file to be used as a JSR223 script, if a relative file path is used,
then it will be relative to directory referenced by "user.dir" System property
No
Parameters
List of parameters to be passed to the script file or the script.
No
Cache compiled script if available
If checked (advised) and the language used supports Compilable interface
(Groovy is one of these, java, beanshell and javascript are not), JMeter will
compile the Script and cache it using it's MD5 hash as unique cache key
No
Script
Script to be passed to JSR223 language
Yes (unless script file is provided)
If a script file is supplied, that will be used, otherwise the script will be used.
Before invoking the script, some variables are set up. Note that these are
JSR223 variables - i.e. they can be used directly in the script.
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).
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).
Unlike the BeanShell Sampler, the JSR223 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:
SampleResult.setSuccessful(true/false)
SampleResult.setResponseCode("code")
SampleResult.setResponseMessage("message")
TCP Sampler
P a g e | 48
The TCP Sampler opens a TCP/IP connection to the specified server. It then
sends the text, and waits for a response.
tcp.status.prefix
text that precedes a status number
tcp.status.suffix
text that follows a status number
tcp.status.properties
name of property file to convert status codes to messages
tcp.handler
Name of TCP Handler class (default TCPClientImpl) - only used if
not specified on the GUI
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.
TCPClientImpl
BinaryTCPClientImpl
LengthPrefixedBinaryTCPClientImpl
Parameters
Attribute
Description
Required
Name
Descriptive name for this element that is shown in the tree.
TCPClient classname
Name of the TCPClient class. Defaults to the property tcp.handler, failing
that TCPClientImpl.
No
ServerName or IP
Name or IP of TCP server
Yes
Port Number
Port to be used
Yes
Re-use connection
If selected, the connection is kept open. Otherwise it is closed when the data
has been read.
Yes
Close connection
If selected, the connection will be closed after running the sampler.
Yes
P a g e | 51
SO_LINGER
Enable/disable SO_LINGER with the specified linger time in seconds when a
socket is created. If you set "SO_LINGER" value as 0, you may prevent large
numbers of sockets sitting around with a TIME_WAIT status.
No
End of line(EOL) byte value
Byte value for end of line, set this to a value outside the range -
128 to +127 to skip eol checking. You may set this
in jmeter.properties file as well with eolByte property. If you set this in
TCP Sampler Config and in jmeter.properties file at the same time, the
setting value in the TCP Sampler Config will be used.
No
Connect Timeout
Connect Timeout (milliseconds, 0 disables).
No
Response Timeout
Response Timeout (milliseconds, 0 disables).
No
Set NoDelay
See java.net.Socket.setTcpNoDelay(). If selected, this will disable
Nagle's algorithm, otherwise Nagle's algorithm will be used.
Yes
Text to Send
Text to be sent
Yes
Login User
User Name - not used by default implementation
No
Password
Password - not used by default implementation (N.B. this is stored
unencrypted in the test plan)
No
^
JMS Publisher
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 a g e | 52
JMeter does not include any JMS implementation jar; this must be
downloaded from the JMS provider and put in the lib directory
Parameters
Attribute
Description
Required
Name
Descriptive name for this element that is shown in the tree.
use JNDI properties file
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.
P a g e | 53
Yes
JNDI Initial Context Factory
Name of the context factory
No
Provider URL
The URL for the jms provider
Yes, unless using jndi.properties
Destination
The message destination (topic or queue name)
Yes
Setup
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)
Yes
Authentication
Authentication requirement for the JMS provider
Yes
User
User Name
No
Password
Password (N.B. this is stored unencrypted in the test plan)
No
Expiration
The expiration time (in milliseconds) of the message before it becomes
obsolete. If you do not specify an expiration time, the default value is 0 (never
expires).
No
Priority
The priority level of the message. There are ten priority levels from 0 (lowest)
to 9 (highest). If you do not specify a priority level, the default level is 4.
No
Number of samples to aggregate
Number of samples to aggregate
Yes
Message source
Where to obtain the message:
From File
P a g e | 54
means the referenced file will be read and reused by all samples. If
file name changes it is reloaded since JMeter 3.0
Random File from folder specified below
means a random file will be selected from folder specified below,
this folder must contain either files with extension .dat for Bytes
Messages, or files with extension .txt or .obj for Object or Text
messages
Text area
The Message to use either for Text or Object message
Yes
Message type
Text, Map, Object message or Bytes Message
Yes
Use non-persistent delivery mode?
Whether to set DeliveryMode.NON_PERSISTENT (defaults to false)
No
JMS Properties
The JMS Properties are properties specific for the underlying messaging
system. You can setup the name, the value and the class (type) of value.
Default type is String. For example: for WebSphere 5.1 web services you
will need to set the JMS Property targetService to test webservices through
JMS.
No
For the MapMessage type, JMeter reads the source as lines of text. Each line
must have 3 fields, delimited by commas. The fields are:
Name of entry
Object class name, e.g. "String" (assumes java.lang package if not
specified)
Object string value
valueOf(String)
name,String,Example
size,Integer,1234
The Object message is implemented and works as follow:
Put the JAR that contains your object and its dependencies
in jmeter_home/lib/ folder
Serialize your object as XML using XStream
Either put result in a file suffixed with .txt or .obj or put XML
content directly in Text Area
P a g e | 55
Note that if message is in a file, replacement of properties will not occur while
it will if you use Text Area.
The following table shows some values which may be useful when configuring
JMS:
Apache Active
Value(s) Comment
MQ
Context org.apache.activemq.jndi.ActiveMQInitialCont .
Factory extFactory
Provider URL vm://localhost
Provider URL vm:(broker:(vm://localhost)?persistent=false Disable
) persistence
Queue dynamicQueues/QUEUENAME Dynamically
Reference define the
QUEUENA
ME to JNDI
Topic dynamicTopics/TOPICNAME Dynamically
Reference define the
TOPICNA
ME to JNDI
^
JMS Subscriber
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.
JMeter does not include any JMS implementation jar; this must be
downloaded from the JMS provider and put in the lib directory
P a g e | 56
Screenshot
of Control-Panel of JMS Subscriber
BETA CODE - the code is still subject to change
Parameters
Attribute
Description
Required
Name
Descriptive name for this element that is shown in the tree.
use JNDI properties file
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.
Yes
JNDI Initial Context Factory
Name of the context factory
No
Provider URL
The URL for the jms provider
No
Destination
the message destination (topic or queue name)
P a g e | 57
Yes
Durable Subscription ID
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.
No
Client ID
The Client ID to use when you use a durable subscription. Be sure to add a
variable like ${__threadNum} when you have more than one Thread.
No
JMS Selector
Message Selector as defined by JMS specification to extract only messages
that respect the Selector condition. Syntax uses subpart of SQL 92.
No
Setup
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)
Yes
Authentication
Authentication requirement for the JMS provider
Yes
User
User Name
No
Password
Password (N.B. this is stored unencrypted in the test plan)
No
Number of samples to aggregate
number of samples to aggregate
Yes
Save response
should the sampler store the response. If not, only the response length is
returned.
Yes
Timeout
Specify the timeout to be applied, in milliseconds. 0=none. This is the overall
aggregate timeout, not per sample.
Yes
Client
P a g e | 58
JMS Point-to-Point
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.
JMeter does not include any JMS implementation jar; this must be
downloaded from the JMS provider and put in the lib directory
Parameters
Attribute
Description
Required
Name
Descriptive name for this element that is shown in the tree.
QueueConnection Factory
P a g e | 60
The JNDI name of the queue connection factory to use for connecting to the
messaging system.
Yes
JNDI Name Request queue
This is the JNDI name of the queue to which the messages are sent.
Yes
JNDI Name Reply queue
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.
No
JMS Selector
Message Selector as defined by JMS specification to extract only messages
that respect the Selector condition. Syntax uses subpart of SQL 92.
No
Communication style
The Communication style can be Request Only (also known as Fire and
Forget) or Request Response:
Request Only
will only send messages and will not monitor replies. As such it can
be used to put load on a system.
Request Response
will send messages and monitor the replies it receives. Behaviour
depends on the value of the JNDI Name Reply Queue. If JNDI
Name Reply Queue has a value, this queue is used to monitor the
results. Matching of request and reply is done with the message id
of the request and the correlation id of the reply. If the JNDI Name
Reply Queue is empty, then temporary queues will be used for the
communication between the requestor and the server. This is very
different from the fixed reply queue. With temporary queues the
sending thread will block until the reply message has been received.
With Request Responsemode, you need to have a Server that
listens to messages sent to Request Queue and sends replies to
queue referenced by message.getJMSReplyTo().
Yes
Use alternate fields for message correlation
These check-boxes select the fields which will be used for matching the
response message with the original request.
Use Request Message Id
P a g e | 61
No
JMS Properties
The JMS Properties are properties specific for the underlying messaging
system. You can setup the name, the value and the class (type) of value.
Default type is String. For example: for WebSphere 5.1 web services you
will need to set the JMS Property targetService to test webservices through
JMS.
No
Initial Context Factory
The Initial Context Factory is the factory to be used to look up the JMS
Resources.
No
JNDI properties
The JNDI Properties are the specific properties for the underlying JNDI
implementation.
No
Provider URL
The URL for the jms provider.
No
^
JUnit Request
The current implementation supports standard JUnit convention and
extensions. It also includes extensions
like oneTimeSetUpand oneTimeTearDown. The sampler works like
the Java Request with some differences.
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.
JUnit test jar files should be placed in jmeter/lib/junit instead
of /lib directory. You can also use the "user.classpath" property
to specify where to look for TestCase classes.
JUnit sampler does not use name/value pairs for configuration like
the Java Request. The sampler assumes setUp and tearDown will
configure the test correctly.
The sampler measures the elapsed time only for the test method and
does not include setUp and tearDown.
P a g e | 63
Each time the test method is called, Jmeter will pass the result to the
listeners.
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.
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".
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:
JUnit Constructors
Empty Constructor:
public class myTestCase {
public myTestCase() {}
}
String Constructor:
public class myTestCase {
public myTestCase(String text) {
super(text);
}
}
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.
General Guidelines
If you use setUp and tearDown, make sure the methods are declared public.
If you do not, the test may not run properly.
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.
Write the setUp and tearDown methods so they are thread safe.
This generally means avoid using static members.
Make the test methods discrete units of work and not long
sequences of actions. By keeping the test method to a discrete
P a g e | 64
Parameters
Attribute
Description
Required
Name
Descriptive name for this element that is shown in the tree.
P a g e | 65
@Test
used to find test methods and classes. The "expected" and
"timeout" attributes are supported.
@Before
treated the same as setUp() in JUnit3
@After
treated the same as tearDown() in JUnit3
@BeforeClass, @AfterClass
treated as test methods so they can be run independently as required
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.
^
Parameters
Attribute
Description
Required
Name
Descriptive name for this element that is shown in the tree.
Server Type
The protocol used by the provider: e.g. pop3, pop3s, imap, imaps. or
another string representing the server protocol. For example file for use
with the read-only mail file provider. The actual provider names for POP3 and
IMAP are pop3 and imap
Yes
Server
Hostname or IP address of the server. See below for use with file protocol.
Yes
Port
Port to be used to connect to the server (optional)
No
Username
User login name
Password
User login password (N.B. this is stored unencrypted in the test plan)
Folder
The IMAP(S) folder to use. See below for use with fileprotocol.
P a g e | 68
the message number. Alternatively, the server 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.
Test Action
The Test Action sampler is a sampler that is intended for use in a conditional
controller. Rather than generate a sample, the test element either pauses or
stops the selected target.
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.
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.
Screenshot of
Control-Panel of Test Action
Parameters
Attribute
P a g e | 70
Description
Required
Name
Descriptive name for this element that is shown in the tree.
Target
Current Thread / All Threads (ignored for Pause)
Yes
Action
Pause / Stop / Stop Now / Go to next loop iteration
Yes
Duration
How long to pause for (milliseconds)
Yes, if Pause is selected
^
SMTP Sampler
The SMTP Sampler can send mail messages using SMTP/SMTPS protocol. It
is possible to set security protocols for the connection (SSL and TLS), as well
as user authentication. If a security protocol is used a verification on the
server certificate will occur.
Two alternatives to handle this verification are available:
Parameters
Attribute
Description
Required
Server
Hostname or IP address of the server. See below for use with file protocol.
Yes
Port
Port to be used to connect to the server. Defaults are: SMTP=25, SSL=465,
StartTLS=587
No
Connection timeout
Connection timeout value in milliseconds (socket level). Default is infinite
timeout.
No
Read timeout
Read timeout value in milliseconds (socket level). Default is infinite timeout.
No
Address From
The from address that will appear in the e-mail
Yes
Address To
P a g e | 72
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.
Include timestamp in subject
Includes the System.currentTimemillis() in the subject line.
Add Header
Additional headers can be defined using this button.
No
Message
The message body.
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.
No
Attach files
Files to be attached to the message.
Send .eml
If set, the .eml file will be sent instead of the entries in
the Subject, Message, and Attach file(s) fields
Calculate message size
Calculates the message size and stores it in the sample result.
Enable debug logging?
If set, then the "mail.debug" property is set to "true"
^
OS Process Sampler
The OS Process Sampler is a sampler that can be used to execute
commands on the local machine.
It should allow execution of any command that can be run from the command
line.
Validation of the return code can be enabled, and the expected return code
can be specified.
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.
Many OSes have some built-in commands which are not provided as separate
executables. For example the Windows DIRcommand 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.
Command:
CMD
Param 1:
/C
Param 2:
DIR
Param 3:
C:\TEMP
Screenshot of
Control-Panel of OS Process Sampler
Parameters
Attribute
P a g e | 75
Description
Required
Command
The program name to execute.
Yes
Working directory
Directory from which command will be executed, defaults to folder referenced
by "user.dir" System property
No
Command Parameters
Parameters passed to the program name.
No
Environment Parameters
Key/Value pairs added to environment when running command.
No
Standard input (stdin)
Name of file from which input is to be taken (STDIN).
No
Standard output (stdout
Name of output file for standard output (STDOUT). If omitted, output is
captured and returned as the response data.
No
Standard error (stderr)
Name of output file for standard error (STDERR). If omitted, output is captured
and returned as the response data.
No
Check Return Code
If checked, sampler will compare return code with Expected Return Code.
No
Expected Return Code
Expected return code for System Call, required if "Check Return Code" is
checked.
No
Timeout
Timeout for command in milliseconds, defaults to 0, which means no timeout.
If the timeout expires before the command finishes, JMeter will attempt to kill
the OS process.
No
^
Before using this you need to set up a MongoDB Source Config Configuration
element
Parameters
Attribute
Description
Required
Name
Descriptive name for this sampler that is shown in the tree.
No
MongoDB Source
Name of the JMeter variable that the MongoDB connection is bound to. This
must agree with the 'MongoDB Source' field of a MongoDB Source Config.
Yes
Database Name
Database Name, will be used in your script
P a g e | 77
Yes
Username
No
Password
No
Script
Mongo script as it would be used in MongoDB shell
Yes
See also:
Simple Controller
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.
Screenshot of Control-Panel of
Simple Controller
Parameters
Attribute
Description
Required
Name
Descriptive name for this controller that is shown in the tree.
P a g e | 78
No
Using the Simple Controller
Download 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.
Loop Controller
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 a g e | 79
Parameters
Attribute
Description
Required
Name
Descriptive name for this controller that is shown in the tree.
No
Loop Count
The number of times the subelements of this controller will be iterated each
time through a test run.
Special Case: The Loop Controller embedded in the Thread Group element
behaves slightly different. Unless set to forever, it stops the test after the given
number of iterations have been done.
Download 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 a g e | 80
Figure 4 -
Loop Controller Example
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.
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.
^
The Once Only Controller will now execute always during the first iteration of
any looping parent controller. Thus, if the Once Only Controller is placed
under a Loop Controller specified to loop 5 times, then the Once Only
Controller will execute only on the first iteration through the Loop Controller
(i.e. every 5 times).
Note this means the Once Only Controller will still behave as previously
expected if put under a Thread Group (runs only once per test per Thread),
but now the user has more flexibility in the use of the Once Only Controller.
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 a g e | 81
Screenshot of Control-Panel of
Once Only Controller
Parameters
Attribute
Description
Required
Name
Descriptive name for this controller that is shown in the tree.
No
Once Only Example
Download 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.
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.
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.
^
P a g e | 82
Interleave Controller
If you add Generative or Logic Controllers to an Interleave Controller, JMeter
will alternate among each of the other controllers for each loop iteration.
Parameters
Attribute
Description
Required
name
Descriptive name for this controller that is shown in the tree.
No
ignore sub-controller blocks
If checked, the interleave controller will treat sub-controllers like single request
elements and only allow one request per controller at a time.
No
Interleave accross threads
If checked, the interleave controller will alternate among each of its children
controllers for each loop iteration but accross all threads, for example in a
configuration with 4 threads and 3 child controllers, on first iteration thread 1
will run first child, thread 2 second child, thread 3 third child, thread 4 first
child, on next iteration each thread will run the following child controller
No
Simple Interleave Example
Download 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 a g e | 83
Download 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 a g e | 84
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.
If the two interleave controllers under the main interleave controller were
instead simple controllers, then the order would be: Home Page, CVS Page,
Interleaved, Bug Page, FAQ Page, Interleaved.
P a g e | 85
Random Controller
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.
Screenshot of Control-Panel of
Random Controller
Parameters
Attribute
Description
Required
Name
Descriptive name for this controller that is shown in the tree.
No
ignore sub-controller blocks
If checked, the interleave controller will treat sub-controllers like single request
elements and only allow one request per controller at a time.
No
^
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.
Screenshot of Control-Panel of
Random Order Controller
Parameters
Attribute
Description
Required
Name
Descriptive name for this controller that is shown in the tree.
No
^
Throughput Controller
The Throughput Controller allows the user to control how often it is executed.
There are two modes:
percent execution
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.
This controller is badly named, as it does not control throughput. Please refer
to the Constant Throughput Timer for an element that can be used to adjust
the throughput.
P a g e | 87
Screenshot of Control-Panel of
Throughput Controller
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).
Parameters
Attribute
Description
Required
Name
Descriptive name for this controller that is shown in the tree.
No
Execution Style
Whether the controller will run in percent executions or total executions mode.
Yes
Throughput
A number. For percent execution mode, a number from 0-100that indicates
the percentage of times the controller will execute. "50" means the controller
will execute during half the iterations through the test plan. For total execution
mode, the number indicates the total number of times the controller will
execute.
Yes
Per User
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.
No
P a g e | 88
Runtime Controller
The Runtime Controller controls how long its children are allowed to run.
Screenshot of Control-Panel of
Runtime Controller
Parameters
Attribute
Description
Required
Name
Descriptive name for this controller that is shown in the tree, and used to
name the transaction.
Yes
Runtime (seconds)
Desired runtime in seconds
Yes
^
If Controller
The If Controller allows the user to control whether the test elements below it
(its children) are run or not.
By default, the condition is evaluated only once on initial entry, but you have
the option to have it evaluated for every runnable element contained in the
controller.
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 __jexl3, __groovy or __javaScript() (discouraged for performance)
function call. You can then use the objects "vars", "log", "ctx" etc. in the
script.
To test if a variable is undefined (or null) do the following, suppose var is
named myVar, expression will be:
"${myVar}" == "\${myVar}"
Or use:
"${myVar}" != "\${myVar}"
to test if a variable is defined and is not null.
Screenshot of
Control-Panel of If Controller
Parameters
Attribute
Description
Required
Name
Descriptive name for this controller that is shown in the tree.
No
Condition (default Javascript)
By default the condition is interpreted as Javascript code that returns "true"
or "false", but this can be overridden (see below)
Yes
Interpret Condition as Variable Expression?
P a g e | 90
While Controller
The While Controller runs its children until the condition is "false".
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 that the condition is evaluated twice, once before starting sampling
children and once at end of children sampling, so putting non idempotent
functions in Condition (like __counter) can introduce issues.
For example:
Screenshot of Control-Panel of
While Controller
Parameters
Attribute
Description
Required
Name
Descriptive name for this controller that is shown in the tree, and used to
name the transaction.
Yes
Condition
blank, LAST, or variable/function
Yes
^
Switch Controller
P a g e | 92
The Switch Controller acts like the 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.
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.
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.
Screenshot of Control-Panel of
Switch Controller
Parameters
Attribute
Description
Required
Name
Descriptive name for this controller that is shown in the tree, and used to
name the transaction.
Yes
Switch Value
The number (or name) of the subordinate element to be invoked. Elements
are numbered from 0.
Yes
^
ForEach Controller
P a g e | 93
inputVar_1 = wendy
inputVar_2 = charles
inputVar_3 = peter
inputVar_4 = john
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.
Screenshot of Control-Panel of
ForEach Controller
P a g e | 94
Parameters
Attribute
Description
Required
Name
Descriptive name for this controller that is shown in the tree.
No
Input variable prefix
Prefix for the variable names to be used as input.
Yes
Start index for loop
Start index (exclusive) for loop over variables (first element is at start index +
1)
No
End index for loop
End index (inclusive) for loop over variables
No
Output variable
The name of the variable which can be used in the loop for replacement in the
samplers
Yes
Use Separator
If not checked, the "_" separator is omitted.
Yes
ForEach Example
Download 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.
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.
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
In the ForEach loop, a HTTP sampler is added which requests all the links
that were extracted from the first returned HTML page.
ForEach Example
Here is another example 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
The Thread Group has a single thread and a loop count of two.
Sample 1 uses the JavaTest Sampler to return the string "a b c d".
The Regex Extractor uses the expression (\w)\s which matches a letter
followed by a space, and returns the letter (not the space). Any matches are
prefixed with the string "inputVar".
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 a g e | 96
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.
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.
Module Controller
The Module Controller provides a mechanism for substituting test plan
fragments into the current test plan at run-time.
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 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.
A fragment name is made up of the Controller name and all its parent names.
For example:
Test Plan / Protocol: JDBC / Control / Interleave Controller (Module1)
Any fragments used by the Module Controller must have a unique name,
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 a g e | 97
Parameters
Attribute
Description
Required
Name
Descriptive name for this controller that is shown in the tree.
No
Module to Run
The module controller provides a list of all controllers loaded into the gui.
Select the one you want to substitute in at runtime.
Yes
^
Include Controller
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 a g e | 98
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.
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.
Screenshot of Control-
Panel of Include Controller
Parameters
Attribute
Description
Required
Filename
The file to include.
Yes
^
Transaction Controller
P a g e | 99
Note: when the check box "Include duration of timer and pre-
post processors in generated sample" is checked, the time includes
all processing within the controller scope, not just the samples.
The generated sample time includes all the times for the nested samplers
excluding by default (since 2.11) timers and processing time of pre/post
processors unless checkbox "Include duration of timer and pre-
post processors in generated sample" is checked. Depending on
the clock resolution, it may be slightly longer than the sum of the individual
samplers plus timers. The clock might tick after the controller recorded the
start time but before the first sample starts. Similarly at the end.
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.
Parameters
Attribute
Description
Required
Name
Descriptive name for this controller that is shown in the tree, and used to
name the transaction.
Yes
Generate Parent Sample
If checked, then the sample is generated as a parent of the other samples,
otherwise the sample is generated as an independent sample.
Yes
Include duration of timer and pre-post processors in generated sample
Whether to include timer, pre- and post-processing delays in the generated
sample. Default is false
Yes
^
Recording Controller
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 HTTP(S) Test Script
Recorder, all recorded samples will by default be saved under the Recording
Controller.
Screenshot of Control-
Panel of Recording Controller
P a g e | 101
Parameters
Attribute
Description
Required
Name
Descriptive name for this controller that is shown in the tree.
No
^
Screenshot of
Control-Panel of Critical Section Controller
The figure below shows an example of using Critical Section Controller, in the
figure below 2 Critical Section Controllers ensure that:
Parameters
Attribute
Description
Required
Lock Name
Lock that will be taken by controller, ensure you use different lock names for
unrelated sections
Yes
Critical Section Controller takes locks only within one JVM, so if using
Distributed testing ensure your use case does not rely on all threads of all
JVMs blocking.
^
^
19.3 Listeners
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.
Note that Listeners are processed at the end of the scope in which they are
found.
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
P a g e | 103
".jtl" extension. Storing as CSV is the most efficient option, but is less
detailed than XML (the other available option).
Listeners do not process sample data in non-GUI mode, but the raw data
will be saved if an output file has been configured. In order to analyse the
data generated by a non-GUI test run, you need to load the file into the
appropriate Listener.
To read existing results and display them, use the file panel Browse button to
open the file.
If you want to clear any current data before loading a new file, use the menu
item Run → Clear (Ctrl + Shift + E) or Run → Clear All(Ctrl + E) before
loading the file.
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. In order to interpret a header-less CSV file correctly, the
appropriate properties must be set in jmeter.properties.
XML files written by JMeter have version 1.0 declared in header while actual
file is serialized with 1.1 rules. (This is done for historical compatibility
reasons; see Bug 59973 and Bug 58679) This causes strict XML parsers to
fail. Consider using non-strict XML parsers to read JTL files.
The file name can contain function and/or variable references. However
variable references do not work in client-server mode (functions work OK).
This is because the file is created on the client, and the client does not run the
test locally so does not set up variables.
Listeners can use a lot of memory if there are a lot of samples. Most of
the listeners currently keep a copy of every sample in their scope, apart from:
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 a g e | 104
Aggregate Report
Aggregate Graph
To minimise the amount of memory needed, use the Simple Data Writer, and
use the CSV format.
JMeter variables can be saved to the output files. This can only be specified
using a property. See the Listener Sample Variables for details
For full details on setting up the default items to be saved see the Listener
Default Configuration documentation. For details of the contents of the output
files, see the CSV log format or the XML log format.
The figure below shows an example of the result file configuration panel
Parameters
Attribute
Description
Required
Filename
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).
JMeter 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.
P a g e | 105
No
Browse …
File Browse Button
No
Errors
Select this to write/read only results with errors
No
Successes
Select this to write/read only results without errors. If
neither Errorsnor Successes is selected, then all results are processed.
No
Configure
Configure Button, see below
No
Note that cookies, method and the query string are saved as part of the
"Sampler Data" option.
P a g e | 106
Graph Results
Graph Results MUST NOT BE USED during load test as it consumes a lot of
resources (memory and CPU). Use it only for either functional testing or
during Test Plan debugging and Validation.
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.
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.
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".
The value displayed on the top left of graph is the max of 90th percentile of
response time.
Assertion Results
Assertion Results MUST NOT BE USED during load test as it consumes a lot
of resources (memory and CPU). Use it only for either functional testing or
during Test Plan debugging and Validation.
The Assertion Results visualizer shows the Label of each sample taken. It
also reports failures of any Assertions that are part of the test plan.
See also:
Response Assertion
There are several ways to view the response, selectable by a drop-down box
at the bottom of the left hand panel.
Renderer Description
CSS/JQuery The CSS/JQuery Tester only works for text responses. It shows the plain text
Tester in the upper panel. The "Test" button allows the user to apply the
CSS/JQuery to the upper panel and the results will be displayed in the lower
panel.
The CSS/JQuery expression engine can be JSoup or Jodd, syntax of these 2
implementation differs slightly.
For example, the Selector a[class=sectionlink] with
attribute href applied to the current JMeter functions page gives the
following output:
Match count: 74
Match[1]=#functions
Match[2]=#what_can_do
Match[3]=#where
Match[4]=#how
Match[5]=#function_helper
Match[6]=#functions
Match[7]=#__regexFunction
Match[8]=#__regexFunction_parms
Match[9]=#__counter
… and so on …
P a g e | 110
Document The Document view will show the extract text from various type of documents
like Microsoft Office (Word, Excel, PowerPoint 97-2003, 2007-2010
(openxml), Apache OpenOffice (writer, calc, impress), HTML, gzip, jar/zip
files (list of content), and some meta-data on "multimedia" files like mp3,
mp4, flv, etc. The complete list of support format is available on Apache Tika
format page.
A requirement to the Document view is to download the Apache Tika
binary package (tika-app-x.x.jar) and put this
in JMETER_HOME/lib directory.
If the document is larger than 10 MB, then it won't be displayed. To change
this limit, set the JMeter property document.max_size (unit is byte) or set
to 0 to remove the limit.
HTML 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.
Images, style-sheets, etc. aren't downloaded.
HTML If the HTML (download resources) view option is selected, the renderer may
(download download images, style-sheets, etc. referenced by the HTML code.
resources)
HTML Source If the HTML Source formatted view option is selected, the renderer will
formatted display the HTML source code formatted and cleaned by Jsoup.
JSON The JSON view will show the response in tree style (also handles JSON
embedded in JavaScript).
JSON Path The JSON Path Tester view will let you test your JSON-PATH expressions
Tester and see the extracted data from a particular response.
Regexp The Regexp Tester view only works for text responses. It shows the plain text
Tester 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.
The regular expression engine is the same as that used in the Regular
Expression Extractor.
For example, the RE (JMeter\w*).* applied to the current JMeter home
page gives the following output:
Match count: 26
Match[1][0]=JMeter - Apache JMeter</title>
Match[1][1]=JMeter
Match[2][0]=JMeter" title="JMeter" border="0"/></a>
Match[2][1]=JMeter
Match[3][0]=JMeterCommitters">Contributors</a>
Match[3][1]=JMeterCommitters
… and so on …
P a g e | 111
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).
Text 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.
image/
audio/
video/
XML 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.
XPath The XPath Tester only works for text responses. It shows the plain text in the
Tester upper panel. The "Test" button allows the user to apply the XPath query to
the upper panel and the results will be displayed in the lower panel.
With Search option, most of the views also allow the displayed data to be
searched; the result of the search will be high-lighted in the display above. For
example the Control panel screenshot below shows one result of searching
for "Java". Note that the search operates on the visible text, so you may get
different results when searching the Text and HTML views.
Note: The regular expression uses the Java engine (not ORO engine like the
Regular Expression Extractor or Regexp Tester view).
If the response data is larger than 200K, then it won't be displayed. To change
this limit, set the JMeter property view.results.tree.max_size. You can
also use save the entire response to a file using Save Responses to a file.
Aggregate Report
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
P a g e | 116
(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.
The throughput is calculated from the point of view of the sampler target (e.g.
the remote server in the case of HTTP samples). JMeter takes into account
the total time over which the requests have been generated. If other samplers
and timers are in the same thread, these will increase the total time, and
therefore reduce the throughput value. So two identical samplers with different
names will have half the throughput of two samplers with the same name. It is
important to choose the sampler names correctly to get the best results from
the Aggregate Report.
Calculation of the Median and 90% Line (90th percentile) values requires
additional memory. JMeter now combines samples with the same elapsed
time, so far less memory is used. However, for samples that take more than a
few seconds, the probability is that fewer samples will have identical times, in
which case more memory will be needed. Note you can use this listener
afterwards to reload a CSV or XML results file which is the recommended way
to avoid performance impacts. See the Summary Report for a similar Listener
that does not store individual samples and so needs constant memory.
Starting with JMeter 2.12, you can configure the 3 percentile values you want
to compute, this can be done by setting properties:
99% Line - 99% of the samples took no more than this time. The
remaining samples took at least as long as this. (99thpercentile)
Min - The shortest time for the samples with the same label
Max - The longest time for the samples with the same label
Error % - Percent of requests with errors
Throughput - the Throughput 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.
Received KB/sec - The throughput measured in received Kilobytes
per second
Sent KB/sec - The throughput measured in sent Kilobytes per second
By default, it only displays the main (parent) samples; it does not display the
sub-samples (child samples). JMeter has a "Child Samples?" check-box. If
this is selected, then the sub-samples are displayed instead of the main
samples.
P a g e | 119
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.
The monitor requires Tomcat 5 or above. Use a browser to check that you can
access the Tomcat status servlet OK.
For a detailed description of how to use the monitor, please refer to Building a
Monitor Test Plan
P a g e | 121
Aggregate Graph
P a g e | 122
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.
P a g e | 123
P a g e | 124
Parameters
Attribute
Description
Required
Column settings
Yes
Title
Define the graph's title on the head of chart. Empty value is the default value :
"Aggregate Graph". The button Synchronize with name define the title
with the label of the listener. And define font settings for graph title
No
Graph size
Compute the graph size by the width and height depending of the current
JMeter's window size. Use Width and Height fields to define a custom size.
The unit is pixel.
No
X Axis settings
Define the max length of X Axis label (in pixel).
No
Y Axis settings
Define a custom maximum value for Y Axis.
No
Legend
Define the placement and font settings for chart legend
Yes
^
Parameters
Attribute
Description
Required
Interval (ms)
The time in milli-seconds for X axis interval. Samples are grouped according
to this value. Before display the graph, click on Apply interval button to
refresh internal data.
Yes
Sampler label selection
Filter by result label. A regular expression can be used,
ex. .*Transaction.*. Before display the graph, click on Apply
filter button to refresh internal data.
No
P a g e | 128
Title
Define the graph's title on the head of chart. Empty value is the default value :
"Response Time Graph". The button Synchronize with name define
the title with the label of the listener. And define font settings for graph title
No
Line settings
Define the width of the line. Define the type of each value point.
Choose none to have a line without mark
Yes
Graph size
Compute the graph size by the width and height depending of the current
JMeter's window size. Use Width and Height fields to define a custom size.
The unit is pixel.
No
X Axis settings
Customize the date format of X axis label. The syntax is the
Java SimpleDateFormat API.
No
Y Axis settings
Define a custom maximum value for Y Axis in milli-seconds. Define the
increment for the scale (in ms) Show or not the number grouping in Y Axis
labels.
No
Legend
Define the placement and font settings for chart legend
Yes
^
Mailer Visualizer
The mailer visualizer can be set up to send email if a test run receives too
many failed responses from the server.
P a g e | 129
Parameters
Attribute
Description
Required
Name
Descriptive name for this element that is shown in the tree.
No
From
Email address to send messages from.
Yes
Addressee(s)
Email address to send messages to, comma-separated.
Yes
Success Subject
Email subject line for success messages.
No
Success Limit
P a g e | 130
BeanShell Listener
The BeanShell Listener allows the use of BeanShell for processing samples
for saving etc.
For full details on using BeanShell, please see the BeanShell website.
P a g e | 131
Parameters
Attribute
Description
P a g e | 132
Required
Name
Descriptive name for this element that is shown in the tree. The name is
stored in the script variable Label
Reset bsh.Interpreter before each call
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 Best Practices - BeanShell scripting.
Yes
Parameters
Parameters to pass to the BeanShell script. The parameters are stored in the
following variables:
Parameters
string containing the parameters as a single variable
bsh.args
String array containing parameters, split on white-space
No
Script file
A file containing the BeanShell script to run. The file name is stored in the
script variable FileName
No
Script
The BeanShell script to run. The return value is ignored.
Yes (unless script file is provided)
Before invoking the script, some variables are set up in the BeanShell
interpreter:
For details of all the methods available on each of the above variables, please
check the Javadoc
Summary Report
The summary report creates a table row for each differently named request in
your test. This is similar to the Aggregate Report , except that it uses less
memory.
The throughput is calculated from the point of view of the sampler target (e.g.
the remote server in the case of HTTP samples). JMeter takes into account
the total time over which the requests have been generated. If other samplers
and timers are in the same thread, these will increase the total time, and
therefore reduce the throughput value. So two identical samplers with different
names will have half the throughput of two samplers with the same name. It is
important to choose the sampler labels correctly to get the best results from
the Report.
Screenshot of
Control-Panel of Save Responses to a file
Parameters
Attribute
Description
Required
Name
Descriptive name for this element that is shown in the tree.
No
Filename Prefix
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). JMeter also supports 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.
Yes
Variable Name
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.
No
Save Failed Responses only
If selected, then only failed responses are saved
Yes
Save Successful Responses only
P a g e | 137
Parameters
Attribute
Description
Required
Name
Descriptive name for this element that is shown in the tree.
No
Language
P a g e | 139
The script (or file) is processed using the BSFEngine.exec() method, which
does not return a value.
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.
log
(Logger) - can be used to write to the log file
Label
the String Label
FileName
the script file name (if any)
Parameters
the parameters (as a String)
args
the parameters as a String array (split on whitespace)
ctx
(JMeterContext) - gives access to the context
vars
(JMeterVariables) - gives read/write access to variables:
vars.get(key);
vars.put(key,val);
vars.putObject("OBJ1",new Object());
vars.getObject("OBJ2");
props
P a g e | 140
For details of all the methods available on each of the above variables, please
check the Javadoc
JSR223 Listener
The JSR223 Listener allows JSR223 script code to be applied to sample
results.
Parameters
Attribute
Description
Required
Name
Descriptive name for this element that is shown in the tree.
No
Language
The JSR223 language to be used
Yes
Parameters
Parameters to pass to the script. The parameters are stored in the following
variables:
Parameters
string containing the parameters as a single variable
args
String array containing parameters, split on white-space
No
Script file
P a g e | 141
A file containing the script to run, if a relative file path is used, then it will be
relative to directory referenced by "user.dir" System property
No
Script compilation caching
Unique String across Test Plan that JMeter will use to cache result of Script
compilation if language used supports Compilable interface (Groovy is one
of these, java, beanshell and javascript are not).
See note in JSR223 Sampler Java System property if you're using Groovy
without checking this option
No
Script
The script to run.
Yes (unless script file is provided)
Before invoking the script, some variables are set up. Note that these are
JSR223 variables - i.e. they can be used directly in the script.
log
(Logger) - can be used to write to the log file
Label
the String Label
FileName
the script file name (if any)
Parameters
the parameters (as a String)
args
the parameters as a String array (split on whitespace)
ctx
(JMeterContext) - gives access to the context
vars
(JMeterVariables) - gives read/write access to variables:
vars.get(key);
vars.put(key,val);
vars.putObject("OBJ1",new Object());
vars.getObject("OBJ2");
props
(JMeterProperties - class java.util.Properties) -
e.g. props.get("START.HMS"); props.put("PROP1","1234")
;
sampleResult, prev
(SampleResult) - gives access to the SampleResult
sampleEvent
P a g e | 142
For details of all the methods available on each of the above variables, please
check the Javadoc
label + 80 in 0:00:30 = 2.7/s Avg: 1531 Min: 1013 Max: 2014 Err:
0 (0.00%) Active: 5 Started: 5 Finished: 0
label = 342 in 0:02:12 = 2.6/s Avg: 1536 Min: 1003 Max: 2020 Err:
0 (0.00%)
label + 83 in 0:00:31 = 2.7/s Avg: 1512 Min: 1003 Max: 1982 Err:
0 (0.00%) Active: 5 Started: 5 Finished: 0
label = 425 in 0:02:43 = 2.6/s Avg: 1531 Min: 1003 Max: 2020 Err:
0 (0.00%)
label + 83 in 0:00:29 = 2.8/s Avg: 1487 Min: 1023 Max: 2013 Err:
0 (0.00%) Active: 5 Started: 5 Finished: 0
label = 508 in 0:03:12 = 2.6/s Avg: 1524 Min: 1003 Max: 2020 Err:
0 (0.00%)
label + 78 in 0:00:30 = 2.6/s Avg: 1594 Min: 1013 Max: 2016 Err:
0 (0.00%) Active: 5 Started: 5 Finished: 0
label = 586 in 0:03:43 = 2.6/s Avg: 1533 Min: 1003 Max: 2020 Err:
0 (0.00%)
label + 80 in 0:00:30 = 2.7/s Avg: 1516 Min: 1013 Max: 2005 Err:
0 (0.00%) Active: 5 Started: 5 Finished: 0
label = 666 in 0:04:12 = 2.6/s Avg: 1531 Min: 1003 Max: 2020 Err:
0 (0.00%)
label + 86 in 0:00:30 = 2.9/s Avg: 1449 Min: 1004 Max: 2017 Err:
0 (0.00%) Active: 5 Started: 5 Finished: 0
label = 752 in 0:04:43 = 2.7/s Avg: 1522 Min: 1003 Max: 2020 Err:
0 (0.00%)
label + 65 in 0:00:24 = 2.7/s Avg: 1579 Min: 1007 Max: 2003 Err:
0 (0.00%) Active: 0 Started: 5 Finished: 5
label = 817 in 0:05:07 = 2.7/s Avg: 1526 Min: 1003 Max: 2020 Err:
0 (0.00%)
The "label" is 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 total line, i.e. it shows the running total.
Entries in the JMeter log file also include time-stamps. The example "817 in
0:05:07 = 2.7/s" means that there were 817 samples recorded in 5
minutes and 7 seconds, and that works out at 2.7 samples per second.
The Avg (Average), Min (Minimum) and Max (Maximum) 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 synchronizes to the
interval boundary. The last delta will be lower, as the test will generally not
finish on an exact interval boundary.
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
P a g e | 144
Screenshot of Control-Panel of
Generate Summary Results
Parameters
Attribute
Description
Required
Name
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.
Yes
^
Parameters
Attribute
Description
Required
Name
Descriptive name for this element that is shown in the tree.
Yes
^
Backend Listener
The backend listener is an Asynchronous listener that enables you to plug
custom implementations of BackendListenerClient. By default, a Graphite
implementation is provided.
P a g e | 146
Parameters
Attribute
Description
Required
Name
Descriptive name for this element that is shown in the tree.
Yes
Backend Listener implementation
Class of the BackendListenerClient implementation.
Yes
Async Queue size
Size of the queue that holds the SampleResults while they are processed
asynchronously.
Yes
Parameters
Parameters of the BackendListenerClient implementation.
Yes
Parameters
P a g e | 147
Attribute
Description
Required
graphiteMetricsSender
org.apache.jmeter.visualizers.backend.graphite.TextGraphi
teMetricsSenderor org.apache.jmeter.visualizers.backend.gr
aphite.PickleGraphiteMetricsSender
Yes
graphiteHost
Graphite or InfluxDB (with Graphite plugin enabled) server host
Yes
graphitePort
Graphite or InfluxDB (with Graphite plugin enabled) server port, defaults
to 2003. Note PickleGraphiteMetricsSender (port 2004) can only talk
to Graphite server.
Yes
rootMetricsPrefix
Prefix of metrics sent to backend. Defaults to "jmeter." Note that JMeter
does not add a separator between the root prefix and the samplerName which
is why the trailing dot is currently needed.
Yes
summaryOnly
Only send a summary with no detail. Defaults to true.
Yes
samplersList
Defines the names (labels) of sample results to be sent to the back end.
If useRegexpForSamplersList=false this is a list of semi-colon
separated names. If useRegexpForSamplersList=true this is a regular
expression which will be matched against the names.
Yes
useRegexpForSamplersList
Consider samplersList as a regular expression to select the samplers for
which you want to report metrics to backend. Defaults to false.
Yes
percentiles
The percentiles you want to send to the backend. A percentile may contain a
fractional part, for example 12.5. (The separator is always ".") List must be
semicolon separated. Generally 3 or 4 values should be sufficient.
Yes
Grafana dashboard
^
^
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 testing with
"random" and unique values.
JMeter allows values to be quoted; this allows the value to contain a delimiter.
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:
1,"2,3","4""5" =>
1
2,3
4"5
JMeter supports 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.
JMeter supports CSV files with quoted data that includes new-lines.
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.
See the description of the Share mode below for additional options. If you
want each thread to have its own set of values, then you will need to create a
set of files, one for each thread. For example test1.csv, test2.csv,
…, testn.csv. Use the filename test${__threadNum}.csv and set the
"Sharing mode" to "Current thread".
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
P a g e | 150
As a special case, the string "\t" (without quotes) in the delimiter field is
treated as a Tab.
When the end of file (EOF) is reached, and the recycle option is true, reading
starts again with the first line of the file.
If the recycle option is false, and stopThread is false, then all the variables
are set to <EOF> when the end of file is reached. This value can be changed
by setting the JMeter property csvdataset.eofstring.
Screenshot of Control-
Panel of CSV Data Set Config
Parameters
Attribute
Description
Required
Name
Descriptive name for this element that is shown in the tree.
Filename
P a g e | 151
Name of the file to be read. Relative file names are resolved with respect
to the path of the active test plan. For distributed testing, the CSV file
must be stored on the server host system in the correct relative
directory to where the jmeter server is started. 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.
Yes
File Encoding
The encoding to be used to read the file, if not the platform default.
No
Variable Names
List of variable names (comma-delimited). JMeter supports CSV header lines:
if the variable name field empty, then the first line of the file is read and
interpreted as the list of column names. The names must be separated by the
delimiter character. They can be quoted using double-quotes.
Yes
Delimiter
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).
Yes
Allow quoted data?
Should the CSV file allow values to be quoted? If enabled, then values can be
enclosed in " - double-quote - allowing values to contain a delimiter.
Yes
Recycle on EOF?
Should the file be re-read from the beginning on reaching EOF? (default
is true)
Yes
Stop thread on EOF?
Should the thread be stopped on EOF, if Recycle is false? (default is false)
Yes
Sharing mode
All threads - (the default) the file is shared between all the
threads.
P a g e | 152
Yes
^
Screenshot
of Control-Panel of FTP Request Defaults
^
Parameters
Attribute
Description
Required
Name
Descriptive name for this element that is shown in the tree.
No
Clear cache each Iteration
If selected, DNS cache of every Thread is cleared each time new iteration is
started.
No
Use system DNS resolver
System DNS resolver will be used. For correct work
edit$JAVA_HOME/jre/lib/security/java.security and
add networkaddress.cache.ttl=0
P a g e | 154
N/A
Use custom DNS resolver
Custom DNS resolver(from dnsjava library) will be used.
N/A
Hostname or IP address
List of DNS servers to use. If empty, network configuration DNS will used.
No
Add Button
Add an entry to the DNS servers table.
N/A
Delete Button
Delete the currently selected table entry.
N/A
^
The Authorization headers may not be shown in the Tree View Listener
"Request" tab. The Java implementation does pre-emptive authentication,
but it does not return the Authorization header when JMeter fetches the
headers. The Commons HttpClient (3.1) implementation defaults to pre-
emptive and the header will be shown. The HttpComponents (HC 4.5.X)
implementation does not do pre-emptive auth (it is supported by the library but
JMeter does not enable it)
In the
file jmeter.properties set httpclient.parameters.file=httpclie
nt.parameters and
in httpclient.parameters set http.authentication.preemptive$
Boolean=false
P a g e | 155
Parameters
Attribute
Description
Required
Name
Descriptive name for this element that is shown in the tree.
No
Clear auth on each iteration?
Used by Kerberos authentication. If checked, authentication will be done on
each iteration of Main Thread Group loop even if it has already been done in a
previous one. This is usually useful if each main thread group iteration
represents behaviour of one Virtual User.
P a g e | 156
Yes
Base URL
A partial or complete URL that matches one or more HTTP Request URLs. As
an example, say you specify a Base URL of
"http://localhost/restricted/" with a Username of "jmeter" and
a Password of "jmeter". If you send an HTTP request to the URL
"http://localhost/restricted/ant/myPage.html", the Authorization
Manager sends the login information for the user named, "jmeter".
Yes
Username
The username to authorize.
Yes
Password
The password for the user. (N.B. this is stored unencrypted in the test plan)
Yes
Domain
The domain to use for NTLM.
No
Realm
The realm to use for NTLM.
No
Mechanism
Type of authentication to perform. JMeter can perform different types of
authentications based on used Http Samplers:
Java
BASIC
HttpClient 3.1
BASIC and DIGEST
HttpClient 4
BASIC, DIGEST and Kerberos
No
The Realm only applies to the HttpClient sampler.
Kerberos Configuration:
To configure Kerberos you need to setup at least two JVM system properties:
-Djava.security.krb5.conf=krb5.conf
-Djava.security.auth.login.config=jaas.conf
P a g e | 157
kerberos.spnego.strip_port=false
Controls:
When you save the Test Plan, JMeter automatically saves all of the
authorization table entries - including any passwords, which are not
encrypted.
Authorization Example
When we run the Test Plan, JMeter looks in the Authorization table for the
URL it is requesting. If the Base URL matches the URL, then JMeter passes
this information along with the request.
You can download the Test Plan, but since it is built as a test for our local
server, you will not be able to run it. However, you can use it as a reference in
constructing your own Test Plan.
^
If a sample is successful (i.e. has response code 2xx) then the Last-
Modified and Etag (and Expired if relevant) values are saved for the URL.
Before executing the next sample, the sampler checks to see if there is an
entry in the cache, and if so, the If-Last-Modified and If-None-
Match conditional headers are set for the request.
If the requested document has not changed since it was cached, then the
response body will be empty. Likewise if the Expires date is in the future.
This may cause problems for Assertions.
Responses with a Vary header will not be cached.
P a g e | 160
Screenshot of
Control-Panel of HTTP Cache Manager
Parameters
Attribute
Description
Required
Name
Descriptive name for this element that is shown in the tree.
No
Clear cache each iteration
If selected, then the cache is cleared at the start of the thread.
Yes
Use Cache Control/Expires header when processing GET requests
See description above.
Yes
Max Number of elements in cache
See description above.
Yes
^
appear on the Cookie Manager display, but they can be seen using the View
Results Tree Listener.
JMeter checks that received cookies are valid for the URL. This means that
cross-domain cookies are not stored. If you have bugged behaviour or want
Cross-Domain cookies to be used, define the JMeter property
"CookieManager.check.cookies=false".
Second, you can manually add a cookie to the Cookie Manager. However, if
you do this, the cookie will be shared by all JMeter threads.
Note that such Cookies are created with an Expiration time far in the future
Cookies with null values are ignored by default. This can be changed by
setting the JMeter
property: CookieManager.delete_null_cookies=false. Note that this
also applies to manually defined cookies - any such cookies will be removed
from the display when it is updated. Note also that the cookie name must be
unique - if a second cookie is defined with the same name, it will replace the
first.
P a g e | 162
Parameters
Attribute
Description
Required
Name
Descriptive name for this element that is shown in the tree.
No
Clear Cookies each Iteration
If selected, all server-defined cookies are cleared each time the main Thread
Group loop is executed. Any cookie defined in the GUI are not cleared.
Yes
Cookie Policy
The cookie policy that will be used to manage the cookies. "standard" is the
default since 3.0, and should work in most cases. See Cookie
specifications and CookieSpec implementations [Note: "ignoreCookies" is
equivalent to omitting the CookieManager.] If you still use HC3CookieHandler
P a g e | 163
could add a single HTTP Request Defaults element with the "Server Name
or IP" field filled in. Then, when you add the 25 HTTP Request controllers,
leave the "Server Name or IP" field empty. The controllers will inherit this
field value from the HTTP Request Defaults element.
All port values are treated equally; a sampler that does not specify a port will
use the HTTP Request Defaults port, if one is provided.
Parameters
Attribute
Description
Required
Name
Descriptive name for this element that is shown in the tree.
No
Server
Domain name or IP address of the web server. e.g. www.example.com. [Do
not include the http:// prefix.
No
Port
Port the web server is listening to.
No
Connect Timeout
Connection Timeout. Number of milliseconds to wait for a connection to open.
No
Response Timeout
Response Timeout. Number of milliseconds to wait for a response.
No
Implementation
Java, HttpClient3.1 (DEPRECATED SINCE 3.0), HttpClient4. If not
specified the default depends on the value of the JMeter
property jmeter.httpsampler, failing that, the Java implementation is
used.
No
P a g e | 166
Protocol
HTTP or HTTPS.
No
Content encoding
The encoding to be used for the request.
No
Path
The path to resource (for example, /servlets/myServlet). If the resource
requires query string parameters, add them below in the "Send Parameters
With the Request" section. Note that the path is the default for the full
path, not a prefix to be applied to paths specified on the HTTP Request
screens.
No
Send Parameters With the Request
The query string will be generated from the list of parameters you provide.
Each parameter has a name and value. The query string will be generated in
the correct fashion, depending on the choice of "Method" you made (i.e. if you
chose GET, the query string will be appended to the URL, if POST, then it will
be sent separately). Also, if you are sending a file using a multipart form, the
query string will be created using the multipart form specifications.
No
Server (proxy)
Hostname or IP address of a proxy server to perform request. [Do not include
the http:// prefix.]
No
Port
Port the proxy server is listening to.
No, unless proxy hostname is specified
Username
(Optional) username for proxy server.
No
Password
(Optional) password for proxy server. (N.B. this is stored unencrypted in the
test plan)
No
Retrieve All Embedded Resources from HTML Files
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.
No
Use concurrent pool
Use a pool of concurrent connections to get embedded resources.
P a g e | 167
No
Size
Pool size for concurrent connections used to get embedded resources.
No
Embedded URLs must match:
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/.*
No
Note: radio buttons only have two states - on or off. This makes it impossible
to override settings consistently - does off mean off, or does it mean use the
current default? JMeter uses the latter (otherwise defaults would not work at
all). So if the button is off, then a later element can set it on, but if the button is
on, a later element cannot set it off.
^
JMeter now supports multiple Header Managers. The header entries are
merged to form the list for the sampler. If an entry to be merged matches an
existing header name, it replaces the previous entry, unless the entry value is
empty, in which case any existing entry is removed. This allows one to set up
a default set of headers, and apply adjustments to particular samplers.
Parameters
Attribute
Description
Required
Name
Descriptive name for this element that is shown in the tree.
No
Name (Header)
Name of the request header. Two common request headers you may want to
experiment with are "User-Agent" and "Referer".
No (You should have at least one, however)
Value
Request header value.
No (You should have at least one, however)
Add Button
Add an entry to the header table.
N/A
Delete Button
Delete the currently selected table entry.
N/A
Load Button
Load a previously saved header table and add the entries to the existing
header table entries.
N/A
Save As Button
Save the current header table to a file.
N/A
Header Manager example
Download this example. In this example, we created a Test Plan that tells
JMeter to override the default "User-Agent" request header and use a
particular Internet Explorer agent string instead. (see figures 12 and 13).
P a g e | 169
Figure 13 - Header
Manager Control Panel
^
Screenshot of
Control-Panel of JDBC Connection Configuration
Parameters
Attribute
Description
Required
Name
Descriptive name for the connection configuration that is shown in the tree.
No
Variable Name
The name of the variable the connection is tied to. Multiple connections can
be used, each tied to a different variable, allowing JDBC Samplers to select
the appropriate connection.
Each name must be different. If there are two configuration elements using
the same name, only one will be saved. JMeter logs a message if a duplicate
name is detected.
Yes
Max Number of Connections
P a g e | 172
Maximum number of connections allowed in the pool. In most cases, set this
to zero (0). This means that each thread will get its own pool with a single
connection in it, i.e. the connections are not shared between threads.
If you really want to use shared pooling (why?), then set the max count to the
same as the number of threads to ensure threads don't wait on each other.
Yes
Max Wait (ms)
Pool throws an error if the timeout period is exceeded in the process of trying
to retrieve a connection, see BasicDataSource.html#getMaxWaitMillis
Yes
Time Between Eviction Runs (ms)
The number of milliseconds to sleep between runs of the idle object evictor
thread. When non-positive, no idle object evictor thread will be run. (Defaults
to "60000", 1 minute).
See BasicDataSource.html#getTimeBetweenEvictionRunsMillis
Yes
Auto Commit
Turn auto commit on or off for the connections.
Yes
Test While Idle
Test idle connections of the pool,
see BasicDataSource.html#getTestWhileIdle. Validation Query will be used to
test it.
Yes
Soft Min Evictable Idle Time(ms)
Minimum amount of time a connection may sit idle in the pool before it is
eligible for eviction by the idle object evictor, with the extra condition that at
least minIdle connections remain in the pool.
See BasicDataSource.html#getSoftMinEvictableIdleTimeMillis. Defaults to
5000 (5 seconds)
Yes
Validation Query
A simple query used to determine if the database is still responding. This
defaults to the 'isValid()' method of the jdbc driver, which is suitable for
many databases. However some may require a different query; for example
Oracle something like 'SELECT 1 FROM DUAL' could be used.
Note this validation query is used on pool creation to validate it even if "Test
While Idle" suggests query would only be used on idle connections. This is
DBCP behaviour.
No
Database URL
P a g e | 173
Different databases and JDBC drivers require different JDBC settings. The
Database URL and JDBC Driver class are defined by the provider of the
JDBC implementation.
Some possible settings are shown below. Please check the exact details in
the JDBC driver documentation.
The driver class was not found. In this case, there will be a log message
such as DataSourceElement: Could not load driver:
{classname} java.lang.ClassNotFoundException:
{classname}
The driver class was found, but the class does not support the
connection string. This could be because of a syntax error in the
connection string, or because the wrong classname was used.
java.net.ConnectException
Datab
Driver class Database URL
ase
MyS com.mysql.jdbc.Driver jdbc:mysql://host[:port]/dbname
QL
Postgr org.postgresql.Driver jdbc:postgresql:{dbname}
eSQL
Oracl oracle.jdbc.OracleDrive jdbc:oracle:thin:@//host:port/servi
e r ce OR
jdbc:oracle:thin:@(description=(add
ress=(host={mc-
P a g e | 174
name})(protocol=tcp)(port={port-
no}))(connect_data=(sid={sid})))
Ingres ingres.jdbc.IngresDrive jdbc:ingres://host:port/db[;attr=va
(2006 r lue]
)
SQL com.microsoft.sqlserver jdbc:sqlserver://host:port;Database
Server .jdbc.SQLServerDriver Name=dbname
(MS
JDBC
driver
)
Apach org.apache.derby.jdbc.C jdbc:derby://server[:port]/database
e lientDriver Name[;URLAttributes=value[;…]]
Derby
The above may not be correct - please check the relevant JDBC driver
documentation.
^
Keystore Configuration
The Keystore Config Element lets you configure how Keystore will be loaded
and which keys it will use. This component is typically used in HTTPS
scenarios where you don't want to take into account keystore initialization into
account in response time.
To use this element, you need to setup first a Java Key Store with the client
certificates you want to test, to do that:
Screenshot of Control-
Panel of Keystore Configuration
Parameters
Attribute
Description
Required
Name
Descriptive name for this element that is shown in the tree.
No
Preload
Wether or not to preload Keystore. Setting it to true is usually the best
option.
Yes
Variable name holding certificate alias
Variable name that will contain the alias to use for authentication by client
certificate. Variable value will be filled from CSV Data Set for example. In the
screenshot, "certificat_ssl" will also be a variable in CSV Data Set.
False
Alias Start Index
The index of the first key to use in Keystore, 0-based.
Yes
Alias End Index
The index of the last key to use in Keystore, 0-based. When using "Variable
name holding certificate alias" ensure it is large enough so that all
keys are loaded at startup.
Yes
To make JMeter use more than one certificate you need to ensure that:
https.use.cached.ssl.context=false is set
in jmeter.properties or user.properties
P a g e | 176
Screenshot of
Control-Panel of Login Config Element
Parameters
Attribute
Description
Required
Name
Descriptive name for this element that is shown in the tree.
No
Username
The default username to use.
No
Password
The default password to use. (N.B. this is stored unencrypted in the test plan)
No
^
Parameters
Attribute
Description
Required
Name
Descriptive name for this element that is shown in the tree.
TCPClient classname
Name of the TCPClient class. Defaults to the property tcp.handler, failing
that TCPClientImpl.
No
ServerName or IP
Name or IP of TCP server
Port Number
Port to be used
Re-use connection
If selected, the connection is kept open. Otherwise it is closed when the data
has been read.
P a g e | 179
Yes
Close connection
If selected, the connection will be closed after running the sampler.
Yes
SO_LINGER
Enable/disable SO_LINGER with the specified linger time in seconds when a
socket is created. If you set "SO_LINGER" value as 0, you may prevent large
numbers of sockets sitting around with a TIME_WAIT status.
No
End of line(EOL) byte value
Byte value for end of line, set this to a value outside the range -
128 to +127 to skip eol checking. You may set this
in jmeter.properties file as well with the tcp.eolByte property. If you
set this in TCP Sampler Config and in jmeter.properties file at the same
time, the setting value in the TCP Sampler Config will be used.
No
Connect Timeout
Connect Timeout (milliseconds, 0 disables).
No
Response Timeout
Response Timeout (milliseconds, 0 disables).
No
Set Nodelay
Should the nodelay property be set?
Text to Send
Text to be sent
^
Note that all the UDV elements in a test plan - no matter where they are - are
processed at the start.
So you cannot reference variables which are defined as part of a test run, e.g.
in a Post-Processor.
UDVs should not be used with functions that generate different results
each time they are called. Only the result of the first function call will be
P a g e | 180
saved in the variable. However, UDVs can be used with functions such
as __P(), for example:
HOST ${__P(host,localhost)}
which would define the variable "HOST" to have the value of the JMeter
property "host", defaulting to "localhost" if not defined.
For defining variables during a test run, see User Parameters. UDVs are
processed in the order they appear in the Plan, from top to bottom.
For simplicity, it is suggested that UDVs are placed only at the start of a
Thread Group (or perhaps under the Test Plan itself).
Once the Test Plan and all UDVs have been processed, the resulting set of
variables is copied to each thread to provide the initial set of variables.
Parameters
Attribute
Description
Required
Name
Descriptive name for this element that is shown in the tree.
User Defined Variables
Variable name/value pairs. The string under the "Name" column is what you'll
need to place inside the brackets in ${…}constructs to use the variables later
on. The whole ${…} will then be replaced by the string in the "Value" column.
^
Random Variable
The Random Variable Config Element is used to generate random numeric
strings and store them in variable for use later. It's simpler than using User
Defined Variables together with the __Random() function.
Screenshot of
Control-Panel of Random Variable
Parameters
Attribute
Description
Required
Name
Descriptive name for this element that is shown in the tree.
Yes
Variable Name
The name of the variable in which to store the random string.
Yes
Format String
The java.text.DecimalFormat format string to be used. For example
"000" which will generate numbers with at least 3 digits, or "USER_000" which
will generate output of the form USER_nnn. If not specified, the default is to
generate the number using Long.toString()
No
Minimum Value
The minimum value (long) of the generated random number.
Yes
Maximum Value
The maximum value (long) of the generated random number.
Yes
Random Seed
P a g e | 183
The seed for the random number generator. Default is the current time in
milliseconds. If you use the same seed value with Per Thread set to true,
you will get the same value for each Thread as per Random class.
No
Per Thread(User)?
If False, the generator is shared between all threads in the thread group.
If True, then each thread has its own random generator.
Yes
^
Counter
Allows the user to create a counter that can be referenced anywhere in the
Thread Group. The counter config lets the user configure a starting point, a
maximum, and the increment. The counter will loop from the start to the max,
and then start over with the start, continuing on like that until the test is ended.
The counter uses a long to store the value, so the range is from -
2^63 to 2^63-1.
Screenshot of Control-
Panel of Counter
Parameters
Attribute
Description
Required
Name
P a g e | 184
primarily for developers as a basic GUI that they can use while developing
new JMeter components.
Parameters
Attribute
Description
Required
Name
Descriptive name for this element that is shown in the tree.
Yes
Parameter Name
The name of each parameter. These values are internal to JMeter's workings
and are not generally documented. Only those familiar with the code will know
these values.
Yes
Parameter Value
The value to apply to that parameter.
Yes
^
Parameters
Attribute
Description
Required
Name
Descriptive name for the connection configuration that is shown in the tree.
No
Server Address List
Mongo DB Servers
Yes
MongoDB Source
The name of the variable the connection is tied to.
Each name must be different. If there are two configuration elements using
the same name, only one will be saved.
Yes
Keep Trying
If true, the driver will keep trying to connect to the same server in case that
the socket cannot be established.
There is maximum amount of time to keep retrying, which is 15s by default.
This can be useful to avoid some exceptions being thrown when a server is
down temporarily by blocking the operations.
It can also be useful to smooth the transition to a new master (so that a new
master is elected within the retry time).
Note that when using this flag
for a replica set, the driver will try to connect to the old master for
that time, instead of failing over to the new one right away
this does not prevent exception from being thrown in read/write
operations on the socket, which must be handled by application.
Even if this flag is false, the driver already has mechanisms to automatically
recreate broken connections and retry the read operations.
Default is false.
No
Maximum connections per host
No
Connection timeout
The connection timeout in milliseconds.
It is used solely when establishing a new
P a g e | 188
19.5 Assertions
Assertions are used to perform additional checks on samplers, and are
processed after every sampler in the same scope. To ensure that an
Assertion is applied only to a particular sampler, add it as a child of the
sampler.
Assertions can be applied to either the main sample, the sub-samples or both.
The default is to apply the assertion to the main sample only. If the Assertion
supports this option, then there will be an entry on the GUI which looks like
the following:
P a g e | 190
Assertion Scope
If a sub-sampler fails and the main sample is successful, then the main
sample will be set to failed status and an Assertion Result will be added. If the
JMeter variable option is used, it is assumed to relate to the main sample, and
any failure will be applied to the main sample only.
Response Assertion
The response assertion control panel lets you add pattern strings to be
compared against various fields of the response. The pattern strings are:
You can also choose whether the strings will be expected to match the entire
response, or if the response is only expected to contain the pattern. You can
attach multiple assertions to any controller for additional flexibility.
Note that the pattern string should not include the enclosing delimiters, i.e.
use Price: \d+ not /Price: \d+/.
By default, the pattern is in multi-line mode, which means that the "." meta-
character does not match newline. In multi-line mode, "^" and "$" match the
start or end of any line anywhere within the string - not just the start and end
of the entire string. Note that \s does match new-line. Case is also significant.
To override these settings, one can use the extended regular
expressionsyntax. For example:
P a g e | 191
(?i)
ignore case
(?s)
treat target as single line, i.e. "." matches new-line
(?is)
both the above
These can be used anywhere within the expression and remain in effect until
overridden. E.g.
(?i)apple(?-i) Pie
matches "ApPLe Pie", but not "ApPLe pIe"
(?s)Apple.+?Pie
matches Apple followed by Pie, which may be on a subsequent line.
Apple(?s).+?Pie
same as above, but it's probably clearer to use the (?s) at the start.
Parameters
Attribute
Description
Required
P a g e | 192
Name
Descriptive name for this element that is shown in the tree.
No
Apply to:
This is for use with samplers that can generate sub-samples, e.g. HTTP
Sampler with embedded resources, Mail Reader or samples generated by the
Transaction Controller.
Yes
Response Field to Test
Instructs JMeter which field of the Response to test.
Text Response - the response text from the server, i.e. the body,
excluding any HTTP headers.
Document (text) - the extract text from various type of
documents via Apache Tika (see View Results Tree Document view
section).
URL sampled
Response Code - e.g. 200
Response Message - e.g. OK
Response Headers, including Set-Cookie headers (if any)
Yes
Ignore status
Instructs JMeter to set the status to success initially.
HTTP Responses with statuses in the 4xx and 5xx ranges are normally
regarded as unsuccessful. The "Ignore status" checkbox can be used to
set the status successful before performing further checks. Note that this will
have the effect of clearing any previous assertion failures, so make sure that
this is only set on the first assertion.
P a g e | 193
Yes
Pattern Matching Rules
Indicates how the text being tested is checked against the pattern.
Assertion Examples
P a g e | 194
Duration Assertion
The Duration Assertion tests that each response was received within a given
amount of time. Any response that takes longer than the given number of
milliseconds (specified by the user) is marked as a failed response.
Parameters
Attribute
Description
Required
Name
Descriptive name for this element that is shown in the tree.
Duration in Milliseconds
The maximum number of milliseconds each response is allowed before being
marked as failed.
P a g e | 196
Yes
^
Size Assertion
The Size Assertion tests that each response contains the right number of
bytes in it. You can specify that the size be equal to, greater than, less than,
or not equal to a given number of bytes.
Parameters
Attribute
Description
Required
Name
Descriptive name for this element that is shown in the tree.
Apply to:
P a g e | 197
This is for use with samplers that can generate sub-samples, e.g. HTTP
Sampler with embedded resources, Mail Reader or samples generated by the
Transaction Controller.
Yes
Size in bytes
The number of bytes to use in testing the size of the response (or value of the
JMeter variable).
Yes
Type of Comparison
Whether to test that the response is equal to, greater than, less than, or not
equal to, the number of bytes specified.
Yes
^
XML Assertion
The XML Assertion tests that the response data consists of a formally correct
XML document. It does not validate the XML based on a DTD or schema or
do any further validation.
Screenshot of
Control-Panel of XML Assertion
Parameters
Attribute
Description
Required
Name
Descriptive name for this element that is shown in the tree.
P a g e | 198
BeanShell Assertion
The BeanShell Assertion allows the user to perform assertion checking using
a BeanShell script.
For full details on using BeanShell, please see the BeanShell website.
All Assertions are called from the same thread as the sampler.
Parameters
Attribute
Description
Required
Name
Descriptive name for this element that is shown in the tree. The name is
stored in the script variable Label
Reset bsh.Interpreter before each call
P a g e | 200
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 Best Practices - BeanShell scripting.
Yes
Parameters
Parameters to pass to the BeanShell script. The parameters are stored in the
following variables:
No
Script file
A file containing the BeanShell script to run. This overrides the script. The file
name is stored in the script variable FileName
No
Script
The BeanShell script to run. The return value is ignored.
Yes (unless script file is provided)
Before invoking the script, some variables are set up in the BeanShell
interpreter. These are strings unless otherwise noted:
setStopThread(boolean)
setStopTest(boolean)
String getSampleLabel()
setSampleLabel(String)
MD5Hex Assertion
The MD5Hex Assertion allows the user to check the MD5 hash of the
response data.
Screenshot of Control-
Panel of MD5Hex Assertion
Parameters
Attribute
Description
Required
Name
Descriptive name for this element that is shown in the tree.
MD5 sum
32 hex digits representing the MD5 hash (case not significant)
Yes
^
P a g e | 202
HTML Assertion
The HTML Assertion allows the user to check the HTML syntax of the
response data using JTidy.
Screenshot of
Control-Panel of HTML Assertion
Parameters
Attribute
Description
Required
Name
Descriptive name for this element that is shown in the tree.
doctype
omit, auto, strict or loose
Yes
Format
HTML, XHTML or XML
Yes
Errors only
Only take note of errors?
Yes
Error threshold
Number of errors allowed before classing the response as failed
P a g e | 203
Yes
Warning threshold
Number of warnings allowed before classing the response as failed
Yes
Filename
Name of file to which report is written
No
^
XPath Assertion
The XPath Assertion tests a document for well formedness, has the option of
validating against a DTD, or putting the document through JTidy and testing
for an XPath. If that XPath exists, the Assertion is true. Using "/" will match
any well-formed document, and is the default XPath Expression. The
assertion also supports boolean expressions, such as
"count(//*error)=2". See http://www.w3.org/TR/xpath for more
information on XPath.
Parameters
Attribute
Description
Required
Name
Descriptive name for this element that is shown in the tree.
No
Use Tidy (tolerant parser)
Use Tidy, i.e. be tolerant of XML/HTML errors
P a g e | 205
Yes
Quiet
Sets the Tidy Quiet flag
If Tidy is selected
Report Errors
If a Tidy error occurs, then set the Assertion accordingly
If Tidy is selected
Show warnings
Sets the Tidy showWarnings option
If Tidy is selected
Use Namespaces
Should namespaces be honoured? (see note below on NAMESPACES)
If Tidy is not selected
Validate XML
Check the document against its schema.
If Tidy is not selected
Ignore Whitespace
Ignore Element Whitespace.
If Tidy is not selected
Fetch External DTDs
If selected, external DTDs are fetched.
If Tidy is not selected
XPath Assertion
XPath to match in the document.
Yes
True if nothing matches
True if a XPath expression is not matched
No
The non-tolerant parser can be quite slow, as it may need to download the
DTD etc.
NAMESPACES As a work-round for namespace limitations of the Xalan
XPath parser implementation on which JMeter is based, you can provide a
Properties file which contains mappings for the namespace prefixes:
prefix1=Full Namespace 1
prefix2=Full Namespace 2
…
You reference this file in jmeter.properties file using the property:
xpath.namespace.config
^
P a g e | 206
Screenshot of
Control-Panel of XML Schema Assertion
Parameters
Attribute
Description
Required
Name
Descriptive name for this element that is shown in the tree.
File Name
Specify XML Schema File Name
Yes
^
Parameters
Attribute
Description
Required
Name
Descriptive name for this element that is shown in the tree.
No
Language
P a g e | 208
No
Script file
A file containing the script to run, if a relative file path is used, then it will be
relative to directory referenced by "user.dir" System property
No
Script
The script to run.
Yes (unless script file is provided)
The script (or file) is processed using the BSFEngine.exec() method, which
does not return a value.
For further details of all the methods available on each of the above variables,
please check the Javadoc
JSR223 Assertion
The JSR223 Assertion allows JSR223 script code to be used to check the
status of the previous sample.
Parameters
Attribute
Description
Required
Name
Descriptive name for this element that is shown in the tree.
No
Language
The JSR223 language to be used
Yes
Parameters
Parameters to pass to the script. The parameters are stored in the following
variables:
No
Script file
A file containing the script to run, if a relative file path is used, then it will be
relative to directory referenced by "user.dir" System property
No
Script compilation caching
P a g e | 210
Unique String across Test Plan that JMeter will use to cache result of Script
compilation if language used supports Compilable interface (Groovy is one
of these, java, beanshell and javascript are not)
See note in JSR223 Sampler Java System property if you're using Groovy
without checking this option
No
Script
The script to run.
Yes (unless script file is provided)
For further details of all the methods available on each of the above variables,
please check the Javadoc
^
P a g e | 211
Compare Assertion
Compare Assertion must not be used during load test as it consumes a lot of
resources (memory and CPU). Use it only for either functional testing or
during Test Plan debugging and Validation.
The Compare Assertion can be used to compare sample results within its
scope. Either the contents or the elapsed time can be compared, and the
contents can be filtered before comparison. The assertion comparisons can
be seen in the Comparison Assertion Visualizer.
Parameters
Attribute
Description
Required
Name
Descriptive name for this element that is shown in the tree.
No
Compare Content
Whether or not to compare the content (response data)
Yes
Compare Time
If the value is ≥0, then check if the response time difference is no greater than
the value. I.e. if the value is 0, then the response times must be exactly equal.
Yes
P a g e | 212
Comparison Filters
Filters can be used to remove strings from the content comparison. For
example, if the page has a time-stamp, it might be matched with: "Time:
\d\d:\d\d:\d\d" and replaced with a dummy fixed time "Time:
HH:MM:SS".
No
^
SMIME Assertion
The SMIME Assertion can be used to evaluate the sample results from the
Mail Reader Sampler. This assertion verifies if the body of a mime message is
signed or not. The signature can also be verified against a specific signer
certificate. As this is a functionality that is not necessarily needed by most
users, additional jars need to be downloaded and added
to JMETER_HOME/lib:
If using the Mail Reader Sampler, please ensure that you select "Store the
message using MIME (raw)" otherwise the Assertion won't be able to
process the message correctly.
P a g e | 213
Screenshot of
Control-Panel of SMIME Assertion
Parameters
Attribute
Description
Required
Name
Descriptive name for this element that is shown in the tree.
No
Verify Signature
If selected, the assertion will verify if it is a valid signature according to the
parameters defined in the Signer Certificate box.
Yes
Message not signed
Whether or not to expect a signature in the message
Yes
Signer Cerificate
"No Check" means that it will not perform signature verification. "Check
values" is used to verify the signature against the inputs provided. And
P a g e | 214
19.6 Timers
Since version 3.1, a new feature (in Beta mode as of JMeter 3.1 and subject
to changes) has been implemented which provides the following feature.
You can apply a multiplication factor on the sleep delays computed by
Random timer by setting property timer.factor=float number where
float number is a decimal positive number.
JMeter will multiply this factor by the computed sleep delay. This feature can
be used by:
Note that timers are processed before each sampler in the scope in which
they are found; if there are several timers in the same scope, all the timers will
be processed before each sampler.
Timers are only processed in conjunction with a sampler. A timer which is not
in the same scope as a sampler will not be processed at all.
To apply a timer to a single sampler, add the timer as a child element of the
sampler. The timer will be applied before the sampler is executed. To apply a
timer after a sampler, either add it to the next sampler, or add it as the child of
a Test ActionSampler.
Constant Timer
P a g e | 215
If you want to have each thread pause for the same amount of time between
requests, use this timer.
Screenshot of Control-Panel of
Constant Timer
Parameters
Attribute
Description
Required
Name
Descriptive name for this timer that is shown in the tree.
No
Thread Delay
Number of milliseconds to pause.
Yes
^
Screenshot of Control-Panel of
Gaussian Random Timer
P a g e | 216
Parameters
Attribute
Description
Required
Name
Descriptive name for this timer that is shown in the tree
No
Deviation
Deviation in milliseconds.
Yes
Constant Delay Offset
Number of milliseconds to pause in addition to the random delay.
Yes
^
Screenshot of Control-Panel of
Uniform Random Timer
Parameters
Attribute
Description
Required
Name
Descriptive name for this timer that is shown in the tree.
No
Random Delay Maximum
Maximum random number of milliseconds to pause.
P a g e | 217
Yes
Constant Delay Offset
Number of milliseconds to pause in addition to the random delay.
Yes
^
N.B. although the Timer is called the Constant Throughput timer, the
throughput value does not need to be constant. It can be defined in terms of a
variable or function call, and the value can be changed during a test. The
value can be changed in various ways:
Note that the throughput value should not be changed too often during a test -
it will take a while for the new value to take effect.
Parameters
Attribute
Description
Required
Name
P a g e | 218
Yes
The shared and non-shared algorithms both aim to generate the desired
throughput, and will produce similar results.
The shared algorithm should generate a more accurate overall transaction
rate.
The non-shared algorithm should generate a more even spread of
transactions across threads.
Synchronizing Timer
The purpose of the SyncTimer is to block threads until X number of threads
have been blocked, and then they are all released at once. A SyncTimer can
thus create large instant loads at various points of the test plan.
P a g e | 219
Screenshot of Control-
Panel of Synchronizing Timer
Parameters
Attribute
Description
Required
Name
Descriptive name for this timer that is shown in the tree.
No
Number of Simultaneous Users to Group by
Number of threads to release at once. Setting it to 0 is equivalent to setting it
to Number of threads in Thread Group.
Yes
Timeout in milliseconds
If set to 0, Timer will wait for the number of threads to reach the value in
"Number of Simultaneous Users to Group". If superior to 0, then
timer will wait at max "Timeout in milliseconds" for the number of
Threads. If after the timeout interval the number of users waiting is not
reached, timer will stop waiting. Defaults to 0
No
If timeout in milliseconds is set to 0 and number of threads never reaches
"Number of Simultaneous Users to Group by" then Test will pause
infinitely. Only a forced stop will stop it. Setting Timeout in milliseconds is an
option to consider in this case.
Synchronizing timer blocks only within one JVM, so if using Distributed testing
ensure you never set "Number of Simultaneous Users to Group by"
to a value superior to the number of users of its containing Thread group
considering 1 injector only.
^
BeanShell Timer
P a g e | 220
For full details on using BeanShell, please see the BeanShell website.
Parameters
Attribute
Description
Required
Name
Descriptive name for this element that is shown in the tree. The name is
stored in the script variable Label
No
Reset bsh.Interpreter before each call
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 Best Practices - BeanShell scripting.
Yes
Parameters
Parameters to pass to the BeanShell script. The parameters are stored in the
following variables:
No
Script file
A file containing the BeanShell script to run. The file name is stored in the
script variable FileName The return value is used as the number of
milliseconds to wait.
No
Script
The BeanShell script. The return value is used as the number of milliseconds
to wait.
Yes (unless script file is provided)
Before invoking the script, some variables are set up in the BeanShell
interpreter:
For details of all the methods available on each of the above variables, please
check the Javadoc
Parameters
Attribute
Description
Required
Name
Descriptive name for this element that is shown in the tree.
No
ScriptLanguage
P a g e | 224
No
Script file
A file containing the script to run, if a relative file path is used, then it will be
relative to directory referenced by "user.dir" System property The return
value is converted to a long integer and used as the number of milliseconds to
wait.
No
Script
The script. The return value is used as the number of milliseconds to wait.
Yes (unless script file is provided)
Before invoking the script, some variables are set up in the script interpreter:
For details of all the methods available on each of the above variables, please
check the Javadoc
^
P a g e | 225
JSR223 Timer
The JSR223 Timer can be used to generate a delay using a JSR223 scripting
language,
Parameters
Attribute
Description
Required
Name
Descriptive name for this element that is shown in the tree.
No
ScriptLanguage
The scripting language to be used.
Yes
Parameters
Parameters to pass to the script. The parameters are stored in the following
variables:
No
Script file
A file containing the script to run, if a relative file path is used, then it will be
relative to directory referenced by "user.dir" System property The return
value is converted to a long integer and used as the number of milliseconds to
wait.
No
Script compilation caching
Unique String across Test Plan that JMeter will use to cache result of Script
compilation if language used supports Compilable interface (Groovy is one
of these, java, beanshell and javascript are not)
See note in JSR223 Sampler Java System property if you're using Groovy
without checking this option
No
Script
The script. The return value is used as the number of milliseconds to wait.
Yes (unless script file is provided)
P a g e | 226
Before invoking the script, some variables are set up in the script interpreter:
For details of all the methods available on each of the above variables, please
check the Javadoc
Screenshot of Control-Panel of
Poisson Random Timer
Parameters
Attribute
P a g e | 227
Description
Required
Name
Descriptive name for this timer that is shown in the tree
No
Lambda
Lambda value in milliseconds.
Yes
Constant Delay Offset
Number of milliseconds to pause in addition to the random delay.
Yes
^
^
Screenshot of Control-Panel of
HTML Link Parser
Matches are performed using protocol, host, path and parameter
names. The target sampler cannot contain parameters that are not in the
response links.
If using distributed testing, ensure you switch mode
(see jmeter.properties) so that it's not a stripping one, see Bug 56376
P a g e | 228
Spidering Example
Consider a simple example: let's say you wanted JMeter to "spider" through
your site, hitting link after link parsed from the HTML returned from your
server (this is not actually the most useful thing to do, but it serves as a good
example). You would create a Simple Controller, and add the "HTML Link
Parser" to it. Then, create an HTTP Request, and set the domain to ".*", and
the path likewise. This will cause your test sample to match with any link
found on the returned pages. If you wanted to restrict the spidering to a
particular domain, then change the domain value to the one you want. Then,
only links to that domain will be followed.
Poll Example
A more useful example: given a web polling application, you might have a
page with several poll options as radio buttons for the user to select. Let's say
the values of the poll options are very dynamic - maybe user generated. If you
wanted JMeter to test the poll, you could either create test samples with
hardcoded values chosen, or you could let the HTML Link Parser parse the
form, and insert a random poll option into your URL test sample. To do this,
follow the above example, except, when configuring your Web Test
controller's URL options, be sure to choose "POST" as the method. Put in
hard-coded values for the domain, path, and any additional form
parameters. Then, for the actual radio button parameter, put in the name (let's
say it's called "poll_choice"), and then ".*" for the value of that parameter.
When the modifier examines this URL test sample, it will find that it "matches"
the poll form (and it shouldn't match any other form, given that you've
specified all the other aspects of the URL test sample), and it will replace your
form parameters with the matching parameters from the form. Since the
regular expression ".*" will match with anything, the modifier will probably
have a list of radio buttons to choose from. It will choose at random, and
replace the value in your URL test sample. Each time through the test, a new
random value will be chosen.
P a g e | 229
Alternatively, this modifier can be attached to select requests and it will modify
only them. Clever users will even determine that this modifier can be used to
grab values that elude the HTML Link Parser.
Parameters
Attribute
Description
Required
Name
Descriptive name given to this element in the test tree.
No
Session Argument Name
The name of the parameter to grab from previous response. This modifier will
find the parameter anywhere it exists on the page, and grab the value
assigned to it, whether it's in an HREF or a form.
Yes
Path Extension
Some web apps rewrite URLs by appending a semi-colon plus the session id
parameter. Check this box if that is so.
No
Do not use equals in path extension
Some web apps rewrite URLs without using an "=" sign between the
parameter name and value (such as Intershop Enfinity).
No
Do not use questionmark in path extension
Prevents the query string to end up in the path extension (such as Intershop
Enfinity).
P a g e | 231
No
Cache Session Id?
Should the value of the session Id be saved for later use when the session Id
is not present?
Yes
URL Encode
URL Encode value when writing parameter
No
If using distributed testing, ensure you switch mode
(see jmeter.properties) so that it's not a stripping one, see Bug 56376.
^
User Parameters
Allows the user to specify values for User Variables specific to individual
threads.
User Variables can also be specified in the Test Plan but not specific to
individual threads. This panel allows you to specify a series of values for any
User Variable. For each thread, the variable will be assigned one of the values
from the series in sequence. If there are more threads than values, the values
get re-used. For example, this can be used to assign a distinct user id to be
used by each thread. User variables can be referenced in any field of any
jMeter Component.
The variable is specified by clicking the Add Variable button in the bottom
of the panel and filling in the Variable name in the 'Name:' column. To add a
new value to the series, click the 'Add User' button and fill in the desired
value in the newly added column.
Values can be accessed in any test component in the same thread group,
using the function syntax: ${variable}.
See also the CSV Data Set Config element, which is more suitable for large
numbers of parameters
P a g e | 232
Parameters
Attribute
Description
Required
Name
Descriptive name for this element that is shown in the tree.
Update Once Per Iteration
A flag to indicate whether the User Parameters element should update its
variables only once per iteration. if you embed functions into the UP, then you
may need greater control over how often the values of the variables are
updated. Keep this box checked to ensure the values are updated each time
through the UP's parent controller. Uncheck the box, and the UP will update
the parameters for every sample request made within its scope.
Yes
^
BeanShell PreProcessor
The BeanShell PreProcessor allows arbitrary code to be applied before taking
a sample.
For full details on using BeanShell, please see the BeanShell website.
P a g e | 233
Parameters
Attribute
Description
P a g e | 234
Required
Name
Descriptive name for this element that is shown in the tree. The name is
stored in the script variable Label
No
Reset bsh.Interpreter before each call
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 Best Practices - BeanShell scripting.
Yes
Parameters
Parameters to pass to the BeanShell script. The parameters are stored in the
following variables:
No
Script file
A file containing the BeanShell script to run. The file name is stored in the
script variable FileName
No
Script
The BeanShell script. The return value is ignored.
Yes (unless script file is provided)
Before invoking the script, some variables are set up in the BeanShell
interpreter:
For details of all the methods available on each of the above variables, please
check the Javadoc
Parameters
Attribute
Description
Required
Name
Descriptive name for this element that is shown in the tree.
No
Language
P a g e | 237
No
Script file
A file containing the script to run, if a relative file path is used, then it will be
relative to directory referenced by "user.dir" System property
No
Script
The script to run.
Yes (unless script file is provided)
The script (or file) is processed using the BSFEngine.exec() method, which
does not return a value.
The following BSF variables are set up for use by the script:
For details of all the methods available on each of the above variables, please
check the Javadoc
JSR223 PreProcessor
The JSR223 PreProcessor allows JSR223 script code to be applied before
taking a sample.
Parameters
Attribute
Description
Required
Name
Descriptive name for this element that is shown in the tree.
No
Language
The JSR223 language to be used
Yes
Parameters
Parameters to pass to the script. The parameters are stored in the following
variables:
No
Script file
A file containing the script to run, if a relative file path is used, then it will be
relative to directory referenced by "user.dir" System property
No
Script compilation caching
Unique String across Test Plan that JMeter will use to cache result of Script
compilation if language used supports Compilable interface (Groovy is one
of these, java, beanshell and javascript are not)
See note in JSR223 Sampler Java System property if you're using Groovy
without checking this option
No
Script
P a g e | 239
The following JSR223 variables are set up for use by the script:
For details of all the methods available on each of the above variables, please
check the Javadoc
JDBC PreProcessor
The JDBC PreProcessor enables you to run some SQL statement just before
a sample runs. This can be useful if your JDBC Sample requires some data to
be in DataBase and you cannot compute this in a setup Thread group. For
details, see JDBC Request.
See also:
In the linked test plan, "Create Price Cut-Off" JDBC PreProcessor calls
a stored procedure to create a Price Cut-Off in Database, this one will be used
by "Calculate Price cut off".
Parameters
Attribute
Description
Required
Name
Descriptive name for this element that is shown in the tree.
Regular Expression Reference Name
Name of a reference to a regular expression
Yes
Parameter names regexp group number
Group number of regular expression used to extract parameter names
Yes
Parameter values regex group number
Group number of regular expression used to extract parameter values
Yes
Regexp Example
Suppose we have a request which returns a form with 3 input parameters and
we want to extract the value of 2 of them to inject them in next request
See also the Regular Expression Extractor element, which is used to extract
parametes names and values
^
See also:
Sample Timeout
BETA CODE - the test element may be moved or replaced in a future release
The test element is intended for use where individual timeouts such as
Connection Timeout or Response Timeout are insufficient, or where the
Sampler does not support timeouts. The timeout should be set sufficiently
long so that it is not triggered in normal tests, but short enough that it
interrupts samples that are stuck.
[By default, JMeter uses a Callable to interrupt the sampler. This executes in
the same thread as the timer, so if the interrupt takes a long while, it may
delay the processing of subsequent timeouts. This is not expected to be a
problem, but if necessary the property InterruptTimer.useRunnable can
be set to true to use a separate Runnable thread instead of the Callable.]
P a g e | 243
Screenshot of Control-Panel of
Sample Timeout
Parameters
Attribute
Description
Required
Name
Descriptive name for this timer that is shown in the tree.
No
Sample Timeout
If the sample takes longer to complete, it will be interrupted.
Yes
^
^
19.8 Post-Processors
As the name suggests, Post-Processors are applied after samplers. Note that
they are applied to all the samplers in the same scope, so to ensure that a
post-processor is applied only to a particular sampler, add it as a child of the
sampler.
Post-Processors are run before Assertions, so they do not have access to any
Assertion Results, nor will the sample status reflect the results of any
Assertions. If you require access to Assertion Results, try using a Listener
P a g e | 244
Parameters
Attribute
Description
Required
Name
Descriptive name for this element that is shown in the tree.
Apply to:
This is for use with samplers that can generate sub-samples, e.g. HTTP
Sampler with embedded resources, Mail Reader or samples generated by the
Transaction Controller.
Headers can be useful for HTTP samples; it may not be present for other
sample types.
Yes
Reference Name
P a g e | 246
The name of the JMeter variable in which to store the result. Also note that
each group is stored as [refname]_g#, where [refname] is the string you
entered as the reference name, and # is the group number, where group 0 is
the entire match, group 1 is the match from the first set of parentheses, etc.
Yes
Regular Expression
The regular expression used to parse the response data. This must contain at
least one set of parentheses "()" to capture a portion of the string, unless
using the group $0$. Do not enclose the expression in / / - unless of course
you want to match these characters as well.
Yes
Template
The template used to create a string from the matches found. This is an
arbitrary string with special elements to refer to groups within the regular
expression. The syntax to refer to a group is: '$1$' to refer to group 1, '$2$' to
refer to group 2, etc. $0$refers to whatever the entire expression matches.
Yes
Match No.
Indicates which match to use. The regular expression may match multiple
times.
Yes
Default Value
If the regular expression does not match, then the reference variable will be
set to the default value. This is particularly useful for debugging tests. If no
default is provided, then it is difficult to tell whether the regular expression did
not match, or the RE element was not processed or maybe the wrong variable
is being used.
However, if you have several test elements that set the same variable, you
may wish to leave the variable unchanged if the expression does not match.
In this case, remove the default value once debugging is complete.
If the checkbox is checked and Default Value is empty, then JMeter will
set the variable to empty string instead of not setting it. Thus when you will for
example use ${var} (if Reference Name is var) in your Test Plan, if the
extracted value is not found then ${var} will be equal to empty string instead
of containing ${var} which may be useful if extracted value is optional.
No
If the match number is set to a non-negative number, and a match occurs, the
variables are set as follows:
If no match occurs, then the refName variable is set to the default (unless this
is absent). Also, the following variables are removed:
refName_g0
refName_g1
refName_g
If the match number is set to a negative number, then all the possible matches
in the sampler data are processed. The variables are set as follows:
Note that the refName variable is always set to the default value in this case,
and the associated group variables are not set.
See also Response Assertion for some examples of how to specify modifiers,
and for further information on JMeter regular expressions.
CSS/JQuery Extractor
P a g e | 248
Allows the user to extract values from a server response using a CSS/JQuery
selector like syntax. As a post-processor, this element will execute after each
Sample request in its scope, applying the CSS/JQuery expression, extracting
the requested nodes, extracting the node as text or attribute value and store
the result into the given variable name.
Parameters
Attribute
Description
Required
Name
Descriptive name for this element that is shown in the tree.
Apply to:
This is for use with samplers that can generate sub-samples, e.g. HTTP
Sampler with embedded resources, Mail Reader or samples generated by the
Transaction Controller.
the extractor will match the 3rd sub-sample. For match number = 3, Main
sample and sub-samples, the extractor will match the 2nd sub-sample
(1st match is main sample). For match number = 0 or negative, all qualifying
samples will be processed. For match number > 0, matching will stop as soon
as enough matches have been found.
Yes
CSS/JQuery extractor Implementation
2 Implementations for CSS/JQuery based syntax are supported:
JSoup
Jodd-Lagarto (CSSelly)
JSoup
Jodd-Lagarto (CSSelly)
Yes
Attribute
Name of attribute (as per HTML syntax) to extract from nodes that matched
the selector. If empty, then the combined text of this element and all its
children will be returned.
P a g e | 250
Yes
Default Value
If the expression does not match, then the reference variable will be set to the
default value. This is particularly useful for debugging tests. If no default is
provided, then it is difficult to tell whether the expression did not match, or the
CSS/JQuery element was not processed or maybe the wrong variable is being
used.
However, if you have several test elements that set the same variable, you
may wish to leave the variable unchanged if the expression does not match.
In this case, remove the default value once debugging is complete.
If the match number is set to a non-negative number, and a match occurs, the
variables are set as follows:
If no match occurs, then the refName variable is set to the default (unless this
is absent).
If the match number is set to a negative number, then all the possible matches
in the sampler data are processed. The variables are set as follows:
Note that the refName variable is always set to the default value in this case.
P a g e | 252
XPath Extractor
This test element allows the user to extract value(s) from structured response
- XML or (X)HTML - using XPath query language.
Parameters
Attribute
Description
Required
Name
Descriptive name for this element that is shown in the tree.
No
Apply to:
This is for use with samplers that can generate sub-samples, e.g. HTTP
Sampler with embedded resources, Mail Reader or samples generated by the
Transaction Controller.
XPath matching is applied to all qualifying samples in turn, and all the
matching results will be returned.
Yes
Use Tidy (tolerant parser)
If checked use Tidy to parse HTML response into XHTML.
Yes
Quiet
Sets the Tidy Quiet flag
If Tidy is selected
Report Errors
If a Tidy error occurs, then set the Assertion accordingly
If Tidy is selected
Show warnings
Sets the Tidy showWarnings option
If Tidy is selected
Use Namespaces
If checked, then the XML parser will use namespace resolution.(see note
below on NAMESPACES) Note that currently only namespaces declared on
the root element will be recognised. A later version of JMeter may support
user-definition of additional workspace names. Meanwhile, a work-round is to
replace:
//mynamespace:tagname
by
//*[local-name()='tagname' and namespace-uri()='uri-for-namespace']
where "uri-for-namespace" is the uri for the "mynamespace" namespace.
(not applicable if Tidy is selected)
If Tidy is not selected
Validate XML
Check the document against its schema.
If Tidy is not selected
Ignore Whitespace
Ignore Element Whitespace.
If Tidy is not selected
Fetch External DTDs
If selected, external DTDs are fetched.
P a g e | 254
To allow for use in a ForEach Controller, the following variables are set on
return:
refName- set to first (or only) match; if no match, then set to default
refName_matchNr - set to number of matches (may be 0)
refName_n - n=1, 2, 3, etc. Set to the 1st, 2nd 3rd match etc.
Note: The next refName_n variable is set to null - e.g. if there are 2
matches, then refName_3 is set to null, and if there are no matches,
then refName_1 is set to null.
/html/head/title
extracts title element from HTML response
/book/page[2]
extracts 2nd page from a book
/book/page
extracts all pages from a book
//form[@name='countryForm']//select[@name='country']/opti
on[text()='Czech Republic'])/@value
P a g e | 255
Parameters
Attribute
Description
Required
Name
Descriptive name for this element that is shown in the tree.
Action to be taken after a Sampler error
P a g e | 256
No
^
BeanShell PostProcessor
The BeanShell PreProcessor allows arbitrary code to be applied after taking a
sample.
For full details on using BeanShell, please see the BeanShell website.
Parameters
Attribute
Description
Required
Name
Descriptive name for this element that is shown in the tree. The name is
stored in the script variable Label
No
P a g e | 258
No
Script file
A file containing the BeanShell script to run. The file name is stored in the
script variable FileName
No
Script
The BeanShell script. The return value is ignored.
Yes (unless script file is provided)
The following BeanShell variables are set up for use by the script:
For details of all the methods available on each of the above variables, please
check the Javadoc
P a g e | 259
Parameters
Attribute
Description
Required
Name
Descriptive name for this element that is shown in the tree.
No
Language
P a g e | 261
No
Script file
A file containing the script to run, if a relative file path is used, then it will be
relative to directory referenced by "user.dir" System property
No
Script
The script to run.
Yes (unless script file is provided)
The script (or file) is processed using the BSFEngine.exec() method, which
does not return a value.
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.
For details of all the methods available on each of the above variables, please
check the Javadoc
JSR223 PostProcessor
The JSR223 PostProcessor allows JSR223 script code to be applied after
taking a sample.
Parameters
Attribute
Description
Required
Name
Descriptive name for this element that is shown in the tree.
No
Language
The JSR223 language to be used
Yes
Parameters
Parameters to pass to the script. The parameters are stored in the following
variables:
No
Script file
A file containing the script to run, if a relative file path is used, then it will be
relative to directory referenced by "user.dir" System property
No
Script compilation caching
Unique String across Test Plan that JMeter will use to cache result of Script
compilation if language used supports Compilable interface (Groovy is one
of these, java, beanshell and javascript are not)
See note in JSR223 Sampler Java System property if you're using Groovy
without checking this option
P a g e | 263
No
Script
The script to run.
Yes (unless script file is provided)
Before invoking the script, some variables are set up. Note that these are
JSR223 variables - i.e. they can be used directly in the script.
For details of all the methods available on each of the above variables, please
check the Javadoc
JDBC PostProcessor
The JDBC PostProcessor enables you to run some SQL statement just after a
sample has run. This can be useful if your JDBC Sample changes some data
and you want to reset state to what it was before the JDBC sample run.
See also:
P a g e | 264
JDBC PostProcessor
^
JSON Extractor
The JSON PostProcessor enables you extract data from JSON responses
using JSON-PATH syntax. This post processor is very similar to Regular
expression extractor. It must be placed as a child of HTTP Sampler or any
other sampler that has responses. It will allow you to extract in a very easy
way text content, see JSON Path syntax.
Parameters
Attribute
Description
Required
P a g e | 265
Name
Descriptive name for this element that is shown in the tree.
No
Variable Names
Semi-colon separated names of variables that will contain the results of
JSON-PATH expressions (must match number of JSON-PATH expressions)
Yes
JSON Path Expressions
Semi-colon separated JSON-PATH expressions (must match number of
variables)
Yes
Default Values
Semi-colon separated default values if JSON-PATH expressions do not return
any result(must match number of variables)
No
Match Numbers
If the JSON Path query leads to many results, you can choose which one(s) to
extract as Variables:
No
Compute concatenation var
If many results are found, plugin will concatenate them using ‘,’ separator and
store it in a var named <variable name>_ALL
No
P a g e | 266
JSON PostProcessor
^
Test Plan
The Test Plan is where the overall settings for a test are specified.
Static variables can be defined for values that are repeated throughout a test,
such as server names. For example the variable SERVER could be defined
as www.example.com, and the rest of the test plan could refer to it
as ${SERVER}. This simplifies changing the name later.
The option does not affect CSV result files, which cannot currently store such
information.
Also, an option exists here to instruct JMeter to run the Thread Group serially
rather than in parallel.
Run tearDown Thread Groups after shutdown of main threads: if selected, the
tearDown groups (if any) will be run after graceful shutdown of the main
threads. The tearDown threads won't be run if the test is forcibly stopped.
Test plan now provides an easy way to add classpath setting to a specific test
plan. The feature is additive, meaning that you can add jar files or directories,
but removing an entry requires restarting JMeter.
Note that this cannot be used to add JMeter GUI plugins, because they are
processed earlier.
However it can be useful for utility jars such as JDBC drivers. The jars are
only added to the search path for the JMeter loader, not for the system class
loader.
Thread Group
A Thread Group defines a pool of users that will execute a particular test case
against your server. In the Thread Group GUI, you can control the number of
users simulated (num of threads), the ramp up time (how long it takes to start
all the threads), the number of times to perform the test, and optionally, a start
and stop time for the test.
When using the scheduler, JMeter runs the thread group until either the
number of loops is reached or the duration/end-time is reached - whichever
occurs first. Note that the condition is only checked between samples; when
the end condition is reached, that thread will stop. JMeter does not interrupt
samplers which are waiting for a response, so the end time may be delayed
arbitrarily.
P a g e | 269
Since JMeter 3.0, you can run a selection of Thread Group by selecting them
and right clicking. A popup menu will appear:
P a g e | 270
Popup menu to
start a selection of Thread Groups
Notice you have 3 options to run the selection of Thread Groups:
P a g e | 271
Validation Mode:
This mode enables rapid validation of a Thread Group by running it with 1
thread, 1 iteration, no timers and no Startup delayset to 0. Behaviour can
be modified with some properties by setting in user.properties:
testplan_validation.nb_threads_per_thread_group :
Number of threads to use to validate a Thread Group, by default 1
testplan_validation.ignore_timers : Ignore timers when
validating the thread group of plan, by default 1
testplan_validation.number_iterations : Number of
iterations to use to validate a Thread Group
testplan_validation.tpc_force_100_pct : Wether to force
Throughput Controller in percentage mode to run as if percentage
was 100%. Defaults to false
Parameters
Attribute
Description
Required
Name
Descriptive name for this element that is shown in the tree.
Action to be taken after a Sampler error
Determines what happens if a sampler error occurs, either because the
sample itself failed or an assertion failed. The possible choices are:
No
P a g e | 272
Number of Threads
Number of users to simulate.
Yes
Ramp-up Period
How long JMeter should take to get all the threads started. If there are 10
threads and a ramp-up time of 100 seconds, then each thread will begin 10
seconds after the previous thread started, for a total time of 100 seconds to
get the test fully up to speed.
Yes
Loop Count
Number of times to perform the test case. Alternatively, "forever" can be
selected causing the test to run until manually stopped.
Yes, unless forever is selected
Delay Thread creation until needed
If selected, threads are created only when the appropriate proportion of the
ramp-up time has elapsed. This is most appropriate for tests with a ramp-up
time that is significantly longer than the time to execute a single thread. I.e.
where earlier threads finish before later ones start.
If not selected, all threads are created when the test starts (they then pause
for the appropriate proportion of the ramp-up time). This is the original default,
and is appropriate for tests where threads are active throughout most of the
test.
Yes
Scheduler
If selected, enables the scheduler
Yes
Start Time
If the scheduler checkbox is selected, one can choose an absolute start time.
When you start your test, JMeter will wait until the specified start time to begin
testing. Note: the Startup Delay field over-rides this - see below.
No
End Time
If the scheduler checkbox is selected, one can choose an absolute end time.
When you start your test, JMeter will wait until the specified start time to begin
testing, and it will stop at the specified end time. Note: the Duration field
over-rides this - see below.
No
Duration (seconds)
If the scheduler checkbox is selected, one can choose a relative end time.
JMeter will use this to calculate the End Time, and ignore the End
Time value.
P a g e | 273
No
Startup delay (seconds)
If the scheduler checkbox is selected, one can choose a relative startup delay.
JMeter will use this to calculate the Start Time, and ignore the Start
Time value.
No
^
WorkBench
The WorkBench simply provides a place to temporarily store test elements
while not in use, for copy/paste purposes, or any other purpose you desire.
When you save your test plan, WorkBench items are not saved with it by
default unless you check "Save Workbench" option. Your WorkBench can
be saved independently, if you like (right-click on WorkBench and
choose Save).
Parameters
Attribute
Description
Required
Save WorkBench
Allow to save the WorkBench's elements into the JMX file.
No
Screenshot of Control-Panel
of WorkBench
^
P a g e | 274
SSL Manager
The SSL Manager is a way to select a client certificate so that you can test
applications that use Public Key Infrastructure (PKI). It is only needed if you
have not set up the appropriate System properties.
You may either use a Java Key Store (JKS) format key store, or a Public Key
Certificate Standard #12 (PKCS12) file for your client certificates. There is a
feature of the JSSE libraries that require you to have at least a six character
password on your key (at least for the keytool utility that comes with your
JDK).
To select the client certificate, choose Options → SSL Manager from the
menu bar. You will be presented with a file finder that looks for PKCS12 files
by default. Your PKCS12 file must have the extension '.p12' for SSL
Manager to recognize it as a PKCS12 file. Any other file will be treated like an
average JKS key store. If JSSE is correctly installed, you will be prompted for
the password. The text box does not hide the characters you type at this point
-- so make sure no one is looking over your shoulder. The current
implementation assumes that the password for the keystore is also the
password for the private key of the client you want to authenticate as.
The next time you run your test, the SSL Manager will examine your key store
to see if it has at least one key available to it. If there is only one key, SSL
Manager will select it for you. If there is more than one key, it currently selects
the first key. There is currently no way to select other entries in the keystore,
so the desired key must be the first.
You must have your Certificate Authority (CA) certificate installed properly if it
is not signed by one of the five CA certificates that ships with your JDK. One
method to install it is to import your CA certificate into a JKS file, and name
the JKS file "jssecacerts". Place the file in your
JRE's lib/security folder. This file will be read before the "cacerts" file
in the same directory. Keep in mind that as long as the "jssecacerts" file
P a g e | 275
exists, the certificates installed in "cacerts" will not be used. This may cause
problems for you. If you don't mind importing your CA certificate into the
"cacerts" file, then you can authenticate against all of the CA certificates
installed.
To use the recorder, add the HTTP(S) Test Script Recorder element to the
workbench. Select the WorkBench element in the tree, and right-click on this
element to get the Add menu (Add → Non-Test Elements → HTTP(S) Test
Script Recorder ).
Do not use JMeter as the proxy for any other request types - FTP, etc. - as
JMeter cannot handle them.
Ideally use private browsing mode when recording the session. This should
ensure that the browser starts with no stored cookies, and prevents certain
changes from being saved. For example, Firefox does not allow certificate
overrides to be saved permanently.
Browsers also check that the certificate is for the correct host or domain, and
that it is valid and not expired.
P a g e | 276
If any of the browser checks fail, it will prompt the user who can then decide
whether to allow the connection to proceed.
JMeter needs to use its own certificate to enable it to intercept the HTTPS
connection from the browser. Effectively JMeter has to pretend to be the
target server.
JMeter will generate its own certificate(s). These are generated with a validity
period defined by the property proxy.cert.validity, default 7 days, and
random passwords. If JMeter detects that it is running under Java 7 or later, it
will generate certificates for each target server as necessary (dynamic mode)
unless the following property is
defined: proxy.cert.dynamic_keys=false. When using dynamic mode,
the certificate will be for the correct host name, and will be signed by a
JMeter-generated CA certificate. By default, this CA certificate won't be
trusted by the browser, however it can be installed as a trusted certificate.
Once this is done, the generated server certificates will be accepted by the
browser. This has the advantage that even embedded HTTPS resources can
be intercepted, and there is no need to override the browser checks for each
new server.
The JMeter certificates are generated (if necessary) when the Start button is
pressed.
Certificate generation can take some while, during which time the GUI will be
unresponsive.
The cursor is changed to an hour-glass whilst this is happening. When
certificate generation is complete, the GUI will display a pop-up dialogue
containing the details of the certificate for the root CA. This certificate needs to
P a g e | 277
If necessary, you can force JMeter to regenerate the keystore (and the
exported certificates - ApacheJMeterTemporaryRootCA[.usr|.crt]) by
deleting the keystore file proxyserver.jks from the JMeter directory.
This certificate is not one of the certificates that browsers normally trust, and
will not be for the correct host.
As a consequence:
The browser should display a dialogue asking if you want to accept the
certificate or not. For example:
1) The server's name "www.example.com" does not match the
certificate's name
"JMeter Proxy (DO NOT TRUST)". Somebody may be trying to eavesdrop
on you.
2) The certificate for "JMeter Proxy (DO NOT TRUST)" is signed by the
unknown Certificate Authority
"JMeter Proxy (DO NOT TRUST)". It is not possible to verify that
this is a valid certificate.
You will need to accept the certificate in order to allow the JMeter
Proxy to intercept the SSL traffic in order to record it. However, do not
accept this certificate permanently; it should only be accepted
temporarily. Browsers only prompt this dialogue for the certificate of
the main url, not for the resources loaded in the page, such as
images, css or javascript files hosted on a secured external CDN. If
you have such resources (gmail has for example), you'll have to first
browse manually to these other domains in order to accept JMeter's
certificate for them. Check in jmeter.log for secure domains that
you need to register certificate for.
Versions of JMeter from 2.10 onwards still support this method, and will
continue to do so if you define the following
property:proxy.cert.alias The following properties can be used to
change the certificate that is used:
P a g e | 278
If your browser currently uses a proxy (e.g. a company intranet may route all
external requests via a proxy), then you need to tell JMeter to use that
proxy before starting JMeter, using the command-line options -H and -P. This
setting will also be needed when running the generated test plan.
As mentioned above, when run under Java 7, JMeter can generate certificates
for each server. For this to work smoothly, the root CA signing certificate used
by JMeter needs to be trusted by the browser. The first time that the recorder
is started, it will generate the certificates if necessary. The root CA certificate
is exported into a file with the name ApacheJMeterTemporaryRootCA in
the current launch directory. When the certificates have been set up, JMeter
will show a dialog with the current certificate details. At this point, the
certificate can be imported into the browser, as per the instructions below.
Note that once the root CA certificate has been installed as a trusted CA, the
browser will trust any certificates signed by it. Until such time as the certificate
expires or the certificate is removed from the browser, it will not warn the user
that the certificate is being relied upon. So anyone that can get hold of the
keystore and password can use the certificate to generate certificates which
will be accepted by any browsers that trust the JMeter root CA certificate. For
this reason, the password for the keystore and private keys are randomly
generated and a short validity period used. The passwords are stored in the
P a g e | 279
local preferences area. Please ensure that only trusted users have access to
the host with the keystore.
The popup that displays once you start the Recorder is an informational
popup:
P a g e | 280
Tools / Options
Advanced / Certificates
View Certificates
Authorities
Import …
Browse to the JMeter launch directory, and click on the
file ApacheJMeterTemporaryRootCA.crt, press Open
Click View and check that the certificate details agree with the ones
displayed by the JMeter Test Script Recorder
If OK, select "Trust this CA to identify web sites", and
press OK
Close dialogs by pressing OK as necessary
Both Chrome and Internet Explorer use the same trust store for certificates.
Parameters
Attribute
Description
Required
Name
P a g e | 283
The property proxy.pause determines the minimum gap that JMeter needs
between requests to treat them as separate "clicks". The default
P a g e | 284
is 5000 (milliseconds) i.e. 5 seconds. If you are using grouping, please ensure
that you leave the required gap between clicks.
Yes
Capture HTTP Headers
Should headers be added to the plan? If specified, a Header Manager will be
added to each HTTP Sampler. The Proxy server always removes Cookie and
Authorization headers from the generated Header Managers. By default it also
removes If-Modified-Since and If-None-Match headers. These are
used to determine if the browser cache items are up to date; when recording
one normally wants to download all the content. To change which additional
headers are removed, define the JMeter
property proxy.headers.remove as a comma-separated list of headers.
Yes
Add Assertions
Add a blank assertion to each sampler?
Yes
Regex Matching
Use Regex Matching when replacing variables? If checked replacement will
use word boundaries, i.e. it will only replace word matching values of variable,
not part of a word. A word boundary follows Perl5 definition and is equivalent
to \b. More information below in the paragraph about "User Defined
Variable replacement".
Yes
Type
Which type of sampler to generate (the HTTPClient default or Java)
Yes
Redirect Automatically
Set Redirect Automatically in the generated samplers?
Yes
Follow Redirects
Set Follow Redirects in the generated samplers?
Note: see "Recording and redirects" section below for important information.
Yes
Use Keep-Alive
Set Use Keep-Alive in the generated samplers?
Yes
Retrieve all Embedded Resources
Set Retrieve all Embedded Resources in the generated samplers?
Yes
Content Type filter
P a g e | 285
Stops and restarts the proxy server. This is useful when you
change/add/delete an include/exclude filter expression.
N/A
During recording, the browser will follow a redirect response and generate an
additional request. The Proxy will record both the original request and the
redirected request (subject to whatever exclusions are configured). The
generated samples have "Follow Redirects" selected by default, because
that is generally better.
Now if JMeter is set to follow the redirect during replay, it will issue the original
request, and then replay the redirect request that was recorded. To avoid this
duplicate replay, JMeter tries to detect when a sample is the result of a
previous redirect. If the current response is a redirect, JMeter will save the
redirect URL. When the next request is received, it is compared with the
saved redirect URL and if there is a match, JMeter will disable the generated
sample. It also adds comments to the redirect chain. This assumes that all the
requests in a redirect chain will follow each other without any intervening
requests. To disable the redirect detection, set the
property proxy.redirect.disabling=false
The include and exclude patterns are treated as regular expressions (using
Jakarta ORO). They will be matched against the host name, port (actual or
implied), path and query (if any) of each browser request. If the URL you are
browsing is
"http://localhost/jmeter/index.html?username=xxxx",
then the regular expression will be tested against the string:
"localhost:80/jmeter/index.html?username=xxxx".
Thus, if you want to include all .html files, your regular expression might look
like:
".*\.html(\?.*)?" - or ".*\.html if you know that there is no query string
or you only want html pages without query strings.
If there are any include patterns, then the URL must match at least one of
the patterns , otherwise it will not be recorded. If there are any exclude
P a g e | 287
patterns, then the URL must not match any of the patterns , otherwise it will
not be recorded. Using a combination of includes and excludes, you should be
able to record what you are interested in and skip what you are not.
N.B. the string that is matched by the regular expression must be the same as
the whole host+path string.
Thus "\.html" will not match localhost:80/index.html
Adding timers
It is also possible to have the proxy add timers to the recorded script. To do
this, create a timer directly within the HTTP(S) Test Script Recorder
component. The proxy will place a copy of this timer into each sample it
records, or into the first sample of each group if you're using grouping. This
copy will then be scanned for occurrences of variable ${T} in its properties,
and any such occurrences will be replaced by the time gap from the previous
sampler recorded (in milliseconds).
You will need to edit the proxy settings of your browser to point at the
appropriate server and port, where the server is the machine JMeter is
running on, and the port # is from the Proxy Control Panel shown above.
JMeter places the recorded samples in the Target Controller you choose. If
you choose the default option "Use Recording Controller", they will be
stored in the first Recording Controller found in the test object tree (so be sure
to add a Recording Controller before you start recording).
P a g e | 288
If the Proxy does not seem to record any samples, this could be because the
browser is not actually using the proxy. To check if this is the case, try
stopping the proxy. If the browser still downloads pages, then it was not
sending requests via the proxy. Double-check the browser options. If you are
trying to record from a server running on the same host, then check that the
browser is not set to "Bypass proxy server for local addresses"
(this example is from IE7, but there will be similar options for other browsers).
If JMeter does not record browser URLs such
as http://localhost/ or http://127.0.0.1/, try using the non-
loopback hostname or IP address,
e.g. http://myhost/ or http://192.168.0.2/.
Note that the boundary characters are not part of the matching group,
e.g. n.* to match name out of You can call me 'name'.
If you don't want your regex to be enclosed with those boundary matchers,
you have to enclose your regex within parens, e.g ('.*?') to
match 'name' out of You can call me 'name'.
The variables will be checked in random order. So ensure, that the potential
matches don't overlap. Overlapping matchers would be .* (which matches
anything) and www (which matches www only). Non-overlapping matchers
would be a+ (matches a sequence of a's) and b+ (matches a sequence
of b's).
If you want to match /images at the start of a string only, use the
value (^/images). Jakarta ORO also supports zero-width look-ahead, so
one can match /images/… but retain the trailing / in the output by
using (^/images(?=/)).
Note that the current version of Jakara ORO does not support look-behind -
i.e. (?<=…) or (?<!…).
Look out for overlapping matchers. For example the value .* as a regex in a
variable named regex will partly match a previous replaced variable, which
will result in something like ${{regex}, which is most probably not the
desired result.
If there are any problems interpreting any variables as patterns, these are
reported in jmeter.log, so be sure to check this if UDVs are not working as
expected.
When you are done recording your test samples, stop the proxy server (hit the
"stop" button). Remember to reset your browser's proxy settings. Now, you
P a g e | 290
may want to sort and re-order the test script, add timers, listeners, a cookie
manager, etc.
Just place a View Results Tree listener as a child of the HTTP(S) Test Script
Recorder and the responses will be displayed. You can also add a Save
Responses to a file Post-Processor which will save the responses to files.
Cookie Manager
If the server you are testing against uses cookies, remember to add an HTTP
Cookie Manager to the test plan when you have finished recording it. During
recording, the browser handles any cookies, but JMeter needs a Cookie
Manager to do the cookie handling during a test run. The JMeter Proxy server
passes on all cookies sent by the browser during recording, but does not save
them to the test plan because they are likely to change between runs.
Authorization Manager
Uploading files
Some browsers (e.g. Firefox and Opera) don't include the full name of a file
when uploading files. This can cause the JMeter proxy server to fail. One
solution is to ensure that any files to be uploaded are in the JMeter working
directory, either by copying the files there or by starting JMeter in the directory
containing the files.
P a g e | 291
Recording HTTP Based Non Textual Protocols not natively available in JMeter
You may have to record an HTTP protocol that is not handled by default by
JMeter (Custom Binary Protocol, Adobe Flex, Microsoft Silverlight, … ).
Although JMeter does not provide a native proxy implementation to record
these protocols, you have the ability to record these protocols by
implementing a custom SamplerCreator. This Sampler Creator will
translate the binary format into a HTTPSamplerBase subclass that can be
added to the JMeter Test Case. For more details see "Extending JMeter".
Parameters
Attribute
Description
Required
Port
Port on which Mirror server listens, defaults to 8081.
Yes
Max Number of threads
If set to a value > 0, number of threads serving requests will be limited to the
configured number, if set to a value ≤ 0 a new thread will be created to serve
each incoming request. Defaults to 0
No
P a g e | 292
Parameters
Attribute
Description
Required
X-Sleep
Time to sleep in ms before sending response
No
X-SetCookie
Cookies to be set on response
No
X-ResponseStatus
Response status, see HTTP Status responses, example 200 OK, 500 Internal
Server Error, ….
No
X-ResponseLength
Size of response, this trims the response to the requested size if that is less
than the total size
No
X-SetHeaders
Pipe separated list of headers, example:
headerA=valueA|headerB=valueB would
set headerA to valueA and headerB to valueB.
No
Parameters
Attribute
Description
Required
redirect
P a g e | 293
Property Display
The Property Display shows the values of System or JMeter properties.
Values can be changed by entering new text in the Value column. It is
available only on the WorkBench.
Parameters
Attribute
P a g e | 294
Description
Required
Name
Descriptive name for this element that is shown in the tree.
No
^
Debug Sampler
The Debug Sampler generates a sample containing the values of all JMeter
variables and/or properties.
The values can be seen in the View Results Tree Listener Response Data
pane.
Screenshot of Control-
Panel of Debug Sampler
Parameters
Attribute
Description
Required
Name
Descriptive name for this element that is shown in the tree.
No
JMeter Properties
Include JMeter properties?
Yes
JMeter Variables
Include JMeter variables?
Yes
System Properties
Include System properties?
P a g e | 295
Yes
^
Debug PostProcessor
The Debug PostProcessor creates a subSample with the details of the
previous Sampler properties, JMeter variables, properties and/or System
Properties.
The values can be seen in the View Results Tree Listener Response Data
pane.
Screenshot of Control-Panel of
Debug PostProcessor
Parameters
Attribute
Description
Required
Name
Descriptive name for this element that is shown in the tree.
No
JMeter Properties
Whether to show JMeter properties (default false).
Yes
JMeter Variables
Whether to show JMeter variables (default false).
Yes
Sampler Properties
Whether to show Sampler properties (default true).
Yes
System Properties
P a g e | 296
Test Fragment
The Test Fragment is used in conjunction with the Include
Controller and Module Controller.
Parameters
Attribute
Description
Required
Name
Descriptive name for this element that is shown in the tree.
Yes
When using Test Fragment with Module Controller, ensure you disable the
Test Fragment to avoid the execution of Test Fragment itself. This is done by
default since JMeter 2.13.
^