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.

Other software that you may need to download:

• BeanShell - needed for the BeanShell

 function and test elements
• Java Activation Framework - needed for
JavaMail
• Java Mail - needed for Mail Visualiser,
Mail Reader and WebService(SOAP) sampler
• JMS - for JMS samplers
• General Java download page

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.4 or higher.
Version 2.2 and later no longer
support Java 1.3.

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 or want to use Sun's
Java Standard Extension packages, 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.4 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 limited Email capabilities. It can send email based
on test results, and has a POP/IMAP sampler. It does not
currently support SMTP sampling. To enable Email support,
add Sun's JavaMail packages and the activation packages to
JMeter's classpath .
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 defaults to protocol level TLS. This can be changed by

editting the JMeter property "https.default.protocol" in
jmeter.properties or user.properties.

JMeter is 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) does not support
recording SSL (https).

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

Apache SOAP requires mail.jar and activation.jar. You need to
download and copy these two jar files to your jmeter/lib
directory. Once the files are in there, JMeter will automatically
pick them up.

2.2.7 BeanShell
To run the BeanShell function or any of the BeanShell test
elements (sampler, timer etc), you need to download the
beanshell jar from http://www.beanshell.org/ and copy the jar
file to the jmeter/lib directory , where JMeter will
automatically pick it up.
2.2.7 Libraries for ActiveMQ 3.0
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
Note: avoid installing JMeter in
a path with spaces in the name.
This causes problems for
remote testing.

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.

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 (e.g. jakarta-jmeter-2.3.1)

if you want, but do not change any of the sub-directory names.
The path to the parent directory should not contain any spaces;
if it does, then you may have problems running client-server
mode.

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

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.

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

• jmeter - run JMeter (in GUI mode by

default)
• jmeter-server - start JMeter in server
mode

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 the extension jars in the lib/ext

directory, then define the property search_paths in
jmeter.properties. Do not use lib/ext for utility jars; it is only
intended for JMeter components.

Other jars (such as JDBC, JavaMail, Beanshell 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 (but not HTTPS)
browser sessions. This is not to
be confused with the proxy
settings described above,
which are used when JMeter
makes HTTP or HTTPS
requests itself.

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

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

-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. [in JMeter 2.2 and earlier, this
was forced to be the JMeter bin directory.]

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 don't
ssl.provider No
want to use the built-in Java
implementation.
You can specify an
implementation as your XML
xml.parser parser. The default value is: No
org.apache.xerces.parsers.SAXPar
ser
remote_hosts Comma-delimited list of remote No
JMeter hosts (or host:port if
 required). If you are running
JMeter in a distributed
environment, list the machines
where you have JMeter remote
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
not_in_menu only those components you are No
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 add-
search_paths on classes; for example additional No
samplers. This is in addition to any
jars found in the lib/ext directory.
List of paths that JMeter will
search for utility classes. This is in
user.classpath No
addition to any jars found in the lib
directory.
Name of file containing additional
JMeter properties. These are added
user.properties after the initial property file, but No
before the -q and -J options are
processed.
Name of file containing additional
system.propertie system properties. These are added
No
s before the -S and -D 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.

Index Next Prev

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 "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 "open" option. Choose the file where your elements
are saved. JMeter will load the elements into the tree.

To save tree elements, right click on an element and choose the

"save" option. JMeter will save the element selected, plus all
child elements beneath it. In this way, you can save test tree
fragments, individual elements, or the entire test plan.

The workbench is not

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

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 Test Plan 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 As menu item.
Alternatively, select the
appropriate Test Plan element
and then select Save As from
the Edit menu.

3.5 Running a Test Plan

To run your test plan, choose "start" from the "run" menu item.
To stop your test plan, choose "stop" from the same menu.
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).

There are two types of stop command:

• Stop (Control + '.') - stops the threads

immediately

• Shutdown (Control + ',')- requests the

threads to stop at the end of any current work

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

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.
About Index Next Prev

• Overview
• Changes • 18.1 Samplers
• Known Bugs o FTP Request
• License o HTTP Request
• Contributors o JDBC Request
o Java Request
Download o SOAP/XML-RPC Request
o WebService(SOAP) Request
• Download o LDAP Request
Releases o LDAP Extended Request
• Developer o Access Log Sampler
(Nightly) o BeanShell Sampler
Builds o BSF Sampler
o TCP Sampler
Documentation o JMS Publisher
o JMS Subscriber
• User Manual o JMS Point-to-Point
• Javadocs o JUnit Request
• Localisation o Mail Reader Sampler
(Translator's o Test Action
Guide) • 18.2 Logic Controllers
• Building o Simple Controller
JMeter and o Loop Controller
Add-Ons
o Once Only Controller
• JMeter Wiki
o Interleave Controller
• FAQ (Wiki)
o Random Controller
o Random Order Controller
Tutorials (PDF
o Throughput Controller
format)
o Runtime Controller
o If Controller
• Distributed
o While Controller
Testing
• Recording o Switch Controller
Tests o ForEach Controller
• JUnit Sampler o Module Controller
• Access Log o Include Controller
Sampler o Transaction Controller
• Extending o Recording Controller
JMeter • 18.3 Listeners
o Sample Result Save Configuration
Community o Graph Full Results
o Graph Results
• Get Involved o Spline Visualizer
• Mailing Lists o Assertion Results
o View Results Tree
• SVN
 Copyright © 1999-2008, Apache Software Foundation
Functions and Variables

JMeter functions are special values that can populate fields of any Sampler or other element in a
test tree. A function call looks like this:

${__functionName(var1,var2,var3)}

Where "__functionName" matches the name of a function.

Parentheses surround the parameters sent to the function, for example ${__time(YMD)} The
actual parameters vary from function to function. Functions that require no parameters can leave
off the parentheses, for example ${__threadNum}.

If a function parameter contains a comma, then be sure to escape this with "\", otherwise JMeter
will treat it as a parameter delimiter. For example:

${__time(EEE\, d MMM yyyy)}

Variables are referenced as follows:

${VARIABLE}

If an undefined function or variable is referenced, JMeter does not report/log an error - the
reference is returned unchanged. For example if UNDEF is not defined as a variable, then
the value of ${UNDEF} is ${UNDEF}. Variables, functions (and properties) are all case-
sensitive. Versions of JMeter after 2.3.1 trim spaces from variable names before use, so for
example ${__Random(1,63, LOTTERY )} will use the variable 'LOTTERY' rather than '
LOTTERY '.

Properties are not the same as variables.

Variables are local to a thread; properties are
common to all threads, and need to be referenced
using the __P or __property function.

List of functions, loosely grouped into types.

Type of function Name Comment

Information threadNum get thread number
Information machineName get the local machine name
Information time return current time in various formats
Information log log (or display) a message (and return the value)
Information logn log (or display) a message (empty return value)
Input StringFromFile read a line from a file
Input CSVRead read from CSV delimited file
Input XPath Use an XPath expression to read from a file
Calculation counter generate an incrementing number
Calculation intSum add int numbers
Calculation longSum add long numbers
Calculation Random generate a random number
Calculation regexFunction parse previous response using a regular expression
Scripting BeanShell run a BeanShell script
Scripting javaScript process JavaScript (Mozilla Rhino)
Scripting jexl evaluate a Commons Jexl expression
Properties property read a property
Properties P read a property (shorthand method)
Properties setProperty set a JMeter property
Variables split Split a string into variables
Variables V evaluate a variable name
Variables eval evaluate a variable expression
Variables evalVar evaluate an expression stored in a variable
19.1 What can functions do
There are two kinds of functions: user-defined static values (or variables), and built-in functions.
User-defined static values allow the user to define variables to be replaced with their static value
when a test tree is compiled and submitted to be run. This replacement happens once at the
beginning of the test run. This could be used to replace the DOMAIN field of all HTTP requests,
for example - making it a simple matter to change a test to target a different server with the same
test.

Note that variables cannot currently be nested; i.e ${Var${N}} does not work. The __V
(variable) function (versions after 2.2) can be used to do this: ${__V(Var${N})}. In earlier
JMeter versions one can use ${__BeanShell(vars.get("Var${N}")}.

This type of replacement is possible without functions, but was less convenient and less intuitive.
It required users to create default config elements that would fill in blank values of Samplers.
Variables allow one to replace only part of any given value, not just filling in blank values.

With built-in functions users can compute new values at run-time based on previous response
data, which thread the function is in, the time, and many other sources. These values are
generated fresh for every request throughout the course of the test.

Functions are shared between threads. Each

occurrence of a function call in a test plan is
handled by a separate function instance.
19.2 Where can functions and variables be used?
Functions and variables can be written into any field of any test component (apart from the
TestPlan - see below). Some fields do not allow random strings because they are expecting
numbers, and thus will not accept a function. However, most fields will allow functions.

Functions which are used on the Test Plan have some restrictions. JMeter thread variables will
have not been fully set up when the functions are processed, so variable names passed as
parameters will not be set up, and variable references will not work, so split() and regex() and the
variable evaluation functions won't work. The threadNum() function won't work (and does not
make sense at test plan level). The following functions should work OK on the test plan:

• intSum
• longSum
• machineName
• BeanShell
• javaScript
• jexl
• random
• time
• property functions
• log functions

Configuration elements are processed by a separate thread. Therefore functions such as

__threadNum do not work properly in elements such as User Defined Variables. Also note that
variables defined in a UDV element are not available until the element has been processed.

When using variable/function references in SQL

code (etc), remember to include any necessary
quotes for text strings, i.e. use
SELECT item from table where name='$
{VAR}'
not
SELECT item from table where name=${VAR}

(unless VAR itself contains the quotes)

19.3 How to reference variables and functions

Referencing a variable in a test element is done by bracketing the variable name with '${' and '}'.

Functions are referenced in the same manner, but by convention, the names of functions begin
with "__" to avoid conflict with user value names * . Some functions take arguments to configure
them, and these go in parentheses, comma-delimited. If the function takes no arguments, the
parentheses can be omitted.

Argument values that themselves contain commas should be escaped as necessary. If you need to
include a comma in your parameter value, escape it like so: '\,'. This applies for example to the
scripting functions - Javascript, Beanshell, Jexl - where it is necessary to escape any commas that
may be needed in script method calls - e.g.

${__BeanShell(vars.put("name"\,"value"))}

Functions can reference variables and other functions, for example ${__XPath($
{__P(xpath.file),${XPATH})} will use the property "xpath.file" as the file name and the
contents of the variable XPATH as the expression to search for.

JMeter provides a tool to help you construct function calls for various built-in functions, which
you can then copy-paste. It will not automatically escape values for you, since functions can be
parameters to other functions, and you should only escape values you intend as literal.

The value of a variable or function can be reported using the __logn() function. The __logn()
function reference can be used anywhere in the test plan after the variable has been defined.
Alternatively, the Java Request sampler can be used to create a sample containing variable
references; the output will be shown in the appropriate Listener. For versions of JMeter later than
2.3, there is a Debug Sampler that can be used to display the values of variables etc in the Tree
View Listener.

*
If you define a user-defined static variable with
the same name as a built-in function, your static
variable will override the built-in function.

19.4 The Function Helper Dialog

The Function Helper dialog is available from JMeter's Tools menu.

Function Helper Dialog

Using the Function Helper, you can select a function from the pull down, and assign values for
its arguments. The left column in the table provides a brief description of the argument, and the
right column is where you write in the value for that argument. Different functions take different
arguments.

Once you have done this, click the "generate" button, and the appropriate string is generated for
you to copy-paste into your test plan wherever you like.

19.5 Functions
19.5.1 __regexFunction
The Regex Function is used to parse the previous response (or the value of a variable) using any
regular expression (provided by user). The function returns the template string with variable
values filled in.

The __regexFunction can also store values for future use. In the sixth parameter, you can specify
a reference name. After this function executes, the same values can be retrieved at later times
using the syntax for user-defined values. For instance, if you enter "refName" as the sixth
parameter you will be able to use:

• ${refName} to refer to the computed result of the second parameter ("Template for the
replacement string") parsed by this function
• ${refName_g0} to refer to the entire match parsed by this function.
• ${refName_g1} to refer to the first group parsed by this function.
• ${refName_g#} to refer to the n th group parsed by this function.
• ${refName_matchNr} to refer to the number of groups found by this function.

Parameters

Attribute Description Required

The first argument is the regular expression to be applied to the
response data. It will grab all matches. Any parts of this expression that
you wish to use in your template string, be sure to surround in
First parentheses. Example: <a href="(.*)">. This will grab the value of the
Yes
argument link and store it as the first group (there is only 1 group). Another
example: <input type="hidden" name="(.*)" value="(.*)">. This will
grab the name as the first group, and the value as the second group.
These values can be used in your template string
This is the template string that will replace the function at run-time. To
Second
refer to a group captured in the regular expression, use the syntax: $ Yes
argument
[group_number]$. Ie: $1$, or $2$. Your template can be any string.
The third argument tells JMeter which match to use. Your regular
expression might find numerous matches. You have four choices:

• An integer - Tells JMeter to use that match. '1' for the first found
match, '2' for the second, and so on
• RAND - Tells JMeter to choose a match at random.
Third No,
• ALL - Tells JMeter to use all matches, and create a template
argument default=1
string for each one and then append them all together. This
option is little used.

• A float number between 0 and 1 - tells JMeter to find the Xth

match using the formula: (number_of_matches_found *
float_number) rounded to nearest integer.
Fourth If 'ALL' was selected for the above argument value, then this argument
19.6 Pre-defined Variables
Most variables are set by calling functions or by test elements such as User Defined Variables; in
which case the user has full control over the variable name that is used. However some variables
are defined internally by JMeter. These are listed below.

• cookiename - contains the cookie value

• JMeterThread.last_sample_ok - whether or not the last sample was OK -
true/false

• START variables (see next section)

19.6 Pre-defined Properties

The set of JMeter properties is initialised from the system properties defined when JMeter starts;
additional JMeter properties are defined in jmeter.properties, user.properties or on the command
line.

Some built-in properties are defined by JMeter. These are listed below. For convenience, the
START properties are also copied to variables with the same names.

• START.MS - JMeter start time in milliseconds

• START.YMD - JMeter start time as yyyyMMdd
• START.HMS - JMeter start time as HHmmss
• TESTSTART.MS - test start time in milliseconds

Please note that the START variables / properties represent JMeter startup time, not the test start
time. They are mainly intended for use in file names etc.

Regular Expressions
20.1 Overview
JMeter includes the pattern matching software Apache Jakarta ORO
There is some documentation for this on the Jakarta web-site, for example a summary of the
pattern matching characters

There is also documentation on an older incarnation of the product at OROMatcher User's guide
, which might prove useful.

The pattern matching is very similar to the pattern matching in Perl. A full installation of Perl
will include plenty of documentation on regular expressions - look for perlrequick, perlretut,
perlre, perlreref.

It is worth stressing the difference between "contains" and "matches", as used on the Response
Assertion test element:
 • "contains" means that the regular expression matched at least some part of
the target, so 'alphabet' "contains" 'ph.b.' because the regular expression matches
the substring 'phabe'.
• "matches" means that the regular expression matched the whole target. So
'alphabet' is "matched" by 'al.*t'.

In this case, it is equivalent to wrapping the regular expression in ^ and $, viz '^al.*t$'.

However, this is not always the case. For example, the regular expression 'alp|.lp.*' is
"contained" in 'alphabet', but does not match 'alphabet'.

Why? Because when the pattern matcher finds the sequence 'alp' in 'alphabet', it stops trying any
other combinations - and 'alp' is not the same as 'alphabet', as it does not include 'habet'.

Note: unlike Perl, there is no need to (i.e. do not) enclose the regular expression in //.

So how does one use the modifiers ismx etc if there is no trailing /? The solution is to use
extended regular expressions , i.e. /abc/i becomes (?i)abc. See also Placement of modifiers
below.

20.2 Examples
Extract single string
Suppose you want to match the following portion of a web-page:
name="file" value="readme.txt" and you want to extract readme.txt.
A suitable reqular expression would be:
name="file" value="(.+?)"

The special characters above are:

• ( and ) - these enclose the portion of the match string to be returned

• . - match any character. + - one or more times. ? - don't be greedy, i.e. stop
when first match succeeds

Note: without the ?, the .+ would continue past the first " until it found the last possible " -
probably not what was intended.

Extract multiple strings

Suppose you want to match the following portion of a web-page: name="file.name"

value="readme.txt" and you want to extract file.name and readme.txt.
A suitable reqular expression would be:
name="(.+?)" value="(.+?)"
This would create 2 groups, which could be used in the JMeter Regular Expression Extractor
template as $1$ and $2$.
The JMeter Regex Extractor saves the values of the groups in additional variables.

For example, assume:

• Reference Name: MYREF

• Regex: name="(.+?)" value="(.+?)"
• Template: $1$$2$

Do not enclose the regular expression in / /

The following variables would be set:

• MYREF: file.namereadme.txt
• MYREF_g0: name="file.name" value="readme.txt"
• MYREF_g1: file.name
• MYREF_g2: readme.txt

These variables can be referred to later on in the JMeter test plan, as ${MYREF}, $
{MYREF_g1} etc

20.3 Line mode

The pattern matching behaves in various slightly different ways, depending on the setting of the
multi-line and single-line modifiers. Note that the single-line and multi-line operators have
nothing to do with each other; they can be specified independently.

Single-line mode

Single-line mode only affects how the '.' meta-character is interpreted.

Default behaviour is that '.' matches any character except newline. In single-line mode, '.' also
matches newline.

Multi-line mode

Multi-line mode only affects how the meta-characters '^' and '$' are interpreted.

Default behaviour is that '^' and '$' only match at the very beginning and end of the string. When
Multi-line mode is used, the '^' metacharacter matches at the beginning of every line, and the '$'
metacharacter matches at the end of every line.

20.4 Meta characters

Regular expressions use certain characters as meta characters - these characters have a special
meaning to the RE engine. Such characters must be escaped by preceeding them with \
(backslash) in order to treat them as ordinary characters. Here is a list of the meta characters and
their meaning (please check the ORO documentation if in doubt).

• ( ) - grouping
• [ ] - character classes
• { } - repetition
• * + ? - repetition
• . - wild-card character
• \ - escape character
• | - alternatives
• ^ $ - start and end of string or line

Please note that ORO does not support the \Q and \E meta-characters. [In other RE engines, these
can be used to quote a portion of an RE so that the meta-characters stand for themselves.]

20.5 Placement of modifiers

Modifiers can be placed anywhere in the regex, and apply from that point onwards. [A bug in
ORO means that they cannot be used at the very end of the regex. However they would have no
effect there anyway.]

The single-line (?s) and multi-line (?m) modifiers are normally placed at the start of the regex.

The ignore-case modifier (?i) may be usefully applied to just part of a regex, for example:

Match ExAct case or (?i)ArBiTrARY(?-i) case

Glossary

Latency . JMeter measures the latency from just before sending the request to just after the first
response has been received. Thus the time includes all the processing needed to assemble the
request as well as assembling the response, which in general will be longer than one byte.
Protocol analysers (such as Wireshark) measure the time when bytes are actually sent/received
over the interface. The JMeter time should be closer to that which is experienced by a browser or
other application client.

Median is a number which divides the samples into two equal halves. Half of the samples are
smaller than the median, and half are larger. [Some samples may equal the median.] This is a
standard statistical measure. See, for example: Median entry at Wikipedia. The Median is the
same as the 50 th Percentile

90% Line (90 th Percentile) is the value below which 90% of the samples fall. The remaining
samples too at least as long as the value. This is a standard statistical measure. See, for example:
Percentile entry at Wikipedia.
Throughput is calculated as requests/unit of time. The time is calculated from the start of the
first sample to the end of the last sample. This includes any intervals between samples.