User's Manual

Click on the section name to go straight to the section. Click on the "+" to go to the relevant section
of the detailed section list, where you can select individual subsections.

Section Summary
 Changes
 + ... 1. Introduction
 + ... 2. Getting Started
 + ... 3. Building a Test Plan
 + ... 4. Elements of a Test Plan
 + ... 5. Building a Web Test Plan
 + ... 6. Building an Advanced Web Test Plan
 + ... 7. Building a Database Test Plan
 + ... 8. Building an FTP Test Plan
 + ... 9a. Building an LDAP Test Plan
 + ... 9b. Building an Extended LDAP Test Plan
 + ... 10. Building a Webservice Test Plan
 + ... 11. Building a JMS Point to point Test Plan
 + ... 12. Building a JMS Topic Test Plan
 + ... 13. Building a Monitor Test Plan
 + ... 14. Listeners
 + ... 15. Remote Testing
 + ... 16. Best Practices
 + ... 17. Help! My boss wants me to load test our web app!
 + ... 18. Component Reference
 + ... 19. Functions
 + ... 20. Regular Expressions
 + ... 21. Hints and Tips

 + ... 22. Glossary

Detailed Section List

 1. Introduction
 o 1.1 History

o 1.2 The Future

 2. Getting Started
o 2.1 Requirements

 2.1.1 Java Version

 2.1.2 Operating Systems
o 2.2 Optional

 2.2.1 Java Compiler

 2.2.2 SAX XML Parser
 2.2.3 Email Support
 2.2.4 SSL Encryption
 2.2.5 JDBC Driver
 2.2.6 Apache SOAP
 2.2.7 BeanShell
 2.2.8 Libraries for ActiveMQ 3.0
o 2.3 Installation

 2.3.1 Downloading the Latest Release

 2.3.2 Downloading Nightly Builds
o 2.4 Running JMeter

 2.4.1 JMeter's Classpath

 2.4.2 Using a Proxy Server
 2.4.3 Non-GUI Mode
 2.4.4 Distributed Mode
 2.4.5 Overriding Properties Via The Command Line
 2.4.6 Logging and Error Messages
 2.4.7 Full list of command-line options
o 2.5 Configuring JMeter
 3. Building a Test Plan
o 3.1 Adding and Removing Elements

o 3.2 Loading and Saving Elements

o 3.3 Configuring Tree Elements

o 3.4 Saving the Test Plan

o 3.5 Running a Test Plan

o 3.6 Error reporting

 4. Elements of a Test Plan

o 4.1 Thread Group

o 4.2 Controllers

 4.2.1 Samplers
 4.2.2 Logic Controllers
o 4.3 Listeners

o 4.4 Timers

o 4.5 Assertions

o 4.6 Configuration Elements

o 4.7 Pre-Processor Elements

o 4.8 Post-Processor Elements

o 4.9 Execution order

o 4.10 Scoping Rules

o 4.11 Properties and Variables

o 4.12 Using Variables to parameterise tests

 5. Building a Web Test Plan

o 5.1 Adding Users

o 5.2 Adding Default HTTP Request Properties

o 5.3 Adding Cookie Support

o 5.4 Adding HTTP Requests

o 5.5 Adding a Listener to View/Store the Test Results

 o 5.6 Logging in to a web-site

 6. Building an Advanced Web Test Plan

o 6.1 Handling User Sessions With URL Rewriting

o 6.2 Using a Header Manager

 7. Building a Database Test Plan

o 7.1 Adding Users

o 7.2 Adding JDBC Requests

o 7.3 Adding a Listener to View/Store the Test Results

 8. Building an FTP Test Plan

o 8.1 Adding Users

o 8.2 Adding Default FTP Request Properties

o 8.3 Adding FTP Requests

o 8.4 Adding a Listener to View/Store the Test Results

 9a. Building an LDAP Test Plan

o 9a.1 Adding Users

o 9a.2 Adding Login Config Element

o 9a.3 Adding LDAP Request Defaults

o 9a.4 Adding LDAP Requests

o 9a.5 Adding a Listener to View/Store the Test Results

 9b. Building an Extended LDAP Test Plan

o 9b.1 Adding Users

o 9b.2 Adding LDAP Extended Request Defaults

o 9b.3 Adding LDAP Requests

o 9b.4 Adding a Listener to View/Store the Test Results

 10. Building a Webservice Test Plan

 11. Building a JMS Point to point Test Plan
 12. Building a JMS topic Test Plan
 13. Building a Monitor Test Plan
 14. Listeners
 15. Remote Testing
 16. Best Practices
o 16.1 Limit the Number of Threads

o 16.2 Where to Put the Cookie Manager

o 16.3 Where to Put the Authorization Manager

o 16.4 Using the Proxy Server to record test scripts

o 16.5 User variables

o 16.6 Reducing resource requirements

o 16.7 BeanShell server

o 16.8 BeanShell scripting

o 16.9 Developing script functions in BeanShell, Javascript or

Jexl etc.
o 16.10 Parameterising tests

 17. Help! My boss wants me to load test our web app!

 18. Component Reference
 19. Functions
 20. Regular Expressions
 21. Hints and Tips

 22. Glossary
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.

But please note that JMeter is not a browser.

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.

1.2 The Future

We hope to see JMeter's capabilities rapidly expand as developers take advantage of its
pluggable architecture. The primary goal of further development is to make JMeter the most
useful regression testing tool as possible, without compromising JMeter's load-testing
capabilities.
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.

JMeter includes the JMS API jar, but does not include a JMS client implementation. If you
want to run JMS tests, you will need to download the appropriate jars from the JMS
provider.

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:
  Advanced Web Test Plan
 JDBC
 FTP
 JMS Point-to-Point
 JMS Topic
 LDAP
 LDAP Extended
 WebServices (SOAP)

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.

2.1.1 Java Version

JMeter requires a fully compliant JVM 1.5 or
higher.
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.

2.1.2 Operating Systems

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:

 Unix (Solaris, Linux, etc)
 Windows (98, NT, XP, etc)

 OpenVMS Alpha 7.3+

2.2 Optional
If you plan on doing JMeter development, then you will need one or more optional packages listed
below.

2.2.1 Java Compiler

If you want to build the JMeter source or develop JMeter plugins, then you will need a fully
compliant JDK 1.5 or higher.
2.2.2 SAX XML Parser
JMeter comes with Apache's Xerces XML parser . You have the option of telling JMeter to
use a different XML parser. To do so, include the classes for the third-party parser in
JMeter's classpath , and update the jmeter.properties file with the full classname of the
parser implementation.

2.2.3 Email Support

JMeter has extensive Email capabilities. It can send email based on test results, and has a
POP3(S)/IMAP(S) sampler. It also has an SMTP sampler.

2.2.4 SSL Encryption

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
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 HTTP 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 HTTP samplers are configured to accept all certificates, whether trusted
or not, regardless of validity periods etc. This is to allow the maximum flexibility in
testing servers.

If the server requires a client certificate, this can be provided.

There is also the SSL Manager , for greater control of certificates.

The JMeter proxy server (see below)

supports recording HTTPS (SSL) in versions
after 2.3.4
The SMTP sampler can optionally use a local trust store or trust all certificates.

2.2.5 JDBC Driver

You will need to add your database vendor's JDBC driver to the classpath if you want to do
JDBC testing. Make sure the file is a jar file, not a zip.

2.2.6 JMS client

JMeter now includes the JMS API from Apache Geronimo, so you just need to add the
appropriate JMS Client implementation jar(s) from the JMS provider. Please refer to their
documentation for details. There may also be some information on the JMeter Wiki .

2.2.7 Libraries for ActiveMQ JMS

At the time of writing, the current version of ActiveMQ is 5.3.2. You will need to add the
jar activemq-all-5.3.2.jar to your classpath, e.g. by storing it in the lib/ directory.
Alternatively, add the jar activemq-core-5.3.2.jar to the classpath; this requires the
javax/management/j2ee classes which can be found in the Apache Geronimo jar geronimo-
j2ee-management_1.0_spec-1.0.jar. The other required jars (such as commons-logging) are
already included with JMeter.

See http://activemq.apache.org/initial-configuration.html for details.

See the JMeter Classpath section for more

details on installing additional jars.

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):

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.

2.4 Running JMeter

To run JMeter, run the jmeter.bat (for Windows) or jmeter (for Unix) file. These files are
found in the bin directory. After a short pause, the JMeter GUI should appear.

There are some additional scripts in the bin directory that you may find useful. Windows
script files (the .CMD files require Win2K or later):

 jmeter.bat - run JMeter (in GUI mode by default)

 jmeter-n.cmd - drop a JMX file on this to run a non-GUI test
  jmeter-n-r.cmd - drop a JMX file on this to run a non-GUI test remotely
 jmeter-t.cmd - drop a JMX file on this to load it in GUI mode
 jmeter-server.bat - start JMeter in server mode
 mirror-server.cmd - runs the JMeter Mirror Server in non-GUI mode
 shutdown.cmd - Run the Shutdown client to stop a non-GUI instance
gracefully
 stoptest.cmd - Run the Shutdown client to stop a non-GUI instance abruptly

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:

set JVM_ARGS="-Xms1024m -Xmx1024m -Dpropname=propvalue"

jmeter -t test.jmx ...

Un*x script files; should work on most Linux/Unix systems:

 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.
 mirror-server.sh - runs the JMeter Mirror Server in non-GUI mode
 shutdown.sh - Run the Shutdown client to stop a non-GUI instance gracefully
 stoptest.sh - Run the Shutdown client to stop a non-GUI instance abruptly

It may be necessary to edit the jmeter shell script if some of the JVM options are not
supported by the JVM you are using. The JVM_ARGS environment variable can be used to
override or set additional JVM options, for example:

JVM_ARGS="-Xms1024m -Xmx1024m" jmeter -t test.jmx [etc.]

will override the HEAP settings in the script.

2.4.1 JMeter's Classpath
JMeter automatically finds classes from jars in the following directories:
 JMETER_HOME/lib - used for utility jars
 JMETER_HOME/lib/ext - used for JMeter components and add-ons
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.

Support jars (libraries etc) should be placed in the lib directory.

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, JMS implementations and any other support libaries needed by
the JMeter code) should be placed in the lib directory - not the lib/ext directory

Note: JMeter will only find .jar files, not .zip.

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.]

2.4.2 Using a Proxy Server

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:

-H [proxy server hostname or ip address]

-P [proxy server port]

-N [nonproxy hosts] (e.g. *.apache.org|localhost)

-u [username for proxy authentication - if required]

-a [password for proxy authentication - if required]

Example : jmeter -H my.proxy.server -P 8000 -u username -a password -N localhost

Alternatively, you can use --proxyHost, --proxyPort, --username, and --password

JMeter also has its own in-built HTTP Proxy

Server , which can be used for recording
HTTP or 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.

2.4.3 Non-GUI Mode (Command Line mode)

For non-interactive testing, you may choose to run JMeter without the GUI. To do so, use
the following command options

-n This specifies JMeter is to run in non-gui mode

-t [name of JMX file that contains the Test Plan].

-l [name of JTL file to log sample results to].

-j [name of JMeter run log file].

-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:

-H [proxy server hostname or ip address]

-P [proxy server port]

Example : jmeter -n -t my_test.jmx -l log.jtl -H my.proxy.server -P 8000

2.4.4 Server Mode

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:

-H [proxy server hostname or ip address]

-P [proxy server port]

Example : jmeter-server -H my.proxy.server -P 8000

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:

jmeter -n -t testplan.jmx -r [-Gprop=val] [-Gglobal.properties] [-Z]

where:
-G is used to define JMeter properties to be set in the servers
-X means exit the servers at the end of the test
-Rserver1,server2 - can be used instead of -r to provide a list of servers
to start
Overrides remote_hosts, but does not define the property.

2.4.5 Overriding Properties Via The Command Line

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:

-D[prop_name]=[value] - defines a java system property value.

-J[prop name]=[value] - defines a local JMeter property.

-G[prop name]=[value] - defines a JMeter property to be sent to all remote servers.

-G[propertyfile] - defines a file containing JMeter properties to be sent to all remote servers.

-L[category]=[priority] - overrides a logging setting, setting a particular category to the

given priority level.

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.

2.4.6 Logging and error messages

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 mis-spelt 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 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:

10/17/2003 12:19:20 PM INFO - jmeter.JMeter: Version 1.9.20031002

10/17/2003 12:19:45 PM INFO - jmeter.gui.action.Load: Loading file:
c:\mytestfiles\BSH.jmx
10/17/2003 12:19:52 PM INFO - jmeter.engine.StandardJMeterEngine: Running
the test!
10/17/2003 12:19:52 PM INFO - jmeter.engine.StandardJMeterEngine:
Starting 1 threads for group BSH. Ramp up = 1.
10/17/2003 12:19:52 PM INFO - jmeter.engine.StandardJMeterEngine:
Continue on error
10/17/2003 12:19:52 PM INFO - jmeter.threads.JMeterThread: Thread BSH1-1
started
10/17/2003 12:19:52 PM INFO - jmeter.threads.JMeterThread: Thread BSH1-1
is done
10/17/2003 12:19:52 PM INFO - jmeter.engine.StandardJMeterEngine: Test
has ended

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.

2.4.7 Full list of command-line options

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
run JMeter in nongui mode
-s, --server
run the JMeter server
-H, --proxyHost {argument}
Set a proxy server for JMeter to use
-P, --proxyPort {argument}
Set proxy server port for JMeter to use
-u, --username {argument}
Set username for proxy server that JMeter is to use
-a, --password {argument}
Set password for proxy server that JMeter is to use
-J, --jmeterproperty {argument}={value}
Define additional JMeter properties
-G, --globalproperty (argument)[=(value)]
Define Global properties (sent to servers)
e.g. -Gport=123
or -Gglobal.properties
-D, --systemproperty {argument}={value}
Define additional System properties
-S, --systemPropertyFile {filename}
a property file to be added as System properties
-L, --loglevel {argument}={value}
Define loglevel: [category=]level
e.g. jorphan=INFO or jmeter.util=DEBUG
-r, --runremote (non-GUI only)
Start remote servers (as defined by the jmeter property
remote_hosts)
-R, --remotestart server1,... (non-GUI only)
Start these remote servers (overrides remote_hosts)
-d, --homedir {argument}
the jmeter home directory to use
-X, --remoteexit
Exit the remote servers at end of test (non-GUI)

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.

2.5 Configuring JMeter

If you wish to modify the properties with which JMeter runs you need to either modify the
jmeter.properties in the /bin directory or create your own copy of the jmeter.properties and
specify it in the command line.

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.

Parameters

Attribute Description Required

You can specify the class for your SSL implementation if you
ssl.provider No
don't want to use the built-in Java implementation.
You can specify an implementation as your XML parser. The
xml.parser No
default value is: org.apache.xerces.parsers.SAXParser
Comma-delimited list of remote JMeter hosts (or host:port if
required). If you are running JMeter in a distributed
remote_hosts environment, list the machines where you have JMeter remote No
servers running. This will allow you to control those servers
from this machine's GUI
A list of components you do not want to see in JMeter's menus.
As JMeter has more and more components added, you may
wish to customize your JMeter to show only those components
not_in_menu No
you are interested in. You may list their classname or their
class label (the string that appears in JMeter's UI) here, and
they will no longer appear in the menus.
List of paths (separated by ;) that JMeter will search for JMeter
search_paths add-on classes; for example additional samplers. This is in No
addition to any jars found in the lib/ext directory.
List of paths that JMeter will search for utility classes. This is
user.classpath No
in addition to any jars found in the lib directory.
Name of file containing additional JMeter properties. These are
user.properties added after the initial property file, but before the -q and -J No
options are processed.
Name of file containing additional system properties. These are
system.properties No
added before the -S and -D options are processed.

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

See also the comments in the jmeter.properties, user.properties and system.properties

files for further information on other settings you can change.
3. Building a Test Plan
A test plan describes a series of steps JMeter will execute when run. A complete test plan will
consist of one or more Thread Groups, logic conrollers, sample generating controllers, listeners,
timers, assertions, and configuration elements.

3.1 Adding and Removing Elements

Adding elements to a test plan can be done by right-clicking on an element in the tree, and
choosing a new element from the "add" list. Alternatively, elements can be loaded from file
and added by choosing the "merge" or "open" option.
To remove an element, make sure the element is selected, right-click on the element, and
choose the "remove" option.

3.2 Loading and Saving Elements

To load an element from file, right click on the existing tree element to which you want to
add the loaded element, and select the "merge" option. Choose the file where your elements
are saved. JMeter will merge the elements into the tree.

To save tree elements, right click on an element and choose the "Save Selection As ..."
option. JMeter will save the element selected, plus all child elements beneath it. In this way,
you can save test tree fragments and individual elements for later use.

The workbench is not automatically saved

with the test plan, but it can be saved
separately as above.

3.3 Configuring Tree Elements

Any element in the test tree will present controls in JMeter's right-hand frame. These
controls allow you to configure the behavior of that particular test element. What can be
configured for an element depends on what type of element it is.

The Test Tree itself can be manipulated by

dragging and dropping components around
the test tree.
3.4 Saving the Test Plan
Although it is not required, we recommend that you save the Test Plan to a file before
running it. To save the Test Plan, select "Save" or "Save Test Plan As ..." from the File
menu (with the latest release, it is no longer necessary to select the Test Plan element first).

JMeter allows you to save the entire Test

Plan tree or only a portion of it. To save only
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 Selection As ..."
menu item. Alternatively, select the
appropriate Test Plan element and then select
"Save Selection As ..." from the Edit menu.

3.5 Running a Test Plan

To run your test plan, choose "Start" (Control + r) from the "Run" menu item. When JMeter
is running, it shows a small green box at the right hand end of the section just under the
menu bar. You can also check the "Run" menu. If "Start" is disabled, and "Stop" is enabled,
then JMeter is running your test plan (or, at least, it thinks it is).
The numbers to the left of the green box are the number of active threads / total number of
threads. These only apply to a locally run test; they do not include any threads started on
remote systems when using client-server mode.

3.6 Stopping a Test

There are two types of stop command available from the menu:
 Stop (Control + '.') - stops the threads immediately if possible. In
Versions of JMeter after 2.3.2, many samplers are now Interruptible
which means that active samples can be terminated early. The stop
command will check that all threads have stopped within the default
timeout, which is 5000 ms = 5 seconds. [This can be changed using
the JMeter property jmeterengine.threadstop.wait ] If the
threads have not stopped, then a message is displayed. The Stop
command can be retried, but if it fails, then it is necessary to exit
JMeter to clean up.
 Shutdown (Control + ',')- requests the threads to stop at the end of any
 current work. Will not interrupt any active samples. The modal
shutdown dialog box will remain active until all threads have stopped.

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:

 Shutdown - graceful shutdown

 StopTestNow - immediate shutdown

These commands can be sent by using the shutdown[.cmd|.sh] or stoptest[.cmd|.sh]

script respectively. The scripts are to be found in the JMeter bin directory.

3.7 Error reporting

JMeter reports warnings and errors to the jmeter.log file, as well as some information on the
test run itself. Just occasionally there may be some errors that JMeter is unable to trap and
log; these will appear on the command console. If a test is not behaving as you expect,
please check the log file in case any errors have been reported (e.g. perhaps a syntax error in
a function call).
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.
4. Elements of a Test Plan
The Test Plan object has a checkbox called "Functional Testing". If selected, it will cause
JMeter to record the data returned from the server for each sample. If you have selected a file
in your test listeners, this data will be written to file. This can be useful if you are doing a
small run to ensure that JMeter is configured correctly, and that your server is returning the
expected results. The consequence is that the file will grow huge quickly, and JMeter's
performance will suffer. This option should be off if you are doing stress-testing (it is off by
default).

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:
 Set the number of threads
 Set the ramp-up period
 Set the number of times to execute the test

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).

Start with Ramp-up = number of threads and adjust up or down as needed.

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 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.

JMeter samplers include:

 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).

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.

JMeter's built-in samplers

4.2.2 Logic Controllers

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, cause 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 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.

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.

There are several listeners that come with JMeter.

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 sampler which is
in its scope .

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.

Note that assertions apply to all samplers which are in its scope . To restrict the assertion to
a single sampler, add the assertion as a child of the sampler.

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.

4.6 Configuration Elements

A configuration element works closely with a Sampler. Although it does not send requests
(except for HTTP Proxy Server ), it can add to or modify requests.

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).

Figure 1 - Test Plan Showing Accessability of Configuration Elements

The User Defined Variables Configuration
element is different. It is processed at the
start of a test, no matter where it is placed.
For simplicity, it is suggested that the
element is placed only at the start of a Thread
Group.

4.7 Pre-Processor Elements

A Pre-Processor executes some action prior to a Sampler Request being made. If a Pre-
Processor is attached to a Sampler element, then it will execute just prior to that sampler
element running. A Pre-Processor is most often used to modify the settings of a Sample
Request just before it runs, or to update variables that aren't extracted from response text.
See the scoping rules for more details on when Pre-Processors are executed.

4.8 Post-Processor Elements

A Post-Processor executes some action after a Sampler Request has been made. If a Post-
Processor is attached to a Sampler element, then it will execute just after that sampler
element runs. A Post-Processor is most often used to process the response data, often to
extract values from it. See the scoping rules for more details on when Post-Processors are
executed.
4.9 Execution order
1. Configuration elements
2. Pre-Processors
3. Timers
4. Sampler
5. Post-Processors (unless SampleResult is null)
6. Assertions (unless SampleResult is null)
7. Listeners (unless SampleResult is null)

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].

For example, in the following test plan:

 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

The order of execution would be:

Pre-Processor 1
Timer 1
Timer 2
Sampler 1
Post-Processor 1
Post-Processor 2
Assertion 1

Pre-Processor 1
Timer 1
Timer 2
Sampler 2
Post-Processor 1
Post-Processor 2
Assertion 1

4.10 Scoping Rules

The JMeter test tree contains elements that are both hierarchical and ordered. Some elements in
the test trees are strictly hierarchical (Listeners, Config Elements, Post-Procesors, Pre-Processors,
Assertions, Timers), and some are primarily ordered (controllers, samplers). When you create your
test plan, you will create an ordered list of sample request (via Samplers) that represent a set of
steps to be executed. These requests are often organized within controllers that are also ordered.
Given the following test tree:

Example test tree

The order of requests will be, One, Two, Three, Four.

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

Assertion #1 is applied only to Request One, while Assertion #2 is applied to Requests Two
and Three.

Another example, this time using Timers:

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.

The Configuration elements Header Manager, Cookie Manager and Authorization

manager are treated differently from the Configuration Default elements. The settings
from the Configuration Default elements are merged into a set of values that the
Sampler has access to. However, the settings from the Managers are not merged. If
more than one Manager is in the scope of a Sampler, only one Manager is used, but
there is currently no way to specify which is used.
4.11 Properties and Variables
JMeter properties are defined in jmeter.properties (see Gettting Started - Configuring
JMeter for more details).

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.

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.

Both variables and properties are case-

sensitive.

4.12 Using Variables to parameterise tests

Variables don't have to vary - they can be defined once, and if left alone, will not change
value. So you can use them as short-hand for expressions that appear frequently in a test
plan. Or for items which are constant during a run, but which may vary between runs. For
example, the name of a host, or the number of threads in a thread group.

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)}
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

5. Building a Web Test Plan

In this section, you will learn how to create a basic Test Plan to test a Web site. You will
create five users that send requests to two pages on the Jakarta Web site. Also, you will tell
the users to run their tests twice. So, the total number of requests is (5 users) x (2 requests) x
(repeat 2 times) = 20 HTTP requests. To construct the Test Plan, you will use the following
elements: Thread Group , HTTP Request , HTTP Request Defaults , and Graph Results .
For a more advanced Test Plan, see Building an Advanced Web Test Plan .

5.1 Adding Users

The first step you want to do with every JMeter Test Plan is to add a Thread Group element.
The Thread Group tells JMeter the number of users you want to simulate, how often the
users should send requests, and the how many requests they should send.

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)
Figure 5.1. Thread Group with Default Values

Start by providing a more descriptive name for our Thread Group. In the name field, enter
Jakarta Users.

Next, increase the number of users (called threads) to 5.

In the next field, the Ramp-Up Period, leave the the default value of 1 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.
Figure 5.2. Jakarta Users Thread Group

5.2 Adding Default HTTP Request Properties

Now that we have defined our users, it is time to define the tasks that they will be
performing. In this section, you will specify the default settings for your HTTP requests. And
then, in section 5.3, you will add HTTP Request elements which use some of the default
settings you specified here.

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).

Figure 5.3. HTTP Request Defaults

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.

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

Figure 5.4. HTTP Defaults for our Test Plan

5.3 Adding Cookie Support

Nearly all web testing should use cookie support, unless your application specifically doesn't
use cookies. To add cookie support, simply add an HTTP Cookie Manager to each Thread
Group in your test plan. This will ensure that each thread gets its own cookies, but shared
across all HTTP Request objects.
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.

5.4 Adding HTTP Requests

In our Test Plan, we need to make two HTTP requests. The first one is for the Jakarta home
page (http://jakarta.apache.org/), and the second one is for the Project Guidelines page
(http://jakarta.apache.org/site/guidelines.html).

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):

1. Change the Name field to "Home Page".

2. Set the Path field to "/". Remember that you do not have to set the Server Name
field because you already specified this value in the HTTP Request Defaults element.

Figure 5.5. HTTP Request for Jakarta Home Page

Next, add the second HTTP Request and edit the following properties (see Figure 5.6:

1. Change the Name field to "Project Guidelines".

2. Set the Path field to "/site/guidelines.html".
Figure 5.6. HTTP Request for Jakarta Project Guidelines Page

5.5 Adding a Listener to View Store the Test Results

The final element you need to add to your Test Plan is a Listener . This element is
responsible for storing all of the results of your HTTP requests in a file and presenting a
visual model of the data.

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.
Figure 5.7. Graph Results Listener

5.6 Logging in to a web-site

It's not the case here, but some web-sites require you to login before permitting you to
perform certain actions. In a web-browser, the login will be shown as a form for the user
name and password, and a button to submit the form. The button generates a POST request,
passing the values of the form items as parameters.

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.
Figure 5.8. Sample HTTP login request

6. Building an Advanced Web Test Plan

In this section, you will learn how to create advanced Test Plans to test a Web site.
For an example of a basic Test Plan, see Building a Web Test Plan .

6.1 Handling User Sessions With URL Rewriting

If your web application uses URL rewriting rather than cookies to save session information,
then you'll need to do a bit of extra work to test your site.

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.

URL Rewriting Example

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.

Figure 1 - Test Tree

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

Figure 2 - Request parameters

6.2 Using a Header Manager

The HTTP Header Manager lets you customize what information JMeter sends in the HTTP
request header. This header includes properties like "User-Agent", "Pragma", "Referer", etc.
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.
7. Building a Database Test Plan
In this section, you will learn how to create a basic Test Plan to test a database server. You
will create ten users that send five SQL requests to the database server. Also, you will tell the
users to run their tests three times. So, the total number of requests is (10 users) x (2
requests) x (repeat 3 times) = 60 JDBC requests. To construct the Test Plan, you will use the
following elements: Thread Group , JDBC Request , Graph Results .

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).

7.1 Adding Users

The first step you want to do with every JMeter Test Plan is to add a Thread Group element.
The Thread Group tells JMeter the number of users you want to simulate, how often the
users should send requests, and the how many requests they should send.

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)

Figure 7.1. Thread Group with Default Values

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'.

Next, increase the number of users to 10.

In the next field, the Ramp-Up Period, leave the 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.

Figure 7.2. JDBC Users Thread Group

7.2 Adding JDBC Requests
Now that we have defined our users, it is time to define the tasks that they will be
performing. In this section, you will specify the JDBC requests to perform.

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

The other fields on the screen can be left as the defaults.

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.
Figure 7.3. JDBC Configuration

Selecting 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).

Figure 7.4. JDBC Request

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.

Start by editing the following properties (see Figure 7.5):

 Change the Name to "Kodak".

 Enter the Pool Name: MySQL (same as in the configuration element)
 Enter the SQL Query String field.

Figure 7.5. JDBC Request for Eastman Kodak stock

Next, add the second JDBC Request and edit the following properties (see Figure 7.6):

 Change the Name to "Pfizer".

 Enter the SQL Query String field.
Figure 7.6. JDBC Request for Pfizer stock

7.3 Adding a Listener to View/Store the Test Results

The final element you need to add to your Test Plan is a Listener . This element is
responsible for storing all of the results of your JDBC requests in a file and presenting a
visual model of the data.

Select the JDBC Users element and add a Graph Results listener (Add --> Listener --> Graph
Results).

Figure 7.7. Graph results Listener

8. Building an FTP Test Plan
In this section, you will learn how to create a basic Test Plan to test an FTP site. You will
create four users that send requests for two files on the O'Reilly FTP site. Also, you will tell
the users to run their tests twice. So, the total number of requests is (4 users) x (2 requests) x
(repeat 2 times) = 16 FTP requests. To construct the Test Plan, you will use the following
elements: Thread Group , FTP Request , FTP Request Defaults , and Spline Visualizer .

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.

8.1 Adding Users

The first step you want to do with every JMeter Test Plan is to add a Thread Group element.
The Thread Group tells JMeter the number of users you want to simulate, how often the
users should send requests, and the how many requests they should send.

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)

Figure 8.1. Thread Group with Default Values

Start by providing a more descriptive name for our Thread Group. In the name field, enter
O'Reilly Users.
Next, increase the number of users to 4.

In the next field, the Ramp-Up Period, leave the 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.

Figure 8.2. O'Reilly Users Thread Group

8.2 Adding Default FTP Request Properties
Now that we have defined our users, it is time define the tasks that they will be performing.
In this section, you will specify the default settings for your FTP requests. And then, in
section 8.3, you will add FTP Request elements which use some of the default settings you
specified here.

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).

Figure 8.3. FTP Request Defaults

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.

See Figure 8.4 for the completed FTP Request Defaults element
Figure 8.4. FTP Defaults for our Test Plan

8.3 Adding FTP Requests

In our Test Plan, we need to make two FTP requests. The first one is for the O'Reilly mSQL
Java README file (ftp://ftp.oro.com/pub/msql/java/README), and the second is for the
tutorial file (ftp://ftp.oro.com/pub/msql/java/tutorial.txt).

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):

1. Change the Name to "README".

2. Change the File to Retrieve From Server field to "pub/msql/java/README".
3. Change the Username field to "anonymous".
4. Change the Password field to "anonymous".

You do not have to set the Server Name field

because you already specified this value in
the FTP Request Defaults element.
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:

1. Change the Name to "tutorial".

2. Change the File to Retrieve From Server field to "pub/msql/java/tutorial.txt".
3. Change the Username field to "anonymous".
4. Change the Password field to "anonymous".

Figure 8.6. FTP Request for O'Reilly mSQL Java tutorial file

8.4 Adding a Listener to View/Store the Test Results

The final element you need to add to your Test Plan is a Listener . This element is
responsible for storing all of the results of your FTP requests in a file and presenting a visual
model of the data.
Select the O'Reilly Users element and add a Spline Visualizer listener (Add --> Listener -->
Spline Visualizer).

Figure 8.7. Spline Visualizer Listener

9a. Building an LDAP Test Plan

In this section, you will learn how to create a basic Test Plan to test an LDAP server. 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 , LDAP Request , LDAP Request Defaults , and View Results in
Table .
This example assumes that the LDAP Server is installed in your Local machine.

9a.1 Adding Users

The first step you want to do with every JMeter Test Plan is to add a Thread Group element.
The Thread Group tells JMeter the number of users you want to simulate, how often the
users should send requests, and the how many requests they should send.

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.
Figure 9a.1. Thread Group with Default Values

9a.2 Adding Login Config Element

Begin by selecting the Siptech Users element. Click your right mouse button to get the Add
menu, and then select Add --> Config Element --> Login Config Element. Then, select this
new element to view its Control Panel.

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.

Figure 9a.2 Login Config Element for our Test Plan

Enter Username field to "your Server
Username",

The password field to "your Server

Passowrd"
These values are default for the LDAP
Requests.
9a.3 Adding LDAP Request Defaults
Begin by selecting the Siptech Users element. Click your right mouse button to get the Add
menu, and then select Add --> Config Element -->LDAP Request Defaults. Then, select this
new element to view its Control Panel.

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.

Figure 9a.3 LDAP Defaults for our Test Plan

Enter DN field to "your Server Root Dn".

Enter LDAP Server's Servername field to

"localhost".

The port to 389.

These values are default for the LDAP

Requests.

9a.4 Adding LDAP Requests

In our Test Plan, we need to make four LDAP requests.
1. Inbuilt Add Test
2. Inbuilt Modify Test
3. Inbuilt Delete Test
4. Inbuilt Search Test

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

1. Change the Name to "Inbuilt-Add Test".

2. Select the Add test Radio button

Figure 9a.4.1 LDAP Request for Inbuilt Add test

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

1. Change the Name to "Inbuilt-Modify Test".

2. Select the Modify test Radio button
Figure 9a.4.2 LDAP Request for Inbuilt Modify test
1. Change the Name to "Inbuilt-Delete Test".
2. Select the Delete test Radio button

Figure 9a.4.3 LDAP Request for Inbuilt Delete test

1. Change the Name to "Inbuilt-Search Test".
2. Select the Search test Radio button
Figure 9a.4.4 LDAP Request for Inbuilt Search test

9a.5 Adding a Listener to View/Store the Test Results

The final element you need to add to your Test Plan is a Listener. This element is responsible for
storing all of the results of your LDAP requests in a file and presenting a visual model of the
data.Select the Siptech Users element and add a View Results in Table (Add --> Listener -->View
Results in Table)

Figure 9a.5 View result in Table Listener

9b. Building an Extended LDAP Test Plan

In this section, you will learn how to create a basic Test Plan to test an LDAP server.

As the Extended LDAP Sampler is highly configurable, this also means that it takes some
time to build a correct testplan. 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 testplan.

Take care when using LDAP special characters in the distinghuished name, in that case (eg, you want
to use a + sign in a distinghuished name) you need to escape the character by adding an "\" sign
before that character. extra exeption: 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

9b.1 Adding Users

The first step you want to do with every JMeter Test Plan is to add a Thread Group element.
The Thread Group tells JMeter the number of users you want to simulate, how often the
users should send requests, and the how many requests they should send.

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.
Figure 9b.1. Thread Group with Default Values

9b.2 Adding LDAP Extended Request Defaults

Begin by selecting the Thread Group element. Click your right mouse button to get the Add
menu, and then select Add --> Config Element -->LDAP Extended Request Defaults. Then,
select this new element to view its Control Panel.

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.

Figure 9b.2 LDAP Defaults for our Test Plan

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!
9b.3 Adding LDAP Requests
In our Test Plan, we want to use all 8 LDAP requests.
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.

Adding a requests always start by:

Adding the LDAP Extended Request to the Thread Group element (Add --> Sampler --> LDAP Ext
Request). Then, select the LDAP Ext Request element in the tree and edit the following properties.

9b.3.1 Adding a Thread bind Request

1. Select the "Thread bind" button.
2. enter the hostname value from the LDAP server in the Servername field
3. Enter the portnumber from the LDAP server (389) in the port field
4. (optional) enter the baseDN in the DN field, this baseDN will be used as
thestarting point for searches, add, deletes etc.

take care that this must be the uppermost shared level for all your request, eg
When all information is stored under ou=people, dc=siemens, dc=com, you
can use this value in the basedn.

You cannot search or rename anymore in the subtree

ou=users,dc=siemens,dc=com!

If you need to search or rename objects in both subtrees, use the common
denominator (dc=siemens,dc=com) as the baseDN.
5. (Optional) enter the distinghuised name from the user you want to use for
authentication. When this field is kept empty, an anonymous bind will be
established.
6. (optional) Enter the password for the user you want to authenticate with, an
 empty password will also lead to an anonymous bind.

Figure 9b.3.1. Thread Bind example

9b.3.2 Adding a search Request

1. Select the "Search Test" button.
2. (Optional) enter the searchbase under which you want to perform the search,
relative to the basedn, used in the thread bind request.

When left empty, the basedn is used as a search base, this files is important
if you want to use a "base-entry" or "one-level" search (see below)
3. Enter the searchfilter, any decent LDAP serach filter will do, but for now,
use something simple, like cn=john doe
4. (optional) enter the scope in the scope field, it has three options:
1. Base level, Enter the value 0

only the given searchbase is used, only for checking attributes or

existence.
2. One level, Enter the value 1

Only search in one level below given searchbase is used

3. Subtree, Enter the value 2

Searches for object at any point below the given basedn

5. (Optional) Sizelimit, specifies the maximun number of returned entries,
6. (optional) Timelimit, psecifies the maximum number of miliseconds, the
SERVER can use for performing the search. it is NOT the maximun time the
 application will wait!

When a very large returnset is returned, from a very fast server, over a very
slow line, you may have to wait for ages for the completion of the search
request, but this parameter will not influence this.
7. (Optional) Attributes you want in the search answer. This can be used to
limit the size of the answer, especially when an onject has very large
attributes (like jpegPhoto). There are three possibilities:
1. Leave empty (the default setting must also be empty) This will return
all attributes.
2. Put in one empty value (""), it will request a non-existent attributes,
so in reality it returns no attributes
3. Put in the attributes, seperated by a semi-colon. It will return only the
requested attributes
8. (Optional) Return object, possible values are "true" and "false". True will
return all java-object attributes, it will add these to the requested attributes,
as specified above.

false will mean no java-object attributes will be returned.

9. (Optional) Dereference aliases. possible values "true" and "false". True will mean it
will follow references, false says it will not.

Figure 9b.3.2. search request example

9b.3.3 Adding a Compare Request

 1. Select the "Compare" button.
2. enter the entryname form the object on which you want the compare
operation to work, relative to the basedn, eg "cn=john doe,ou=people"
3. Enter the compare filter, this must be in the form "attribute=value", eg
"mail=John.doe@siemens.com"

Figure 9b.3.3. Compare example

9b.3.4 Adding a Single bind/unbind

1. Select the "Single bind/unbind" button.
2. Enter the FULL distinghuised name from the user you want to use for
authentication.

eg. cn=john doe,ou=people,dc=siemens,dc=com When this field is kept

empty, an anonymous bind will be established.
3. Enter the password for the user you want to authenticate with, an empty
password will also lead to an anonymous bind.
4. Take care: This single bind/unbind is in reality two seperate operations but cannot
easily be split!
Figure 9b.3.4. Single bind/unbind example

9b.3.5 Adding an Add Request

1. Select the "Add" button.
2. Enter the distinghuised name for the object to add, relative to the basedn.
3. Add a line in the "add test" table, fill in the attribute and value.

When you need the same attribute more than once, just add a new line, add the
attribute again, and a different value.

All necessary attributes and values must be specified to pass the test, see picture!

(sometimes the server adds the attribute "objectClass=top", this might give a
problem.
Figure 9b.3.5. Add request example

9b.3.6 Adding a Modify Request

1. Select the "Modify test" button.
2. Enter the distinghuised name for the object to modify, relative to the basedn.
3. Add a line in the "modify test" table, with the "add" button.
4. You need to enter the attribute you want to modify, (optional) a value, and
the opcode. The meaning of this opcode:
1. add

this will mean that the attribute value (not optional in this case)
willbe added to the attribute.

When the attribute is not existing, it will be created and the value
added

When it is existing, and defined multi-valued, the new value is

added.

when it is existing, but single valued, it will fail.

2. replace

This will overwrite the attribute with the given new value (not
optional here)
 When the attribute is not existing, it will be created and the value
added

When it is existing, old values are removed, the new value is added.
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.

Figure 9b.3.6. Modify example

9b.3.7 Adding a Delete Request

1. Select the "Delete" button.
2. enter the name of the entry, relative to the baseDN, in the Delete-Field.

that is, if you want to remove "cn=john doe,ou=people,dc=siemens,dc=com", and

you set the baseDN to "dc=siemens,dc=com", you need to enter "cn=john
doe,ou=people" in the Delete-field.
-
Figure 9b.3.7. Delete example

9b.3.8 Adding a Rename Request (moddn)

1. Select the "Rename Entry" button.
2. enter the name of the entry, relative to the baseDN, in the "old entry name-
Field".

that is, if you want to rename "cn=john

doe,ou=people,dc=siemens,dc=com", and you set the baseDN to
"dc=siemens,dc=com", you need to enter "cn=john doe,ou=people" in the
old entry name-field.
3. enter the new name of the entry, relative to the baseDN, in the "new
distinghuised name-Field".

whne you only change the RDN, it will simply rename the entry

when you also add a differten subtree, eg you change from cn=john
doe,ou=people to cn=john doe,ou=users, it will move the entry. You can also move
a complete subtree (If your LDAP server supports this!!!!), eg
ou=people,ou=retired, to ou=oldusers,ou=users, this will move the complete
subtee, plus all retired people in the subtree to the new place in the tree.
Figure 9b.3.8. Rename example

9b.3.9 Adding an unbind Request

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

Figure 9b.3.9. Unbind example

9b.4 Adding a Listener to View/Store the Test Results

The final element you need to add to your Test Plan is a Listener. This element is responsible for
storing all of the results of your LDAP requests in a file and presenting a visual model of the
data.Select the Thread group element and add a View Results Tree (Add --> Listener -->View
Results Tree)
Figure 9b.4. View result Tree Listener

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.
10. Building a WebService Test Plan
In this section, you will learn how to create a Test Plan to test a WebService. You will create
five users that send requests to One page. Also, you will tell the users to run their tests twice.
So, the total number of requests is (5 users) x (1 requests) x (repeat 2 times) = 10 HTTP
requests. To construct the Test Plan, you will use the following elements: Thread Group ,
WebService(SOAP) Request (Beta Code) , and Graph Results .
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.

10.1 Adding Users

The first step you want to do with every JMeter Test Plan is to add a Thread Group element.
The Thread Group tells JMeter the number of users you want to simulate, how often the
users should send requests, and the how many requests they should send.

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 10.1 below)

Figure 10.1. Thread Group with Default Values

Start by providing a more descriptive name for our Thread Group. In the name field, enter
Jakarta Users.

Next, increase the number of users (called threads) to 10.

In the next field, the Ramp-Up Period, leave the 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 10.2 for the completed Jakarta Users Thread Group.

Figure 10.2. Jakarta Users Thread Group

10.2 Adding WebService Requests

In our Test Plan, we will use a .NET webservice. Since you're using the webservice sampler,
we won't go into the details of writing a webservice. If you don't know how to write a
webservice, google for webservice and familiarize yourself with writing webservices for
Java and .NET. It should be noted there is a significant difference between how .NET and
Java implement webservices. The topic is too broad to cover in the user manual. Please refer
to other sources to get a better idea of the differences.

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 10.5):

1. Change the Name field to "WebService(SOAP) Request (Beta Code)".

2. Enter the WSDL URL and click "Load WSDL".
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.

10.3 Adding a Listener to View Store the Test Results

The final element you need to add to your Test Plan is a Listener . This element is
responsible for storing all of the results of your HTTP requests in a file and presenting a
visual model of the data.

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.
Figure 10.7. Graph Results Listener

11. Building a JMS Point-to-Point Test Plan

Make sure the required jar files are in
JMeter's lib directory. If they are not,
shutdown JMeter, copy the jar files over and
restart JMeter. See Getting Started for details.

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.

11.1 Adding a Thread Group

The first step you want to do with every JMeter Test Plan is to add a Thread Group element.
The Thread Group tells JMeter the number of users you want to simulate, how often the
users should send requests, and the how many requests they should send.

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)

Figure 11.1. Thread Group with Default Values

Start by providing a more descriptive name for our Thread Group. In the name field, enter
Point-to-Point.

Next, increase the number of users (called threads) to 5.

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).

11.2 Adding JMS Point-to-Point Sampler

Start by adding the sampler JMS Point-to-Point to the Point-to-Point element (Add --> Sampler
--> JMS Point-to-Point). Then, select the JMS Point-to-Point sampler element in the tree. In building
the example a configuration will be provided that works with ActiveMQ 3.0.

Name Value Description

JMS Resources
QueueuConnectionFactory ConnectionFactory This is the default JNDI
entry for the connection
factory within active mq.
JNDI Name Request Q.REQ This is equal to the JNDI
Queue name defined in the
JNDI properties.
JNDI Name Reply Queue Q.RPL This is equal to the JNDI
name defined in the
JNDI properties.
Message Properties
Communication Style Request Response This means that you
need at least a service
that responds to the
requests.
Content test This is just the content
of the message.
JMS Properties   Nothing needed for
active mq.
JNDI Properties
InitialContextFactory org.activemq.jndi.ActiveMQInitialContextFactory The standard
InitialContextFactory for
Active MQ
Properties
providerURL tcp://localhost:61616 This defines the URL of
the active mq
messaging system.
queue.Q.REQ example.A This defines a JNDI
name Q.REQ for the
request queue that
points to the queue
example.A
queue.Q.RPL example.B This defines a JNDI
name Q.RPL for the
reply queue that points
to the queue example.B

11.3 Adding a Listener to View Store the Test Results

The final element you need to add to your Test Plan is a Listener . This element is
responsible for storing all of the results of your JMS requests in a file and presenting a visual
model of the data.

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.

Figure 11.2. Graph Results Listener

12. Building a JMS Topic Test Plan

JMS requires some optional jars to be
downloaded. Please refer to Getting Started
for full details.

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.

12.1 Adding Users

The first step is add a Thread Group element. The Thread Group tells JMeter the number of
users you want to simulate, how often the users should send requests, and how many
requests they should send.

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)

Figure 12.1. Thread Group with Default Values

Start by providing a more descriptive name for our Thread Group. In the name field, enter
Subscribers.

Next, increase the number of users (called threads) to 5.

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).

12.2 Adding JMS Subscriber and Publisher

Make sure the required jar files are in JMeter's lib directory. If they are not, shutdown
JMeter, copy the jar files over and restart JMeter.

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:

1. Change the Name field to "sample subscriber"

2. If the JMS provider uses the jndi.properties file, check the box
3. Enter the name of the InitialContextFactory class
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
6. Enter the name of the message topic
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
8. Enter 10 in "Number of samples to aggregate". For performance reasons, the
sampler will aggregate messages, since small messages will arrive very
quickly. If the sampler didn't aggregate the messages, JMeter wouldn't be able
 to keep up.
9. If you want to read the response, check the box
10. There are two client implementations for subscribers. If the JMS provider exhibits
zombie threads with one client, try the other.

Figure 12.2. JMS Subscriber

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:

1. Change the Name field to "sample publisher".

2. If the JMS provider uses the jndi.properties file, check the box
3. Enter the name of the InitialContextFactory class.
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
6. Enter the name of the message topic
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
8. Enter 10 in "Number of samples to aggregate". For performance reasons, the
 sampler will aggregate messages, since small messages will arrive very
quickly. If the sampler didn't aggregate the messages, JMeter wouldn't be able
to keep up.
9. Select the appropriate configuration for getting the message to publish. If you
want the sampler to randomly select the message, place the messages in a
directory and select the directory using browse.
10. Select the message type. If the message is in object format, make sure the message
is generated correctly.
Figure 12.3. JMS Publisher

12.3 Adding a Listener to View Store the Test Results

The final element you need to add to your Test Plan is a Listener . This element is
responsible for storing all of the results of your HTTP requests in a file and presenting a
visual model of the data.

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.

Figure 12.4. Graph Results Listener

13. Building a Monitor Test Plan

In this section, you will learn how to create a Test Plan to monitor webservers. Monitors are
useful for a stress testing and system management. Used with stress testing, the monitor
provides additional information about server performance. It also makes it easier to see the
relationship between server performance and response time on the client side. As a system
administration tool, the monitor provides an easy way to monitor multiple servers from one
console. The monitor was designed to work with the status servlet in Tomcat 5. In theory,
any servlet container that supports JMX (Java Management Extension) can port the status
servlet to provide the same information.
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.

13.1 Adding A Server

The first step is to add a Thread Group element. The Thread Group tells JMeter the number
of threads you want. Always use 1, since we are using JMeter as a monitor. This is very
important for those not familiar with server monitors. As a general rule, using multiple
threads for a single server is bad and can create significant stress.

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.

Figure 13.1. Thread Group with Default Values

Change the loop count to forever (or some large number) so that enough samples are
generated.

13.2 HTTP Auth Manager

Add the HTTP Authorization Manager to the Thread Group element (Add --> Config
element --> HTTP Authorization Manager). Enter the username and password for your
webserver. Important note: the monitor only works with Tomcat5 build 5.0.19 and newer.
For instructions on how to setup Tomcat, please refer to tomcat 5 documentation.
1. leave the base URL blank
2. enter the username

3. enter the password

13.3 Adding HTTP Request

Add the HTTP Request to the Thread Group element (Add --> Sampler --> HTTP Request).
Then, select the HTTP Request element in the tree and edit the following properties):
1. Change the Name field to "Server Status".
2. Enter the IP address or Hostname
3. Enter the port number
4. Set the Path field to "/manager/status" if you're using Tomcat.
 5. Add a request parameter named "XML" in uppercase. Give it a value of "true"
in lowercase.

6. Check "Use as Monitor" at the bottom of the sampler

13.4 Adding Constant Timer

Add a timer to this thread group (Add --> Timer --> Constant Timer). Enter 5000
milliseconds in the "Thread Delay" box. In general, using intervals shorter than 5 seconds
will add stress to your server. Find out what is an acceptable interval before you deploy the
monitor in your production environment.

13.5 Adding a Listener to Store the Results

If you want to save the raw results from the server, add a simple data Listener . If you want
to save the calculated statistics, enter a filename in the listener. If you want to save both the
raw data and statistics, make sure you use different filenames.
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.

13.6 Adding Monitor Results

Add the Listener by selecting the test plan element (Add --> Listener -- > Monitor Results).

By default, the Listener will select the results from the first connector in the sample
response. The Connector prefix field can be used to select a different connector. If specified,
the Listener will choose the first connector which matches the prefix. If no match is found,
then the first connector is selected.

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.
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.

14. Introduction to listeners

A listener is a component that shows the results of the samples. The results can be shown in
a tree, tables, graphs or simply written to a log file. To view the contents of a response from
any given sampler, add either of the Listeners "View Results Tree" or "View Results in
table" to a test plan. To view the response time graphically, add graph results, spline results
or distribution graph. The listeners section of the components page has full descriptions of all
the listeners.

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!

14.1 Default Configuration

The default items to be saved can be defined in the jmeter.properties (or user.properties) file.
The properties are used as the initial settings for the Listener Config pop-up, and are also
used for the log file specified by the -l command-line flag (commonly used for non-GUI test
runs).

To change the default format, find the following line in jmeter.properties:

jmeter.save.saveservice.output_format=

The information to be saved is configurable. For maximum information, choose "xml" as the
format and specify "Functional Test Mode" on the Test Plan element. If this box is not
checked, the default saved data includes a time stamp (the number of milliseconds since
midnight, January 1, 1970 UTC), the data type, the thread name, the label, the response time,
message, and code, and a success indicator. If checked, all information, including the full
response data will be logged.

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:
expected to contain: password etc.

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
#-------------------------------------------------------------------------
--

# This section helps determine how result data will be saved.

# The commented out values are the defaults.

# legitimate values: xml, csv, db. Only xml and csv are currently
supported.
#jmeter.save.saveservice.output_format=xml

# true when field should be saved; false otherwise

# assertion_results_failure_message only affects CSV output

#jmeter.save.saveservice.assertion_results_failure_message=false
#
#jmeter.save.saveservice.data_type=true
#jmeter.save.saveservice.label=true
#jmeter.save.saveservice.response_code=true
# response_data is not currently supported for CSV output
#jmeter.save.saveservice.response_data=false
# Save ResponseData for failed samples
#jmeter.save.saveservice.response_data.on_error=false
#jmeter.save.saveservice.response_message=true
#jmeter.save.saveservice.successful=true
#jmeter.save.saveservice.thread_name=true
#jmeter.save.saveservice.time=true
#jmeter.save.saveservice.subresults=true
#jmeter.save.saveservice.assertions=true
#jmeter.save.saveservice.latency=true
#jmeter.save.saveservice.samplerData=false
#jmeter.save.saveservice.responseHeaders=false
#jmeter.save.saveservice.requestHeaders=false
#jmeter.save.saveservice.encoding=false
#jmeter.save.saveservice.bytes=true
#jmeter.save.saveservice.url=false
#jmeter.save.saveservice.filename=false
#jmeter.save.saveservice.hostname=false
#jmeter.save.saveservice.thread_counts=false
#jmeter.save.saveservice.sample_count=false
#jmeter.save.saveservice.idle_time=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

# Put the start time stamp in logs instead of the end

sampleresult.timestamp.start=true

# legitimate values: none, first, all

#jmeter.save.saveservice.assertion_results=none

# For use with Comma-separated value (CSV) files or other formats

# where the fields' values are separated by specified delimiters.
# Default:
#jmeter.save.saveservice.default_delimiter=,
# For TAB, since JMeter 2.3 one can use:
#jmeter.save.saveservice.default_delimiter=\t

#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.

# Optional xml processing instruction for line 2 of the file:

#jmeter.save.saveservice.xml_pi=<?xml-stylesheet type="text/xsl"
href="sample.xsl"?>

The date format to be used for the timestamp_format is described in SimpleDateFormat .

Bear in mind that choosing a date format other than "ms" is likely to make it impossible for JMeter
to interpret the value when it is read in later for viewing purposes.

14.1.1 Sample Variables

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.

14.1.2 Sample Result Save Configuration

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.

14.2 non-GUI (batch) test runs

When running in non-GUI mode, the -l flag can be used to create a top-level listener for the
test run. This is in addition to any Listeners defined in the test plan. The configuration of this
listener is controlled by entries in the file jmeter.properties as described in the previous
section.

This feature can be used to specify different data and log files for each test run, for example:

jmeter -n -t testplan.jmx -l testplan_01.jtl -j testplan_01.log

jmeter -n -t testplan.jmx -l testplan_02.jtl -j testplan_02.log

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.

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.

14.3 Resource usage

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 they display, apart from:
 Simple Data Writer
  BeanShell/BSF Listener
 Mailer Visualizer
 Monitor Results
 Summary Report

The following Listeners no longer need to keep copies of every single sample. Instead,
samples with the same elapsed time are aggregated. Less memory is now needed, especially
if most samples only take a second or two at most.

 Aggregate Report
 Aggregate Graph
 Distribution Graph

To minimise the amount of memory needed, use the Simple Data Writer, and use the CSV
format.

14.4 CSV Log format

The CSV log format depends on which data items are selected in the configuration. Only the
specified data items are recorded in the file. The order of appearance of columns is fixed,
and is as follows:
 timeStamp - in milliseconds since 1/1/1970
 elapsed - in milliseconds
 label - sampler label
 responseCode - e.g. 200, 404
 responseMessage - e.g. OK
 threadName
 dataType - e.g. text
 success - true or false
 failureMessage - if any
 bytes - number of bytes in the sample
 grpThreads - number of active threads in this thread group
 allThreads - total number of active threads in all groups
 URL
 Filename - if Save Response to File was used
 latency - time to first response
  encoding
 SampleCount - number of samples (1, unless multiple samples are
aggregated)
 ErrorCount - number of errors (0 or 1, unless multiple samples are
aggregated)
 Hostname where the sample was generated
 IdleTime - number of milliseconds of 'Idle' time (normally 0)

 Variables, if specified

14.5 XML Log format 2.1

The format of the updated XML (2.1) is as follows (line breaks will be different):

<?xml version="1.0" encoding="UTF-8"?>

<testResults version="1.2">

-- HTTP Sample, with nested samples

<httpSample t="1392" lt="351" ts="1144371014619" s="true"

lb="HTTP Request" rc="200" rm="OK"
tn="Listen 1-1" dt="text" de="iso-8859-1" by="12407">
<httpSample t="170" lt="170" ts="1144371015471" s="true"
lb="http://www.apache.org/style/style.css" rc="200" rm="OK"
tn="Listen 1-1" dt="text" de="ISO-8859-1" by="1002">
<responseHeader class="java.lang.String">HTTP/1.1 200 OK
Date: Fri, 07 Apr 2006 00:50:14 GMT
...
Content-Type: text/css
</responseHeader>
<requestHeader class="java.lang.String">MyHeader:
MyValue</requestHeader>
<responseData class="java.lang.String">body, td, th {
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">
...
&lt;html&gt;
&lt;head&gt;
...
&lt;/head&gt;
&lt;body&gt;
...
&lt;/body&gt;
&lt;/html&gt;
</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

<sample t="0" lt="0" ts="1144372616082" s="true" lb="Example Sampler"

rc="200" rm="OK" tn="Listen 1-1" dt="text" de="ISO-8859-1" by="10">
<responseHeader class="java.lang.String"></responseHeader>
<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".

14.6 XML Log format 2.2

The format of the JTL files is identical for 2.2 and 2.1. Format 2.2 only affects JMX files.

14.7 Sample Attributes

The sample attributes have the following meaning:

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
it Idle Time = time not spent sampling (milliseconds) (generally 0)
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.

14.8 Saving response data

As shown above, the response data can be saved in the XML log file if required. However,
this can make the file rather large, and the text has to be encoded so that it is still valid XML.
Also, images cannot be included.

Another solution is to use the Post-Processor Save_Responses_to_a_file . This generates a

new file for each sample, and saves the file name with the sample. The file name can then be
included in the sample log output. The data will be retrieved from the file if necessary when
the sample log file is reloaded.

14.9 Loading (reading) response data

To view an existing results file, you can use the File "Browse..." button to select a file. If
necessary, just create a dummy testplan with the appropriate Listener in it.

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.

14.10 Saving Listener GUI data

JMeter is capable of saving any listener as a PNG file. To do so, select the listener in the left
panel. Click edit -> Save As Image. A file dialog will appear. Enter the desired name and
save the listener.

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.

Figure 1 - Edit -> Save As Image

15. Remote Testing

In the event that your JMeter client machine is unable, performance-wise, to simulate enough
users to stress your server, an option exists to control multiple, remote JMeter engines from a
single JMeter GUI client. By running JMeter remotely, you can replicate a test across many
low-end computers and thus simulate a larger load on the server. One instance of the JMeter
GUI client can control any number of remote JMeter instances, and collect all the data from
them. This offers the following features:
 Saving of test samples to the local machine
  Managment of multiple JMeterEngines from a single machine
 No need to copy the test plan to each server - the client sends it to all the
servers

Note: The same test plan is run by all the

servers. JMeter does not distribute the load
between servers, each runs the full test plan.

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.

Step 0: Configure the nodes

Make sure that all the nodes (client and servers) are running exactly the same version of
JMeter. As far as possible, also use the same version of Java on all systems. Using different
versions of Java may work - but is best avoided.

If the test uses any data files, note that these are not sent across by the client so make sure
that these are available in the appropriate directory on each server. If necessary you can
define different values for properties by editting the user.properties or system.properties files
on each server. These properties will be picked up when the server is started and may be
used in the test plan to affect its behaviour (e.g. connecting to a different remote server).
Alternatively use different content in any datafiles used by the test (e.g. if each server must
use unique ids, divide these between the data files)

Step 1: Start the servers

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.

Step 2: Add the server IP to your client's Properties File

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)

Step 3a: Start the JMeter Client from a GUI client

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.

Figure 1 - Run Menu

Step 3b: Start the JMeter from a non-GUI Client

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...

Other flags that may be useful:

-Gproperty=value - define a property in all the servers (may appear more
than once)
-Z - Exit remote servers at the end of the test.

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.
15.1 Doing it Manually
In some cases, the jmeter-server script may not work for you (if you are using an OS
platform not anticipated by the JMeter developers). Here is how to start the JMeter servers
(step 1 above) with a more manual process:

Step 1a: Start the RMI Registry

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.

Step 1b: Start the JMeter Server

Once the RMI Registry application is running, start the JMeter Server. Use the "-s" option
with the jmeter startup script ("jmeter -s").

Steps 2 and 3 remain the same.

15.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.

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

 `dirname $0`/jmeter -s "$@"

With

 HOST="-Djava.rmi.server.hostname=[computer_name][computer_domain]
 -Djava.security.policy=`dirname $0`/[policy_file]"
 `dirname $0`/jmeter $HOST -s "$@"

Also create a policy file and add [computer_name][computer_domain] line to /etc/hosts.

15.3 Using a different port

By default, JMeter uses the standard RMI port 1099. It is possible to change this. For this to
work successfully, all the following need to agree:
 On the server, start rmiregistry using the new port number
 On the server, start JMeter with the property server_port defined
 On the client, update the remote_hosts property to include the new remote
host:port settings

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 Windows (in a DOS box)

C:\JMETER> SET SERVER_PORT=1664
C:\JMETER> JMETER-SERVER [other options]

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.

The chosen port will be logged in the server jmeter.log file (rmiregistry does not create a log
file).
15.4 Using sample batching
Listeners in the test plan send their results back to the client JMeter which writes the results
to the specified files By default, samples are sent back as they are generated. This can place
a large load on the network and the JMeter client. There are some JMeter properties that can
be set to alter this behaviour.
 mode - sample sending mode - default is Standard
o Standard - send samples as soon as they are generated

o Hold - hold samples in an array until the end of a run. This may use a
lot of memory on the server.
o Batch - send saved samples when either the count or time exceeds a
threshold
o Statistical - send a summary sample when either the count or time
exceeds a threshold. The samples are summarised by thread group
name and sample label. The following fields are accumulated:
 elapsed time
 latency
 bytes
 sample count
 error count

Other fields that vary between samples are lost.

o Stripped - remove responseData from succesful samples

o StrippedBatch - remove responseData from succesful samples, and
send as batches
o Custom implementation : set the mode parameter to your custom
sample sender class name. This must implement the interface
SampleSender and have a constructor which takes a single parameter
of type RemoteSampleListener.

The following properties apply to the Batch and Statistical modes:

 num_sample_threshold - number of samples in a batch (default 100)

 time_threshold - number of milliseconds to wait (default 60 seconds)

16. Best Practices

16.1 Limit the Number of Threads

Your hardware's capabilities will limit the number of threads you can effectively run with
JMeter. It will also depend on how fast your server is (a faster server gives makes JMeter
work harder since it returns request quicker). The more JMeter works, the less accurate its
timing information will be. The more work JMeter does, the more each thread has to wait to
get access to the CPU, the more inflated the timing information gets. If you need large-scale
load testing, consider running multiple non-GUI JMeter instances on multiple machines.

16.2 Where to Put the Cookie Manager

See Building a Web Test for information.

16.3 Where to Put the Authorization Manager

See Building an Advanced Web Test for information.

16.4 Using the Proxy Server

Refer to HTTP Proxy Server for details on setting up the proxy server. The most important
thing to do is filter out all requests you aren't interested in. For instance, there's no point in
recording image requests (JMeter can be instructed to download all images on a page - see
HTTP Request ). These will just clutter your test plan. Most likely, there is an extension all
your files share, such as .jsp, .asp, .php, .html or the like. These you should "include" by
entering ".*\.jsp" as an "Include Pattern".

Alternatively, you can exclude images by entering ".*\.gif" as an "Exclude Pattern".

Depending on your application, this may or may not be a better way to go. You may also
have to exclude stylesheets, javascript files, and other included files. Test out your settings to
verify you are recording what you want, and then erase and start fresh.

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 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}".

Please note that matching is case-sensitive.

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.

The error "unknown_ca" probably means that you are trying to record HTTPS, and the
browser has not accepted the JMeter Proxy server certificate.

16.5 User variables

Some test plans need to use different values for different users/threads. For example, you
might want to test a sequence that requires a unique login for each user. This is easy to
achieve with the facilities provided by JMeter.

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.

16.6 Reducing resource requirements

Some suggestions on reducing resource usage.
 Use non-GUI mode: jmeter -n -t test.jmx -l test.jtl
 Use as few Listeners as possible; if using the -l flag as above they can all be
deleted or disabled.
 Rather than using lots of similar samplers, use the same sampler in a loop,
and use variables (CSV Data Set) to vary the sample. Or perhaps use the
Access Log Sampler. [The Include Controller does not help here, as it adds all
the test elements in the file to the test plan.]
 Don't use functional mode
 Use CSV output rather than XML
 Only save the data that you need
 Use as few Assertions as possible

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.

16.7 BeanShell server

The BeanShell interpreter has a very useful feature - it can act as a server, which is
accessible by telnet or http.

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.

If you do wish to use the server, define the following in jmeter.properties:

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:

Startup script running

Startup script completed
Httpd started on port: 9000
Sessiond started on port: 9001

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);
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:

java -jar ../lib/bshclient.jar localhost 9000 throughput.bsh 70 5 100 60

16.8 BeanShell scripting
16.8.1 Overview
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:

$ java -cp bsh-xxx.jar[;other jars as needed] bsh.Interperter file.bsh

[parameters]
or
$ java -cp bsh-xxx.jar bsh.Interperter
bsh% source("file.bsh");
bsh% exit(); // or use EOF key (e.g. ^Z or ^D)

16.8.2 Sharing Variables

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;
String value=JMeterUtils.getPropDefault("name","");
JMeterUtils.setProperty("name", "value");

The sample .bshrc files contain sample definitions of getprop() and setprop() methods.

Another possible method of sharing variables is to use the "bsh.shared" shared namespace.
For example:

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.

16.9 Developing script functions in BeanShell, Javascript or Jexl etc.

It's quite hard to write and test scripts as functions. However, JMeter has the BSF (and
BeanShell) samplers which can be used instead.

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.

16.10 Parameterising tests

Often it is useful to be able to re-run the same test with different settings. For example,
changing the number of threads or loops, or changing a hostname.

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 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.

17. Help! My boss wants me to load test our web app!

This is a fairly open-ended proposition. There are a number of questions to be asked first, and
additionally a number of resources that will be needed. You will need some hardware to run the
benchmarks/load-tests from. A number of tools will prove useful. There are a number of products
to consider. And finally, why is Java a good choice to implement a load-testing/Benchmarking
product.

17.1 Questions to ask

What is our anticipated average number of users (normal load) ?
What is our anticipated peak number of users ?

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) ?

What is the testing intended to achieve?

17.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.

17.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 ?

17.2.2 Application
Who knows how our application functions ? The normal sequence is
 test (low-volume - can we benchmark our application?)
 benchmark (the average number of users)
 load-test (the maximum number of users)
 test destructively (what is our hard limit?)

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.

17.3 What platform should I use to run the benchmarks/load-tests ?

This should be a widely-used piece of hardware, with a standard (i.e. vanilla) software
installation. Remember, if you publish your results, the first thing your clients will do is hire
a graduate student to verify them. You might as well make it as easy for this person as you
possibly can.

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.

For non-Windows platforms, investigate "ulimit -n unlimited" with a view to including it in

your user account startup scripts (.bashrc or .cshrc scripts for the testing account).

As you progress to larger-scale benchmarks/load-tests, this platform will become the

limiting factor. So it's worth using the best hardware and software that you have available.
Remember to include the hardware/software configuration in your published benchmarks.

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.

17.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).

17.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'.

17.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.

17.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.

17.5 What other products are there ?

There are a number of commercial products, which generally have fairly hefty pricetags. If
you can justify it, these are probably the way to go. If, however, these products do not do
exactly what you want, or you are on a limited budget, the following are worth a look. In
fact, you should probably start by trying the Apache ab tool, as it may very well do the job if
your requirements are not particularly complicated.
17.5.1 Apache 'ab' tool
You should definitely start with this one. It handles HTTP 'get' requests very well, and can
be made to handle HTTP 'post' requests with a little effort. Written in 'C', it performs very
well, and offers good (if basic) performance reporting.

17.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 .

17.5.3 Microsoft WAS

This is definitely worth a look. It has an excellent user interface but it may not do exactly
what you want. If this is the case, be aware that the functionality of this product is not likely
to change.

17.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.

17.6 Why Java ?

Why not Perl or C ?

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.

 18.1 Samplers
o FTP Request
 o HTTP Request

o JDBC Request

o Java Request

o SOAP/XML-RPC Request

o WebService(SOAP) Request

o LDAP Request

o LDAP Extended Request

o Access Log Sampler

o BeanShell Sampler

o BSF Sampler

o JSR223 Sampler

o TCP Sampler

o JMS Publisher

o JMS Subscriber

o JMS Point-to-Point

o JUnit Request

o Mail Reader Sampler

o Test Action

o SMTP Sampler

 18.2 Logic Controllers

o Simple Controller

o Loop Controller

o Once Only Controller

o Interleave Controller

o Random Controller

o Random Order Controller

o Throughput Controller

o Runtime Controller

o If Controller
 o While Controller

o Switch Controller

o ForEach Controller

o Module Controller

o Include Controller

o Transaction Controller

o Recording Controller

 18.3 Listeners
o Sample Result Save Configuration

o Graph Full Results

o Graph Results

o Spline Visualizer

o Assertion Results

o View Results Tree

o Aggregate Report

o View Results in Table

o Simple Data Writer

o Monitor Results

o Distribution Graph (alpha)

o Aggregate Graph

o Mailer Visualizer

o BeanShell Listener

o Summary Report

o Save Responses to a file

o BSF Listener

o JSR223 Listener

o Generate Summary Results

o Comparison Assertion Visualizer

 18.4 Configuration Elements

 o CSV Data Set Config

o FTP Request Defaults

o HTTP Authorization Manager

o HTTP Cache Manager

o HTTP Cookie Manager

o HTTP Request Defaults

o HTTP Header Manager

o Java Request Defaults

o JDBC Connection Configuration

o Login Config Element

o LDAP Request Defaults

o LDAP Extended Request Defaults

o TCP Sampler Config

o User Defined Variables

o Random Variable

o Counter

o Simple Config Element

 18.5 Assertions
o Response Assertion

o Duration Assertion

o Size Assertion

o XML Assertion

o BeanShell Assertion

o MD5Hex Assertion

o HTML Assertion

o XPath Assertion

o XML Schema Assertion

o BSF Assertion

o JSR223 Assertion
 o Compare Assertion

o SMIME Assertion

 18.6 Timers
o Constant Timer

o Gaussian Random Timer

o Uniform Random Timer

o Constant Throughput Timer

o Synchronizing Timer

o BeanShell Timer

o BSF Timer

o JSR223 Timer

 18.7 Pre Processors

o HTML Link Parser

o HTTP URL Re-writing Modifier

o HTML Parameter Mask

o HTTP User Parameter Modifier

o User Parameters

o BeanShell PreProcessor

o BSF PreProcessor

o JSR223 PreProcessor

 18.8 Post-Processors
o Regular Expression Extractor

o XPath Extractor

o Result Status Action Handler

o BeanShell PostProcessor

o BSF PostProcessor

o JSR223 PostProcessor

 18.9 Miscellaneous Features

o Test Plan
 o Thread Group

o WorkBench

o SSL Manager

o HTTP Proxy Server

o HTTP Mirror Server

o Property Display

o Debug Sampler

o Debug PostProcessor

 18.10 Reports
o Report Plan

o Report Table

o HTML Report Writer

o Report Page

o Line Graph

o Bar Chart

18.1 Samplers
Samplers perform the actual work of JMeter. Each sampler (except Test Action) generates one or
more sample results. The sample results have various attributes (success/fail, elapsed time, data
size etc) and can be viewed in the various listeners.

18.1.1 FTP Request

This controller lets you send an FTP "retrieve file" or "upload file" request to an FTP server.
If you are going to send multiple requests to the same FTP server, consider using a FTP
Request Defaults Configuration Element so you do not have to enter the same information
for each FTP Request Generative Controller. When downloading a file, it can be stored on
disk (Local File) or in the Response Data, or both.

Latency is set to the time it takes to login (versions of JMeter after 2.3.1).

Control Panel
Parameters

Attribute Description Required

Descriptive name for this controller that is shown in the
Name No
tree.
Server Name or
Domain name or IP address of the FTP server. Yes
IP
Port to use. If this is >0, then this specific port is used,
Port No
otherwise JMeter uses the default FTP port.
Remote File: File to retrieve or name of destination file to upload. Yes
File to upload, or destination for downloads (defaults to Yes, if
Local File:
remote file name). uploading (*)
Local File Provides the contents for the upload, overrides the Local Yes, if
Contents: File property. uploading (*)
get(RETR) /
Whether to retrieve or upload a file. Yes
put(STOR)
Use Binary
Check this to use Binary mode (default Ascii) Yes
mode ?
Whether to store contents of retrieved file in response
Save File in Yes, if
data. If the mode is Ascii, then the contents will be visible
Response ? downloading
in the Tree View Listener.
Username FTP account username. Usually
FTP account password. N.B. This will be visible in the
Password Usually
test plan.

See Also:
  Assertions
 FTP Request Defaults

 Building an FTP Test Plan

18.1.2 HTTP Request

This sampler lets you send an HTTP/HTTPS request to a web server. It also lets you control
whether or not JMeter parses HTML files for images and other embedded resources and
sends HTTP requests to retrieve them. The following types of embedded resource are
retrieved:
 images
 applets
 stylesheets
 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.

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.

There are three versions of the sampler:

 HTTP Request - uses the default Java HTTP implementation

 HTTP Request HTTPClient - uses Apache Commons HttpClient
 AJP/1.3 Sampler - uses the Tomcat mod_jk protocol (allows testing of Tomcat in
AJP mode without needing Apache httpd) The AJP Sampler does not support
multiple file upload; only the first file will be used.

The default (Java) implementation has some limitations:

 There is no control over how connections are re-used. When a connection is released
by JMeter, it may or may not be re-used by the same thread.
 The API is best suited to single-threaded usage - various settings (e.g. proxy) are
 defined via system properties, and therefore apply to all connections.
 There is a bug in the handling of HTTPS via a Proxy (the CONNECT is not handled
correctly). See Java bugs 6226610 and 6208335.

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:

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
Parameters

Attribute Description Required

Name Descriptive name for this controller that is shown in the tree. No
Yes, unless
provided
Domain name or IP address of the web server. e.g.
Server by HTTP
www.example.com. [Do not include the http:// prefix.]
Request
Defaults
Port Port the web server is listening to. Default: 80 No
Connect Connection Timeout. Number of milliseconds to wait for a
No
Timeout connection to open.
Response Response Timeout. Number of milliseconds to wait for a
No
Timeout response.
Server (proxy) Hostname or IP address of a proxy server to perform request. No
 [Do not include the http:// prefix.]
Port Port the proxy server is listening to. No
Username (Optional) username for proxy server. No
Password (Optional) password for proxy server. No
Protocol HTTP, HTTPS or FILE. Default: HTTP No
Method GET, POST, HEAD, TRACE, OPTIONS, PUT, DELETE Yes
Content
Content encoding to be used (for POST and FILE) No
Encoding
Sets the underlying http protocol handler to automatically
follow redirects, so they are not seen by JMeter, and thus will
Redirect not appear as samples. Should only be used for GET and
Yes
Automatically HEAD requests. The HttpClient sampler will reject attempts to
use it for POST or PUT. Warning: see below for
information on cookie and header handling.
This only has any effect if "Redirect Automatically" is not
enabled. If set, the JMeter sampler will check if the response is
a redirect and follow it if so. The initial redirect and further
responses will appear as additional samples. The URL and
data fields of the parent sample will be taken from the final
(non-redirected) sample, but the parent byte count and elapsed
time include all samples. The latency is taken from the initial
response (versions of JMeter after 2.3.4 - previously it was
zero). Note that the HttpClient sampler may log the following
Follow message:
Yes
Redirects
"Redirect requested but followRedirects is disabled"

This can be ignored.

In versions after 2.3.4, JMeter will collapse paths of the form

'/../segment' in both absolute and relative redirect URLs. For
example http://host/one/../two => http://host/two. If necessary,
this behaviour can be suppressed by setting the JMeter
property
httpsampler.redirect.removeslashdotdot=false

JMeter sets the Connection: keep-alive header. This does not

work properly with the default HTTP implementation, as
Use KeepAlive Yes
connection re-use is not under user-control. It does work with
the Jakarta httpClient implementation.
Use
multipart/form- Use a multipart/form-data or application/x-www-form-
Yes
data for HTTP urlencoded post request
POST
Path The path to resource (for example, /servlets/myServlet). If the Yes
 resource requires query string parameters, add them below in
the "Send Parameters With the Request" section. As a special
case, if the path starts with "http://" or "https://" then this
is used as the full URL. In this case, the server, port and
protocol are ignored; parameters are also ignored for GET and
DELETE methods.
The query string will be generated from the list of parameters
you provide. Each parameter has a name and value , the
options to encode the parameter, and an option to include or
exclude an equals sign (some applications don't expect an
equals when the value is the empty string). The query string
will be generated in the correct fashion, depending on the
choice of "Method" you made (ie if you chose GET or
Send Parameters DELETE, the query string will be appended to the URL, if
With the POST or PUT, then it will be sent separately). Also, if you are No
Request sending a file using a multipart form, the query string will be
created using the multipart form specifications. See below for
some further information on parameter handling.
Additionally, you can specify whether each parameter should
be URL encoded. If you are not sure what this means, it is
probably best to select it. If your values contain characters
such as & or spaces, or question marks, then encoding is
usually required.
Name of the file to send. If left blank, JMeter does not send a
file, if filled in, JMeter automatically sends the request as a
multipart form request.
If it is a POST or PUT request and there is a single file whose
'name' attribute (below) is omitted, then the file is sent as the
File Path: No
entire body of the request, i.e. no wrappers are added. This
allows arbitrary bodies to be sent. This functionality is present
for POST requests after version 2.2, and also for PUT requests
after version 2.3. See below for some further information on
parameter handling.
Parameter name: Value of the "name" web request parameter. No
MIME type (for example, text/plain). If it is a POST or PUT
request and either the 'name' atribute (below) are omitted or
MIME Type the request body is constructed from parameter values only, No
then the value of this field is used as the value of the content-
type request header.
Retrieve All
Tell JMeter to parse the HTML file and send HTTP/HTTPS
Embedded
requests for all images, Java applets, JavaScript files, CSSs, No
Resources from
etc. referenced in the file. See below for more details.
HTML Files
Use as monitor For use with the Monitor Results listener. Yes
Save response If this is selected, then the response is not stored in the sample Yes
as MD5 hash? result. Instead, the 32 character MD5 hash of the data is
 calculated and stored instead. This is intended for testing large
amounts of data.
If present, this must be a regular expression that is used to
Embedded
match against any embedded URLs found. So if you only want
URLs must No
to download embedded resources from http://example.com/,
match:
use the expression: http://example\.com/.*
[Only for HTTP Request HTTPClient] Override the default
local IP address for this sample. The JMeter host must have
Source IP
multiple IP addresses (i.e. IP aliases or network interfaces). If No
address:
the property httpclient.localaddress is defined, that is used
for all HttpClient requests.

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:

 define the body as a file

 define the body as parameter value(s) with no name

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:

 id.types - a list of content types

 id.className - the parser to be used to extract the embedded resources

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

Emulating slow connections (HttpClient only):

# Define characters per second > 0 to emulate slow connections

#httpclient.socket.http.cps=0
#httpclient.socket.https.cps=0

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

18.1.3 JDBC Request

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:

A_#=2 (number of rows)

A_1=column 1, row 1
A_2=column 1, row 2
C_#=2 (number of rows)
C_1=column 3, row 1
C_2=column 3, row 2

If the Select statement returns zero rows, then the A_# and C_# variables would be set to 0,
and no other variables would be set.

Old variables are cleared if necessary - e.g. if the first select retrieves 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

Attribute Description Required

Name Descriptive name for this controller that is shown in the tree. No
Name of the JMeter variable that the connection pool is bound to.
Variable
This must agree with the 'Variable Name' field of a JDBC Yes
Name
Connection Configuration.
Query Set this according to the statement type: Yes
Type  Select Statement
 Update Statement - use this for Inserts as well
  Callable Statement
 Prepared Select Statement
 Prepared Update Statement - use this for Inserts as well
 Commit
 Rollback
 Autocommit(false)
 Autocommit(true)

 Edit - this should be a variable reference that evaluates to

one of the above
SQL query. Do not enter a trailing semi-colon. There is generally
no need to use { and } to enclose Callable statements; however
they mey be used if the database uses a non-standard syntax. [The
JDBC driver automatically converts the statement if necessary
when it is enclosed in {}]. For example:
 select * from t_customers where id=23
SQL  CALL SYSCS_UTIL.SYSCS_EXPORT_TABLE
(null,?, ?, null, null, null) Yes
Query
o Parameter values: tablename,filename

o Parameter types: VARCHAR,VARCHAR

The second example assumes you are using Apache

Derby.
Comma-separated list of parameter values. Use ]NULL[ to
indicate a NULL parameter. (If required, the null string can be
changed by defining the property "jdbcsampler.nullmarker".) Yes, if a
prepared or
Parameter The list must be enclosed in double-quotes if any of the values
callable
values contain a comma or double-quote, and any embedded double- statement has
quotes must be doubled-up, for example: parameters
"Dbl-Quote: "" and Comma: ,"
There must be as many values as there are placeholders in the
statement.
Parameter Comma-separated list of SQL parameter types (e.g. INTEGER, Yes, if a
types DATE, VARCHAR, DOUBLE). These are defined as fields in prepared or
the class java.sql.Types, see for example: Javadoc for callable
java.sql.Types . [Note: JMeter will use whatever types are statement has
defined by the runtime JVM, so if you are running on a different parameters
JVM, be sure to check the appropriate document] If the callable
statement has INOUT or OUT parameters, then these must be
indicated by prefixing the appropriate parameter types, e.g.
instead of "INTEGER", use "INOUT INTEGER". If not
 specified, "IN" is assumed, i.e. "DATE" is the same as "IN
DATE".

If the type is not one of the fields found in java.sql.Types,

versions of JMeter after 2.3.2 also accept the corresponding
integer number, e.g. since INTEGER == 4, you can use "INOUT
4".

There must be as many types as there are placeholders in the

statement.
Variable Comma-separated list of variable names to hold values returned
No
Names by Select statements

See Also:

 Building a Database Test Plan

 JDBC Connection Configuration

Versions of JMeter after 2.3.2 use UTF-8 as

the character encoding. Previously the
platform default was used.

18.1.4 Java Request

This sampler lets you control a java class that implements the
org.apache.jmeter.protocol.java.sampler.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
The Add/Delete buttons don't serve any
purpose at present.

Parameters

Attribute Description Required

Name Descriptive name for this sampler that is shown in the tree. No
The specific implementation of the JavaSamplerClient
Classname Yes
interface to be sampled.
Send Parameters A list of arguments that will be passed to the sampled
No
with Request class. All arguments are sent as Strings.

The sleep time is calculated as follows:

SleepTime is in milliseconds
SleepMask is used to add a "random" element to the time:
totalSleepTime = SleepTime + (System.currentTimeMillis() % SleepMask)

18.1.5 SOAP/XML-RPC Request

This sampler lets you send a SOAP request to a webservice. It can also be used to send
XML-RPC over HTTP. It creates an HTTP POST request, with the specified XML as the
POST content. To change the "Content-type" from the default of "text/xml", use a
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

Parameters

Attribute Description Required

Name Descriptive name for this sampler that is shown in the tree. No
URL The URL to direct the SOAP request to. Yes
Send SOAP action Send a SOAP action header? (overrides the Header Manager) No
Soap/XML-RPC The Soap XML message, or XML-RPC instructions. Not
No
Data used if the filename is provided.
If specified, then the contents of the file are sent, and the Data
Filename No
field is ignored
18.1.6 WebService(SOAP) Request
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.

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.

By default, the webservice sampler sets SOAPHTTPConnection.setMaintainSession (true).

If you need to maintain the session, add a blank Header Manager. The sampler uses the
Header Manager to store the SOAPHTTPConnection object, since the version of apache
soap does not provide a easy way to get and set the cookies.

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:

<?xml version="1.0" encoding="utf-8"?>

<soap:Envelope
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<foo xmlns="http://clients-xlmns"/>
</soap:Body>
</soap:Envelope>

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
18.1.7 LDAP Request
This Sampler lets you send a different Ldap request(Add, Modify, Delete and Search) to an
LDAP server.

If you are going to send multiple requests to the same LDAP server, consider using an LDAP
Request Defaults Configuration Element so you do not have to enter the same information
for each LDAP Request.

The same way the Login Config Element also using for Login and password.

Control Panel

There are two ways to create test cases for testing an LDAP Server.

1. Inbuilt Test cases.

2. User defined Test cases.

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.

2. User defined test :

This will add the entry in the LDAP Server. User has to enter all the attributes
in the table.The entries are collected from the table to add. The execution time
is calculated. The created entry will not be deleted after the test.

2. Modify Test
1. Inbuilt test :

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.

2. User defined test

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.

2. User defined test

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.

2. User defined test

This will delete the user-defined entry in the LDAP Server. The entries should
 be available in the LDAP Server. The execution time is calculated.

Parameters

Attribute Description Required

Name Descriptive name for this controller that is shown in the tree. No
Server Name Domain name or IP address of the LDAP server. JMeter assumes
Yes
or IP the LDAP server is listening on the default port(389).
Port default port(389). Yes
root DN DN for the server to communicate Yes
Username LDAP server username. Usually
Password LDAP server password. Usually
the name of the context to create or Modify; may not be empty
Entry DN Example: do you want to add cn=apache,ou=test you have to add Yes
in table name=cn, value=apache
Delete the name of the context to Delete; may not be empty Yes
Search base the name of the context or object to search Yes
Search filter the filter expression to use for the search; may not be null Yes
add test this name, value pair to added in the given context object Yes
modify test this name, value pair to add or modify in the given context object Yes

See Also:

 Building an Ldap Test Plan

 LDAP Request Defaults

18.1.8 LDAP Extended Request

This Sampler can send all 8 different LDAP request to an LDAP server. It is an extended
version of the LDAP sampler, therefore it is harder to configure, but can be made much
closer resembling a real LDAP session.

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
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

Attribute Description Required

Name Descriptive name for this sampler that is shown in the tree. No
Servername The name (or IP-address) of the LDAP server. Yes
 The port number that the LDAP server is listening to. If this
Port is omitted JMeter assumes the LDAP server is listening on No
the default port(389).
The distinguished name of the base object that will be used
for any subsequent operation. It can be used as a starting
DN No
point for all operations. You cannot start any operation on a
higher level than this DN!
Full distinguished name of the user as which you want to
Username No
bind.
Password for the above user. If omitted it will result in an
Password anonymous bind. If is is incorrect, the sampler will return an No
error and revert to an anonymous bind.

2. Thread unbind

This is simply the operation to end a session. It is equal to the LDAP "unbind"
operation.

Parameters

Attribute Description Required

Name Descriptive name for this sampler that is shown in the tree. No

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

Attribute Description Required

Name Descriptive name for this sampler that is shown in the tree. No
Username Full distinguished name of the user as which you want to bind. Yes
Password for the above user. If omitted it will result in an
Password anonymous bind. If is is incorrect, the sampler will return an No
error.

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

Attribute Description Required

Descriptive name for this sampler that is shown in the
Name No
tree.
The current distinguished name of the object you want
Old entry name to rename or move, relative to the given DN in the Yes
thread bind operation.
New The new distinguished name of the object you want to
distinguished rename or move, relative to the given DN in the thread Yes
name bind operation.

5. Add test

This is the ldap "add" operation. It can be used to add any kind of object to the LDAP
server.

Parameters

Attribute Description Required

Name Descriptive name for this sampler that is shown in the tree. No
Distinguished name of the object you want to add, relative to
Entry DN Yes
the given DN in the thread bind operation.
A list of attributes and their values you want to use for the
object. If you need to add a multiple value attribute, you need
Add test Yes
to add the same attribute with their respective values several
times to the list.

6. Delete test

This is the LDAP "delete" operation, it can be used to delete an object from the
LDAP tree

Parameters

Attribute Description Required

Name Descriptive name for this sampler that is shown in the tree. No
Distinguished name of the object you want to delete, relative
Delete Yes
to the given DN in the thread bind operation.
7. Search test

This is the LDAP "search" operation, and will be used for defining searches.

Parameters

Attribute Description Required

Name Descriptive name for this sampler that is shown in the tree. No
Distinguished name of the subtree you want your search to
Search base look in, relative to the given DN in the thread bind No
operation.
Search Filter searchfilter, must be specified in LDAP syntax. Yes
Use 0 for baseobject-, 1 for onelevel- and 2 for a subtree
Scope No
search. (Default=0)
Specify the maximum number of results you want back
from the server. (default=0, which means no limit.) When
Size Limit No
the sampler hits the maximum number of results, it will
fail with errorcode 4
Specify the maximum amount of (cpu)time (in
miliseconds) that the server can spend on your search.
Time Limit No
Take care, this does not say anything about the
responsetime. (default is 0, which means no limit)
Specify the attributes you want to have returned, seperated
Attributes No
by a semicolon. An empty field will return all attributes
Whether the object will be returned (true) or not (false).
Return object No
Default=false
Dereference If true, it will dereference aliases, if false, it will not follow
No
aliases them (default=false)

8. Modification test

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

Attribute Description Required

Name Descriptive name for this sampler that is shown in the tree. No
Distinguished name of the object you want to modify,
Entry name Yes
relative to the given DN in the thread bind operation
 The attribute-value-opCode triples. The opCode can be any
valid LDAP operationCode (add, delete/remove or
replace). If you don't specify a value with a delete
Modification
operation, all values of the given attribute will be deleted. Yes
test
If you do specify a value in a delete operation, only the
given value will be deleted. If this value is non-existent,
the sampler will fail the test.

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

Attribute Description Required

Name Descriptive name for this sampler that is shown in the tree. No
The current distinguished name of the object of which you
Entry DN want to compare an attribute, relative to the given DN in the Yes
thread bind operation.
Compare
In the form "attribute=value" Yes
filter

See Also:

 Building an LDAP Test Plan

 LDAP Extended Request Defaults

18.1.9 Access Log Sampler

(Alpha Code)
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:

127.0.0.1 - - [21/Oct/2003:05:37:21 -0500] "GET /index.jsp?%2Findex.jsp= HTTP/1.1" 200

8343

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

The current implementation of AccessLogSampler uses the generator to create a new

HTTPSampler. The servername, port and get images are set by AccessLogSampler. Next,
the parser is called with integer 1, telling it to parse one entry. After that,
HTTPSampler.sample() is called to make the request.

samp = (HTTPSampler) GENERATOR.generateRequest();

samp.setDomain(this.getDomain());
samp.setPort(this.getPort());
samp.setImageParser(this.isImageParser());
PARSER.parse(1);
res = samp.sample();
res.setSampleLabel(samp.toString());

The required methods in LogParser are: setGenerator(Generator) and parse(int). Classes

implementing Generator interface should provide concrete implementation for all the
methods. For an example of how to implement either interface, refer to StandardGenerator
and TCLogParser.

Control Panel
Parameters

Attribute Description Required

Descriptive name for this controller that is shown in
Name No
the tree.
Server Domain name or IP address of the web server. Yes
Port Port the web server is listening to. No (defaults to 80)
The log parser class is responsible for parsing the Yes (default
Log parser class
logs. provided)
Filter The filter class is used to filter out certain lines. No
Location of log
The location of the access log file. Yes
file

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.
Parameters

Attribute Description Required

Name Descriptive name for this sampler that is shown in No

the tree.
The WSDL URL with the service description.
WSDL URL Versions of JMeter after 2.3.1 support the file: No
protocol for local WSDL files.
Will be populated from the WSDL when the Load
WSDL button is pressed. Select one of the
Web Methods methods and press the Configure button to No
populate the Protocol, Server, Port, Path and
SOAPAction fields.
Protocol HTTP or HTTPS are acceptable protocol. Yes
Server Name or
Yes
IP The hostname or IP address.
Port Number Port Number. Yes
Path Path for the webservice. Yes

SOAPAction The SOAPAction defined in the webservice Yes

description or WSDL.
Soap/XML-RPC
Yes
Data The Soap XML message
Soap file File containing soap message No
Message Folder Folder containing soap files No
When using external files, setting this causes the
Memory cache file to be processed once and caches the result. Yes
This may use a lot of memory if there are many
different large files.
Use HTTP Proxy Check box if http proxy should be used No
Proxy Host Proxy hostname No
Proxy Port Proxy host port No

18.1.7 LDAP Request

This Sampler lets you send a different Ldap request(Add, Modify, Delete and Search) to an
LDAP server.

If you are going to send multiple requests to the same LDAP server, consider using an LDAP
Request Defaults Configuration Element so you do not have to enter the same information for
each LDAP Request.

The same way the Login Config Element also using for Login and password.

Control Panel
There are two ways to create test cases for testing an LDAP Server.

1. Inbuilt Test cases.

2. User defined Test cases.

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.

2. User defined test :

This will add the entry in the LDAP Server. User has to enter all the attributes
in the table.The entries are collected from the table to add. The execution time
is calculated. The created entry will not be deleted after the test.

2. Modify Test
1. Inbuilt test :
 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.

2. User defined test

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.

2. User defined test

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.

2. User defined test

This will delete the user-defined entry in the LDAP Server. The entries should
be available in the LDAP Server. The execution time is calculated.

Parameters

Attribute Description Required

Name Descriptive name for this controller that is shown in the tree. No
Server Name Domain name or IP address of the LDAP server. JMeter assumes
Yes
or IP the LDAP server is listening on the default port(389).
Port default port(389). Yes
root DN DN for the server to communicate Yes
Username LDAP server username. Usually
Password LDAP server password. Usually
 the name of the context to create or Modify; may not be empty
Entry DN Example: do you want to add cn=apache,ou=test you have to add in Yes
table name=cn, value=apache
Delete the name of the context to Delete; may not be empty Yes
Search base the name of the context or object to search Yes
Search filter the filter expression to use for the search; may not be null Yes
add test this name, value pair to added in the given context object Yes
modify test this name, value pair to add or modify in the given context object Yes

See Also:

 Building an Ldap Test Plan

 LDAP Request Defaults

18.1.8 LDAP Extended Request

This Sampler can send all 8 different LDAP request to an LDAP server. It is an extended
version of the LDAP sampler, therefore it is harder to configure, but can be made much
closer resembling a real LDAP session.

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
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

Attribute Description Required

Name Descriptive name for this sampler that is shown in the tree. No
Servername The name (or IP-address) of the LDAP server. Yes
The port number that the LDAP server is listening to. If this
Port is omitted JMeter assumes the LDAP server is listening on No
the default port(389).
The distinguished name of the base object that will be used
for any subsequent operation. It can be used as a starting
DN No
point for all operations. You cannot start any operation on a
higher level than this DN!
Full distinguished name of the user as which you want to
Username No
bind.
 Password for the above user. If omitted it will result in an
Password anonymous bind. If is is incorrect, the sampler will return an No
error and revert to an anonymous bind.

2. Thread unbind

This is simply the operation to end a session. It is equal to the LDAP "unbind"
operation.

Parameters

Attribute Description Required

Name Descriptive name for this sampler that is shown in the tree. No

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

Attribute Description Required

Name Descriptive name for this sampler that is shown in the tree. No
Username Full distinguished name of the user as which you want to bind. Yes
Password for the above user. If omitted it will result in an
Password anonymous bind. If is is incorrect, the sampler will return an No
error.

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

Attribute Description Required

Descriptive name for this sampler that is shown in the
Name No
tree.
The current distinguished name of the object you want
Old entry name to rename or move, relative to the given DN in the Yes
thread bind operation.
 New The new distinguished name of the object you want to
distinguished rename or move, relative to the given DN in the thread Yes
name bind operation.

5. Add test

This is the ldap "add" operation. It can be used to add any kind of object to the LDAP
server.

Parameters

Attribute Description Required

Name Descriptive name for this sampler that is shown in the tree. No
Distinguished name of the object you want to add, relative to
Entry DN Yes
the given DN in the thread bind operation.
A list of attributes and their values you want to use for the
object. If you need to add a multiple value attribute, you need
Add test Yes
to add the same attribute with their respective values several
times to the list.

6. Delete test

This is the LDAP "delete" operation, it can be used to delete an object from the LDAP
tree

Parameters

Attribute Description Required

Name Descriptive name for this sampler that is shown in the tree. No
Distinguished name of the object you want to delete, relative to
Delete Yes
the given DN in the thread bind operation.

7. Search test

This is the LDAP "search" operation, and will be used for defining searches.

Parameters

Attribute Description Required

Name Descriptive name for this sampler that is shown in the tree. No
Search base Distinguished name of the subtree you want your search to No
 look in, relative to the given DN in the thread bind
operation.
Search Filter searchfilter, must be specified in LDAP syntax. Yes
Use 0 for baseobject-, 1 for onelevel- and 2 for a subtree
Scope No
search. (Default=0)
Specify the maximum number of results you want back
from the server. (default=0, which means no limit.) When
Size Limit No
the sampler hits the maximum number of results, it will fail
with errorcode 4
Specify the maximum amount of (cpu)time (in
miliseconds) that the server can spend on your search. Take
Time Limit No
care, this does not say anything about the responsetime.
(default is 0, which means no limit)
Specify the attributes you want to have returned, seperated
Attributes No
by a semicolon. An empty field will return all attributes
Whether the object will be returned (true) or not (false).
Return object No
Default=false
Dereference If true, it will dereference aliases, if false, it will not follow
No
aliases them (default=false)

8. Modification test

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

Attribute Description Required

Name Descriptive name for this sampler that is shown in the tree. No
Distinguished name of the object you want to modify,
Entry name Yes
relative to the given DN in the thread bind operation
The attribute-value-opCode triples. The opCode can be any
valid LDAP operationCode (add, delete/remove or replace).
If you don't specify a value with a delete operation, all
Modification
values of the given attribute will be deleted. If you do Yes
test
specify a value in a delete operation, only the given value
will be deleted. If this value is non-existent, the sampler
will fail the test.

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

Attribute Description Required

Name Descriptive name for this sampler that is shown in the tree. No
The current distinguished name of the object of which you
Entry DN want to compare an attribute, relative to the given DN in the Yes
thread bind operation.
Compare
In the form "attribute=value" Yes
filter

See Also:

 Building an LDAP Test Plan

 LDAP Extended Request Defaults

18.1.9 Access Log Sampler

(Alpha Code)
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:

127.0.0.1 - - [21/Oct/2003:05:37:21 -0500] "GET /index.jsp?%2Findex.jsp= HTTP/1.1" 200

8343

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

The current implementation of AccessLogSampler uses the generator to create a new

HTTPSampler. The servername, port and get images are set by AccessLogSampler. Next, the
parser is called with integer 1, telling it to parse one entry. After that, HTTPSampler.sample()
is called to make the request.

samp = (HTTPSampler) GENERATOR.generateRequest();

samp.setDomain(this.getDomain());
samp.setPort(this.getPort());
samp.setImageParser(this.isImageParser());
PARSER.parse(1);
res = samp.sample();
res.setSampleLabel(samp.toString());

The required methods in LogParser are: setGenerator(Generator) and parse(int). Classes

implementing Generator interface should provide concrete implementation for all the
methods. For an example of how to implement either interface, refer to StandardGenerator
and TCLogParser.

Control Panel
Parameters

Attribute Description Required

Hostname or IP address of the server. See below for
Server Yes
use with file protocol.
Port to be used to connect to the server. Defaults are:
Port No
SMTP=25, SSL=465, StartTLS=587
Address From The from address that will appear in the e-mail Yes
 Yes, unless CC or
Address To The destination e-mail address
BCC is specified
Address To BCC Blind carbon copy destinations e-mail address No
Address To CC Carbon copy destinations e-mail address No
Indicates if the SMTP server requires user
Use Auth No
authentication
Username User login name No
User login password (N.B. this is stored unencrypted
Password No
in the test plan)
Use no security Indicates that the connection to the SMTP server
No
features does not use any security protocol.
Indicates that the connection to the SMTP server
Use SSL No
must use the SSL protocol.
Indicates that the connection to the SMTP server
Use StartTLS No
should attempt to start the TLS protocol.
If the server does not start the TLS protocol the
Enforce StartTLS No
connection will be terminated.
Trust All When selected it will accept all certificates
No
Certificates independent of the CA.
Use local When selected it will only accept certificates that are
No
truststore locally trusted.
Path to file containing the trusted certificates.
Relative paths are resolved against the current
directory.
Local truststore No
Failing that, against the directory containing the test
script (JMX file).
Subject The e-mail message subject. No
Include
Includes the System.currentTimemilis() in the
timestamp in No
subject line.
subject
Add Header Additional headers can be defined using this button. No
Message The message body. No
Attach files Files to be attached to the message. No
If set, the .eml file will be sent instead of the entries
Send .eml No
in the Subject, Message, and Attached files
Calculate Calculates the message size and stores it in the
No
message size sample result.
Enable debug
If set, then the "mail.debug" property is set to "true" No
logging?
^

18.2 Logic Controllers

Logic Controllers determine the order in which Samplers are processed.

18.2.1 Simple Controller

The Simple Logic Controller lets you organize your Samplers and other Logic Controllers.
Unlike other Logic Controllers, this controller provides no functionality beyond that of a
storage device.

Control Panel

Parameters

Attribute Description Required

Name Descriptive name for this controller that is shown in the tree. No

Using the Simple Controller

Download this example (see Figure 6). In this example, we created a Test Plan that sends two Ant
HTTP requests and two Log4J HTTP requests. We grouped the Ant and Log4J requests by placing
them inside Simple Logic Controllers. Remember, the Simple Logic Controller has no effect on how
JMeter processes the controller(s) you add to it. So, in this example, JMeter sends the requests in
the following order: Ant Home Page, Ant News Page, Log4J Home Page, Log4J History Page. Note,
the File Reporter is configured to store the results in a file named "simple-test.dat" in the current
directory.
Figure 6 Simple Controller Example

18.2.2 Loop Controller

If you add Generative or Logic Controllers to a Loop Controller, JMeter will loop through
them a certain number of times, in addition to the loop value you specified for the Thread
Group. For example, if you add one HTTP Request to a Loop Controller with a loop count
of two, and configure the Thread Group loop count to three, JMeter will send a total of 2 * 3
= 6 HTTP Requests.

Control Panel

Parameters

Attribute Description Required

Name Descriptive name for this controller that is shown in the tree. No
The number of times the subelements of this controller will be
iterated each time through a test run.
Yes, unless
Loop Special Case: The Loop Controller embedded in the Thread
"Forever" is
Count Group element behaves slightly differently. Unless set to
checked
forever, it stops the test after the given number of iterations
have been done.

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.

Figure 4 - Loop Controller Example

We configured the Thread Group for a single thread and a loop count value of one. Instead
of letting the Thread Group control the looping, we used a Loop Controller. You can see
that we added one HTTP Request to the Thread Group and another HTTP Request to a Loop
Controller. We configured the Loop Controller with a loop count value of five.

JMeter will send the requests in the following order: Home Page, News Page, News Page,
News Page, News Page, and News Page. Note, the File Reporter is configured to store the
results in a file named "loop-test.dat" in the current directory.

18.2.3 Once Only Controller

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

Attribute Description Required

Name Descriptive name for this controller that is shown in the tree. No

Once Only Example

Download this example (see Figure 5). In this example, we created a Test Plan that has two
threads that send HTTP request. Each thread sends one request to the Home Page, followed by
three requests to the Bug Page. Although we configured the Thread Group to iterate three times,
each JMeter thread only sends one request to the Home Page because this request lives inside a
Once Only Controller.

Figure 5. Once Only Controller Example

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.

18.2.4 Interleave Controller

If you add Generative or Logic Controllers to an Interleave Controller, JMeter will alternate
among each of the other controllers for each loop iteration.

Control Panel

Parameters

Attribute Description Required

name Descriptive name for this controller that is shown in the tree. No
ignore sub- If checked, the interleave controller will treat sub-controllers No
 like single request elements and only allow one request per
controller blocks
controller at a time.

Simple Interleave Example

Download this example (see Figure 1). In this example, we configured the Thread Group to have
two threads and a loop count of five, for a total of ten requests per thread. See the table below for
the sequence JMeter sends the HTTP Requests.

Figure 1 - Interleave Controller Example 1

Loop Iteration Each JMeter Thread Sends These HTTP Requests
1 News Page
1 Log Page
2 FAQ Page
2 Log Page
3 Gump Page
3 Log Page
4 Because there are no more requests in the controller,

JMeter starts over and sends the first HTTP Request, which is the News Page.
4 Log Page
5 FAQ Page
5 Log Page

Useful Interleave Example

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.
Figure 2 - Interleave Controller Example 2

The outer Interleave Controller alternates between the two inner ones. Then, each inner Interleave
Controller alternates between each of the HTTP Requests. Each JMeter thread will send the
requests in the following order: Home Page, Interleaved, Bug Page, Interleaved, CVS Page,
Interleaved, and FAQ Page, Interleaved. Note, the File Reporter is configured to store the results in
a file named "interleave-test2.dat" in the current directory.

Figure 3 - Interleave Controller Example 3

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.
Parameters

Attribute Description Required

Descriptive name for this controller that is shown in
Name No
the tree.
Server Domain name or IP address of the web server. Yes
Port Port the web server is listening to. No (defaults to 80)
The log parser class is responsible for parsing the Yes (default
Log parser class
logs. provided)
Filter The filter class is used to filter out certain lines. No
Location of log
The location of the access log file. Yes
file

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.
18.2.5 Random Controller
The Random Logic Controller acts similarly to the Interleave Controller, except that instead
of going in order through its sub-controllers and samplers, it picks one at random at each
pass.

Interactions between multiple controllers can

yield complex behavior. This is particularly
true of the Random Controller. Experiment
before you assume what results any given
interaction will give

Control Panel

Parameters

Attribute Description Required

Name Descriptive name for this controller that is shown in the tree. No

18.2.6 Random Order Controller

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

Attribute Description Required

Name Descriptive name for this controller that is shown in the tree. No

18.2.7 Throughput Controller

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 causes the controller to
execute a certain percentage of the iterations through the test plan. Total executions causes
the controller to stop executing after a certain number of executions have occurred. Like the
Once Only Controller, this setting is reset when a parent Loop Controller restarts.

Control Panel

The Throughput Controller can yield very

complex behavior when combined with other
controllers - in particular with interleave or
random controllers as parents (also very
useful).

Parameters

Attribute Description Required

Name Descriptive name for this controller that is shown in the tree. No
Execution Whether the controller will run in percent executions or total
Yes
Style executions mode.
A number. for percent execution mode, a number from 0-100 that
indicates the percentage of times the controller will execute. "50"
Throughput means the controller will execute during half the iterations throught Yes
the test plan. for total execution mode, the number indicates the
total number of times the controller will execute.
If checked, per user will cause the controller to calculate whether it
should execute on a per user (per thread) basis. if unchecked, then
the calculation will be global for all users. for example, if using
Per User total execution mode, and uncheck "per user", then the number No
given for throughput will be the total number of executions made. if
"per user" is checked, then the total number of executions would be
the number of users times the number given for throughput.

18.2.8 Runtime Controller

The Runtime Controller controls how long its children are allowed to run.

Control Panel

Parameters

Attribute Description Required

Descriptive name for this controller that is shown in the tree, and
Name Yes
used to name the transaction.
Runtime
Desired runtime in seconds Yes
(seconds)

18.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

Parameters

Attribute Description Required

Name Descriptive name for this controller that is shown in the tree. No
Condition
By default the condition is interpreted as Javascript code that
(default Yes
returns "true" or "false", but this can be overriden (see below)
Javascript)
If this is selected, then the condition must be an expression
Interpret
that evaluates to "true" (case is ignored). For example, $
Condition as
{FOUND} or ${__jexl(${VAR} > 100)} . Unlike the Yes
Variable
Javascript case, the condition is only checked to see if it
Expression?
matches "true" (case is ignored).
Evaluate for all Should condition be evaluated for all children? If not checked,
Yes
children then the condition is only evaluated on entry.

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.

Examples (Variable Expression):

 ${__jexl(${COUNT} < 10)}

 ${RESULT}
18.2.10 While Controller
The While Controller runs its children until the condition is "false".

Possible condition values:

 blank - exit loop when last sample in loop fails

 LAST - exit loop when last sample in loop fails. If the last sample just before the
loop failed, don't enter loop.
 Otherwise - exit (or don't enter) the loop when the condition is equal to the string
"false"

The condition can be any variable or function

that eventually evaluates to the string "false".
This allows the use of JavaScript, BeanShell,
properties or variables as needed.

For example:
 ${VAR} - where VAR is set to false by some other test element
 ${__javaScript(${C}==10)}

 ${__javaScript("${VAR2}"=="abcd")}
 ${_P(property)} - where property is set to "false" somewhere else

Control Panel

Parameters

Attribute Description Required

Descriptive name for this controller that is shown in the tree, and used
Name Yes
to name the transaction.
Condition blank, LAST, or variable/function Yes

18.2.11 Switch Controller

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.

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

Attribute Description Required

Descriptive name for this controller that is shown in the tree, and
Name Yes
used to name the transaction.
Switch The number (or name) of the subordinate element to be invoked.
Yes
Value Elements are numbered from 0.

18.2.12 ForEach Controller

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
Note: the "_" separator is now optional.

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.

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

Attribute Description Required

Name Descriptive name for this controller that is shown in the tree. No
Input variable
Prefix for the variable names to be used as input. Yes
prefix
The name of the variable which can be used in the loop for
Output variable Yes
replacement in the samplers
Use Separator If not checked, the "_" separator is omitted. Yes

ForEach Example

Download this example (see Figure 7). In this example, we created a Test Plan that sends a
particular HTTP Request only once and sends another HTTP Request to every link that can be found
on the page.
Figure 7 - ForEach Controller Example

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

Figure 8 - ForEach Controller Example 2

The Thread Group has a single thread and a loop count of two.

Sample 1 uses the JavaTest Sampler to return the string "a b c d".

The Regex Extractor uses the expression (\w)\s which matches a letter followed by a space,
and returns the letter (not the space). Any matches are prefixed with the string "inputVar".

The ForEach Controller extracts all variables with the prefix "inputVar_", and executes its
sample, passing the value in the variable "returnVar". In this case it will set the variable to
the values "a" "b" and "c" in turn.

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.

18.2.13 Module Controller

The Module Controller provides a mechanism for substituting test plan fragments into the
current test plan at run-time.

A test plan fragment consists of a Controller and all the test elements (samplers etc)
contained in it. The fragment can be located in any Thread Group, or on the WorkBench . If
the fragment is located in a Thread Group, then its Controller can be disabled to prevent the
fragment being run except by the Module Controller. Or you can store the fragments in a
dummy Thread Group, and disable the entire Thread Group.

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:

Test Plan / Protocol: JDBC / Control / Interleave Controller (Module1)

Any fragments used by the Module Controller must have a unique name , as the name is
used to find the target controller when a test plan is reloaded. For this reason it is best to
ensure that the Controller name is changed from the default - as shown in the example above
- otherwise a duplicate may be accidentally created when new elements are added to the test
plan.

Control Panel
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

Attribute Description Required

Name Descriptive name for this controller that is shown in the tree. No
Module to The module controller provides a list of all controllers loaded into
Yes
Run the gui. Select the one you want to substitute in at runtime.

18.2.14 Include Controller

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.

This element does not support

variables/functions in the filename field.

However, if the property

includecontroller.prefix is defined, the
contents are used to prefix the pathname.

If the file cannot be found at the location given by prefix+filename, then the controller
attempts to open the fileName relative to the JMX launch directory (versions of JMeter after
2.3.4).

Control Panel

Parameters

Attribute Description Required

Filename The file to include. Yes

18.2.15 Transaction Controller

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

 additional sample is added after the nested samples

 additional sample is added as a parent of the nested samples

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

Parameters

Attribute Description Required

Descriptive name for this controller that is shown in the
Name Yes
tree, and used to name the transaction.
If checked, then the sample is generated as a parent of the
Generate Parent
other samples, otherwise the sample is generated as an Yes
Sample
independent sample.
Include timer Whether to include timer, pre- and post-processing delays in
duration in the generated sample. Default is true to be compatible with Yes
generated sample the behaviour in previous versions of JMeter.

18.2.16 Recording Controller

The Recording Controller is a place holder indicating where the proxy server should record
samples to. During test run, it has no effect, similar to the Simple Controller. But during
recording using the HTTP Proxy Server , all recorded samples will by default be saved under
the Recording Controller.

Control Panel

Parameters

Attribute Description Required

Name Descriptive name for this controller that is shown in the tree. No

18.3 Listeners

Most of the listeners perform several roles in addition to "listening" to the test results. They
also provide means to view, save, and read saved test results.

Note that Listeners are processed at the end of the scope in which they are found.

The saving and reading of test results is generic. The various listeners have a panel whereby
one can specify the file to which the results will be written (or read from). By default, the
results are stored as XML files, typically with a ".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:

 Simple Data Writer

 BeanShell/BSF Listener
  Mailer Visualizer
 Monitor Results
 Summary Report

The following Listeners no longer need to keep copies of every single sample. Instead,
samples with the same elapsed time are aggregated. Less memory is now needed, especially
if most samples only take a second or two at most.

 Aggregate Report
 Aggregate Graph
 Distribution Graph

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.
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

Result file configuration panel

Parameters

Attribute Description Required

File Name Name of the file containing sample results No
Browse... File Browse Button No
Errors Select this to write/read only results with errors No
Select this to write/read only results without errors. If neither Errors
Successes No
nor Successes is selected, then all results are processed.
Configure Configure Button, see below No
18.3.1 Sample Result Save Configuration
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

18.3.2 Graph Full Results

No Description

Control Panel
18.3.3 Graph Results
The Graph Results listener generates a simple graph that plots all sample times. Along the
bottom of the graph, the current sample (black), the current average of all samples(blue), the
current standard deviation (red), and the current throughput rate (green) are displayed in
milliseconds.

The 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.

 Data - plot the actual data values

 Average - plot the Average
 Median - plot the Median (midway value)
 Deviation - plot the Standard Deviation (a measure of the variation)
 Throughput - plot the number of samples per unit of time

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".

18.3.4 Spline Visualizer

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

18.3.5 Assertion Results

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.

Control Panel
See Also:

 Response Assertion

18.3.6 View Results Tree

The View Results Tree shows a tree of all sample responses, allowing you to view the
response for any sample. In addition to showing the response, you can see the time it took to
get this response, and some response codes. Note that the Request panel only shows the
headers added by JMeter. It does not show any headers (such as Host) that may be added by
the HTTP protocol implementation.

There are several ways to view the response, selectable by a drop-down box at the bottom of
the left hand panel.

 HTML
 HTML (download embedded resources)
 JSON
 Regexp Tester
 Text
 XML

Additional renderers can be created. The class must implement the interface
org.apache.jmeter.visualizers.ResultRenderer and/or extend the abstract class
org.apache.jmeter.visualizers.SamplerResultTab , and the compiled code must be
available to JMeter (e.g. by adding it to the lib/ext directory).

The default "Text" view shows all of the text contained in the response. Note that this will
only work if the response content-type is considered to be text. If the content-type begins
with any of the following, it is considered as binary, otherwise it is considered to be text.

image/
audio/
video/

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. No images etc are
downloaded. If the HTML (download embedded resources) option is selected, the renderer
may download images and style-sheets etc referenced by the HTML.

The XML view will show response in tree style. Any DTD nodes or Prolog nodes will not
show up in tree; however, response may contain those nodes.

The JSON view will show the response in tree style (also handles JSON embedded in
JavaScript).

Most of the views also allow the displayed data to be searched; the result of the search will be
high-lighted in the display above. For example the Control panel screenshot below shows one
result of searching for "Java". Note that the search operates on the visible text, so you may
get different results when searching the Text and HTML views.

The "Regexp Tester" view only works for text responses. It shows the plain text in the upper
panel. The "Test" button allows the user to apply the Regular Expression to the upper panel
and the results will be displayed in the lower panel. For example, the RE (JMeter\w*).*
applied to the current JMeter home page gives the following output:

Match count: 26
Match[1][0]=JMeter - Apache JMeter</title>
Match[1][1]=JMeter
Match[2][0]=JMeter" title="JMeter" border="0"/></a>
Match[2][1]=JMeter
Match[3][0]=JMeterCommitters">Contributors</a>
Match[3][1]=JMeterCommitters
... and so on ...

The first number in [] is the match number; the second number is the group. Group [0] is
whatever matched the whole RE. Group [1] is whatever matched the 1st group, i.e.
(JMeter\w*) in this case. See Figure 9b (below).

Control Panel
The Control Panel (above) shows an example of an HTML display. Figure 9 (below) shows an example
of an XML display.
Figure 9 Sample XML display

Figure 9a Sample Regexp Test display

18.3.7 Aggregate Report

The aggregate report creates a table row for each differently named request in your test. For
each request, it totals the response information and provides request count, min, max,
average, error rate, approximate throughput (request/second) and Kilobytes per second
throughput. Once the test is done, the throughput is the actual through for the duration of the
entire test.

The 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 additional
memory. For JMeter 2.3.4 and earlier, details of each sample were saved separately, which
meant a lot of memory was needed. JMeter now combines samples with the same elapsed
time, so far less memory is used. However, for samples that take more than a few seconds,
the probability is that fewer samples will have identical times, in which case more memory
will be needed. See the Summary Report for a similar Listener that does not store individual
samples and so needs constant memory.

 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

Times are in milliseconds.

Control Panel

The figure below shows an example of selecting the "Include group name" checkbox.
Sample "Include group name" display

18.3.8 View Results in Table

This visualizer creates a row for every sample result. Like the View Results Tree , this
visualizer uses a lot of memory.

Control Panel
18.3.9 Simple Data Writer
This listener can record results to a file but not to the UI. It is meant to provide an efficient
means of recording data by eliminating GUI overhead. When running in non-GUI mode, the
-l flag can be used to create a data file. The fields to save are defined by JMeter properties.
See the jmeter.properties file for details.

Control Panel

18.3.10 Monitor Results

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
18.3.11 Distribution Graph (alpha)
The distribution graph will display a bar for every unique response time. Since the granularity
of System.currentTimeMillis() is 10 milliseconds, the 90% threshold should be within the
width of the graph. The graph will draw two threshold lines: 50% and 90%. What this means
is 50% of the response times finished between 0 and the line. The same is true of 90% line.
Several tests with Tomcat were performed using 30 threads for 600K requests. The graph was
able to display the distribution without any problems and both the 50% and 90% line were
within the width of the graph. A performant application will generally produce results that
clump together. A poorly written application that has memory leaks may result in wild
fluctuations. In those situations, the threshold lines may be beyond the width of the graph.
The recommended solution to this specific problem is fix the webapp so it performs well. If
your test plan produces distribution graphs with no apparent clumping or pattern, it may
indicate a memory leak. The only way to know for sure is to use a profiling tool.

Control Panel
18.3.12 Aggregate Graph
The aggregate graph is similar to the aggregate report. The primary difference is the
aggregate graph provides an easy way to generate bar graphs and save the graph as a PNG
file. By default, the aggregate graph will generate a bar chart 450 x 250 pixels.

Control Panel
18.3.13 Mailer Visualizer
The mailer visualizer can be set up to send email if a test run receives too many failed
responses from the server.

Control Panel
Parameters

Attribute Description Required

Name Descriptive name for this element that is shown in the tree. No
From Email address to send messages from. Yes
Addressee(s) Email address to send messages to, comma-separated. Yes
SMTP Host IP address or host name of SMTP (email redirector) server. No
Failure
Email subject line for fail messages. No
Subject
Success
Email subject line for success messages. No
Subject
Once this number of failed responses is exceeded, a failure email is
Failure Limit Yes
sent - i.e. set the count to 0 to send an e-mail on the first failure.
Once this number of successful responses is exceeded after
previously reaching the failure limit , a success email is sent.
Success Limit Yes
The mailer will thus only send out messages in a sequence of
failed-succeeded-failed-succeeded, etc.
Test Mail Press this button to send a test mail No
A field that keeps a running total of number of failures so far
Failures No
received.