Professional Documents
Culture Documents
4 User’s Manual
1. Introduction ........................................................................................ 9
1.1 History................................................................................................................. 9
1.2 The Future........................................................................................................... 9
2. Getting Started.................................................................................. 10
2.1 Requirements .................................................................................................... 10
2.1.1 Java Version.............................................................................................. 11
2.1.2 Operating Systems .................................................................................... 11
2.2 Optional............................................................................................................. 11
2.2.1 Java Compiler ........................................................................................... 11
2.2.2 SAX XML Parser...................................................................................... 11
2.2.3 Email Support ........................................................................................... 11
2.2.4 SSL Encryption......................................................................................... 11
2.2.5 JDBC Driver ............................................................................................. 12
2.2.6 Apache SOAP ........................................................................................... 12
2.2.7 Libraries for ActiveMQ 3.0 ...................................................................... 12
2.3 Installation......................................................................................................... 12
2.4 Running JMeter................................................................................................. 13
2.4.1 JMeter's Classpath..................................................................................... 14
2.4.2 Using a Proxy Server ................................................................................ 14
2.4.3 Non-GUI Mode (Command Line mode) .................................................. 15
2.4.4 Server Mode.............................................................................................. 15
2.4.5 Overriding Properties Via The Command Line........................................ 16
2.4.6 Logging and error messages ..................................................................... 16
2.4.7 Full list of command-line options ............................................................. 17
2.5 Configuring JMeter........................................................................................... 18
3. Building a Test Plan ......................................................................... 20
3.1 Adding and Removing Elements ...................................................................... 20
3.2 Loading and Saving Elements .......................................................................... 20
3.3 Configuring Tree Elements............................................................................... 20
3.4 Saving the Test Plan.......................................................................................... 20
3.5 Running a Test Plan .......................................................................................... 21
3.6 Stopping a Test ................................................................................................. 21
3.7 Error reporting .................................................................................................. 22
4. Elements of a Test Plan.................................................................... 23
4.1 ThreadGroup ..................................................................................................... 23
4.2 Controllers......................................................................................................... 24
4.2.1 Samplers.................................................................................................... 24
4.2.2 Logic Controllers ...................................................................................... 25
4.3 Listeners............................................................................................................ 26
4.4 Timers ............................................................................................................... 27
4.5 Assertions.......................................................................................................... 27
4.6 Configuration Elements .................................................................................... 27
1
Jmeter 2.3.4 User’s Manual
2
Jmeter 2.3.4 User’s Manual
3
Jmeter 2.3.4 User’s Manual
4
Jmeter 2.3.4 User’s Manual
5
Jmeter 2.3.4 User’s Manual
6
Jmeter 2.3.4 User’s Manual
7
Jmeter 2.3.4 User’s Manual
8
Jmeter 2.3.4 User’s Manual
1. Introduction
Apache JMeter is a 100% pure Java desktop application designed to load test
client/server software (such as a web application ). It may be used to test performance
both on static and dynamic resources such as static files, Java Servlets, CGI scripts, Java
objects, databases , FTP servers , and more. JMeter can be used to simulate a heavy load
on a server, network or object to test its strength or to analyze overall performance under
different load types.
Additionally, JMeter can help you regression test your application by letting you create
test scripts with assertions to validate that your application is returning the results you
expect. For maximum flexibility, JMeter lets you create these assertions using regular
expressions.
1.1 History
Stefano Mazzocchi of the Apache Software Foundation was the original developer of
JMeter. He wrote it primarily to test the performance of Apache JServ (a project that has
since been replaced by the Apache Tomcat project). We redesigned JMeter to enhance
the GUI and to add functional-testing capabilities.
9
Jmeter 2.3.4 User’s Manual
2. Getting Started
The easiest way to begin using JMeter is to first download the latest production release
and install it. The release contains all of the files you need to build and run most types of
tests, e.g. Web (HTTP/HTTPS), FTP, JDBC, LDAP, Java, and JUnit.
If you want to perform JDBC testing, then you will, of course, need the appropriate
JDBC driver from your vendor. JMeter does not come with any JDBC drivers.
See the JMeter Classpath section for details on installing additional jars.
Next, start JMeter and go through the Building a Test Plan section of the User Guide to
familiarize yourself with JMeter basics (for example, adding and removing elements).
Finally, go through the appropriate section on how to build a specific type of Test Plan.
For example, if you are interested in testing a Web application, then see the section
Building a Web Test Plan . The other specific Test Plan sections are:
Once you are comfortable with building and running JMeter Test Plans, you can look into
the various configuration elements (timers, listeners, assertions, and others) which give
you more control over your Test Plans.
2.1 Requirements
JMeter requires your computing environment meets some minimum requirements.
10
Jmeter 2.3.4 User’s Manual
Because JMeter uses only standard Java APIs, please do not file bug reports if your JRE
fails to run JMeter because of JRE implementation issues.
JMeter is a 100% Java application and should run correctly on any system that has a
compliant Java implementation.
JMeter has been tested and works under:
2.2 Optional
If you plan on doing JMeter development, then you will need one or more optional
packages listed below.
To test a web server using SSL encryption (HTTPS), JMeter requires that an
implementation of SSL be provided, as is the case with Sun Java 1.4 and above. If your
11
Jmeter 2.3.4 User’s Manual
version of Java does not include SSL support, then it is possible to add an external
implementation. Include the necessary encryption packages in JMeter's classpath . Also,
update system.properties to register the SSL Provider.
JMeter defaults to protocol level TLS. This can be changed by editting the JMeter
property "https.default.protocol" in jmeter.properties or user.properties.
The JMeter proxy server (see below) does not support recording SSL (https).
2.3 Installation
We recommend that most users run the latest release .
To install a release build, simply unzip the zip/tar file into the directory where you want
JMeter to be installed. Provided that you have a JRE/JDK correctly installed and the
JAVA_HOME environment variable set, there is nothing more for you to do.
Note: there can be problems (especially with client-server mode) if the directory path
contains any spaces.
The installation directory structure should look something like this (for version 2.3.1):
12
Jmeter 2.3.4 User’s Manual
jakarta-jmeter-2.3.1
jakarta-jmeter-2.3.1/bin
jakarta-jmeter-2.3.1/docs
jakarta-jmeter-2.3.1/extras
jakarta-jmeter-2.3.1/lib/
jakarta-jmeter-2.3.1/lib/ext
jakarta-jmeter-2.3.1/lib/junit
jakarta-jmeter-2.3.1/printable_docs
You can rename the parent directory (i.e. jakarta-jmeter-2.3.1) if you want, but do not
change any of the sub-directory names.
There are some additional scripts in the bin directory that you may find useful. Windows
script files (the .CMD files require Win2K or later):
Note: the special name LAST can be used with jmeter-n.cmd, jmeter-t.cmd and jmeter-n-
r.cmd and means the last test plan that was run interactively.
The environment variable JVM_ARGS can be used to override JVM settings in the
jmeter.bat script. For example:
• jmeter - run JMeter (in GUI mode by default). Defines some JVM settings which
may not work for all JVMs.
• jmeter-server - start JMeter in server mode (calls jmeter script with appropriate
parameters)
• jmeter.sh - very basic JMeter script with no JVM options specified.
It may be necessary to edit the jmeter shell script if some of the JVM options are not
supported. The JVM_ARGS environment variable can be used to override or set
additional JVM options, for example:
13
Jmeter 2.3.4 User’s Manual
If you have developed new JMeter components, then you should jar them and copy the
jar into JMeter's lib/ext directory. JMeter will automatically find JMeter components in
any jars found here.
If you don't want to put JMeter extension jars in the lib/ext directory, then define the
property search_paths in jmeter.properties. Do not use lib/ext for utility jars; it is only
intended for JMeter components.
Other jars (such as JDBC, JavaMail and any other support libaries needed by the JMeter
code) should be placed in the lib directory - not the lib/ext directory
You can also install utility Jar files in $JAVA_HOME/jre/lib/ext, or (since 2.1.1) you can
set the property user.classpath in jmeter.properties
Note that setting the CLASSPATH environment variable will have no effect. This is
because JMeter is started with "java -jar", and the java command silently ignores the
CLASSPATH variable, and the -classpath/-cp options when -jar is used. [This occurs
with all Java programs, not just JMeter.]
If you are testing from behind a firewall/proxy server, you may need to provide JMeter
with the firewall/proxy server hostname and port number. To do so, run the
jmeter.bat/jmeter file from a command line with the following parameters:
14
Jmeter 2.3.4 User’s Manual
JMeter also has its own in-built HTTP Proxy Server , which can be used for
recording HTTP (but not HTTPS) browser sessions. This is not to be confused with
the proxy settings described above, which are used when JMeter makes HTTP or
HTTPS requests itself.
For non-interactive testing, you may choose to run JMeter without the GUI. To do so, use
the following command options
-r Run the test in the servers specified by the JMeter property "remote_hosts"
-R [list of remote servers] Run the test in the specified remote servers
The script also lets you specify the optional firewall/proxy server information:
For distributed testing, run JMeter in server mode on the remote node(s), and then control
the server(s) from the GUI. You can also use non-GUI mode to run remote tests. To start
the server(s), run jmeter-server/jmeter-server.bat on each server host.
The script also lets you specify the optional firewall/proxy server information:
If you want the server to exit after a single test has been run, then define the JMeter
property server.exitaftertest=true.
To run the test from the client in non-GUI mode, use the following command:
15
Jmeter 2.3.4 User’s Manual
Java system properties, JMeter properties, and logging properties can be overriden
directly on the command line (instead of modifying jmeter.properties). To do so, use the
following options:
The -L flag can also be used without the category name to set the root logging level.
Examples:
jmeter -Duser.dir=/home/mstover/jmeter_stuff \
-Jremote_hosts=127.0.0.1 -Ljmeter.engine=DEBUG
jmeter -LDEBUG
N.B.
The command line properties are processed early in startup, but after the logging
system has been set up. Attempts to use the -J flag to update log_level or log_file
properties will have no effect.
JMeter does not generally use pop-up dialog boxes for errors, as these would interfere
with running tests. Nor does it report any error for a misspell variable or function;
instead the reference is just used as is. See Functions and Variables for more
information .
If JMeter detects an error during a test, a message will be written to the log file. The log
file name is defined in the jmeter.properties file (or using the -j option, see below). It
16
Jmeter 2.3.4 User’s Manual
defaults to jmeter.log , and will be found in the directory from which JMeter was
launched.
JMeter versions after 2.2 added a new command-line option, -j jmeterlogfile. This is
processed after the initial properties file is read, and before any further properties are
processed. It therefore allows the default of jmeter.log to be overridden. The jmeter
scripts that take a test plan name as a parameter (e.g. jmeter-n.cmd) have been updated to
define the log file using the test plan name, e.g. for the test plan Test27.jmx the log file is
set to Test27.log.
When running on Windows, the file may appear as just jmeter unless you have set
Windows to show file extensions. [Which you should do anyway, to make it easier to
detect viruses and other nasties that pretend to be text files...]
As well as recording errors, the jmeter.log file records some information about the test
run. For example:
The log file can be helpful in determining the cause of an error, as JMeter does not
interrupt a test to display an error dialogue. .
Invoking JMeter as "jmeter -?" will print a list of all the command-line options. These are
shown below.
-h, --help
print usage information and exit
-v, --version
print the version information and exit
-p, --propfile {argument}
the jmeter property file to use
-q, --addprop {argument}
additional property file(s)
-t, --testfile {argument}
the jmeter test(.jmx) file to run
-j, --jmeterlogfile {argument}
the jmeter log file
-l, --logfile {argument}
the file to log samples to
-n, --nongui
17
Jmeter 2.3.4 User’s Manual
Note: the JMeter log file name is formatted as a SimpleDateFormat (applied to the
current date) if it contains paired single-quotes, .e.g. 'jmeter_'yyyyMMddHHmmss'.log'
If the special name LAST is used for the -t, -j or -l flags, then JMeter takes that to mean
the last test plan that was run in interactive mode.
Note: since 2.2, you can define additional JMeter properties in the file defined by the
JMeter property user.properties which has the default value user.properties . The file
will be automatically loaded if it is found in the current directory or if it is found in the
JMeter bin directory. Similarly, system.properties is used to update system properties.
18
Jmeter 2.3.4 User’s Manual
Parameters
The command line options and properties files are processed in the following order:
• -p propfile
• jmeter.properties (or the file from the -p option) is then loaded
• -j logfile
• Logging is initialised
• user.properties is loaded
• system.properties is loaded
• all other command-line options are processed
19
Jmeter 2.3.4 User’s Manual
To remove an element, make sure the element is selected, right-click on the element, and
choose the "remove" option.
To save tree elements, right click on an element and choose the "save" option. JMeter
will save the element selected, plus all child elements beneath it. In this way, you can
save test tree fragments, individual elements, or the entire test plan.
The workbench is not automatically saved with the test plan, but it can be saved
separately as above.
The Test Tree itself can be manipulated by dragging and dropping components around
the test tree.
JMeter allows you to save the entire Test Plan tree or only a portion of it. To save only
20
Jmeter 2.3.4 User’s Manual
the elements located in a particular "branch" of the Test Plan tree, select the Test Plan
element in the tree from which to start the "branch", and then click your right mouse
button to access the Save As menu item. Alternatively, select the appropriate Test Plan
element and then select Save As from the Edit menu.
The numbers to the left of the green box are the number of active threads / total number
of threads.
Versions of JMeter after 2.3.2 allow a Stop to be initiated if Shutdown is taking too long.
Close the Shutdown dialog box and select Run/Stop, or just press Control + '.'.
When running JMeter in non-GUI mode, there is no Menu, and JMeter does not react to
keystrokes such as Control + '.'. So in versions after 2.3.2, JMeter non-GUI mode will
listen for commands on a specific port (default 4445, see the JMeter property
jmeterengine.nongui.port ). The commands currently supported are:
21
Jmeter 2.3.4 User’s Manual
Sampling errors (e.g. HTTP 404 - file not found) are not normally reported in the log file.
Instead these are stored as attributes of the sample result. The status of a sample result
can be seen in the various different Listeners.
22
Jmeter 2.3.4 User’s Manual
If you are not recording the data to file, this option makes no difference.
You can also use the Configuration button on a listener to decide what fields to save.
4.1 ThreadGroup
Thread group elements are the beginning points of any test plan. All controllers and
samplers must be under a thread group. Other elements, e.g. Listeners, may be placed
directly under the test plan, in which case they will apply to all the thread groups. As the
name implies, the thread group element controls the number of threads JMeter will use to
execute your test. The controls for a thread group allow you to:
Each thread will execute the test plan in its entirety and completely independently of
other test threads. Multiple threads are used to simulate concurrent connections to your
server application.
The ramp-up period tells JMeter how long to take to "ramp-up" to the full number of
threads chosen. If 10 threads are used, and the ramp-up period is 100 seconds, then
JMeter will take 100 seconds to get all 10 threads up and running. Each thread will start
10 (100/10) seconds after the previous thread was begun. If there are 30 threads and a
ramp-up period of 120 seconds, then each successive thread will be delayed by 4 seconds.
Ramp-up needs to be long enough to avoid too large a work-load at the start of a test, and
short enough that the last threads start running before the first ones finish (unless one
wants that to happen).
By default, the thread group is configured to loop once through its elements.
Version 1.9 introduces a test run scheduler. Click the checkbox at the bottom of the
Thread Group panel to reveal extra fields in which you can enter the start and end times
23
Jmeter 2.3.4 User’s Manual
of the run. When the test is started, JMeter will wait if necessary until the start-time has
been reached. At the end of each cycle, JMeter checks if the end-time has been reached,
and if so, the run is stopped, otherwise the test is allowed to continue until the iteration
limit is reached.
Alternatively, one can use the relative delay and duration fields. Note that delay overrides
start-time, and duration over-rides end-time.
4.2 Controllers
JMeter has two types of Controllers: Samplers and Logical Controllers. These drive the
processing of a test.
Samplers tell JMeter to send requests to a server. For example, add an HTTP Request
Sampler if you want JMeter to send an HTTP request. You can also customize a request
by adding one or more Configuration Elements to a Sampler. For more information, see
Samplers .
Logical Controllers let you customize the logic that JMeter uses to decide when to send
requests. For example, you can add an Interleave Logic Controller to alternate between
two HTTP Request Samplers. For more information, see Logical Controllers .
4.2.1 Samplers
Samplers tell JMeter to send requests to a server and wait for a response. They are
processed in the order they appear in the tree. Controllers can be used to modify the
number of repetitions of a sampler.
• FTP Request
• HTTP Request
• JDBC Request
• Java object request
• LDAP Request
• SOAP/XML-RPC Request
• WebService (SOAP) Request
Each sampler has several properties you can set. You can further customize a sampler by
adding one or more Configuration Elements to the Test Plan.
If you are going to send multiple requests of the same type (for example, HTTP Request)
to the same server, consider using a Defaults Configuration Element. Each controller has
one or more Defaults elements (see below).
24
Jmeter 2.3.4 User’s Manual
Remember to add a Listener to your test plan to view and/or store the results of your
requests to disk.
If you are interested in having JMeter perform basic validation on the response of your
request, add an Assertion to the sampler. For example, in stress testing a web application,
the server may return a successful "HTTP Response" code, but the page may have errors
on it or may be missing sections. You could add assertions to check for certain HTML
tags, common error strings, and so on. JMeter lets you create these assertions using
regular expressions.
Logic Controllers let you customize the logic that JMeter uses to decide when to send
requests. Logic Controllers can change the order of requests coming from their child
elements. They can modify the requests themselves, causing JMeter to repeat requests,
etc.
To understand the effect of Logic Controllers on a test plan, consider the following test
tree:
• Test Plan
o Thread Group
Once Only Controller
Login Request (an HTTP Request )
Load Search Page (HTTP Sampler)
Interleave Controller
Search "A" (HTTP Sampler)
Search "B" (HTTP Sampler)
HTTP default request (Configuration Element)
HTTP default request (Configuration Element)
Cookie Manager (Configuration Element)
The first thing about this test is that the login request will be executed only the first time
through. Subsequent iterations will skip it. This is due to the effects of the Once Only
Controller .
After the login, the next Sampler loads the search page (imagine a web application where
the user logs in, and then goes to a search page to do a search). This is just a simple
request, not filtered through any Logic Controller.
After loading the search page, we want to do a search. Actually, we want to do two
different searches. However, we want to re-load the search page itself between each
search. We could do this by having 4 simple HTTP request elements (load search, search
"A", load search, search "B"). Instead, we use the Interleave Controller which passes on
25
Jmeter 2.3.4 User’s Manual
one child request each time through the test. It keeps the ordering (ie - it doesn't pass one
on at random, but "remembers" its place) of its child elements. Interleaving 2 child
requests may be overkill, but there could easily have been 8, or 20 child requests.
Note the HTTP Request Defaults that belongs to the Interleave Controller. Imagine that
"Search A" and "Search B" share the same PATH info (an HTTP request specification
includes domain, port, method, protocol, path, and arguments, plus other optional items).
This makes sense - both are search requests, hitting the same back-end search engine (a
servlet or cgi-script, let's say). Rather than configure both HTTP Samplers with the same
information in their PATH field, we can abstract that information out to a single
Configuration Element. When the Interleave Controller "passes on" requests from
"Search A" or "Search B", it will fill in the blanks with values from the HTTP default
request Configuration Element. So, we leave the PATH field blank for those requests,
and put that information into the Configuration Element. In this case, this is a minor
benefit at best, but it demonstrates the feature.
The next element in the tree is another HTTP default request, this time added to the
Thread Group itself. The Thread Group has a built-in Logic Controller, and thus, it uses
this Configuration Element exactly as described above. It fills in the blanks of any
Request that passes through. It is extremely useful in web testing to leave the DOMAIN
field blank in all your HTTP Sampler elements, and instead, put that information into an
HTTP default request element, added to the Thread Group. By doing so, you can test
your application on a different server simply by changing one field in your Test Plan.
Otherwise, you'd have to edit each and every Sampler.
The last element is a HTTP Cookie Manager . A Cookie Manager should be added to all
web tests - otherwise JMeter will ignore cookies. By adding it at the Thread Group level,
we ensure that all HTTP requests will share the same cookies.
Logic Controllers can be combined to achieve various results. See the list of built-in
Logic Controllers .
4.3 Listeners
Listeners provide access to the information JMeter gathers about the test cases while
JMeter runs. The Graph Results listener plots the response times on a graph. The "View
Results Tree" Listener shows details of sampler requests and responses, and can display
basic HTML and XML representations of the response. Other listeners provide summary
or aggregation information.
Additionally, listeners can direct the data to a file for later use. Every listener in JMeter
provides a field to indicate the file to store data to. There is also a Configuration button
which can be used to choose which fields to save, and whether to use CSV or XML
format. Note that all Listeners save the same data; the only difference is in the way
the data is presented on the screen.
26
Jmeter 2.3.4 User’s Manual
Listeners can be added anywhere in the test, including directly under the test plan. They
will collect data only from elements at or below their level.
4.4 Timers
By default, a JMeter thread sends requests without pausing between each request. We
recommend that you specify a delay by adding one of the available timers to your Thread
Group. If you do not add a delay, JMeter could overwhelm your server by making too
many requests in a very short amount of time.
The timer will cause JMeter to delay a certain amount of time before each request that a
thread makes.
If you choose to add more than one timer to a Thread Group, JMeter takes the sum of the
timers and pauses for that amount of time before executing the samplers to which the
timers apply. Timers can be added as children of samplers or controllers in order to
restrict the samplers to which they are applied.
To provide a pause at a single place in a test plan, one can use the Test Action Sampler.
4.5 Assertions
Assertions allow you to assert facts about responses received from the server being
tested. Using an assertion, you can essentially "test" that your application is returning the
results you expect it to.
For instance, you can assert that the response to a query will contain some particular text.
The text you specify can be a Perl-style regular expression, and you can indicate that the
response is to contain the text, or that it should match the whole response.
You can add an assertion to any Sampler. For example, you can add an assertion to a
HTTP Request that checks for the text, "</HTML>". JMeter will then check that the text
is present in the HTTP response. If JMeter cannot find the text, then it will mark this as a
failed request.
To view the assertion results, add an Assertion Listener to the Thread Group. Failed
Assertions will also show up in the Tree View and Table Listeners, and will count
towards the error %age for example in the Aggregate and Summary reports.
27
Jmeter 2.3.4 User’s Manual
A configuration element is accessible from only inside the tree branch where you place
the element. For example, if you place an HTTP Cookie Manager inside a Simple Logic
Controller, the Cookie Manager will only be accessible to HTTP Request Controllers you
place inside the Simple Logic Controller (see figure 1). The Cookie Manager is
accessible to the HTTP requests "Web Page 1" and "Web Page 2", but not "Web Page 3".
Also, a configuration element inside a tree branch has higher precedence than the same
element in a "parent" branch. For example, we defined two HTTP Request Defaults
elements, "Web Defaults 1" and "Web Defaults 2". Since we placed "Web Defaults 1"
inside a Loop Controller, only "Web Page 2" can access it. The other HTTP requests will
use "Web Defaults 2", since we placed it in the Thread Group (the "parent" of all other
branches).
28
Jmeter 2.3.4 User’s Manual
Please note that Timers, Assertions, Pre- and Post-Processors are only processed if there
is a sampler to which they apply. Logic Controllers and Samplers are processed in the
order in which they appear in the tree. Other test elements are processed according to the
scope in which they are found, and the type of test element. [Within a type, elements are
processed in the order in which they appear in the tree].
• Controller
o Post-Processor 1
o Sampler 1
o Sampler 2
o Timer 1
o Assertion 1
o Pre-Processor 1
o Timer 2
o Post-Processor 2
Pre-Processor 1
Timer 1
Timer 2
Sampler 2
Post-Processor 1
Post-Processor 2
Assertion 1
29
Jmeter 2.3.4 User’s Manual
Some controllers affect the order of their subelements, and you can read about these
specific controllers in the component reference .
Other elements are hierarchical. An Assertion, for instance, is hierarchical in the test tree.
If its parent is a request, then it is applied to that request. If its parent is a Controller, then
it affects all requests that are descendants of that Controller. In the following test tree:
Hierarchy example
30
Jmeter 2.3.4 User’s Manual
complex example
In this example, the requests are named to reflect the order in which they will be
executed. Timer #1 will apply to Requests Two, Three, and Four (notice how order is
irrelevant for hierarchical elements). Assertion #1 will apply only to Request Three.
Timer #2 will affect all the requests.
Hopefully these examples make it clear how configuration (hierarchical) elements are
applied. If you imagine each Request being passed up the tree branches, to its parent, then
to its parent's parent, etc, and each time collecting all the configuration elements of that
parent, then you will see how it works.
Properties are global to jmeter, and are mostly used to define some of the defaults JMeter
uses. For example the property remote_hosts defines the servers that JMeter will try to
run remotely. Properties can be referenced in test plans - see Functions - read a property -
but cannot be used for thread-specific values.
JMeter variables are local to each thread. The values may be the same for each thread, or
they may be different.
31
Jmeter 2.3.4 User’s Manual
If a variable is updated by a thread, only the thread copy of the variable is changed. For
example the Regular Expression Extractor Post-Processor will set its variables according
to the sample that its thread has read, and these can be used later by the same thread. For
details of how to reference variables and functions, see Functions and Variables
Note that the values defined by the Test Plan and the User Defined Variables
configuration element are made available to the whole test plan at startup. If the same
variable is defined by multiple UDV elements, then the last one takes effect. Once a
thread has started, the initial set of variables is copied to each thread. Other elements such
as the User Parameters Pre-Processor or Regular Expression Extractor Post-Processor
may be used to redefine the same variables (or create new ones). These redefinitions only
apply to the current thread.
The setProperty function can be used to define a JMeter property. These are global to the
test plan, so can be used to pass information between threads - should that be needed.
When deciding how to structure a Test Plan, make a note of which items are constant for
the run, but which may change between runs. Decide on some variable names for these -
perhaps use a naming convention such as prefixing them with C_ or K_ or using
uppercase only to distinguish them from variables that need to change during the test.
Also consider which items need to be local to a thread - for example counters or values
extracted with the Regular Expression Post-Processor. You may wish to use a different
naming convention for these.
For example, you might define the following on the Test Plan:
HOST www.example.com
THREADS 10
LOOPS 20
You can refer to these in the test plan as ${HOST} ${THREADS} etc. If you later want
to change the host, just change the value of the HOST variable. This works fine for small
numbers of tests, but becomes tedious when testing lots of different combinations. One
solution is to use a property to define the value of the variables, for example:
HOST ${__P(host,www.example.com)}
32
Jmeter 2.3.4 User’s Manual
THREADS ${__P(threads,10)}
LOOPS ${__P(loops,20)}
You can then change some or all of the values on the command-line as follows:
jmeter ... -Jhost=www3.example.org -Jloops=13
33
Jmeter 2.3.4 User’s Manual
For a more advanced Test Plan, see Building an Advanced Web Test Plan .
Go ahead and add the ThreadGroup element by first selecting the Test Plan, clicking your
right mouse button to get the Add menu, and then select Add --> ThreadGroup.
You should now see the Thread Group element under Test Plan. If you do not see the
element, then "expand" the Test Plan tree by clicking on the Test Plan element.
Next, you need to modify the default properties. Select the Thread Group element in the
tree, if you have not already selected it. You should now see the Thread Group Control
Panel in the right section of the JMeter window (see Figure 5.1 below)
34
Jmeter 2.3.4 User’s Manual
Start by providing a more descriptive name for our Thread Group. In the name field,
enter Jakarta Users.
In the next field, the Ramp-Up Period, leave the default value of 0 seconds. This property
tells JMeter how long to delay between starting each user. For example, if you enter a
Ramp-Up Period of 5 seconds, JMeter will finish starting all of your users by the end of
the 5 seconds. So, if we have 5 users and a 5 second Ramp-Up Period, then the delay
between starting users would be 1 second (5 users / 5 seconds = 1 user per second). If you
set the value to 0, then JMeter will immediately start all of your users.
Finally enter a value of 2 in the Loop Count field. This property tells JMeter how many
times to repeat your test. If you enter a loop count value of 1, then JMeter will run your
test only once. To have JMeter repeatedly run your Test Plan, select the Forever
checkbox.
In most applications, you have to manually accept changes you make in a Control
Panel. However, in JMeter, the Control Panel automatically accepts your changes as
you make them. If you change the name of an element, the tree will be updated with
the new text after you leave the Control Panel (for example, when selecting another
tree element).
See Figure 5.2 for the completed Jakarta Users Thread Group.
35
Jmeter 2.3.4 User’s Manual
Begin by selecting the Jakarta Users (Thread Group) element. Click your right mouse
button to get the Add menu, and then select Add --> Config Element --> HTTP Request
Defaults. Then, select this new element to view its Control Panel (see Figure 5.3).
Like most JMeter elements, the HTTP Request Defaults Control Panel has a name field
that you can modify. In this example, leave this field with the default value.
Skip to the next field, which is the Web Server's Server Name/IP. For the Test Plan that
you are building, all HTTP requests will be sent to the same Web server,
jakarta.apache.org. Enter this domain name into the field. This is the only field that we
will specify a default, so leave the remaining fields with their default values.
36
Jmeter 2.3.4 User’s Manual
The HTTP Request Defaults element does not tell JMeter to send an HTTP request. It
simply defines the default values that the HTTP Request elements use.
See Figure 5.4 for the completed HTTP Request Defaults element
To add the HTTP Cookie Manager , simply select the Thread Group , and choose Add -->
Config Element --> HTTP Cookie Manager, either from the Edit Menu, or from the right-
click pop-up menu.
37
Jmeter 2.3.4 User’s Manual
JMeter sends requests in the order that they appear in the tree.
Start by adding the first HTTP Request to the Jakarta Users element (Add --> Sampler --
> HTTP Request). Then, select the HTTP Request element in the tree and edit the
following properties (see Figure 5.5):
38
Jmeter 2.3.4 User’s Manual
Figure 5.
Next, add the second HTTP Request and edit the following properties (see Figure 5.6:
39
Jmeter 2.3.4 User’s Manual
Select the Jakarta Users element and add a Graph Results listener (Add --> Listener -->
Graph Results). Next, you need to specify a directory and filename of the output file. You
can either type it into the filename field, or select the Browse button and browse to a
directory and then enter a filename.
40
Jmeter 2.3.4 User’s Manual
To do this in JMeter, add an HTTP Request, and set the method to POST. You'll need to
know the names of the fields used by the form, and the target page. These can be found
out by inspecting the code of the login page. [If this is difficult to do, you can use the
JMeter Proxy Recorder to record the login sequence.] Set the path to the target of the
submit button. Click the Add button twice and enter the username and password details.
Sometimes the login form contains additional hidden fields. These will need to be added
as well.
41
Jmeter 2.3.4 User’s Manual
42
Jmeter 2.3.4 User’s Manual
For an example of a basic Test Plan, see Building a Web Test Plan .
To respond correctly to URL rewriting, JMeter needs to parse the HTML received from
the server and retrieve the unique session ID. Use the appropriate HTTP URL Re-writing
Modifier to accomplish this. Simply enter the name of your session ID parameter into the
modifier, and it will find it and add it to each request. If the request already has a value, it
will be replaced. If "Cache Session Id?" is checked, then the last found session id will be
saved, and will be used if the previous HTTP sample does not contain a session id.
Download this example . In Figure 1 is shown a test plan using URL rewriting. Note that
the URL Re-writing modifier is added to the SimpleController, thus assuring that it will
only affect requests under that SimpleController.
In Figure 2, we see the URL Re-writing modifier GUI, which just has a field for the user
to specify the name of the session ID parameter. There is also a checkbox for indicating
that the session ID should be part of the path (separated by a ";"), rather than a request
parameter
43
Jmeter 2.3.4 User’s Manual
The HTTP Header Manager , like the HTTP Cookie Manager , should probably be added
at the Thread Group level, unless for some reason you wish to specify different headers
for the different HTTP Request objects in your test.
44
Jmeter 2.3.4 User’s Manual
This example uses the MySQL database driver. To use this driver, its containing .jar
file must be copied to the JMeter lib directory (see JMeter's Classpath for more
details).
Go ahead and add the ThreadGroup element by first selecting the Test Plan, clicking your
right mouse button to get the Add menu, and then select Add --> ThreadGroup.
You should now see the Thread Group element under Test Plan. If you do not see the
element, then "expand" the Test Plan tree by clicking on the Test Plan element.
Next, you need to modify the default properties. Select the Thread Group element in the
tree, if you have not already selected it. You should now see the Thread Group Control
Panel in the right section of the JMeter window (see Figure 7.1 below)
45
Jmeter 2.3.4 User’s Manual
Start by providing a more descriptive name for our Thread Group. In the name field,
enter JDBC Users.
You will need a valid database, database table, and user-level access to that table. In
the example shown here, the database is 'mydb' and the table name is 'Stocks'.
In the next field, the Ramp-Up Period, leave the default value of 0 seconds. This property
tells JMeter how long to delay between starting each user. For example, if you enter a
Ramp-Up Period of 5 seconds, JMeter will finish starting all of your users by the end of
the 5 seconds. So, if we have 5 users and a 5 second Ramp-Up Period, then the delay
between starting users would be 1 second (5 users / 5 seconds = 1 user per second). If you
set the value to 0, then JMeter will immediately start all of your users.
Finally, enter a value of 3 in the Loop Count field. This property tells JMeter how many
times to repeat your test. To have JMeter repeatedly run your Test Plan, select the
Forever checkbox.
In most applications, you have to manually accept changes you make in a Control
Panel. However, in JMeter, the Control Panel automatically accepts your changes as
you make them. If you change the name of an element, the tree will be updated with
the new text after you leave the Control Panel (for example, when selecting another
tree element).
See Figure 7.2 for the completed JDBC Users Thread Group.
46
Jmeter 2.3.4 User’s Manual
Begin by selecting the JDBC Users element. Click your right mouse button to get the
Add menu, and then select Add --> Config Element --> JDBC Connection Configuration.
Then, select this new element to view its Control Panel (see Figure 7.3).
Set up the following fields (these assume we will be using a local MySQL database
called test):
• Variable name bound to pool. This needs to uniquely identify the configuration. It
is used by the JDBC Sampler to identify the configuration to be used.
• Database URL: jdbc:mysql://localhost:3306/test
• JDBC Driver class: com.mysql.jdbc.Driver
• Username: guest
• Password: password for guest
JMeter creates a database connection pool with the configuration settings as specified in
the Control Panel. The pool is referred to in JDBC Requests in the 'Variable Name' field.
Several different JDBC Configuration elements can be used, but they must have unique
names. Every JDBC Request must refer to a JDBC Configuration pool. More than one
JDBC Request can refer to the same pool.
47
Jmeter 2.3.4 User’s Manual
Select the JDBC Users element again. Click your right mouse button to get the Add
menu, and then select Add --> Sampler --> JDBC Request. Then, select this new element
to view its Control Panel (see Figure 7.4).
48
Jmeter 2.3.4 User’s Manual
In our Test Plan, we will make two JDBC requests. The first one is for Eastman Kodak
stock, and the second is Pfizer stock (obviously you should change these to examples
appropriate for your particular database). These are illustrated below.
JMeter sends requests in the order that you add them to the tree.
Next, add the second JDBC Request and edit the following properties (see Figure 7.6):
49
Jmeter 2.3.4 User’s Manual
Select the JDBC Users element and add a Graph Results listener (Add --> Listener -->
Graph Results).
50
Jmeter 2.3.4 User’s Manual
51
Jmeter 2.3.4 User’s Manual
This example uses the O'Reilly FTP site, www.oro.com. Please be considerate when
running this example, and (if possible) consider running against another FTP site.
Go ahead and add the ThreadGroup element by first selecting the Test Plan, clicking your
right mouse button to get the Add menu, and then select Add --> ThreadGroup.
You should now see the Thread Group element under Test Plan. If you do not see the
element, then "expand" the Test Plan tree by clicking on the Test Plan element.
Next, you need to modify the default properties. Select the Thread Group element in the
tree, if you have not already selected it. You should now see the Thread Group Control
Panel in the right section of the JMeter window (see Figure 8.1 below)
52
Jmeter 2.3.4 User’s Manual
Start by providing a more descriptive name for our Thread Group. In the name field,
enter O'Reilly Users.
In the next field, the Ramp-Up Period, leave the default value of 0 seconds. This property
tells JMeter how long to delay between starting each user. For example, if you enter a
Ramp-Up Period of 5 seconds, JMeter will finish starting all of your users by the end of
the 5 seconds. So, if we have 5 users and a 5 second Ramp-Up Period, then the delay
between starting users would be 1 second (5 users / 5 seconds = 1 user per second). If you
set the value to 0, then JMeter will immediately start all of your users.
Finally, enter a value of 2 in the Loop Count field. This property tells JMeter how many
times to repeat your test. To have JMeter repeatedly run your Test Plan, select the
Forever checkbox.
In most applications, you have to manually accept changes you make in a Control
Panel. However, in JMeter, the Control Panel automatically accepts your changes as
you make them. If you change the name of an element, the tree will be updated with
the new text after you leave the Control Panel (for example, when selecting another
tree element).
See Figure 8.2 for the completed O'Reilly Users Thread Group.
53
Jmeter 2.3.4 User’s Manual
Begin by selecting the O'Reilly Users element. Click your right mouse button to get the
Add menu, and then select Add --> Config Element --> FTP Request Defaults. Then,
select this new element to view its Control Panel (see Figure 8.3).
Like most JMeter elements, the FTP Request Defaults Control Panel has a name field that
you can modify. In this example, leave this field with the default value.
Skip to the next field, which is the FTP Server's Server Name/IP. For the Test Plan that
you are building, all FTP requests will be sent to the same FTP server, ftp.oro.com. Enter
this domain name into the field. This is the only field that we will specify a default, so
leave the remaining fields with their default values.
The FTP Request Defaults element does not tell JMeter to send an FTP request. It simply
defines the default values that the FTP Request elements use.
54
Jmeter 2.3.4 User’s Manual
See Figure 8.4 for the completed FTP Request Defaults element
JMeter sends requests in the order that they appear in the tree.
Start by adding the first FTP Request to the O'Reilly Users element (Add --> Sampler -->
FTP Request). Then, select the FTP Request element in the tree and edit the following
properties (see Figure 8.5):
You do not have to set the Server Name field because you already specified this
value in the FTP Request Defaults element.
55
Jmeter 2.3.4 User’s Manual
Figure 8.5. FTP Request for O'Reilly mSQL Java README file
Next, add the second FTP Request and edit the following properties (see Figure 8.6:
Figure 8.6. FTP Request for O'Reilly mSQL Java tutorial file
56
Jmeter 2.3.4 User’s Manual
Select the O'Reilly Users element and add a Spline Visualizer listener (Add --> Listener -
-> Spline Visualizer).
57
Jmeter 2.3.4 User’s Manual
This example assumes that the LDAP Server is installed in your Local machine.
Go ahead and add the ThreadGroup element by first selecting the Test Plan, clicking your
right mouse button to get the Add menu, and then select Add-->ThreadGroup. You
should now see the Thread Group element under Test Plan. If you do not see the element,
then "expand" the Test Plan tree by clicking on the Test Plan element.
58
Jmeter 2.3.4 User’s Manual
Like most JMeter elements, the Login Config Element Control Panel has a name field
that you can modify. In this example, leave this field with the default value.
Like most JMeter elements, the LDAP Request Defaults Control Panel has a name field
that you can modify. In this example, leave this field with the default value.
59
Jmeter 2.3.4 User’s Manual
JMeter sends requests in the order that you add them to the tree. Start by adding the first
LDAP Request to the Siptech Users element (Add --> Sampler --> LDAP Request).
Then, select the LDAP Request element in the tree and edit the following properties
60
Jmeter 2.3.4 User’s Manual
You do not have to set the Server Name field, port field, Username, Password and DN
because you already specified this value in the Login Config Element and LDAP Request
Defaults.
Next, add the second LDAP Request and edit the following properties
61
Jmeter 2.3.4 User’s Manual
62
Jmeter 2.3.4 User’s Manual
63
Jmeter 2.3.4 User’s Manual
As the Extended LDAP Sampler is highly configurable, this also means that it takes some
time to build a correct test plan. You can however tune it exactly up to your needs.
You will create four users that send requests for four tests on the LDAP server. Also, you
will tell the users to run their tests twice. So, the total number of requests is (4 users) x (4
requests) x repeat 2 times) = 32 LDAP requests. To construct the Test Plan, you will use
the following elements:
Thread Group ,
Adding LDAP Extended Request Defaults ,
Adding LDAP Requests , and
Adding a Listener to View/Store the Test Results
This example assumes that the LDAP Server is installed in your Local machine.
For the less experienced LDAP users, I build a small LDAP tutorial which shortly
explains the several LDAP operations that can be used in building a complex test plan.
Take care when using LDAP special characters in the distinguished name, in that case
(eg, you want to use a + sign in a distinguished name) you need to escape the character
by adding a "\" sign before that character.
Extra exception: if you want to add a \ character in a distinguished name (in an add or
rename operation), you need to use 4 backslashes. Examples: cn=dolf\+smits to
add/search an entry with the name like cn=dolf+smits cn=dolf \\ smits to search an entry
with the name cn=dolf \ smits cn=c:\\\\log.txt to add an entry with a name like
cn=c:\log.txt
Go ahead and add the ThreadGroup element by first selecting the Test Plan, clicking your
right mouse button to get the Add menu, and then select Add-->ThreadGroup. You
should now see the Thread Group element under Test Plan. If you do not see the element,
then "expand" the Test Plan tree by clicking on the Test Plan element.
64
Jmeter 2.3.4 User’s Manual
Like most JMeter elements, the LDAP Extended Request Defaults Control Panel has a
name field that you can modify. In this example, leave this field with the default value.
65
Jmeter 2.3.4 User’s Manual
For each of the different operations, some default values can be filled in. In All cases,
when a default is filled in, this is used for the LDAP extended requests. For each requst,
you can override the defaults by filling in the values in the LDAP extended request
sampler. When no valueis entered which is necesarry for a test, the test will fail in an
unpredictable way!
1. Thread bind
2. Search Test
3. Compare Test
4. Single bind/unbind Test
5. Add Test
6. Modify Test
7. Delete Test
8. Rename entry (moddn)
9. Thread unbind
JMeter sends requests in the order that you add them to the tree.
66
Jmeter 2.3.4 User’s Manual
LDAP Ext Request). Then, select the LDAP Ext Request element in the tree and edit the
following properties.
67
Jmeter 2.3.4 User’s Manual
68
Jmeter 2.3.4 User’s Manual
69
Jmeter 2.3.4 User’s Manual
70
Jmeter 2.3.4 User’s Manual
71
Jmeter 2.3.4 User’s Manual
72
Jmeter 2.3.4 User’s Manual
3. delete
When no value is given, all values will be removed
When a value is given, only that value will be removed
when the given value is not existing, the test will fail
5. (Optional) Add more modifications in the "modify test" table.
All modifications which are specified must succeed, to let the modification test
pass. When one modification fails, NO modifications at all will be made and the
entry will remain unchanged.
73
Jmeter 2.3.4 User’s Manual
74
Jmeter 2.3.4 User’s Manual
1. Select the "Thread unbind" button. This will be enough as it just closes the current
connection. The information which is needed is already known by the system
75
Jmeter 2.3.4 User’s Manual
76
Jmeter 2.3.4 User’s Manual
In this listener you have three tabs to view, the sampler result, the request and the
response data.
1. The sampler result just contains the response time, the returncode and return
message
2. The request gives a short description of the request that was made, in practice no
relevant information is contained here.
3. The response data contains the full details of the sent request, as well the full
details of the received answer, this is given in a (self defined) xml-style. The full
description can be found here.
77
Jmeter 2.3.4 User’s Manual
General notes on the webservices sampler. The current implementation uses Apache
SOAP driver, which requires activation.jar and mail.jar from SUN. Due to license
restrictions, JMeter does not include the jar files in the binary distribution.
If the sampler appears to be getting an error from the webservice, double check the SOAP
message and make sure the format is correct. In particular, make sure the xmlns attributes
are exactly the same as the WSDL. If the xml namespace is different, the webservice will
likely return an error. Xmethods contains a list of public webservice for those who want
to test their test plan.
Go ahead and add the ThreadGroup element by first selecting the Test Plan, clicking your
right mouse button to get the Add menu, and then select Add --> ThreadGroup.
You should now see the Thread Group element under Test Plan. If you do not see the
element, then "expand" the Test Plan tree by clicking on the Test Plan element.
Next, you need to modify the default properties. Select the Thread Group element in the
tree, if you have not already selected it. You should now see the Thread Group Control
Panel in the right section of the JMeter window (see Figure 11.1 below)
78
Jmeter 2.3.4 User’s Manual
Start by providing a more descriptive name for our Thread Group. In the name field,
enter Jakarta Users.
In the next field, the Ramp-Up Period, leave the default value of 0 seconds. This property
tells JMeter how long to delay between starting each user. For example, if you enter a
Ramp-Up Period of 5 seconds, JMeter will finish starting all of your users by the end of
the 5 seconds. So, if we have 5 users and a 5 second Ramp-Up Period, then the delay
between starting users would be 1 second (5 users / 5 seconds = 1 user per second). If you
set the value to 0, then JMeter will immediately start all of your users.
Finally, clear the checkbox labeled "Forever", and enter a value of 2 in the Loop Count
field. This property tells JMeter how many times to repeat your test. If you enter a loop
count value of 0, then JMeter will run your test only once. To have JMeter repeatedly run
your Test Plan, select the Forever checkbox.
In most applications, you have to manually accept changes you make in a Control
Panel. However, in JMeter, the Control Panel automatically accepts your changes as
you make them. If you change the name of an element, the tree will be updated with
the new text after you leave the Control Panel (for example, when selecting another
tree element).
See Figure 11.2 for the completed Jakarta Users Thread Group.
79
Jmeter 2.3.4 User’s Manual
JMeter sends requests in the order that they appear in the tree.
Start by adding the sampler WebService(SOAP) Request (Beta Code) to the Jakarta
Users element (Add --> Sampler --> WebService(SOAP) Request (Beta Code) ). Then,
select the webservice Request element in the tree and edit the following properties (see
Figure 11.5):
80
Jmeter 2.3.4 User’s Manual
81
If the WSDL file was loaded correctly, the "Web Methods" drop down should be
populated. If the drop down remains blank, it means there was a problem getting the
WSDL. You can test the WSDL using a browser that reads XML. For example, if you're
testing an IIS webservice the URL will look like this:
http://localhost/myWebService/Service.asmx?WSDL. At this point, SOAPAction, URL
and SOAP Data should be blank.
Next, select the web method and click "Configure". The sampler should populate the
"URL" and "SOAPAction" text fields. Assuming the WSDL is valid, the correct soap
action should be entered.
The last step is to paste the SOAP message in the "SOAP/XML-RPC Data" text area.
You can optionally save the soap message to a file and browse to the location. For
convienance, there is a third option of using a message folder. The sampler will randomly
select files from a given folder and use the text for the soap message.
If you do not want JMeter to read the response from the SOAP Webservice, uncheck
"Read Soap Responses." If the test plan is intended to stress test a webservice, the box
should be unchecked. If the test plan is a functional test, the box should be checked.
When "Read Soap Responses" is unchecked, no result will be displayed in view result
tree or view results in table.
An important note on the sampler. It will automatically use the proxy host and port
passed to JMeter from command line, if those fields in the sampler are left blank. If a
sampler has values in the proxy host and port text field, it will use the ones provided by
the user. If no host or port are provided and JMeter wasn't started with command line
options, the sampler will fail silently. This behavior may not be what users expect.
Note: If you're using Cassini webserver, it does not work correctly and is not a reliable
webserver. Cassini is meant to be a simple example and isn't a full blown webserver like
IIS. Cassini does not close connections correctly, which causes JMeter to hang or not get
the response contents.
Currently, only .NET uses SOAPAction, so it is normal to have a blank SOAPAction for
all other webservices. The list includes JWSDP, Weblogic, Axis, The Mind Electric
Glue, and gSoap.
Select the Jakarta Users element and add a Graph Results listener (Add --> Listener -->
Graph Results). Next, you need to specify a directory and filename of the output file. You
82
Jmeter 2.3.4 User’s Manual
can either type it into the filename field, or select the Browse button and browse to a
directory and then enter a filename.
83
Jmeter 2.3.4 User’s Manual
In this section, you will learn how to create a Test Plan to test a JMS Point-to-Point
messaging solution. The setup of the test is 1 threadgroup with 5 threads sending 4
messages each through a request queue. A fixed reply queue will be used for monitoring
the reply messages. To construct the Test Plan, you will use the following elements:
Thread Group , JMS Point-to-Point , and Graph Results .
General notes on JMS: There are currently two JMS samplers. One uses JMS topics and
the other uses queues. Topic messages are commonly known as pub/sub messaging.
Topic messaging is generally used in cases where a message is published by a producer
and consumed by multiple subscribers. A JMS sampler needs the JMS implementation jar
files; for example, from Apache ActiveMQ. See here for the list of jars provided by
ActiveMQ 3.0.
Go ahead and add the ThreadGroup element by first selecting the Test Plan, clicking your
right mouse button to get the Add menu, and then select Add --> ThreadGroup.
You should now see the Thread Group element under Test Plan. If you do not see the
element, then "expand" the Test Plan tree by clicking on the Test Plan element.
Next, you need to modify the default properties. Select the Thread Group element in the
tree, if you have not already selected it. You should now see the Thread Group Control
Panel in the right section of the JMeter window (see Figure 12.1 below)
84
Jmeter 2.3.4 User’s Manual
Start by providing a more descriptive name for our Thread Group. In the name field,
enter Point-to-Point.
In the next field, the Ramp-Up Period, leave set the value to 0 seconds. This property
tells JMeter how long to delay between starting each user. For example, if you enter a
Ramp-Up Period of 5 seconds, JMeter will finish starting all of your users by the end of
the 5 seconds. So, if we have 5 users and a 5 second Ramp-Up Period, then the delay
between starting users would be 1 second (5 users / 5 seconds = 1 user per second). If you
set the value to 0, then JMeter will immediately start all of your users.
Clear the checkbox labeled "Forever", and enter a value of 4 in the Loop Count field.
This property tells JMeter how many times to repeat your test. If you enter a loop count
value of 0, then JMeter will run your test only once. To have JMeter repeatedly run your
Test Plan, select the Forever checkbox.
In most applications, you have to manually accept changes you make in a Control
Panel. However, in JMeter, the Control Panel automatically accepts your changes as
you make them. If you change the name of an element, the tree will be updated with
the new text after you leave the Control Panel (for example, when selecting another
tree element).
85
Jmeter 2.3.4 User’s Manual
86
Jmeter 2.3.4 User’s Manual
Select the Thread Group element and add a Graph Results listener (Add --> Listener -->
Graph Results). Next, you need to specify a directory and filename of the output file. You
can either type it into the filename field, or select the Browse button and browse to a
directory and then enter a filename.
87
Jmeter 2.3.4 User’s Manual
In this section, you will learn how to create a Test Plan to test JMS Providers. You will
create five subscribers and one publisher. You will create 2 thread groups and set each
one to 10 iterations. The total messages is (6 threads) x (1 message) x (repeat 10 times) =
60 messages. To construct the Test Plan, you will use the following elements: Thread
Group , JMS Publisher , JMS Subscriber , and Graph Results .
General notes on JMS: There are currently two JMS samplers. One uses JMS topics and
the other uses queues. Topic messages are commonly known as pub/sub messaging.
Topic messaging is generally used in cases where a message is published by a producer
and consumed by multiple subscribers. Queue messaging is generally used for
transactions where the sender expects a response. Messaging systems are quite different
from normal HTTP requests. In HTTP, a single user sends a request and gets a response.
Messaging system can work in sychronous and asynchronous mode. A JMS sampler
needs the JMS implementation jar files; for example, from Apache ActiveMQ. See here
for the list of jars provided by ActiveMQ 3.0.
Go ahead and add the ThreadGroup element by first selecting the Test Plan, clicking your
right mouse button to get the Add menu, and then select Add --> ThreadGroup.
You should now see the Thread Group element under Test Plan. If you do not see the
element, then "expand" the Test Plan tree by clicking on the Test Plan element.
Next, you need to modify the default properties. Select the Thread Group element in the
tree, if you have not already selected it. You should now see the Thread Group Control
Panel in the right section of the JMeter window (see Figure 13.1 below)
88
Jmeter 2.3.4 User’s Manual
Start by providing a more descriptive name for our Thread Group. In the name field,
enter Subscribers.
In the next field, the Ramp-Up Period, set the value to 0 seconds. This property tells
JMeter how long to delay between starting each user. For example, if you enter a Ramp-
Up Period of 5 seconds, JMeter will finish starting all of your users by the end of the 5
seconds. So, if we have 5 users and a 5 second Ramp-Up Period, then the delay between
starting users would be 1 second (5 users / 5 seconds = 1 user per second). If you set the
value to 0, JMeter will immediately start all users.
Clear the checkbox labeled "Forever", and enter a value of 10 in the Loop Count field.
This property tells JMeter how many times to repeat your test. If you enter a loop count
value of 0, then JMeter will run your test only once. To have JMeter repeatedly run your
Test Plan, select the Forever checkbox.
Repeat the process and add another thread group. For the second thread group, enter
"Publisher" in the name field, set the number of threads to 1, and set the iteration to 10.
In most applications, you have to manually accept changes you make in a Control
Panel. However, in JMeter, the Control Panel automatically accepts your changes as
you make them. If you change the name of an element, the tree will be updated with
the new text after you leave the Control Panel (for example, when selecting another
tree element).
89
Jmeter 2.3.4 User’s Manual
Start by adding the sampler JMS Subscriber to the Subscribers element (Add --> Sampler
--> JMS Subscriber). Then, select the JMS Subscriber element in the tree and edit the
following properties:
2. If the JMS provider uses the jndi.properties file, check the box
4. Enter the provider URL. This is the URL for the JNDI server, if there is one
5. Enter the name of the connection factory. Please refer to the documentation of the
JMS provider for the information
7. If the JMS provider requires authentication, check "required" and enter the
username and password. For example, Orion JMS requires authentication, while
ActiveMQ and MQSeries does not
10. There are two client implementations for subscribers. If the JMS provider exhibits
zombie threads with one client, try the other.
90
Jmeter 2.3.4 User’s Manual
Next add the sampler JMS Publisher to the Publisher element (Add --> Sampler --> JMS
Subscriber). Then, select the JMS Publisher element in the tree and edit the following
properties:
91
Jmeter 2.3.4 User’s Manual
92
Jmeter 2.3.4 User’s Manual
Select the Test Plan element and add a Graph Results listener (Add --> Listener -->
Graph Results). Next, you need to specify a directory and filename of the output file. You
can either type it into the filename field, or select the Browse button and browse to a
directory and then enter a filename.
93
Jmeter 2.3.4 User’s Manual
For those who want to use the monitor with other servlet or EJB containers, Tomcat's
status servlet should work with other containers for the memory statistics without any
modifications. To get thread information, you will need to change the MBeanServer
lookup to retrieve the correct MBeans.
Go ahead and add the ThreadGroup element by first selecting the Test Plan, clicking your
right mouse button to get the Add menu, and then select Add --> ThreadGroup.
You should now see the Thread Group element under Test Plan. If you do not see the
element, "expand" the Test Plan tree by clicking on the Test Plan element.
94
Jmeter 2.3.4 User’s Manual
Change the loop count to forever (or some large number) so that enough samples are
generated.
Select the thread group element and add a Simple Data Writer listener (Add --> Listener -
-> Simple Data Writer). Next, you need to specify a directory and filename of the output
file. You can either type it into the filename field, or select the Browse button and browse
to a directory and then enter a filename.
95
Jmeter 2.3.4 User’s Manual
There are two tabs in the monitor results listener. The first is the "Health", which displays
the status of the last sample the monitor received. The second tab is "Performance",
which shows a historical view of the server's performance.
A quick note about how health is calculated. Typically, a server will crash if it runs out of
memory, or reached the maximum number of threads. In the case of Tomcat 5, once the
threads are maxed out, requests are placed in a queue until a thread is available. The
relative importance of threads vary between containers, so the current implementation
uses 50/50 to be conservative. A container that is more efficient with thread management
might not see any performance degradation, but the used memory definitely will show an
impact.
96
Jmeter 2.3.4 User’s Manual
The performance graph shows for different lines. The free memory line shows how much
free memory is left in the current allocated block. Tomcat 5 returns the maximum
memory, but it is not graphed. In a well tuned environment, the server should never reach
the maximum memory.
Note the graph has captions on both sides of the graph. On the left is percent and the right
is dead/healthy. If the memory line spikes up and down rapidly, it could indicate memory
thrashing. In those situations, it is a good idea to profile the application with Borland
OptimizeIt or JProbe. What you want to see is a regular pattern for load, memory and
threads. Any erratic behavior usually indicates poor performance or a bug of some sort.
97
Jmeter 2.3.4 User’s Manual
Different listeners display the response information in different ways. However, they
all write the same raw data to the output file - if one is specified.
The "Configure" button can be used to specify which fields to write to the file, and
whether to write it as CSV or XML. CSV files are much smaller than XML files, so use
CSV if you are generating lots of samples.
If you only wish to record certain samples, add the Listener as a child of the sampler. Or
you can use a Simple Controller to group a set of samplers, and add the Listener to that.
The same filename can be used by multiple samplers - but make sure they all use the
same configuration!
jmeter.save.saveservice.output_format=
The following example indicates how to set properties to get a vertical bar ("|") delimited
format that will output results like:.
timeStamp|time|label|responseCode|threadName|dataType|success|failureMessage
02/06/03 08:21:42|1187|Home|200|Thread Group-1|text|true|
02/06/03 08:21:42|47|Login|200|Thread Group-1|text|false|Test Failed:
98
Jmeter 2.3.4 User’s Manual
The corresponding jmeter.properties that need to be set are shown below. One oddity in
this example is that the output_format is set to csv, which typically indicates comma-
separated values. However, the default_delimiter was set to be a vertical bar instead of a
comma, so the csv tag is a misnomer in this case. (Think of CSV as meaning character
separated values)
jmeter.save.saveservice.output_format=csv
jmeter.save.saveservice.assertion_results_failure_message=true
jmeter.save.saveservice.default_delimiter=|
The full set of properties that affect result file output is shown below.
#---------------------------------------------------------------------------
# Results file configuration
#---------------------------------------------------------------------------
# legitimate values: xml, csv, db. Only xml and csv are currently supported.
#jmeter.save.saveservice.output_format=xml
99
Jmeter 2.3.4 User’s Manual
#jmeter.save.saveservice.filename=false
#jmeter.save.saveservice.hostname=false
#jmeter.save.saveservice.thread_counts=false
#jmeter.save.saveservice.sample_count=false
# Timestamp format
# legitimate values: none, ms, or a format suitable for SimpleDateFormat
#jmeter.save.saveservice.timestamp_format=ms
#jmeter.save.saveservice.timestamp_format=MM/dd/yy HH:mm:ss
#jmeter.save.saveservice.print_field_names=false
# Optional list of JMeter variable names whose values are to be saved in the result data files.
# Use commas to separate the names. For example:
#sample_variables=SESSION_ID,REFERENCE
# N.B. The current implementation saves the values in XML as attributes,
# so the names must be valid XML names.
# Versions of JMeter after 2.3.2 send the variable to all servers
# to ensure that the correct data is available at the client.
Versions of JMeter after 2.3.1 allow one to use the sample_variables property to define a
list of additional JMeter variables which are to be saved with each sample in the JTL
files. The values are written to CSV files as additional columns, and as additional
attributes in XML files. See above for an example.
100
Jmeter 2.3.4 User’s Manual
Listeners can be configured to save different items to the result log files (JTL) by using
the Config popup as shown below. The defaults are defined as described in the Listener
Default Configuration section above. Items with (CSV) after the name only apply to the
CSV format; items with (XML) only apply to XML format. CSV format cannot currently
be used to save any items that include line-breaks.
Configuration dialogue
Note that cookies, method and the query string are saved as part of the "Sampler Data"
option.
This feature can be used to specify different data and log files for each test run, for
example:
Note that JMeter logging messages are written to the file jmeter.log by default. This file
is recreated each time, so if you want to keep the log files for each run, you will need to
rename it using the -j option as above. The -j option was added in version 2.3.
101
Jmeter 2.3.4 User’s Manual
Versions of JMeter after 2.3.1 support variables in the log file name. If the filename
contains paired single-quotes, then the name is processed as a SimpleDateFormat format
applied to the current date, for example: log_file='jmeter_'yyyyMMddHHmmss'.tmp' .
This can be used to generate a unique name for each test run.
To minimise the amount of memory needed, use the Simple Data Writer, and use the
CSV format.
102
Jmeter 2.3.4 User’s Manual
103
Jmeter 2.3.4 User’s Manual
font-size: 95%;
font-family: Arial, Geneva, Helvetica, sans-serif;
color: black;
background-color: white;
}
...
</responseData>
<cookies class="java.lang.String"></cookies>
<method class="java.lang.String">GET</method>
<queryString class="java.lang.String"></queryString>
<url>http://www.apache.org/style/style.css</url>
</httpSample>
<httpSample t="200" lt="180" ts="1144371015641" s="true"
lb="http://www.apache.org/images/asf_logo_wide.gif"
rc="200" rm="OK" tn="Listen 1-1" dt="bin" de="ISO-8859-1" by="5866">
<responseHeader class="java.lang.String">HTTP/1.1 200 OK
Date: Fri, 07 Apr 2006 00:50:14 GMT
...
Content-Type: image/gif
</responseHeader>
<requestHeader class="java.lang.String">MyHeader: MyValue</requestHeader>
<responseData class="java.lang.String">http://www.apache.org/asf.gif</responseData>
<responseFile class="java.lang.String">Mixed1.html</responseFile>
<cookies class="java.lang.String"></cookies>
<method class="java.lang.String">GET</method>
<queryString class="java.lang.String"></queryString>
<url>http://www.apache.org/asf.gif</url>
</httpSample>
<responseHeader class="java.lang.String">HTTP/1.1 200 OK
Date: Fri, 07 Apr 2006 00:50:13 GMT
...
Content-Type: text/html; charset=ISO-8859-1
</responseHeader>
<requestHeader class="java.lang.String">MyHeader: MyValue</requestHeader>
<responseData class="java.lang.String">
...
<html>
<head>
...
</head>
<body>
...
</body>
</html>
</responseData>
<cookies class="java.lang.String"></cookies>
<method class="java.lang.String">GET</method>
<queryString class="java.lang.String"></queryString>
<url>http://www.apache.org/</url>
</httpSample>
-- nonHTTPP Sample
104
Jmeter 2.3.4 User’s Manual
<requestHeader class="java.lang.String"></requestHeader>
<responseData class="java.lang.String">Listen 1-1</responseData>
<responseFile class="java.lang.String">Mixed2.unknown</responseFile>
<samplerData class="java.lang.String">ssssss</samplerData>
</sample>
</testResults>
Note that the sample node name may be either "sample" or "httpSample".
Attribute Content
by Bytes
de Data encoding
dt Data type
ec Error count (0 or 1, unless multiple samples are aggregated)
hn Hostname where the sample was generated
lb Label
lt Latency = time to initial response (milliseconds) - not all samplers support this
na Number of active threads for all thread groups
ng Number of active threads in this group
rc Response Code (e.g. 200)
rm Response Message (e.g. OK)
s Success flag (true/false)
sc Sample count (1, unless multiple samples are aggregated)
t Elapsed time (milliseconds)
tn Thread Name
ts timeStamp (milliseconds since midnight Jan 1, 1970 UTC)
varname Value of the named variable (versions of JMeter after 2.3.1)
Versions 2.1 and 2.1.1 of JMeter saved the Response Code as "rs", but read it back
expecting to find "rc". This has been corrected so that it is always saved as "rc"; either
"rc" or "rs" can be read.
Versions of JMeter after 2.3.1 allow additional variables to be saved with the test
plan. Currently, the variables are saved as additional attributes. The testplan variable
name is used as the attribute name. See Sample variables (above) for more
information.
105
Jmeter 2.3.4 User’s Manual
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 were saved. In order to
interpret a header-less CSV file correctly, the appropriate JMeter properties must
be set.
Versions of JMeter up to 2.3.2 used to clear any current data before loading the new
file. This is no longer done, thus allowing files to be merged. If the previous
behaviour is required, use the menu item Run/Clear (Ctrl+Shift+E) or Run/Clear All
(Ctrl+E) before loading the file.
The Listeners which generate output as tables can also be saved using Copy/Paste. Select
the desired cells in the table, and use the OS Copy short-cut (normally Control+C). The
data will be saved to the clipboard, from where it can be pasted into another application,
e.g. a spreadsheet or text editor.
106
Jmeter 2.3.4 User’s Manual
107
Jmeter 2.3.4 User’s Manual
However, remote mode does use more resources than running the same number of non-
GUI tests independently. If many server instances are used, the client JMeter can become
overloaded, as can the client network connection.
Note that while you can execute the JMeterEngine on your application server, you need
to be mindful of the fact that this will be adding processing overhead on the application
server and thus your testing results will be somewhat tainted. The recommended
approach is to have one or more machines on the same Ethernet segment as your
application server that you configure to run the JMeter Engine. This will minimize the
impact of the network on the test results without impacting the performance of the
application serer itself.
To run JMeter in remote node, start the JMeter server component on all machines you
wish to run on by running the JMETER_HOME/bin/jmeter-server (unix) or
JMETER_HOME/bin/jmeter-server.bat (windows) script.
Note that there can only be one JMeter server on each node unless different RMI ports
are used.
Since JMeter 2.3.1, the JMeter server application starts the RMI registry itself; there is no
need to start RMI registry separately. To revert to the previous behaviour, define the
JMeter property server.rmi.create=false on the server host systems.
By default, RMI uses a dynamic port for the JMeter server engine. This can cause
problems for firewalls, so versions of JMeter after 2.3.2 will check for the JMeter
property server.rmi.localport . If this is non-zero, it will be used as the local port
number for the server engine.
108
Jmeter 2.3.4 User’s Manual
Edit the properties file on the controlling JMeter machine . In /bin/jmeter.properties, find
the property named, "remote_hosts", and add the value of your running JMeter server's IP
address. Multiple such servers can be added, comma-delimited.
Note that you can use the -R command line option instead to specify the remote host(s) to
use. This has the same effect as using -r and -Jremote_hosts={serverlist}. E.g. jmeter -
Rhost1,127.0.0.1,host2
If you define the JMeter property server.exitaftertest=true, then the server will exit after it
runs a single test. See also the -X flag (described below)
Now you are ready to start the controlling JMeter client. For MS-Windows, start the
client with the script "bin/jmeter.bat". For UNIX, use the script "bin/jmeter". You will
notice that the Run menu contains two new sub-menus: "Remote Start" and "Remote
Stop" (see figure 1). These menus contain the client that you set in the properties file. Use
the remote start and stop instead of the normal JMeter start and stop menu items.
As an alternative, you can start the remote server(s) from a non-GUI (command-line)
client. The command to do this is:
jmeter -n -t script.jmx -r
or
jmeter -n -t script.jmx -R server1,server2...
The first example will start whatever servers are defined in the JMeter property
remote_hosts; the second example will define remote_hosts from the list of servers and
then run the remote servers.
The command-line client will exit when all the remote servers have stopped.
109
Jmeter 2.3.4 User’s Manual
Since JMeter 2.3.1, the RMI registry is started by the JMeter server, so this section does
not apply in the normal case. To revert to the previous behaviour, define the JMeter
property server.rmi.create=false on the server host systems and follow the instructions
below.
JMeter uses Remote Method Invocation (RMI) as the remote communication mechanism.
Therefore, you need to run the RMI Registry application (which is named, "rmiregistry")
that comes with the JDK and is located in the "bin" directory. Before running rmiregistry,
make sure that the following jars are in your system claspath:
• JMETER_HOME/lib/ext/ApacheJMeter_core.jar
• JMETER_HOME/lib/jorphan.jar
• JMETER_HOME/lib/logkit-1.2.jar
The rmiregistry application needs access to certain JMeter classes. Run rmiregistry with
no parameters. By default the application listens to port 1099.
Once the RMI Registry application is running, start the JMeter Server. Use the "-s"
option with the jmeter startup script ("jmeter -s").
16.2 Tips
JMeter/RMI requires a connection from the client to the server. This will use the port you
chose, default 1099. JMeter/RMI also requires a reverse connection in order to return
sample results from the server to the client. This will use a high-numbered port. If there
are any firewalls or other network filters between JMeter client and server, you will need
to make sure that they are set up to allow the connections through. If necessary, use
monitoring software to show what traffic is being generated.
If you're running Suse Linux, these tips may help. The default installation may enable the
firewall. In that case, remote testing will not work properly. The following tips were
contributed by Sergey Ten.
If you see connections refused, turn on debugging by passing the following options.
110
Jmeter 2.3.4 User’s Manual
Since JMeter 2.3.1, the RMI registry is started by the server; however the options can still
be passed in from the JMeter command line. For example: "jmeter -s -
Dsun.rmi.loader.logLevel=verbose" (i.e. omit the -J prefixes). Alternatively the
properties can be defined in the system.properties file.
The solution to the problem is to remove the loopbacks 127.0.0.1 and 127.0.0.2 from
etc/hosts. What happens is jmeter-server can't connect to rmiregistry if 127.0.0.2
loopback is not available. Use the following settings to fix the problem.
Replace
With
• HOST="-Djava.rmi.server.hostname=[computer_name][computer_domain]
• -Djava.security.policy=`dirname $0`/[policy_file]"
• `dirname $0`/jmeter $HOST -s "$@"
Since Jmeter 2.1.1, the jmeter-server scripts provide support for changing the port. For
example, assume you want to use port 1664 (perhaps 1099 is already used).
On Unix:
$ SERVER_PORT=1664 jmeter-server [other options]
[N.B. use upper case for the environment variable]
In both cases, the script starts rmiregistry on the specified port, and then starts JMeter in
server mode, having defined the "server_port" property.
111
Jmeter 2.3.4 User’s Manual
The chosen port will be logged in the server jmeter.log file (rmiregistry does not create a
log file).
112
Jmeter 2.3.4 User’s Manual
The Proxy Server expects to find a ThreadGroup element with a Recording Controller
under it where it will record HTTP Requests to. This conveniently packages all your
samples under one controller, which can be given a name that describes the test case.
Now, go through the steps of a Test Case. If you have no pre-defined test cases, use
JMeter to record your actions to define your test cases. Once you have finished a definite
series of steps, save the entire test case in an appropriately named file. Then, wipe clean
and start a new test case. By doing this, you can quickly record a large number of test
case "rough drafts".
One of the most useful features of the Proxy Server is that you can abstract out certain
common elements from the recorded samples. By defining some user-defined variables at
113
Jmeter 2.3.4 User’s Manual
the Test Plan level or in User Defined Variables elements, you can have JMeter
automatically replace values in you recorded samples. For instance, if you are testing an
app on server "xxx.example.com", then you can define a variable called "server" with the
value of "xxx.example.com", and anyplace that value is found in your recorded samples
will be replaced with "${server}".
If JMeter does not record any samples, check that the brower really is using the proxy. If
the browser works OK even if JMeter is not running, then the browser cannot be using
the proxy. Some browsers ignore proxy settings for localhost or 127.0.0.1; try using the
local hostname or IP instead.
For example:
• Create a text file containing the user names and passwords, separated by commas.
Put this in the same directory as your test plan.
• Add a CSV DataSet configuration element to the test plan. Name the variables
USER and PASS.
• Replace the login name with ${USER} and the password with ${PASS} on the
appropriate samplers
The CSV Data Set element will read a new line for each thread.
114
Jmeter 2.3.4 User’s Manual
If your test needs large amounts of data - particularly if it needs to be randomised - create
the test data in a file that can be read with CSV Dataset. This avoids wasting resources at
run-time.
There is no security. Anyone who can connect to the port can issue any BeanShell
commands. These can provide unrestricted access to the JMeter application and the
host. Do not enable the server unless the ports are protected against access, e.g. by
a firewall.
beanshell.server.port=9000
beanshell.server.file=../extras/startup.bsh
In the above example, the server will be started, and will listen on ports 9000 and 9001.
Port 9000 will be used for http access. Port 9001 will be used for telnet access. The
startup.bsh file will be processed by the server, and can be used to define various
functions and set up variables. The startup file defines methods for setting and printing
JMeter and system properties. This is what you should see in the JMeter console:
As a practical example, assume you have a long-running JMeter test running in non-GUI
mode, and you want to vary the throughput at various times during the test. The test-plan
includes a Constant Throughput Timer which is defined in terms of a property, e.g.
${__P(throughput)}. The following BeanShell commands could be used to change the
test:
printprop("throughput");
curr=Integer.decode(args[0]); // Start value
inc=Integer.decode(args[1]); // Increment
end=Integer.decode(args[2]); // Final value
secs=Integer.decode(args[3]); // Wait between changes
while(curr <= end){
setprop("throughput",curr.toString()); // Needs to be a string here
Thread.sleep(secs*1000);
115
Jmeter 2.3.4 User’s Manual
curr += inc;
}
printprop("throughput");
The script can be stored in a file (throughput.bsh, say), and sent to the server using
bshclient.jar. For example:
Each BeanShell test element has its own copy of the interpreter (for each thread). If the
test element is repeatedly called, e.g. within a loop, then the interpreter is retained
between invocations unless the "Reset bsh.Interpreter before each call" option is selected.
Some long-running tests may cause the interpreter to use lots of memory; if this is the
case try using the reset option.
You can test BeanShell scripts outside JMeter by using the command-line interpreter:
Variables can be defined in startup (initialisation) scripts. These will be retained across
invocations of the test element, unless the reset option is used.\
Scripts can also access JMeter variables using the get() and put() methods of the "vars"
variable, for example: vars.get("HOST"); vars.put("MSG","Successful"); . The
get() and put() methods only support variables with String values, but there are also
getObject() and putObject() methods which can be used for arbitrary objects. JMeter
variables are local to a thread, but can be used by all test elements (not just Beanshell).
If you need to share variables between threads, then JMeter properties can be used:
import org.apache.jmeter.util.JMeterUtils;
116
Jmeter 2.3.4 User’s Manual
String value=JMeterUtils.getPropDefault("name","");
JMeterUtils.setProperty("name", "value");
The sample .bshrc files contain sample definitions of getprop() and setprop() methods.
if (bsh.shared.myObj == void){
// not yet defined, so create it:
myObj=new AnyObject();
}
bsh.shared.myObj.process();
Rather than creating the object in the test element, it can be created in the startup file
defined by the JMeter property "beanshell.init.file". This is only processed once.
Create a simple Test Plan containing the BSF Sampler and Tree View Listener. Code the
script in the sampler script pane, and test it by running the test. If there are any errors,
these will show up in the Tree View. Also the result of running the script will show up as
the response.
Once the script is working properly, it can be stored as a variable on the Test Plan. The
script variable can then be used to create the function call. For example, suppose a
BeanShell script is stored in the variable RANDOM_NAME. The function call can then
be coded as ${__BeanShell(${RANDOM_NAME})} . There is no need to escape any
commas in the script, because the function call is parsed before the variable's value is
interpolated.
One way to do this is to define a set of variables on the Test Plan, and then use those
variables in the test elements. For example, one could define the variable LOOPS=10,
and refer to that in the Thread Group as ${LOOPS}. To run the test with 20 loops, just
change the value of the LOOPS variable on the Test Plan.
This quickly becomes tedious if you want to run lots of tests in non-GUI mode. One
solution to this is to define the Test Plan variable in terms of a property, for example
LOOPS=${__P(loops,10))} . This uses the value of the property "loops", defaulting to
117
Jmeter 2.3.4 User’s Manual
10 if the property is not found. The "loops" property can then be defined on the JMeter
command-line: jmeter ... -Jloops=12 ... . If there are a lot of properties that need
to be changed together, then one way to achieve this is to use a set of property files. The
appropriate property file can be passed in to JMeter using the -q command-line option.
118
Jmeter 2.3.4 User’s Manual
When is a good time to load-test our application (i.e. off-hours or week-ends), bearing in
mind that this may very well crash one or more of our servers?
Does our application have state? If so, how does our application manage it (cookies,
session-rewriting, or some other method)?
18.2 Resources
The following resources will prove very helpful. Bear in mind that if you cannot locate
these resources, you will become these resources. As you already have your work cut out
for you, it is worth knowing who the following people are, so that you can ask them for
help if you need it.
18.2.1 Network
Who knows our network topology? If you run into any firewall or proxy issues, this will
become very important. As well, a private testing network (which will therefore have
very low network latency) would be a very nice thing. Knowing who can set one up for
you (if you feel that this is necessary) will be very useful. If the application doesn't scale
as expected, who can add additional hardware?
18.2.2 Application
119
Jmeter 2.3.4 User’s Manual
The test process may progress from black-box testing to white-box testing (the difference
is that the first requires no knowledge of the application [it is treated as a "black box"]
while the second requires some knowledge of the application). It is not uncommon to
discover problems with the application during this process, so be prepared to defend your
work.
For Windows, Windows XP Professional should be a minimum (the others do not multi-
thread past 50-60 connections, and you probably anticipate more users than that).
Good free platforms include the linuxes, the BSDs, and Solaris Intel. If you have a little
more money, there are commercial linuxes. If you can justify it, a commercial Unix
(Solaris, etc) is probably the best choice.
Don't forget JMeter batch mode. This can be useful if you have a powerful server that
supports Java but perhaps does not have a fast graphics implementation, or where you
need to login remotely. Batch (non-GUI) mode can reduce the network traffic compared
with using a remote display or client-server mode. The batch log file can then be loaded
into JMeter on a workstation for analysis, or you can use CSV output and import the data
into a spreadsheet.
18.4 Tools
The following tools will all prove useful. It is definitely worthwhile to become familiar
with them. This should include trying them out, and reading the appropriate
documentation (man-pages, info-files, application --help messages, and any supplied
documentation).
120
Jmeter 2.3.4 User’s Manual
18.4.1 ping
This can be used to establish whether or not you can reach your target site. Options can
be specified so that 'ping' provides the same type of route reporting as 'traceroute'.
18.4.2 nslookup/dig
While the user will normally use a human-readable internet address, you may wish to
avoid the overhead of DNS lookups when performing benchmarking/load-testing. These
can be used to determine the unique address (dotted quad) of your target site.
18.4.3 traceroute
If you cannot "ping" your target site, this may be used to determine the problem (possibly
a firewall or a proxy). It can also be used to estimate the overall network latency (running
locally should give the lowest possible network latency - remember that your users will
be running over a possibly busy internet). Generally, the fewer hops the better.
18.5.2 HttpUnit
This is worth a look. It is a library (and therefore of more interest to developers) that can
be used to perform HTTP tests/benchmarks. It is intended to be used instead of a web
browser (therefore no GUI) in conjunction with JUnit.
121
Jmeter 2.3.4 User’s Manual
18.5.4 JMeter
If you have non-standard requirements, then this solution offers an open-source
community to provide them (of course, if you are reading this , you are probably already
committed to this one). This product is free to evolve along with your requirements.
Well, Perl might be a very good choice except that the Benchmark package seems to give
fairly fuzzy results. Also, simulating multiple users with Perl is a tricky proposition
(multiple connections can be simulated by forking many processes from a shell script, but
these will not be threads, they will be processes). However, the Perl community is very
large. If you find that someone has already written something that seems useful, this
could be a very good solution.
C, of course, is a very good choice (check out the Apache ab tool). But be prepared to
write all of the custom networking, threading, and state management code that you will
need to benchmark your application.
Java gives you (for free) the custom networking, threading, and state management code
that you will need to benchmark your application. Java is aware of HTTP, FTP, and
HTTPS - as well as RMI, IIOP, and JDBC (not to mention cookies, URL-encoding, and
URL-rewriting). In addition Java gives you automatic garbage-collection, and byte-code
level security.
And once Microsoft moves to a CLR (common language run-time) a Windows Java
solution will not be any slower than any other type of solution on the Windows platform.
122
Jmeter 2.3.4 User’s Manual
Latency is set to the time it takes to login (versions of JMeter after 2.3.1).
Control Panel
Parameters
123
Jmeter 2.3.4 User’s Manual
See Also:
• Assertions
• FTP Request Defaults
• Building an FTP Test Plan
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
• external scripts
• frames
• background images (body, table, TD, TR)
• background sound
The default parser is htmlparser. This can be changed by using the property
"htmlparser.classname" - see jmeter.properties for details.
124
Jmeter 2.3.4 User’s Manual
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
Proxy Server to create them. This can save you time if you have a lot of HTTP requests
or requests with many parameters.
Note: the FILE protocol is intended for testing puposes only. It is handled by the same
code regardless of which HTTP Sampler is used.
If the request requires server or proxy login authorization (i.e. where a browser would
create a pop-up dialog box), you will also have to add an HTTP Authorization Manager
Configuration Element. For normal logins (i.e. where the user enters login information in
a form), you will need to work out what the form submit button does, and create an
HTTP request with the appropriate method (usually POST) and the appropriate
parameters from the form definition. If the page uses HTTP, you can use the JMeter
Proxy to capture the login sequence.
In versions of JMeter up to 2.2, only a single SSL context was used for all threads and
samplers. This did not generate the proper load for multiple users. A separate SSL
context is now used for each thread. To revert to the original behaviour, set the JMeter
property:
https.sessioncontext.shared=true
JMeter defaults to the SSL protocol level TLS. If the server needs a different level, e.g.
SSLv3, change the JMeter property, for example:
125
Jmeter 2.3.4 User’s Manual
https.default.protocol=SSLv3
JMeter also allows one to enable additional protocols, by changing the property
https.socket.protocols .
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.
If the request uses a technique called "URL Rewriting" to maintain sessions, then see
section 6.1 Handling User Sessions With URL Rewriting for additional configuration
steps.
Control Panel
126
Jmeter 2.3.4 User’s Manual
Parameters
127
Jmeter 2.3.4 User’s Manual
128
Jmeter 2.3.4 User’s Manual
129
Jmeter 2.3.4 User’s Manual
N.B. when using Automatic Redirection, cookies are only sent for the initial URL. This
can cause unexpected behaviour for web-sites that redirect to a local server. E.g. if
www.example.com redirects to www.example.co.uk. In this case the server will probably
return cookies for both URLs, but JMeter will only see the cookies for the last host, i.e.
www.example.co.uk. If the next request in the test plan uses www.example.com, rather
than www.example.co.uk, it will not get the correct cookies. Likewise, Headers are sent
for the initial request, and won't be sent for the redirect. This is generally only a problem
for manually created test plans, as a test plan created using a recorder would continue
from the redirected URL.
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. This allows arbitrary bodies to be sent. The values are encoded if the
encoding flag is set (versions of JMeter after 2.3). See also the MIME Type above how
you can control the content-type request header that is sent.
For other methods, if the name of the parameter is missing, then the parameter is ignored.
This allows the use of optional parameters defined by variables. (versions of JMeter after
2.3)
Method Handling:
The POST and PUT request methods work similarly, except that the PUT method does
not support multipart requests. The PUT method body must be provided as one of the
following:
If you define any parameters with a name in either the sampler or Http defaults then
nothing is sent. The GET and DELETE request methods work similarly to each other.
Upto and including JMeter 2.1.1, only responses with the content-type "text/html" were
scanned for embedded resources. Other content-types were assumed to be something
other than HTML. JMeter 2.1.2 introduces the a new property HTTPResponse.parsers ,
which is a list of parser ids, e.g. htmlParser and wmlParser . For each id found, JMeter
checks two further properties:
130
Jmeter 2.3.4 User’s Manual
See jmeter.properties file for the details of the settings. If the HTTPResponse.parser
property is not set, JMeter reverts to the previous behaviour, i.e. only text/html responses
will be scanned
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 Proxy Server
• HTTP Request Defaults
• HTTP Requests and Session ID's: URL Rewriting
This sampler lets you send an JDBC Request (an SQL query) to a database.
Before using this you need to set up a JDBC Connection Configuration Configuration
element
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.
131
Jmeter 2.3.4 User’s Manual
Old variables are cleared if necessary - e.g. if the first select retrieves 6 rows and a
second select returns only 3 rows, the additional variables for rows 4, 5 and 6 will be
removed.
Control Panel
Parameters
• Select Statement
• Update Statement - use this for Inserts as well
• Callable Statement
Query • Prepared Select Statement
Yes
Type • Prepared Update Statement - use this for Inserts as well
• Commit
• Rollback
• Autocommit(false)
• Autocommit(true)
• Edit - this should be a variable reference that evaluates
132
Jmeter 2.3.4 User’s Manual
133
Jmeter 2.3.4 User’s Manual
See Also:
Versions of JMeter after 2.3.2 use UTF-8 as the character encoding. Previously the
platform default was used.
This sampler lets you control a java class that implements the JavaSamplerClient
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 used by Assertions, etc. The
fields allow variables to be used, so the values of these can readily be seen.
Control Panel
Parameters
134
Jmeter 2.3.4 User’s Manual
SleepTime is in milliseconds
SleepMask is used to add a "random" element to the time:
totalSleepTime = SleepTime + (System.currentTimeMillis() % SleepMask)
This sampler lets you send a SOAP request to a webservice. It can also be used to send
XML-RPC over HTTP. It creates an HTTP POST request, with the specified XML as the
POST content. To change the "Content-type" from the default of "text/xml", use a
HeaderManager. Note that the sampler will use all the headers from the HeaderManager.
If a SOAP action is specified, that will override any SOAPaction in the HeaderManager.
The primary difference between the soap sampler and webservice sampler, is the soap
sampler uses raw post and does not require conformance to SOAP 1.1.
For versions of JMeter later than 2.2, the sampler no longer uses chunked encoding by
default.
For screen input, it now always uses the size of the data.
File input uses the file length as determined by Java.
On some OSes this may not work for all files, in which case add a child Header
Manager with Content-Length set to the actual length of the file.
Or set Content-Length to -1 to force chunked encoding.
Control Panel
135
Jmeter 2.3.4 User’s Manual
Parameters
This sampler has been tested with IIS Webservice running .NET 1.0 and .NET 1.1. It has
been tested with SUN JWSDP, IBM webservices, Axis and gSoap toolkit for C/C++. The
sampler uses Apache SOAP driver to serialize the message and set the header with the
correct SOAPAction. Right now the sampler doesn't support automatic WSDL handling,
since Apache SOAP currently does not provide support for it. Both IBM and SUN
provide WSDL drivers. There are 3 options for the post data: text area, external file, or
directory. If you want the sampler to randomly select a message, use the directory.
Otherwise, use the text area or a file. The if either the file or path are set, it will not use
the message in the text area. If you need to test a soap service that uses different
encoding, use the file or path. If you paste the message in to text area, it will not retain
the encoding and will result in errors. Save your message to a file with the proper
encoding, and the sampler will read it as java.io.FileInputStream.
The sampler requires mail.jar and activation.jar. This is because Apache SOAP
requires the libs. Because mail.jar and activation.jar are distributed by Sun, you have
to download them separately.
136
Jmeter 2.3.4 User’s Manual
An important note on the sampler is it will automatically use the proxy host and port
passed to JMeter from command line, if those fields in the sampler are left blank. If a
sampler has values in the proxy host and port text field, it will use the ones provided by
the user. This behavior may not be what users expect.
Note: If you are using CSVDataSet, do not check "Memory Cache". If memory cache is
checked, it will not iterate to the next value. That means all the requests will use the first
value.
Make sure you use <soap:Envelope rather than <Envelope. For example:
The SOAP library that is used does not support SOAP 1.2, only SOAP 1.1. Also the
library does not provide access to the HTTP response code (e.g. 200) or message (e.g.
OK). To get round this, versions of JMeter after 2.3.2 check the returned message
length. If this is zero, then the request is marked as failed.
Control Panel
137
Jmeter 2.3.4 User’s Manual
138
Jmeter 2.3.4 User’s Manual
Parameters
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.
139
Jmeter 2.3.4 User’s Manual
Control Panel
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 a pre-defined entry in the LDAP Server and calculate the
execution time. After execution of the test, the created entry will be
deleted from the LDAP Server.
140
Jmeter 2.3.4 User’s Manual
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 :
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.
This will search the user defined entry(Search filter) in the Search base
(again, defined by the user). The entries should be available in the LDAP
Server. The execution time is calculated.
4. Delete Test
1. Inbuilt test :
This will create a pre-defined entry first, then it will be deleted from the
LDAP Server. The execution time is calculated.
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
141
Jmeter 2.3.4 User’s Manual
See Also:
If you are going to send multiple requests to the same LDAP server, consider using an
LDAP Extended Request Defaults Configuration Element so you do not have to enter the
same information for each LDAP Request.
Control Panel
142
Jmeter 2.3.4 User’s Manual
There are nine test operations defined. These operations are given below:
1. 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" operation. The user is requested
to give a username (Distinguished name) and password, which will be used to
initiate a session. When no password, or the wrong password is specified, an
anonymous session is started. Take care, omitting the password will not fail this
test, a wrong password will.
Parameters
143
Jmeter 2.3.4 User’s Manual
2. Thread unbind
This is simply the operation to end a session. It is equal to the LDAP "unbind"
operation.
Parameters
3. Single bind/unbind
This is a combination of the LDAP "bind" and "unbind" operations. It can be used
for an authentication request/password check for any user. It will open an new
session, just to check the validity of the user/password combination, and end the
session again.
Parameters
144
Jmeter 2.3.4 User’s Manual
4. Rename entry
This is the LDAP "moddn" operation. It can be used to rename an entry, but also
for moving an entry or a complete subtree to a different place in the LDAP tree.
Parameters
5. Add test
This is the ldap "add" operation. It can be used to add any kind of object to the
LDAP server.
Parameters
6. Delete test
This is the LDAP "delete" operation, it can be used to delete an object from the
LDAP tree
145
Jmeter 2.3.4 User’s Manual
Parameters
7. Search test
This is the LDAP "search" operation, and will be used for defining searches.
Parameters
8. Modification test
146
Jmeter 2.3.4 User’s Manual
This is the LDAP "modify" operation. It can be used to modify an object. It can
be used to add, delete or replace values of an attribute.
Parameters
9. Compare
This is the LDAP "compare" operation. It can be used to compare the value of a
given attribute with some already known value. In reality this is mostly used to
check whether a given person is a member of some group. In such a case you can
compare the DN of the user as a given value, with the values in the attribute
"member" of an object of the type groupOfNames. If the compare operation fails,
this test fails with errorcode 49.
Parameters
See Also:
147
Jmeter 2.3.4 User’s Manual
AccessLogSampler was designed to read access logs and generate http requests. For
those not familiar with the access log, it is the log the webserver maintains of every
request it accepted. This means the every image and html file. The current
implementation is complete, but some features have not been enabled. There is a filter for
the access log parser, but I haven't figured out how to link to the pre-processor. Once I
do, changes to the sampler will be made to enable that functionality.
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:
The current implemenation of the parser only looks at the text within the quotes.
Everything else is stripped out and igored. For example, the response code is completely
ignored by the parser. For the future, it might be nice to filter out entries that do not have
a response code of 200. Extending the sampler should be fairly simple. There are two
interfaces you have to implement.
org.apache.jmeter.protocol.http.util.accesslog.LogParser
org.apache.jmeter.protocol.http.util.accesslog.Generator
Control Panel
148
Jmeter 2.3.4 User’s Manual
Parameters
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.
The SessionFilter is intended to handle Cookies across threads. It does not filter out any
entries, but modifies the cookie manager so that the cookies for a given IP are processed
by a single thread at a time. If two threads try to process samples from the same client IP
address, then one will be forced to wait until the other has completed.
The LogFilter is intended to allow access log entries to be filtered by filename and regex,
as well as allowing for the replacement of file extensions. However, it is not currently
possible to configure this via the GUI, so it cannot really be used.
149
Jmeter 2.3.4 User’s Manual
This sampler allows you to write a sampler using the BeanShell scripting language.
For full details on using BeanShell, please see the BeanShell web-site at
http://www.beanshell.org/.
The test element supports the ThreadListener and TestListener methods. These should be
defined in the initialisation file. See the file BeanShellListeners.bshrc for example
definitions.
Control Panel
Parameters
150
Jmeter 2.3.4 User’s Manual
N.B. Each Sampler instance has its own BeanShell interpeter, 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.
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:
151
Jmeter 2.3.4 User’s Manual
The SampleResult ResponseData is set from the return value of the script. Since version
2.1.2, if the script returns null, it can set the response directly, by using the method
SampleResult.setResponseData(data), where data is either a String or a byte array. The
data type defaults to "text", but can be set to binary by using the method
SampleResult.setDataType(SampleResult.BINARY).
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);
}
return "Data from sample with Label "+Label;
//or, since version 2.1.2
SampleResult.setResponseData("My data");
return null;
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();
For details on the methods available for the various classes (JMeterVariables,
SampleResult etc) please check the Javadoc or the source code. Beware however that
misuse of any methods can cause subtle faults that may be difficult to find ...
This sampler allows you to write a sampler using a BSF scripting language.
See the Apache Bean Scripting Framework website for details of the languages
supported. You may need to download the appropriate jars for the language; they should
be put in the JMeter lib directory.
• javascript
• jexl (JMeter version 2.3.2 and later)
152
Jmeter 2.3.4 User’s Manual
• xslt
Control Panel
Parameters
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 BSF variables -
i.e. they can be used directly in the script.
153
Jmeter 2.3.4 User’s Manual
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 BSF Sampler does not set the ResponseCode,
ResponseMessage and sample status via script variables. Currently the only way to
changes these is via the SampleResult methods:
• SampleResult.setSuccessful(true/false)
• SampleResult.setResponseCode("code")
• SampleResult.setResponseMessage("message")
The TCP Sampler opens a TCP/IP connection to the specified server. It then sends the
text, and waits for a response.
If "Re-use connection" is selected, connections are shared between Samplers in the same
thread, provided that the exact same host name string and port are used. Different
hosts/port combinations will use different connections, as will different threads.
If an error is detected - or "Re-use connection" is not selected - the socket is closed.
Another socket will be reopened on the next sample.
The following properties can be used to control its operation:
154
Jmeter 2.3.4 User’s Manual
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.
Users can provide their own implementation. The class must extend
org.apache.jmeter.protocol.tcp.sampler.TCPClient.
• TCPClientImpl
• BinaryTCPClientImpl
• LengthPrefixedBinaryTCPClientImpl
TCPClientImpl
This implementation is fairly basic. When reading the response, it reads until the end of
line byte, if this is defined by setting the property tcp.eolByte , otherwise until the end of
the input stream.
BinaryTCPClientImpl
This implementation converts the GUI input, which must be a hex-encoded string, into
binary, and performs the reverse when reading the response. When reading the response,
it reads until the end of message byte, if this is defined by setting the property
tcp.BinaryTCPClient.eomByte , otherwise until the end of the input stream.
LengthPrefixedBinaryTCPClientImpl
This implementation extends BinaryTCPClientImpl by prefixing the binary message data
with a binary length byte. The length prefix defaults to 2 bytes. This can be changed by
setting the property tcp.binarylength.prefix.length .
Timeout handling If the timeout is set, the read will be terminated when this expires. So
if you are using an eolByte/eomByte, make sure the timeout is sufficiently long,
otherwise the read will be terminated early.
Response handling
If tcp.status.prefix is defined, then the response message is searched for the text following
that up to the suffix. If any such text is found, it is used to set the response code. The
response message is then fetched from the properties file (if provided).
For example, if the prefix = "[" and the suffix = "]", then the following repsonse:
[J28] XI123,23,GBP,CR
would have the response code J28.
Response codes in the range "400"-"499" and "500"-"599" are currently regarded as
failures; all others are successful. [This needs to be made configurable!]
155
Jmeter 2.3.4 User’s Manual
Control Panel
Parameters
156
Jmeter 2.3.4 User’s Manual
ALPHA CODE
JMS Publisher will publish messages to a given pub/sub topic. 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 the JMS jar; this must be downloaded and put in the lib
directory
Control Panel
157
Jmeter 2.3.4 User’s Manual
Parameters
158
Jmeter 2.3.4 User’s Manual
in the tree.
use JNDI properties file use jndi.properties to create topic Yes
JNDI Initial Context
Name of the context factory No
Factory
Provider URL The URL for the jms provider No
Topic the message topic Yes
Authentication Authentication requirement for the JMS provider Yes
User User Name No
Password Password No
Number of samples to
number of samples to aggregate Yes
aggregate
configuration setting for the message Yes
Message type text or object message Yes
ALPHA CODE
JMS Publisher will subscribe to messages in a given pub/sub topic. 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 the JMS jar; this must be downloaded and put in the lib
directory
Control Panel
159
Jmeter 2.3.4 User’s Manual
Parameters
160
Jmeter 2.3.4 User’s Manual
ALPHA CODE
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 the JMS jar; this must be downloaded and put in the lib
directory
Control Panel
161
Jmeter 2.3.4 User’s Manual
Parameters
162
Jmeter 2.3.4 User’s Manual
163
Jmeter 2.3.4 User’s Manual
1. Rather than use Jmeter's test interface, it scans the jar files for classes extending
junit's TestCase class. That includes any class or subclass.
2. Junit test jar files should be placed in jmeter/lib/junit instead of /lib directory.
In versions of JMeter after 2.3.1, you can also use the "user.classpath" property to
specify where to look for TestCase classes.
3. Junit sampler does not use name/value pairs for configuration like the
JavaSampler. The sampler assumes setUp and tearDown will configure the test
correctly.
4. The sampler measures the elapsed time only for the test method and does not
include setUp and tearDown.
5. Each time the test method is called, Jmeter will pass the result to the listeners.
6. Support for oneTimeSetUp and oneTimeTearDown is done as a method. Since
Jmeter is multi-threaded, we cannot call oneTimeSetUp/oneTimeTearDown the
same way Maven does it.
7. The sampler reports unexpected exceptions as errors. There are some important
differences between standard JUnit test runners and JMeter's implementation.
Rather than make a new instance of the class for each test, JMeter creates 1
instance per sampler and reuses it.
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:
Empty Constructor:
public class myTestCase {
public myTestCase() {}
}
String Constructor:
public class myTestCase {
public myTestCase(String text) {
super(text);
}
}
164
Jmeter 2.3.4 User’s Manual
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.
1. Write the setUp and tearDown methods so they are thread safe. This generally
means avoid using static memebers.
2. Make the test methods discrete units of work and not long sequences of actions.
By keeping the test method to a descrete operation, it makes it easier to combine
test methods to create new test plans.
3. Avoid making test methods depend on each other. Since Jmeter allows arbitrary
sequencing of test methods, the runtime behavior is different than the default Junit
behavior.
4. If a test method is configurable, be careful about where the properties are
stored. Reading the properties from the Jar file is recommended.
5. Each sampler creates an instance of the test class, so write your test so the setup
happens in oneTimeSetUp and oneTimeTearDown.
Control Panel
165
Jmeter 2.3.4 User’s Manual
Parameters
166
Jmeter 2.3.4 User’s Manual
The Mail Reader Sampler can read (and optionally delete) mail messages using POP3(S)
or IMAP(S) protocols.
The sampler requires the JavaMail and JAF jars to be available on the classpath. To use
POP3S or IMAPS requires a recent version of JavaMail (e.g. JavaMail 1.4.1 and JAF
1.1.1).
Control Panel
167
Jmeter 2.3.4 User’s Manual
Parameters
168
Jmeter 2.3.4 User’s Manual
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. [This can be
changed using the JMeter property jmeterengine.threadstop.wait]
Control Panel
Parameters
169
Jmeter 2.3.4 User’s Manual
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.
Control Panel
Parameters
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.
170
Jmeter 2.3.4 User’s Manual
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.
Control Panel
Parameters
Looping Example
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.
171
Jmeter 2.3.4 User’s Manual
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 Logic Controller tells JMeter to process the controller(s) inside it only
once, and pass over any requests under it during further iterations through the test plan.
The Once Only Controller will now execute always during the first iteration of any
looping parent controller. Thus, if the Once Only Controller is placed under a Loop
Controller specified to loop 5 times, then the Once Only Controller will execute only on
the first iteration through the Loop Controller (ie, every 5 times). Note this means the
Once Only Controller will still behave as previously expected if put under a Thread
Group (runs only once per test), but now the user has more flexibility in the use of the
Once Only Controller.
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.
Control Panel
Parameters
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.
172
Jmeter 2.3.4 User’s Manual
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.
Control Panel
Parameters
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.
173
Jmeter 2.3.4 User’s Manual
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.
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
174
Jmeter 2.3.4 User’s Manual
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. However, if "ignore sub-controller blocks" was checked on the main
interleave controller, then the order would be: Home Page, Interleaved, Bug Page,
Interleaved, CVS Page, Interleaved, and FAQ Page, Interleaved.
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.
Control Panel
Parameters
175
Jmeter 2.3.4 User’s Manual
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.
Control Panel
Parameters
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.
The Throughput Controller allows the user to control how often it is executed. There are
two modes - percent execution and total executions. Percent executions cause the
controller to execute a certain percentage of the iterations through the test plan. Total
executions cause 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.
Control Panel
176
Jmeter 2.3.4 User’s Manual
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
The Runtime Controller controls how long its children are allowed to run.
Control Panel
177
Jmeter 2.3.4 User’s Manual
Parameters
19.2.9 If Controller
The If Controller allows the user to control whether the test elements below it (its
children) are run or not.
Prior to JMeter 2.3RC3, the condition was evaluated for every runnable element
contained in the controller. This sometimes caused unexpected behaviour, so 2.3RC3 was
changed to evaluate the condition only once on initial entry. However, the original
behaviour is also useful, so versions of JMeter after 2.3RC4 have an additional option to
select the original behaviour.
Versions of JMeter after 2.3.2 allow the script to be processed as a variable expression,
rather than requiring Javascript. It was always possible to use functions and variables in
the Javascript condition, so long as they evaluated to "true" or "false"; now this can be
done without the overhead of using Javascript as well. For example, previously one could
use the condition: ${__jexl(${VAR} == 23)} and this would be evaluated as true/false,
the result would then be passed to Javascript which would then return true/false. If the
Variable Expression option is selected, then the expression is evaluated and compared
with "true", without needing to use Javascript. Also, variable expressions can return any
value, whereas the Javascript condition must return "true"/"false" or an error is logged.
No variables are made available to the script when the condition is interpreted as
Javascript. If you need access to such variables, then select "Interpret Condition as
Variable Expression?" and use a __javaScript() function call. You can then use the
objects "vars", "log", "ctx" etc. in the script.
Control Panel
178
Jmeter 2.3.4 User’s Manual
Parameters
Examples (Javascript):
• ${COUNT} < 10
• "${VAR}" == "abcd"
• ${JMeterThread.last_sample_ok} (check if last sample succeeded)
If there is an error interpreting the code, the condition is assumed to be false, and a
message is logged in jmeter.log.
The While Controller runs its children until the condition is "false".
179
Jmeter 2.3.4 User’s Manual
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.
For example:
Control Panel
Parameters
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.
Note: In versions of JMeter after 2.3.1, the switch value can also be a name.
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.
180
Jmeter 2.3.4 User’s Manual
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.
Control Panel
Parameters
A ForEach controller loops through the values of a set of related variables. When you add
samplers (or controllers) to a ForEach controller, every sample sample (or controller) is
executed one or more times, where during every loop the variable has a new value. The
input should consist of several variables, each extended with an underscore and a
number. Each such variable must have a value. So for example when the input variable
has the name inputVar, the following variables should have been defined:
• inputVar_1 = wendy
• inputVar_2 = charles
• inputVar_3 = peter
• inputVar_4 = john
When the return variable is given as "returnVar", the collection of samplers and
controllers under the ForEach controller will be executed 4 consecutive times, with the
return variable having the respective above values, which can then be used in the
samplers.
181
Jmeter 2.3.4 User’s Manual
It is especially suited for running with the regular expression post-processor. This can
"create" the necessary input variables out of the result data of a previous request. By
omitting the "_" separator, the ForEach Controller can be used to loop through the groups
by using the input variable refName_g, and can also loop through all the groups in all the
matches by using an input variable of the form refName_${C}_g, where C is a counter
variable.
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.
Control Panel
Parameters
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.
182
Jmeter 2.3.4 User’s Manual
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".
183
Jmeter 2.3.4 User’s Manual
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.
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.
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.
There can be multiple fragments, each with a different series of samplers under them. The
module controller can then be used to easily switch between these multiple test cases
simply by choosing the appropriate controller in its drop down box. This provides
convenience for running many alternate test plans quickly and easily.
A fragment name is made up of the Controller name and all its parent names. For
example:
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.
Control Panel
184
Jmeter 2.3.4 User’s Manual
The Module Controller should not be used with remote testing or non-gui testing in
conjunction with Workbench components since the Workbench test elements are not
part of test plan .jmx files. Any such test will fail.
Parameters
The include controller is designed to use an external jmx file. To use it, add samples to a
simple controller, then save the simple controller as a jmx file. The file can then be used
in a test plan. The included test plan must not include a Thread Group. It should only
contain the Simple Controller and any samplers, controllers etc below it.
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.
Control Panel
185
Jmeter 2.3.4 User’s Manual
Parameters
The Transaction Controller generates an additional sample which measures the overall
time taken to perform the nested test elements. Note that this time includes all processing
within the controller scope, not just the samples.
For JMeter versions after 2.3, there are two modes of operation
The generated sample time includes all the times for the nested samplers, and any timers
etc. 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.
The generated sample is only regarded as successful if all its sub-samples are successful.
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.
In parent mode, Assertions (etc) can be added to the Transaction Controller. However by
default they will be applied to both the individual samples and the overall transaction
sample. To limit the scope of the Assertions, use a Simple Controller to contain the
samples, and add the Assertions to the Simple Controller. Parent mode controllers do not
currently properly support nested transaction controllers of either type.
Control Panel
186
Jmeter 2.3.4 User’s Manual
Parameters
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 Proxy Server , all recorded samples will by default be
saved under the Recording Controller.
Control Panel
Parameters
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
187
Jmeter 2.3.4 User’s Manual
default, the results are stored as XML files, typically with a ".jtl" extension. Storing as
CSV is the most efficient option, but is less detailed than XML (the other available
option).
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.
Versions of JMeter up to 2.3.2 used to clear any current data before loading the new
file.
This is no longer done, thus allowing files to be merged . If the previous behaviour is
required, use the menu item Run/Clear (Ctrl+Shift+E) or Run/Clear All (Ctrl+E) before
loading the file.
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.
The file name can contain function and/or variable references. However variable
references do not work in client-server mode (functions work OK).
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:
To minimise the amount of memory needed, use the Simple Data Writer, and use the
CSV format.
Versions of JMeter after 2.3.1 allow JMeter variables to be saved to the output files.
This can only be specified using a property. See the 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.
188
Jmeter 2.3.4 User’s Manual
The entries in jmeter.properties are used to define the defaults; these can be overriden
for individual listeners by using the Configure button, as shown below. The settings
in jmeter.properties also apply to the listener that is added by using the -l command-
line flag.
The figure below shows an example of the result file configuration panel
Parameters
Listeners can be configured to save different items to the result log files (JTL) by using
the Config popup as shown below. The defaults are defined as described in the Listener
Default Configuration documentation. Items with (CSV) after the name only apply to the
CSV format; items with (XML) only apply to XML format. CSV format cannot currently
be used to save any items that include line-breaks.
Note that cookies, method and the query string are saved as part of the "Sampler Data"
option.
Control Panel
189
Jmeter 2.3.4 User’s Manual
Control Panel
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
190
Jmeter 2.3.4 User’s Manual
(blue), the current standard deviation (red), and the current throughput rate (green) are
displayed in milliseconds.
The throughput number represents the actual number of requests/minute the server
handled. This calculation includes any delays you added to your test and JMeter's own
internal processing time. The advantage of doing the calculation like this is that this
number represents something real - your server in fact handled that many requests per
minute, and you can increase the number of threads and/or decrease the delays to
discover your server's maximum throughput. Whereas if you made calculations that
factored out delays and JMeter's processing, it would be unclear what you could conclude
from that number.
Control Panel
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.
191
Jmeter 2.3.4 User’s Manual
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 Spline Visualizer provides a view of all sample times from the start of the test till the
end, regardless of how many samples have been taken. The spline has 10 points, each
representing 10% of the samples, and connected using spline logic to show a single
continuous line.
The graph is automatically scaled to fit within the window. This needs to be borne in
mind when comparing graphs.
Control Panel
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.
192
Jmeter 2.3.4 User’s Manual
Control Panel
See Also:
• Response Assertion
There are several ways to view the response, selectable by a radio button.
• Show text
• Render HTML
• Render XML
• Render JSON
The default "Show 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/
193
Jmeter 2.3.4 User’s Manual
If there is no content-type provided, then the content will not be displayed in the any of
the Response Data panels. You can use Save Responses to a file to save the data in this
case. Note that the response data will still be available in the sample result, so can still be
accessed using Post-Processors.
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 .
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. If the
"Download embedded resources" check-box is selected, the renderer may download
images and style-sheets etc referenced by the HTML. If the checkbox is not selected, the
renderer will not download images etc.
The Render 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.
The Render JSON view will show the response in tree style (also handles JSON
embedded in JavaScript).
Control Panel
194
Jmeter 2.3.4 User’s Manual
The Control Panel (above) shows an example of an HTML display. Figure 9 (below)
shows an example of an XML display.
195
Jmeter 2.3.4 User’s Manual
The thoughput is calculated from the point of view of the sampler target (e.g. the remote
server in the case of HTTP samples). JMeter takes into account the total time over which
the requests have been generated. If other samplers and timers are in the same thread,
these will increase the total time, and therefore reduce the throughput value. So two
identical samplers with different names will have half the throughput of two samplers
with the same name. It is important to choose the sampler names correctly to get the best
results from the Aggregate Report.
Calculation of the Median and 90% Line (90 th percentile ) values requires a lot of
memory as details of every Sample have to be saved. See the Summary Report for a
similar Listener that does not need so much memory.
196
Jmeter 2.3.4 User’s Manual
• Label - The label of the sample. If "Include group name in label?" is selected, then
the name of the thread group is added as a prefix. This allows identical labels
from different thread groups to be collated separately if required.
• # Samples - The number of samples with the same label
• Average - The average time of a set of results
• Median - The median is the time in the middle of a set of results. 50% of the
samples took no more than this time; the remainder took at least as long.
• 90% Line - 90% of the samples took no more than this time. The remaining
samples at least as long as this. (90 th percentile )
• 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.
• Kb/sec - The throughput measured in Kilobytes per second
Control Panel
The figure below shows an example of selecting the "Include group name" checkbox.
197
Jmeter 2.3.4 User’s Manual
Control Panel
198
Jmeter 2.3.4 User’s Manual
Control Panel
199
Jmeter 2.3.4 User’s Manual
Monitor Results is a new Visualizer for displaying server status. It is designed for Tomcat
5, but any servlet container can port the status servlet and use this monitor. There are two
primary tabs for the monitor. The first is the "Health" tab, which will show the status of
one or more servers. The second tab labled "Performance" shows the performance for one
server for the last 1000 samples. The equations used for the load calculation is included
in the Visualizer.
Currently, the primary limitation of the monitor is system memory. A quick benchmark
of memory usage indicates a buffer of 1000 data points for 100 servers would take
roughly 10Mb of RAM. On a 1.4Ghz centrino laptop with 1Gb of ram, the monitor
should be able to handle several hundred servers.
As a general rule, monitoring production systems should take care to set an appropriate
interval. Intervals shorter than 5 seconds are too aggressive and have a potential of
impacting the server. With a buffer of 1000 data points at 5 second intervals, the monitor
would check the server status 12 times a minute or 720 times a hour. This means the
buffer shows the performance history of each machine for the last hour.
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
Control Panel
200
Jmeter 2.3.4 User’s Manual
The distribution graph will display a bar for every unique response time. Since the
granularity of System.currentTimeMillis () is 10 milliseconds, the 90% threshold should
be within the width of the graph. The graph will draw two threshold lines: 50% and 90%.
What this means is 50% of the response times finished between 0 and the line. The same
is true of 90% line. Several tests with Tomcat were performed using 30 threads for 600K
requests. The graph was able to display the distribution without any problems and both
201
Jmeter 2.3.4 User’s Manual
the 50% and 90% line were within the width of the graph. A performant application will
generally produce results that clump together. A poorly written application that has
memory leaks may result in wild fluctuations. In those situations, the threshold lines may
be beyond the width of the graph. The recommended solution to this specific problem is
fix the webapp so it performs well. If your test plan produces distribution graphs with no
apparent clumping or pattern, it may indicate a memory leak. The only way to know for
sure is to use a profiling tool.
Control Panel
Control Panel
202
Jmeter 2.3.4 User’s Manual
The mailer visualizer can be set up to send email if a test run receives too many failed
responses from the server.
Control Panel
203
Jmeter 2.3.4 User’s Manual
The Mailer Visualizer requires the optional Javamail jars (activation.jar and mail.jar). If these
are not present in the lib directory, the element will not appear in the menus.
Parameters
204
Jmeter 2.3.4 User’s Manual
received.
The BeanShell Listener allows the use of BeanShell for processing samples for saving
etc.
For full details on using BeanShell, please see the BeanShell web-site at
http://www.beanshell.org/.
The test element supports the ThreadListener and TestListener methods. These should be
defined in the initialisation file. See the file BeanShellListeners.bshrc for example
definitions.
Control Panel
Parameters
205
Jmeter 2.3.4 User’s Manual
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
The thoughput is calculated from the point of view of the sampler target (e.g. the remote
server in the case of HTTP samples). JMeter takes into account the total time over which
the requests have been generated. If other samplers and timers are in the same thread,
these will increase the total time, and therefore reduce the throughput value. So two
identical samplers with different names will have half the throughput of two samplers
with the same name. It is important to choose the sampler labels correctly to get the best
results from the Report.
• Label - The label of the sample. If "Include group name in label?" is selected, then
the name of the thread group is added as a prefix. This allows identical labels
from different thread groups to be collated separately if required.
• # Samples - The number of samples with the same label
206
Jmeter 2.3.4 User’s Manual
Control Panel
The figure below shows an example of selecting the "Include group name" checkbox.
207
Jmeter 2.3.4 User’s Manual
This test element can be placed anywhere in the test plan. For each sample in its scope, it
will create a file of the response Data. The primary use for this is in creating functional
tests, but it can also be useful where the response is too large to be displayed in the View
Results Tree Listener. The file name is created from the specified prefix, plus a number
(unless this is disabled, see below). The file extension is created from the document type,
if known. If not known, the file extension is set to 'unknown'. If numbering is disabled,
and adding a suffix is disabled, then the file prefix is taken as the entire file name. This
allows a fixed file name to be generated if required. The generated file name is stored in
the sample response, and can be saved in the test log output file if required.
The current sample is saved first, followed by any sub-samples (child samples). If a
variable name is provided, then the names of the files are saved in the order that the sub-
samples appear. See below.
Control Panel
208
Jmeter 2.3.4 User’s Manual
Parameters
The BSF Listener allows BSF script code to be applied to sample results.
Control Panel
209
Jmeter 2.3.4 User’s Manual
Parameters
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.
210
Jmeter 2.3.4 User’s Manual
For details of all the methods available on each of the above variables, please check the
Javadoc
The "label" is the the name of the element. The "+" means that the line is a delta line, i.e.
shows the changes since the last output. The "=" means that the line is a totals line, i.e. it
shows the running total. Entries in the jmeter log file also include time-stamps. The
example "806 in 91.6s = 8.8/s" means that there were 806 samples recorded in 91.6
seconds, and that works out at 8.8 samples per second. The Avg (Average), Min(imum)
and Max(imum) times are in milliseconds. "Err" means number of errors (also shown as
211
Jmeter 2.3.4 User’s Manual
percentage). The last two lines will appear at the end of a test. They will not be
synchronised to the appropriate time boundary. Note that the initial and final deltas may
be for less than the interval (in the example above this is 30 seconds). The first delta will
generally be lower, as JMeter synchronises to the interval boundary. The last delta will be
lower, as the test will generally not finish on an exact interval boundary.
The label is used to group sample results together. So if you have multiple Thread Groups
and want to summarize across them all, then use the same label - or add the summariser
to the Test Plan (so all thread groups are in scope). Different summary groupings can be
implemented by using suitable labels and adding the summarisers to appropriate parts of
the test plan.
Control Panel
Parameters
CSV Data Set Config is used to read lines from a file, and split them into variables. It is
easier to use than the __CSVRead() and _StringFromFile() functions. It is well suited to
handling large numbers of variables, and is also useful for tesing with "random" and
unique values. Generating unique random values at run-time is expensive in terms of
CPU and memory, so just create the data in advance of the test. If necessary, the
"random" data from the file can be used in conjunction with a run-time parameter to
create different sets of values from each run - e.g. using concatenation - which is much
cheaper than generating everything at run-time.
212
Jmeter 2.3.4 User’s Manual
Versions of JMeter after 2.3.1 allow variables to be quoted; this allows the value to
contain a delimiter. Previously it was necessary to choose a delimiter that was not used in
any values.
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 (JMeter 2.3.2+). If
you want each thread to have its own set of values, then you will need to create a set of
files, one for each thread. For example test1.csv, test2.csv,... testn.csv. Use the filename
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 configuration
items - such as JDBC Config - that process their contents at configuration time (see
Bug 40394 ) However the variables do work in the HTTP Auth Manager, as the
username etc are processed at run-time.
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 .
If the Recycle option is false, and Stop Thread is true, then reaching EOF will cause the
thread to be stopped.
Control Panel
213
Jmeter 2.3.4 User’s Manual
Parameters
214
Jmeter 2.3.4 User’s Manual
on EOF? is false)
• All threads - (the default) the file is shared between all the
threads.
• Current thread group - each file is opened once for each
thread group in which the element appears
• Current thread - each file is opened separately for each
thread
Sharing
• Identifier - all threads sharing the same identifier share the Yes
mode
same file. So for example if you have 4 thread groups, you
could use a common id for two or more of the groups to
share the file between them. Or you could use the thread
number to share the file between the same thread numbers
in different thread groups.
Control Panel
If there is more than one Authorization Manager in the scope of a Sampler, there is
currently no way to specify which one is to be used.
The Authorization Manager lets you specify one or more user logins for web pages that
are restricted using server authentication. You see this type of authentication when you
use your browser to access a restricted page, and your browser displays a login dialog
box. JMeter transmits the login information when it encounters this type of page.
The Authorisation headers are not shown in the Tree View Listener.
215
Jmeter 2.3.4 User’s Manual
jmeter.properties:
httpclient.parameters.file=httpclient.parameters
httpclient.parameters:
http.authentication.preemptive$Boolean=false
Note: the above settings only apply to the HttpClient sampler (and the SOAP samplers,
which use Httpclient).
When looking for a match against a URL, JMeter checks each entry in turn, and stops
when it finds the first match. Thus the most specific URLs should appear first in the list,
followed by less specific ones. Duplicate URLs will be ignored. If you want to use
different usernames/passwords for different threads, you can use variables. These can be
set up using a CSV Data Set Config Element (for example).
Control Panel
Parameters
216
Jmeter 2.3.4 User’s Manual
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
Download this example. In this example, we created a Test Plan on a local server that
sends three HTTP requests, two requiring a login and the other is open to everyone. See
figure 10 to see the makeup of our Test Plan. On our server, we have a restricted
directory named, "secret", which contains two files, "index.html" and "index2.html". We
created a login id named, "kevin", which has a password of "spot". So, in our
Authorization Manager, we created an entry for the restricted directory and a username
and password (see figure 11). The two HTTP requests named "SecretPage1" and
"SecretPage2" make requests to "/secret/index.html" and "/secret/index2.html". The other
HTTP request, named "NoSecretPage" makes a request to "/index.html".
217
Jmeter 2.3.4 User’s Manual
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.
The HTTP Cache Manager is used to add caching functionality to HTTP requests within
its scope.
If a sample is successful (i.e. has response code 2xx) then the Last-Modified and Etag
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. This may cause problems for Assertions.
Control Panel
218
Jmeter 2.3.4 User’s Manual
If there is more than one Cookie Manager in the scope of a Sampler, there is
currently no way to specify which one is to be used. Also, a cookie stored in one
cookie manager is not available to any other manager, so use multiple Cookie
Managers with care.
JMeter version 2.3.2 and earlier did not check that received cookies were valid for the
URL. This meant that cross-domain cookies were stored, and might be used later. This
has been fixed in later versions. To revert to the earlier behaviour, define the JMeter
property "CookieManager.check.cookies=false".
Received Cookies can be stored as JMeter thread variables (versions of JMeter after 2.3.2
no longer do this by default). To save cookies as variables, define the property
"CookieManager.save.cookies=true". Also, cookies names are prefixed with "COOKIE_"
before they are stored (this avoids accidental corruption of local variables) To revert to
the original behaviour, define the property "CookieManager.name.prefix= " (one or more
spaces). If enabled, the value of a cookie with the name TEST can be referred to as
${COOKIE_TEST}.
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
Since version 2.0.3, 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
219
Jmeter 2.3.4 User’s Manual
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.
Control Panel
Parameters
Attribut
Description Required
e
Name Descriptive name for this element that is shown in the tree. No
Clear
If selected, all server-defined cookies are cleared each time the
Cookies
main Thread Group loop is executed. In JMeter versions after 2.3, Yes
each
any cookies defined in the GUI are not cleared.
Iteration
The cookie policy that will be used to manage the cookies.
"compatibility" is the default, and should work in most cases. See
http://jakarta.apache.org/httpcomponents/httpclient-
Cookie 3.x/cookies.html and
Yes
Policy http://jakarta.apache.org/httpcomponents/httpclient-
3.x/apidocs/org/apache/commons/httpclient/cookie/CookiePolicy.
html [Note: "ignoreCookies" is equivalent to omitting the
CookieManager.]
This gives you the opportunity to use hardcoded cookies that will No
User-
be used by all threads during the test execution. (discourage
Defined
The "domain" is the hostname of the server (without http://); the d, unless
Cookies
port is currently ignored. you know
220
Jmeter 2.3.4 User’s Manual
what you're
doing)
Add
Add an entry to the cookie table. N/A
Button
Delete
Delete the currently selected table entry. N/A
Button
Load Load a previously saved cookie table and add the entries to the
N/A
Button existing cookie table entries.
Save As Save the current cookie table to a file (does not save any cookies
N/A
Button extracted from HTTP Responses).
This element lets you set default values that your HTTP Request controllers use. For
example, if you are creating a Test Plan with 25 HTTP Request controllers and all of the
requests are being sent to the same server, you could add a single HTTP Request Defaults
element with the "Server Name or IP" field filled in. Then, when you add the 25 HTTP
Request controllers, leave the "Server Name or IP" field empty. The controllers will
inherit this field value from the HTTP Request Defaults element.
In JMeter 2.2 and earlier, port 80 was treated specially - it was ignored if the sampler
used the https protocol. JMeter 2.3 and later treat all port values equally; a sampler that
does not specify a port will use the HTTP Request Defaults port, if one is provided.
Control Panel
221
Jmeter 2.3.4 User’s Manual
Parameters
222
Jmeter 2.3.4 User’s Manual
Parameters you provide. Each parameter has a name and value . The query
With the string will be generated in the correct fashion, depending on
Request the choice of "Method" you made (ie if you chose GET, the
query string will be appended to the URL, if POST, then it will
be sent separately). Also, if you are sending a file using a
multipart form, the query string will be created using the
multipart form specifications.
The Header Manager lets you add or override HTTP request headers.
Versions of JMeter up to 2.3.2 supported only one Header Manager per sampler; if there
were more in scope, then only the last one would be used.
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.
Control Panel
Parameters
223
Jmeter 2.3.4 User’s Manual
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 9 and 10).
The Java Request Defaults component lets you set default values for Java testing. See the
Java Request .
Control Panel
224
Jmeter 2.3.4 User’s Manual
Control Panel
225
Jmeter 2.3.4 User’s Manual
Parameters
226
Jmeter 2.3.4 User’s Manual
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
the wrong classname was used.
If the database server is not running or is not accessible, then JMeter will report a
java.net.ConnectException.
227
Jmeter 2.3.4 User’s Manual
jdbc:oracle:thin:@(description=(address=(host={m
c-name})(protocol=tcp)(port={port-
no}))(connect_data=(sid={sid})))
Ingres ingres.jdbc.IngresDriver jdbc:ingres://host:port/db[;attr=value]
(2006)
SQL com.microsoft.sqlserver.jdbc.SQLS jdbc:sqlserver://host:port;DatabaseName=dbname
Server erverDriver
(MS
JDBC
driver)
Apache org.apache.derby.jdbc.ClientDriver jdbc:derby://server[:port]/databaseName[;URLAttri
Derby butes=value[;...]]
The above may not be correct - please check the relevant JDBC driver documentation.
The Login Config Element lets you add or override username and password settings in
samplers that use username and password as part of their setup.
Control Panel
Parameters
The LDAP Request Defaults component lets you set default values for LDAP testing. See
the LDAP Request .
Control Panel
228
Jmeter 2.3.4 User’s Manual
The LDAP Extended Request Defaults component lets you set default values for
extended LDAP testing. See the LDAP Extended Request .
Control Panel
229
Jmeter 2.3.4 User’s Manual
The TCP Sampler Config provides default data for the TCP Sampler
Control Panel
230
Jmeter 2.3.4 User’s Manual
Parameters
The User Defined Variables element lets you define an initial set of variables , just as in
the Test Plan . 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 saved in the variable.
However, UDVs can be used with functions such as __P(), for example:
231
Jmeter 2.3.4 User’s Manual
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.
Control Panel
If you have more than one Thread Group, make sure you use different names for different
values, as UDVs are shared between Thread Groups. Also, the variables are not available
for use until after the element has been processed, so you cannot reference variables that
are defined in the same element. You can reference variables defined in earlier UDVs or
232
Jmeter 2.3.4 User’s Manual
Parameters
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.
The output variable is constructed by using the random number generator, and then the
resulting number is formatted using the format string. The number is calculated using the
formula minimum+Random.nextInt(maximum-minimum+1) . Random.nextInt() requires
a positive integer. This means that maximum-minimum - i.e. the range - must be less than
2147483647, however the minimum and maximum values can be any long values so long
as the range is OK.
Control Panel
Parameters
233
Jmeter 2.3.4 User’s Manual
19.4.16 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.
From version 2.1.2, the counter now uses a long to store the value, so the range is from -
2^63 to 2^63-1.
Control Panel
234
Jmeter 2.3.4 User’s Manual
Parameters
The Simple Config Element lets you add or override arbitrary values in samplers. You
can choose the name of the value and the value itself. Although some adventurous users
235
Jmeter 2.3.4 User’s Manual
might find a use for this element, it's here primarily for developers as a basic GUI that
they can use while developing new JMeter components.
Control Panel
Parameters
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.
Note: Unless documented otherwise, Assertions are not applied to sub-samples (child
samples) - only to the parent sample. In the case of BSF and BeanShell Assertions, the
script can retrieve sub-samples using the method prev.getSubResults() which returns
an array of SampleResults. The array will be empty if there are none.
Versions of JMeter after 2.3.2 include the option to apply certain assertions 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:
236
Jmeter 2.3.4 User’s Manual
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.
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 expression syntax. For example:
Control Panel
237
Jmeter 2.3.4 User’s Manual
Parameters
Response • Text Response - the response text from the server, i.e. the
Field to body, excluing any HTTP headers. Yes
Test • URL sampled
• Response Code - e.g. 200
• Response Message - e.g. OK
238
Jmeter 2.3.4 User’s Manual
The pattern is a Perl5-style regular expression, but without the enclosing brackets.
Assertion Examples
239
Jmeter 2.3.4 User’s Manual
240
Jmeter 2.3.4 User’s Manual
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.
Control Panel
Parameters
241
Jmeter 2.3.4 User’s Manual
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.
Since JMeter 2.3RC3, an empty response is treated as being 0 bytes rather than
reported as an error.
Control Panel
Parameters
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.
242
Jmeter 2.3.4 User’s Manual
Control Panel
Parameters
The BeanShell Assertion allows the user to perform assertion checking using a BeanShell
script.
For full details on using BeanShell, please see the BeanShell web-site at
http://www.beanshell.org/.
Note that a different Interpreter is used for each independent occurence of the assertion in
each thread in a test script, but the same Interpreter is used for subsequent invocations.
This means that variables persist across calls to the assertion.
All Assertions are called from the same thread as the sampler.
The test element supports the ThreadListener and TestListener methods. These should be
defined in the initialisation file. See the file BeanShellListeners.bshrc for example
definitions.
Control Panel
243
Jmeter 2.3.4 User’s Manual
Parameters
Before invoking the script, some variables are set up in the BeanShell interpreter. These
are strings unless otherwise noted:
244
Jmeter 2.3.4 User’s Manual
• setStopThread(boolean)
• setStopTest(boolean)
• String getSampleLabel()
• setSampleLabel(String)
The MD5Hex Assertion allows the user to check the MD5 hash of the response data.
Control Panel
Parameters
245
Jmeter 2.3.4 User’s Manual
The HTML Assertion allows the user to check the HTML syntax of the response data
using JTidy.
Control Panel
Parameters
246
Jmeter 2.3.4 User’s Manual
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.
Control Panel
Parameters
247
Jmeter 2.3.4 User’s Manual
The non-tolerant parser can be quite slow, as it may need to download the DTD etc.
The XML Schema Assertion allows the user to validate a response against an XML
Schema.
Control Panel
Parameters
The BSF Assertion allows BSF script code to be used to check the status of the previous
sample.
Control Panel
248
Jmeter 2.3.4 User’s Manual
Parameters
The script (or file) is processed using the BSFEngine.exec() method, which does not
return a value.
249
Jmeter 2.3.4 User’s Manual
The script can check various aspects of the SampleResult. If an error is detected, the
script should use AssertionResult.setFailureMessage("message") and
AssertionResult.setFailure(true).
For futher details of all the methods available on each of the above variables, please
check the Javadoc
19.6 Timers
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 Action Sampler.
If you want to have each thread pause for the same amount of time between requests, use
this timer.
Control Panel
250
Jmeter 2.3.4 User’s Manual
Parameters
This timer pauses each thread request for a random amount of time, with most of the time
intervals ocurring near a particular value. The total delay is the sum of the Gaussian
distributed value (with mean 0.0 and standard deviation 1.0) times the deviation value
you specify, and the offset value.
Control Panel
Parameters
This timer pauses each thread request for a random amount of time, with each time
interval having the same probability of occurring. The total delay is the sum of the
random value and the offset value.
Control Panel
251
Jmeter 2.3.4 User’s Manual
Parameters
This timer introduces variable pauses, calculated to keep the total throughput (in terms of
samples per minute) as close as possible to a give figure. Of course the throughput will be
lower if the server is not capable of handling it, or if other timers or time-consuming test
elements prevent it.
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:
See Best Practices for further details. 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.
Control Panel
252
Jmeter 2.3.4 User’s Manual
Parameters
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.
Control Panel
253
Jmeter 2.3.4 User’s Manual
Parameters
For full details on using BeanShell, please see the BeanShell web-site at
http://www.beanshell.org/.
The test element supports the ThreadListener and TestListener methods. These should be
defined in the initialisation file. See the file BeanShellListeners.bshrc for example
definitions.
Control Panel
254
Jmeter 2.3.4 User’s Manual
Parameters
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
255
Jmeter 2.3.4 User’s Manual
This modifier parses HTML response from the server and extracts links and forms. A
URL test sample that passes through this modifier will be examined to see if it "matches"
any of the links or forms extracted from the immediately previous response. It would then
replace the values in the URL test sample with appropriate values from the matching link
or form. Perl-type regular expressions are used to find matches.
Control Panel
Matches are performed using protocol, host, path and parameter names. The target
sampler cannot contain parameters that are not in the response links.
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
256
Jmeter 2.3.4 User’s Manual
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.
This modifier works similarly to the HTML Link Parser, except it has a specific purpose
for which it is easier to use than the HTML Link Parser, and more efficient. For web
applications that use URL Re-writing to store session ids instead of cookies, this element
can be attached at the ThreadGroup level, much like the HTTP Cookie Manager . Simply
give it the name of the session id parameter, and it will find it on the page and add the
argument to every request of that ThreadGroup.
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 .
Control Panel
257
Jmeter 2.3.4 User’s Manual
Parameters
The HTML Parameter Mask is used to generate unique values for HTML arguments. By
specifying the name of the parameter, a value prefix and suffix, and counter parameters,
this modifier will generate values of the form " name=prefixcountersuffix ". Any
HTTP Request that it modifies, it will replace any parameter with the same name or add
the appropriate parameter to the requests list of arguments.
258
Jmeter 2.3.4 User’s Manual
The value of the argument in your HTTP Request must be a '*' in order for the HTML
Parameter Mask Modifier to replace it.
As an example, the username for a login script could be modified to send a series of
values such as:
user_1
user_2
user_3
user_4, etc.
Control Panel
Parameters
See also the CSV Data Set Config element, which is more suitable for large numbers of
parameters
259
Jmeter 2.3.4 User’s Manual
The User Parameter Modifier uses an XML file get values for HTTP arguments. Any
HTTP Request that this modifier modifies will be checked for the existence of the
specified arguments. If found, the values for those arguments will be replaced by the
values found in the xml file. The XML file can have multiple sets of the same values.
This modifier will iterate through these values in a round-robin style, thus each request
will get a different set of values until the last set of values is reached, at which point it
will begin again at the first set.
Control Panel
Parameters
Allow 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.
260
Jmeter 2.3.4 User’s Manual
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
Control Panel
Parameters
The BeanShell PreProcessor allows arbitrary code to be applied before taking a sample.
For full details on using BeanShell, please see the BeanShell web-site at
http://www.beanshell.org/.
261
Jmeter 2.3.4 User’s Manual
The test element supports the ThreadListener and TestListener methods. These should be
defined in the initialisation file. See the file BeanShellListeners.bshrc for example
definitions.
Control Panel
Parameters
262
Jmeter 2.3.4 User’s Manual
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
The BSF PreProcessor allows BSF script code to be applied before taking a sample.
Control Panel
Parameters
263
Jmeter 2.3.4 User’s Manual
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
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.
264
Jmeter 2.3.4 User’s Manual
Post-Processors are run before Assertions, so they do not have access to any Assertion
Results, nor will the sample status reflect the results of any Assertions. If you require
access to Assertion Results, try using a Listener instead. Also note that the variable
JMeterThread.last_sample_ok is set to "true" or "false" after all Assertions have been run.
Allow the user to extract values from a server response using a Perl-type regular
expression. As a post-processor, this element will execute after each Sample request in its
scope, applying the regular expression, extracting the requested values, generate the
template string, and store the result into the given variable name.
Control Panel
Parameters
265
Jmeter 2.3.4 User’s Manual
266
Jmeter 2.3.4 User’s Manual
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.
Control Panel
267
Jmeter 2.3.4 User’s Manual
Parameters
If Tidy is
Quiet Sets the Tidy Quiet flag
selected
Report If a Tidy error occurs, then add an Assertion showing the If Tidy is
Errors details selected
Show If Tidy is
Sets the Tidy showWarnings option
warnings selected
If checked, then the XML parser will use namespace
resolution. Note that currently only namespaces declared on
the root element will be recognised. A later version of JMeter
may support user-definition of additional workspace names.
Meanwhile, a work-round is to replace:
Use
//mynamespace:tagname Yes
Namespace?
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)
Reference
The name of the JMeter variable in which to store the result. Yes
Name
Element query in XPath language. Can return more than one
XPath Query Yes
match.
268
Jmeter 2.3.4 User’s Manual
Default
Default value returned when no match found No
Value
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']/option[text()='Czech
Republic'])/@value
extracts value attribute of option element that match text 'Czech Republic' inside
of select element with name attribute 'country' inside of form with name attribute
'countryForm'
When "Use Tidy" is checked on - resulting XML document may slightly differ from
original HTML response:
Control Panel
269
Jmeter 2.3.4 User’s Manual
Parameters
The BeanShell PreProcessor allows arbitrary code to be applied after taking a sample.
For JMeter versions after 2.2 the BeanShell Post-Processor no longer ignores samples
with zero-length result data
For full details on using BeanShell, please see the BeanShell web-site at
http://www.beanshell.org/.
The test element supports the ThreadListener and TestListener methods. These should be
defined in the initialisation file. See the file BeanShellListeners.bshrc for example
definitions.
Control Panel
270
Jmeter 2.3.4 User’s Manual
Parameters
The following BeanShell variables are set up for use by the script:
271
Jmeter 2.3.4 User’s Manual
For details of all the methods available on each of the above variables, please check the
Javadoc
The BSF PostProcessor allows BSF script code to be applied after taking a sample.
Control Panel
Parameters
272
Jmeter 2.3.4 User’s Manual
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
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
273
Jmeter 2.3.4 User’s Manual
www.example.com, and the rest of the test plan could refer to it as ${SERVER}. This
simplifies changing the name later.
If the same variable name is reused on one of more User Defined Variables Configuration
elements, the value is set to the last definition in the test plan (reading from top to
bottom). Such variables should be used for items that may change between test runs, but
which remain the same during a test run.
Note that the Test Plan cannot refer to variables it defines. If you need to construct
other variables from the Test Plan variables, use a User Defined Variables test element.
Selecting Functional Testing instructs JMeter to save the additional sample information -
Response Data and Sampler Data - to all result files. This increases the resources needed
to run a test, and may adversely impact JMeter performance. If more data is required for a
particular sampler only, then add a Listener to it, and configure the fields as required.
[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.
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. In the past, users had to copy all the jar files to
jmeter/lib/ directory. Now that is not necessary. JMeter properties also provides an entry
for loading additional classpaths.
Control Panel
274
Jmeter 2.3.4 User’s Manual
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.
Control Panel
275
Jmeter 2.3.4 User’s Manual
Parameters
Number of
Number of users to simulate. Yes
Threads
How long JMeter should take to get all the threads started.
Ramp-up
If there are 10 threads and a ramp-up time of 100 seconds, Yes
Period
then each thread will begin 10 seconds after the previous
276
Jmeter 2.3.4 User’s Manual
thread started, for a total time of 100 seconds to get the test
fully up to speed.
Number of times to perform the test case. Alternatively, Yes, unless
Loop Count "forever" can be selected causing the test to run until forever is
manually stopped. selected
If the scheduler checkbox is selected, one can choose an
absolute start time. When you start your test, JMeter will
Start Time No
wait until the specified start time to begin testing. Note:
the Startup Delay field over-rides this - see below.
If the scheduler checkbox is selected, one can choose an
absolute end time. When you start your test, JMeter will
End Time wait until the specified start time to begin testing, and it No
will stop at the specified end time. Note: the Duration field
over-rides this - see below.
If the scheduler checkbox is selected, one can choose a
Duration
relative end time. JMeter will use this to calculate the End No
(seconds)
Time, and ignore the End Time value.
If the scheduler checkbox is selected, one can choose a
Startup delay
relative startup delay. JMeter will use this to calculate the No
(seconds)
Start Time, and ignore the Start Time value.
19.9.3 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. Your WorkBench can be saved
independently, if you like (right-click on WorkBench and choose Save).
Control Panel
277
Jmeter 2.3.4 User’s Manual
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.
Or you can set the appropriate System properties - see the system.properties file.
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 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.
The Proxy Server can only record HTTP traffic. It is not possible to record HTTPS
(SSL) sessions; however there is an HTTPS spoofing mode - see below.
278
Jmeter 2.3.4 User’s Manual
The Proxy Server allows JMeter to watch and record your actions while you browse your
web application with your normal browser. JMeter will create test sample objects and
store them directly into your test plan as you go (so you can view samples interactively
while you make them).
To use the proxy server, add the HTTP Proxy Server 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 Proxy Server).
You also need to set up your browser to use the JMeter proxy port as the proxy for HTTP
requests. Do not use JMeter as the proxy for any other request types - HTTPS, FTP, etc. -
as the JMeter proxy cannot handle them.
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.
Control Panel
279
Jmeter 2.3.4 User’s Manual
Parameters
280
Jmeter 2.3.4 User’s Manual
281
Jmeter 2.3.4 User’s Manual
282
Jmeter 2.3.4 User’s Manual
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://jakarta.apache.org/jmeter/index.html?username=xxxx" ,
then the regular expression will be tested against the string:
"jakarta.apache.org: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 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 j.a.o/index.html
Versions of JMeter from 2.3.2 are able to capture binary POST data. To configure which
content-types are treated as binary, update the JMeter property proxy.binary.types. The
default settings are as follows:
It is also possible to have the proxy add timers to the recorded script. To do this, create a
timer directly within the HTTP Proxy Server 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 occurences of variable ${T} in its
properties, and any such occurences 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.
283
Jmeter 2.3.4 User’s Manual
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).
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/.
If the HTTP Proxy Server finds enabled HTTP Request Defaults directly within the
controller where samples are being stored, or directly within any of its parent controllers,
the recorded samples will have empty fields for the default values you specified. You
may further control this behaviour by placing an HTTP Request Defaults element directly
within the HTTP Proxy Server, whose non-blank values will override those in the other
HTTP Request Defaults. See Best Practices with the Proxy Server for more info.
Similarly, if the HTTP Proxy Server finds User Defined Variables (UDV) directly within
the controller where samples are being stored, or directly within any of its parent
controllers, the recorded samples will have any occurences of the values of those
variables replaced by the corresponding variable. Again, you can place User Defined
Variables directly within the HTTP Proxy Server to override the values to be replaced.
See Best Practices with the Proxy Server for more info.
Replacement by Variables: by default, the Proxy server looks for all occurences of UDV
values. If you define the variable "WEB" with the value "www", for example, the string
"www" will be replaced by ${WEB} wherever it is found. To avoid this happening
everywhere, set the "Regex Matching" check-box. This tells the proxy server to treat
values as Regexes (using ORO).
If you want to match a whole string only, enclose it in ^$, e.g. "^thus$".
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 (?<!...)".
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.
284
Jmeter 2.3.4 User’s Manual
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 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 Proxy Server 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
The Proxy server passes on any Authorization headers sent by the browser, but does not
save them in the test plan. If the site requires Authorization, you will need to add an
Authorization Manager and fill it in with the necessary entries.
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.
The HTTP Mirrror Server is a very simple HTTP server - it simply mirrors the data sent
to it. This is useful for checking the content of HTTP requests.
Control Panel
285
Jmeter 2.3.4 User’s Manual
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.
Control Panel
Parameters
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.
286
Jmeter 2.3.4 User’s Manual
Control Panel
Parameters
The Debug PostProcessor creates a subSample with the details of the previous sampler
properties. This is intended for developer use only.
Control Panel
Parameters
287
Jmeter 2.3.4 User’s Manual
19.10 Reports
19.10.1 Report Plan
288
Jmeter 2.3.4 User’s Manual
${__functionName(var1,var2,var3)}
If a function parameter contains a comma, then be sure to escape this with "\", otherwise
JMeter will treat it as a parameter delimiter. For example:
${VARIABLE}
Properties are not the same as variables. Variables are local to a thread; properties
are common to all threads, and need to be referenced using the __P or __property
function.
289
Jmeter 2.3.4 User’s Manual
User-defined static values allow the user to define variables to be replaced with their
static value when a test tree is compiled and submitted to be run. This replacement
happens once at the beginning of the test run. This could be used to replace the DOMAIN
field of all HTTP requests, for example - making it a simple matter to change a test to
target a different server with the same test.
Note that variables cannot currently be nested; i.e ${Var${N}} does not work. The __V
(variable) function (versions after 2.2) can be used to do this: ${__V(Var${N})}. In
earlier JMeter versions one can use ${__BeanShell(vars.get("Var${N}")}.
This type of replacement is possible without functions, but was less convenient and less
intuitive. It required users to create default config elements that would fill in blank values
of Samplers. Variables allow one to replace only part of any given value, not just filling
in blank values.
With built-in functions users can compute new values at run-time based on previous
response data, which thread the function is in, the time, and many other sources. These
values are generated fresh for every request throughout the course of the test.
290
Jmeter 2.3.4 User’s Manual
Functions are shared between threads. Each occurrence of a function call in a test plan
is handled by a separate function instance.
Functions which are used on the Test Plan have some restrictions. JMeter thread variables
will have not been fully set up when the functions are processed, so variable names
passed as parameters will not be set up, and variable references will not work, so split()
and regex() and the variable evaluation functions won't work. The threadNum() function
won't work (and does not make sense at test plan level). The following functions should
work OK on the test plan:
• intSum
• longSum
• machineName
• BeanShell
• javaScript
• jexl
• random
• time
• property functions
• log functions
When using variable/function references in SQL code (etc), remember to include any
necessary quotes for text strings, i.e. use
SELECT item from table where name='${VAR}'
not
SELECT item from table where name=${VAR}
(unless VAR itself contains the quotes)
291
Jmeter 2.3.4 User’s Manual
Functions are referenced in the same manner, but by convention, the names of functions
begin with "__" to avoid conflict with user value names * . Some functions take
arguments to configure them, and these go in parentheses, comma-delimited. If the
function takes no arguments, the parentheses can be omitted.
${__BeanShell(vars.put("name"\,"value"))}
Alternatively, you can define your script as a variable, e.g. on the Test Plan:
SCRIPT vars.put("name","value")
The script can then be referenced as follows:
${__BeanShell(${SCRIPT})}
There is no need to escape commas in the SCRIPT variable because the function call is
parsed before the variable is replaced with its value. This works well in conjunction with
the BSF or BeanShell Samplers, as these can be used to test Javascript, Jexl and
BeanShell scripts.
JMeter provides a tool to help you construct function calls for various built-in functions,
which you can then copy-paste. It will not automatically escape values for you, since
functions can be parameters to other functions, and you should only escape values you
intend as literal.
The value of a variable or function can be reported using the __logn() function. The
__logn() function reference can be used anywhere in the test plan after the variable has
been defined. Alternatively, the Java Request sampler can be used to create a sample
containing variable references; the output will be shown in the appropriate Listener. For
versions of JMeter later than 2.3, there is a Debug Sampler that can be used to display the
values of variables etc in the Tree View Listener.
292
Jmeter 2.3.4 User’s Manual
*
If you define a user-defined static variable with the same name as a built-in function,
your static variable will override the built-in function.
Using the Function Helper, you can select a function from the pull down, and assign
values for its arguments. The left column in the table provides a brief description of the
argument, and the right column is where you write in the value for that argument.
Different functions take different arguments.
Once you have done this, click the "generate" button, and the appropriate string is
generated for you to copy-paste into your test plan wherever you like.
20.5 Functions
20.5.1 __regexFunction
The Regex Function is used to parse the previous response (or the value of a variable)
using any regular expression (provided by user). The function returns the template string
with variable values filled in.
The __regexFunction can also store values for future use. In the sixth parameter, you can
specify a reference name. After this function executes, the same values can be retrieved at
later times using the syntax for user-defined values. For instance, if you enter "refName"
as the sixth parameter you will be able to use:
293
Jmeter 2.3.4 User’s Manual
Control Panel
Parameters
• An integer - Tells JMeter to use that match. '1' for the first
found match, '2' for the second, and so on
• RAND - Tells JMeter to choose a match at random.
Third No,
• ALL - Tells JMeter to use all matches, and create a
argument default=1
template string for each one and then append them all
together. This option is little used.
• A float number between 0 and 1 - tells JMeter to find the
Xth match using the formula: (number_of_matches_found
* float_number) rounded to nearest integer.
If 'ALL' was selected for the above argument value, then this
Fourth
argument will be inserted between each appended copy of the No
argument
template value.
Fifth Default value returned if no match is found No
294
Jmeter 2.3.4 User’s Manual
argument
A reference name for reusing the values parsed by this function.
Sixth Stored values are ${refName} (the replacement template string)
No
argument and ${refName_g#} where "#" is the group number from the
regular expression ("0" can be used to refer to the entire match).
Seventh Input variable name. If specified, then the value of the variable is
No
argument used as the input instead of using the previous sample result.
20.5.2 __counter
The counter generates a new number each time it is called, starting with 1 and
incrementing by +1 each time. The counter can be configured to keep each simulated
user's values separate, or to use the same counter for all users. If each user's values is
incremented separately, that is like counting the number of iterations through the test
plan. A global counter is like counting how many times that request was run.
The counter uses an integer variable to hold the count, which therefore has a maximum of
2,147,483,647.
The counter function instances are now completely independent. [JMeter 2.1.1 and earlier
used a fixed thread variable to keep track of the per-user count, so multiple counter
functions operated on the same value.] The global counter - "FALSE" - is separately
maintained by each counter instance.
Control Panel
Parameters
20.5.3 __threadNum
The thread number function simply returns the number of the thread currently being
executed. These numbers are independent of ThreadGroup, meaning thread #1 in one
295
Jmeter 2.3.4 User’s Manual
Control Panel
This function does not work in any Configuration elements (e.g. User Defined Variables)
as these are run from a separate thread. Nor does it make sense to use it on the Test Plan.
20.5.4 __intSum
The intSum function can be used to compute the sum of two or more integer values.
JMeter Versions 2.3.1 and earlier required the reference name to be present. The
reference name is now optional, but it must not be a valid integer.
Control Panel
Parameters
20.5.5 __longSum
The longSum function can be used to compute the sum of two or more long values.
Control Panel
296
Jmeter 2.3.4 User’s Manual
Parameters
20.5.6 __StringFromFile
The StringFromFile function can be used to read strings from a text file. This is useful for
running tests that require lots of variable data. For example when testing a banking
application, 100s or 1000s of different account numbers might be required.
See also the CSV Data Set Config test element which may be easier to use. However, that
does not currently support multiple input files.
Each time it is called it reads the next line from the file. When the end of the file is
reached, it will start reading again from the beginning, unless the maximum loop count
has been reached. If there are multiple references to the function in a test script, each will
open the file independently, even if the file names are the same. [If the value is to be used
again elsewhere, use different variable names for each function call.]
If an error occurs opening or reading the file, then the function returns the string
"**ERR**"
Control Panel
Parameters
297
Jmeter 2.3.4 User’s Manual
The file name parameter is resolved when the file is opened or re-opened.
The reference name parameter (if supplied) is resolved every time the function is
executed.
When using the optional sequence numbers, the path name is used as the format string for
java.text.DecimalFormat. The current sequence number is passed in as the only
parameter. If the optional start number is not specified, the path name is used as is.
Useful formatting sequences are:
Examples:
pin#'.'dat -> pin1.dat, ... pin9.dat, pin10.dat, ... pin9999.dat
pin000'.'dat -> pin001.dat ... pin099.dat ... pin999.dat ... pin9999.dat
pin'.'dat# -> pin.dat1, ... pin.dat9 ... pin.dat999
If more digits are required than there are formatting characters, the number will be
expanded as necessary.
In other locales (e.g. fr), the decimal point is "," - which means that "#." becomes "nnn,".
See the documentation for DecimalFormat for full details.
If the path name does not contain any special formatting characters, the current sequence
298
Jmeter 2.3.4 User’s Manual
number will be appended to the name, otherwise the number will be inserted aaccording
to the fomatting instructions.
If the start sequence number is omitted, and the end sequence number is specified, the
sequence number is interpreted as a loop count, and the file will be used at most "end"
times. In this case the filename is not formatted.
${_StringFromFile(PIN#'.'DAT,,1,2)} - reads PIN1.DAT, PIN2.DAT
${_StringFromFile(PIN.DAT,,,2)} - reads PIN.DAT twice
Note that the "." in PIN.DAT above should not be quoted. In this case the start number is
omitted, so the file name is used exactly as is.
20.5.7 __machineName
Control Panel
Parameters
20.5.8 __javaScript
The javaScript function executes a piece of JavaScript (not Java!) code and returns its
value
299
Jmeter 2.3.4 User’s Manual
Rhinoscript allows access to static methods via its Packages object. See the Scripting
Java documentation. For example one can access the JMeterContextService static
methods thus:
Packages.org.apache.jmeter.threads.JMeterContextService.getTotalThreads
()
JMeter is not a browser, and does not interpret the JavaScript in downloaded pages.
Control Panel
Parameters
Require
Attribute Description
d
The JavaScript expression to be executed. For example:
Variable
A reference name for reusing the value computed by this function. No
Name
Remember to include any necessary quotes for text strings and JMeter variables. Also, if
the expression has commas, please make sure to escape them. For example in:
${__javaScript('${sp}'.slice(7\,99999))}
the comma after 7 is escaped.
20.5.9 __Random
The random function returns a random number that lies between the given min and max
values.
Control Panel
300
Jmeter 2.3.4 User’s Manual
Parameters
20.5.10 __CSVRead
The CSVRead function returns a string from a CSV file (c.f. StringFromFile )
NOTE: versions up to 1.9.1 only supported a single file. JMeter versions since 1.9.1
support multiple file names.
In most cases, the newer CSV Data Set Config element is easier to use.
When a filename is first encountered, the file is opened and read into an internal array. If
a blank line is detected, this is treated as end of file - this allows trailing comments to be
used (N.B. this feature was introduced in versions after 1.9.1)
All subsequent references to the same file name use the same internal array. N.B. the
filename case is significant to the function, even if the OS doesn't care, so
CSVRead(abc.txt,0) and CSVRead(aBc.txt,0) would refer to different internal arrays.
The *ALIAS feature allows the same file to be opened more than once, and also allows
for shorter file names.
Each thread has its own internal pointer to its current row in the file array. When a thread
first refers to the file it will be allocated the next free row in the array, so each thread will
access a different row from all other threads. [Unless there are more threads than there
are rows in the array.]
Note: the function splits the line at every comma by default. If you want to enter columns
containing commas, then you will need to change the delimiter to a character that does
not appear in any column data, by setting the property: csvread.delimiter
Control Panel
Parameters
301
Jmeter 2.3.4 User’s Manual
• COL1a ${__CSVRead(random.txt,0)}
• COL2a ${__CSVRead(random.txt,1)}${__CSVRead(random.txt,next)}
• COL1b ${__CSVRead(random.txt,0)}
• COL2b ${__CSVRead(random.txt,1)}${__CSVRead(random.txt,next)}
This would read two columns from one line, and two columns from the next available
line. If all the variables are defined on the same User Parameters Pre-Processor, then the
lines will be consecutive. Otherwise, a different thread may grab the next line.
The function is not suitable for use with large files, as the entire file is stored in memory.
For larger files, use CSV Data Set Config element or StringFromFile .
20.5.11 __property
The property function returns the value of a JMeter property. If the property value cannot
be found, and no default has been supplied, it returns the property name. When supplying
a default value, there is no need to provide a function name - the parameter can be set to
null, and it will be ignored.
For example:
Control Panel
Parameters
302
Jmeter 2.3.4 User’s Manual
Name
Variable A reference name for reusing the value computed by this
No
Name function.
Default Value The default value for the property. No
20.5.12 __P
This is a simplified property function which is intended for use with properties defined on
the command line. Unlike the __property function, there is no option to save the value in
a variable, and if no default value is supplied, it is assumed to be 1. The value of 1 was
chosen because it is valid for common test variables such as loops, thread count, ramp up
etc.
For example:
Control Panel
Parameters
20.5.13 __log
The log function logs a message, and returns its input string
Control Panel
303
Jmeter 2.3.4 User’s Manual
Parameters
The OUT and ERR log level names are used to direct the output to System.out and
System.err respectively. In this case, the output is always printed - it does not depend on
the current log setting.
For example:
${__log(Message)} - written to the log file as "...thread Name :
Message"
${__log(Message,OUT)} - written to console window
${__log(${VAR},,,VAR=)} - written to log file as "...thread Name
VAR=value"
20.5.14 __logn
The logn function logs a message, and returns the empty string
Control Panel
Parameters
The OUT and ERR log level names are used to direct the output to System.out and
System.err respectively. In this case, the output is always printed - it does not depend on
the current log setting.
304
Jmeter 2.3.4 User’s Manual
For example:
${__logn(VAR1=${VAR1},OUT)} - write the value of the variable to
the console window
20.5.15 __BeanShell
The BeanShell function evaluates the script passed to it, and returns the result.
For full details on using BeanShell, please see the BeanShell web-site at
http://www.beanshell.org/
Note that a different Interpreter is used for each independent occurence of the function in
a test script, but the same Interpreter is used for subsequent invocations. This means that
variables persist across calls to the function.
A single instance of a function may be called from multiple threads. However the
function execute() method is synchronised.
(*) means that this is set before the init file, if any, is processed. Other variables vary
from invocation to invocation.
Control Panel
Parameters
305
Jmeter 2.3.4 User’s Manual
Example:
Remember to include any necessary quotes for text strings and JMeter variables that
represent text strings.
20.5.16 __split
The split function splits the string passed to it according to the delimiter, and returns the
original string. If any delimiters are adjacent, "?" is returned as the value. The split strings
are returned in the variables ${VAR_1}, ${VAR_2} etc. The count of variables is
returned in ${VAR_n}. From JMeter 2.1.2 onwards, a trailing delimiter is treated as a
missing variable, and "?" is returned. Also, to allow it to work better with the ForEach
controller, __split now deletes the first unused variable in case it was set by a previous
split.
Example:
Define VAR="a||c|" in the test plan.
${__split(${VAR},VAR),|}
This will return the contents of VAR, i.e. "a||c|" and set the
following variables:
VAR_n=4 (3 in JMeter 2.1.1 and earlier)
VAR_1=a
VAR_2=?
VAR_3=c
VAR_4=? (null in JMeter 2.1.1 and earlier)
VAR_5=null (in JMeter 2.1.2 and later)
Control Panel
Parameters
306
Jmeter 2.3.4 User’s Manual
20.5.17 __XPath
The XPath function reads an XML file and matches the XPath. Each time the function is
called, the next match will be returned. At end of file, it will wrap around to the start. If
no nodes matched, then the function will return the empty string, and a warning message
will be written to the JMeter log file.
Example:
${__XPath(/path/to/build.xml, //target/@name)}
This will match all targets in build.xml and return the contents of the
next name attribute
Control Panel
Parameters
20.5.18 __setProperty
The setProperty function sets the value of a JMeter property. The default return value
from the function is the empty string, so the function call can be used anywhere functions
are valid.
The original value can be returned by setting the optional 3rd parameter to "true".
Properties are global to JMeter, so can be used to communicate between threads and
thread groups
Control Panel
Parameters
307
Jmeter 2.3.4 User’s Manual
20.5.19 __time
Control Panel
Parameters
If the format string is omitted, then the function returns the current time in milliseconds.
Otherwise, the current time is passed to SimpleDateFormat. The following shorthand
aliases are provided:
• YMD = yyyyMMdd
• HMS = HHmmss
• YMDHMS = yyyyMMdd-HHmmss
• USER1 = whatever is in the Jmeter property time.USER1
• USER2 = whatever is in the Jmeter property time.USER2
The defaults can be changed by setting the appropriate JMeter property, e.g.
time.YMD=yyMMdd
20.5.20 __jexl
The jexl function returns the result of evaluating a Commons JEXL expression . See links
below for more information on JEXL expressions.
Control Panel
308
Jmeter 2.3.4 User’s Manual
Parameters
Jexl can also create classes and call methods on them, for example:
Systemclass=log.class.forName("java.lang.System");
now=Systemclass.currentTimeMillis(); Note that the Jexl documentation on the
web-site wrongly suggests that "div" does integer division. In fact "div" and "/" both
perform normal division. One can get the same effect as follows: i= 5 / 2;
i.intValue(); // or use i.longValue()
Versions of JMeter after 2.3.2 allow the expression to contain multiple statements.
JMeter 2.3.2 and earlier only processed the first statement (if there were multiple
statements a warning was logged).
20.5.21 __V
The V (variable) function returns the result of evaluating a variable name expression.
This can be used to evaluate nested variable references (which are not currently
supported).
• ${A1} - works OK
• ${A${N}} - does not work (nested variable reference)
• ${__V(A${N})} - works OK. A${N} becomes A1, and the __V function returns
the value of A1
309
Jmeter 2.3.4 User’s Manual
Control Panel
Parameters
20.5.22 __evalVar
The eval function returns the result of evaluating an expression stored in a variable.
This allows one to read a string from a file, and process any variable references in it. For
example, if the variable "query" contains "select ${column} from ${table}" and
"column" and "table" contain "name" and "customers", then ${__evalVar(query)} will
evaluate as "select name from customers".
Control Panel
Parameters
20.5.23 __eval
This allows one to interpolate variable and function references in a string which is stored
in a variable. For example, given the following variables:
• name=Smith
• column=age
• table=birthdays
• SQL=select ${column} from ${table} where name='${name}'
310
Jmeter 2.3.4 User’s Manual
This can be used in conjunction with CSV Dataset, for example where the both SQL
statements and the values are defined in the data file.
Control Panel
Parameters
20.5.24 __char
The char function returns the result of evaluating a list of numbers as Unicode characters.
See also __unescape(), below.
Control Panel
Parameters
Examples:
${__char(0xC,0xA)} = CRLF
${__char(165)} = � (yen)
20.5.25 __unescape
The unescape function returns the result of evaluating a Java-escaped string. See also
__char() above.
This allows one to add characters to fields which are otherwise tricky (or impossible) to
define via the GUI.
Control Panel
311
Jmeter 2.3.4 User’s Manual
Parameters
Examples:
${__unescape(\r\n)} = CRLF
${__unescape(1\t2)} = 1[tab]2
20.5.26 __unescapeHtml
Function to unescape a string containing HTML entity escapes to a string containing the
actual Unicode characters corresponding to the escapes. Supports HTML 4.0 entities.
If an entity is unrecognized, it is left alone, and inserted verbatim into the result string.
e.g. ">&zzzz;x" will become ">&zzzz;x" .
Control Panel
Parameters
20.5.27 __escapeHtml
Function which escapes the characters in a String using HTML entities. Supports HTML
4.0 entities.
Control Panel
312
Jmeter 2.3.4 User’s Manual
Parameters
Some built-in properties are defined by JMeter. These are listed below. For convenience,
the START properties are also copied to variables with the same names.
Please note that the START variables / properties represent JMeter startup time, not the
test start time. They are mainly intended for use in file names etc.
313
Jmeter 2.3.4 User’s Manual
The pattern matching is very similar to the pattern matching in Perl. A full installation of
Perl will include plenty of documentation on regular expressions - look for perlrequick,
perlretut, perlre, perlreref.
It is worth stressing the difference between "contains" and "matches", as used on the
Response Assertion test element:
• "contains" means that the regular expression matched at least some part of the
target, so 'alphabet' "contains" 'ph.b.' because the regular expression matches the
substring 'phabe'.
• "matches" means that the regular expression matched the whole target. So
'alphabet' is "matched" by 'al.*t'.
In this case, it is equivalent to wrapping the regular expression in ^ and $, viz '^al.*t$'.
However, this is not always the case. For example, the regular expression 'alp|.lp.*' is
"contained" in 'alphabet', but does not match 'alphabet'.
Why? Because when the pattern matcher finds the sequence 'alp' in 'alphabet', it stops
trying any other combinations - and 'alp' is not the same as 'alphabet', as it does not
include 'habet'.
Note: unlike Perl, there is no need to (i.e. do not) enclose the regular expression in //.
So how does one use the modifiers ismx etc if there is no trailing /? The solution is to use
extended regular expressions , i.e. /abc/i becomes (?i)abc. See also Placement of
modifiers below.
21.2 Examples
Extract single string
Suppose you want to match the following portion of a web-page:
name="file" value="readme.txt" and you want to extract readme.txt.
A suitable reqular expression would be:
name="file" value="(.+?)"
314
Jmeter 2.3.4 User’s Manual
Note: without the ?, the .+ would continue past the first " until it found the last possible "
- probably not what was intended.
The JMeter Regex Extractor saves the values of the groups in additional variables.
• MYREF: file.namereadme.txt
• MYREF_g0: name="file.name" value="readme.txt"
• MYREF_g1: file.name
• MYREF_g2: readme.txt
These variables can be referred to later on in the JMeter test plan, as ${MYREF},
${MYREF_g1} etc
Single-line mode
315
Jmeter 2.3.4 User’s Manual
Default behaviour is that '.' matches any character except newline. In single-line mode, '.'
also matches newline.
Multi-line mode
Multi-line mode only affects how the meta-characters '^' and '$' are interpreted.
Default behaviour is that '^' and '$' only match at the very beginning and end of the string.
When Multi-line mode is used, the '^' metacharacter matches at the beginning of every
line, and the '$' metacharacter matches at the end of every line.
• ( ) - grouping
• [ ] - character classes
• { } - repetition
• * + ? - repetition
• . - wild-card character
• \ - escape character
• | - alternatives
• ^ $ - start and end of string or line
Please note that ORO does not support the \Q and \E meta-characters. [In other RE
engines, these can be used to quote a portion of an RE so that the meta-characters stand
for themselves.]
The single-line (?s) and multi-line (?m) modifiers are normally placed at the start of the
regex.
The ignore-case modifier (?i) may be usefully applied to just part of a regex, for example:
316
Jmeter 2.3.4 User’s Manual
Another approach is to use a simple test plan to test the regular expressions. The Java
Request sampler can be used to generate a sample, or the HTTP Sampler can be used to
load a file. Add a Debug Sampler and a Tree View Listener and changes to the regular
expression can be tested quickly, without needing to access any external servers.
317
Jmeter 2.3.4 User’s Manual
22. Glossary
Elapsed time
JMeter measures the elapsed time from just before sending the request to just after the
last response has been received. JMeter does not include the time needed to render the
response, nor does JMeter process any client code, for example Javascript.
Latency
JMeter measures the latency from just before sending the request to just after the first
response has been received. Thus the time includes all the processing needed to assemble
the request as well as assembling the first part of the response, which in general will be
longer than one byte. Protocol analysers (such as Wireshark) measure the time when
bytes are actually sent/received over the interface. The JMeter time should be closer to
that which is experienced by a browser or other application client.
Median is a number which divides the samples into two equal halves. Half of the
samples are smaller than the median, and half are larger. [Some samples may equal the
median.] This is a standard statistical measure. See, for example: Median entry at
Wikipedia. The Median is the same as the 50 th Percentile
90% Line (90 th Percentile) is the value below which 90% of the samples fall. The
remaining samples too at least as long as the value. This is a standard statistical measure.
See, for example: Percentile entry at Wikipedia.
The Thread Name as it appears in Listeners and logfiles is derived from the Thread
Group name and the thread within the group.
The name has the format groupName + " " + groupIndex + "-" + threadIndex
where:
A test plan with two Thread Groups each with two threads would use the names:
Thread Group 1-1
Thread Group 1-2
Thread Group 2-1
Thread Group 2-2
Throughput is calculated as requests/unit of time. The time is calculated from the start
of the first sample to the end of the last sample. This includes any intervals between
318
Jmeter 2.3.4 User’s Manual
319