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.1jakarta-jmeter-2.3.1/binjakarta-jmeter-2.3.1/docsjakarta-jmeter-2.3.1/extrasjakarta-jmeter-2.3.1/lib/jakarta-jmeter-2.3.1/lib/extjakarta-jmeter-2.3.1/lib/junitjakarta-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 DescriptionRequire

d

ssl.provider

You can specify the class for your SSL implementation if you don't want to use the built-in Java implementation.

No

xml.parser

You can specify an implementation as your XML parser. The default value is: org.apache.xerces.parsers.SAXParser

No

remote_hosts Comma-delimited list of remote JMeter hosts (or host:port if required). If you are running

No

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

not_in_menu

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

No

search_paths

List of paths (separated by ;) that JMeter will search for JMeter add-on classes; for example additional samplers. This is in addition to any jars found in the lib/ext directory.

No

user.classpath

List of paths that JMeter will search for utility classes. This is in addition to any jars found in the lib directory.

No

user.properties

Name of file containing additional JMeter properties. These are added after the initial property file, but before the -q and -J options are processed.

No

system.properties

Name of file containing additional system properties. These are added before the -S and -D options are processed.

No

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.

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 request that a thread makes.

If you choose to add more than one timer to a Thread Group, JMeter takes the sum of the timers and pauses for that amount of time before executing the samplers to which the timers apply. Timers can be added as children of samplers or controllers in order to restrict the samplers to

which they are applied.

To provide a pause at a single place in a test plan, one can use the Test Action Sampler.

4.5 Assertions

Assertions allow you to assert facts about responses received from the server being tested. Using an assertion, you can essentially "test" that your application is returning the results you expect it to.

For instance, you can assert that the response to a query will contain some particular text. The text you specify can be a Perl-style regular expression, and you can indicate that the response is to contain the text, or that it should match the whole response.

You can add an assertion to any Sampler. For example, you can add an assertion to a HTTP Request that checks for the text, "</HTML>". JMeter will then check that the text is present in the HTTP response. If JMeter cannot find the text, then it will mark this as a failed request.

To view the assertion results, add an Assertion Listener to the Thread Group. Failed Assertions will also show up in the Tree View and Table Listeners, and will count towards the error %age for example in the Aggregate and Summary reports.

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 1Timer 1Timer 2Sampler 1Post-Processor 1Post-Processor 2Assertion 1

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

4.10 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 elements, then the last one takes effect. Other elements such as the User Parameters Pre-Processor or Regular Expression Extractor Post-Processor may be used to redefine the same variables. These redefinitions only apply to the current thread.

Note that global variables cannot be updated during a test. 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.

Changes

Known Bugs

License

Contributors

Download

Download Releases Developer (Nightly) Builds

Documentation

User Manual Javadocs

Localisation (Translator's Guide)

Building JMeter and Add-Ons

JMeter Wiki

FAQ (Wiki)

Tutorials (PDF format)

Distributed Testing Recording Tests

JUnit Sampler

Access Log Sampler

Extending JMeter

Community

Get Involved Mailing Lists

SVN Repositories

Index Next Prev

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 0 seconds. This property tells JMeter how long to delay between starting each user. For example, if you enter a Ramp-Up

Period of 5 seconds, JMeter will finish starting all of your users by the end of the 5 seconds. So, if we have 5 users and a 5 second Ramp-Up Period, then the delay between starting users would be 1 second (5 users / 5 seconds = 1 user per second). If you set the value to 0, then JMeter will immediately start all of your users.

Finally enter a value of 2 in the Loop Count field. This property tells JMeter how many times to repeat your test. If you enter a loop count value of 1, then JMeter will run your test only once. To have JMeter repeatedly run your Test Plan, select the Forever checkbox.

In most applications, you have to manually accept changes you make in a Control Panel. However, in JMeter, the Control Panel automatically accepts your changes as you make them. If you change the name of an element, the tree will be updated with the new text after you leave the Control Panel (for example, when selecting another tree element).

See Figure 5.2 for the completed Jakarta Users Thread Group.

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

Change the Name field to "Home Page". 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:

Change the Name field to "Project Guidelines". Set the Path field to "/site/guidelines.html".

Figure 5.6. HTTP Request for Jakarta Project Guidelines

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

Index Next Prev

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

Index Next Prev

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

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

The port to 389. These values are default for the LDAP

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

Figure 10.3. Webservice Request

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

Index Next Prev

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 Queue

Q.REQQ This is equal to the JNDI 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.Q.REQ This defines a JNDI name Q.REQ for the request queue that points to the queue example.Q.REQ.

queue.Q.RPL example.Q.RPL This defines a JNDI name Q.RPL for the reply queue that points to the queue example.Q.RPL.

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

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

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

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|failureMessage02/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=csvjmeter.save.saveservice.assertion_results_failure_message=truejmeter.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

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

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

Assertion Results

Mailer Visualizer

Monitor Results

Summary Report

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

Variables, if specified

14.5 XML Log format 2.0

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

<?xml version="1.0" encoding="UTF-8"?><testResults version="1.2"><sampleResult timeStamp="1144365463297" dataType="text" threadName="Listen 1-1" label="HTTP Request" time="1502" responseMessage="OK" responseCode="200" success="true">

<sampleResult timeStamp="1144365464238" dataType="text" threadName="Listen 1-1" label="http://www.apache.org/style/style.css" time="171" responseMessage="OK" responseCode="200" success="true"> <property xml:space="preserve" name="samplerData"> GET http://www.apache.org/style/style.css </property> <binary> body, td, th { font-size: 95%; font-family: Arial, Geneva, Helvetica, sans-serif; color: black; background-color: white; } ... </binary> </sampleResult></sampleResult>...</testResults>

14.6 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 OKDate: 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 OKDate: 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 OKDate: 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.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 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.

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.

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 a local machine Managment of multiple JMeterEngines from a single machine

However, remote mode does use more resources than running the same number of non-GUI tests independently.

Note that while you can indeed 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 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.

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

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=1664C:\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.

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)

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.

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

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=9000beanshell.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 runningStartup script completedHttpd started on port: 9000Sessiond 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 valueinc=Integer.decode(args[1]); // Incrementend=Integer.decode(args[2]); // Final valuesecs=Integer.decode(args[3]); // Wait between changeswhile(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.Interperterbsh% 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.

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.

About

Overview Changes

Known Bugs

License

Contributors

Download

Download Releases

Developer (Nightly) Builds

Documentation

User Manual Javadocs

Localisation (Translator's Guide)

Building JMeter and Add-Ons

JMeter Wiki

FAQ (Wiki)

Index Next Prev

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

o JMS Publisher

o JMS Subscriber

o JMS Point-to-Point

o JUnit Request

o Mail Reader Sampler

Tutorials (PDF format)

Distributed Testing

Recording Tests

JUnit Sampler

Access Log Sampler

Extending JMeter

Community

Get Involved Mailing Lists

SVN Repositories

o Test Action

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

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

18.6 Timers

o Constant Timer

o Gaussian Random Timer

o Uniform Random Timer

o Constant Throughput Timer

o Synchronizing Timer

o BeanShell 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 Counter

o BeanShell PreProcessor

o BSF PreProcessor

18.8 Post-Processors

o Regular Expression Extractor

o XPath Extractor

o Result Status Action Handler

o Save Responses to a file

o Generate Summary Results

o BeanShell PostProcessor

o BSF 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 RequestThis 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

NameDescriptive name for this controller that is shown in the tree.

No

Server Name or IP

Domain name or IP address of the FTP server. JMeter assumes the FTP server is listening on the default port.

Yes

Remote File:File to retrieve or name of destination file to upload.

Yes

Local File: File to upload, or destination for Yes, if

downloads (defaults to remote file name).

uploading (*)

Local File Contents:

Provides the contents for the upload, overrides the Local File property.

Yes, if uploading (*)

get(RETR) / put(STOR)

Whether to retrieve or upload a file. Yes

Use Binary mode ?

Check this to use Binary mode (default Ascii)

Yes

Save File in Response ?

Whether to store contents of retrieved file in response data. If the mode is Ascii, then the contents will be visible in the Tree View Listener.

Yes, if downloading

Username FTP account username. Usually

PasswordFTP account password. N.B. This will be visible in the test plan.

Usually

See Also:

Assertions FTP Request Defaults

Building an FTP Test Plan

18.1.2 HTTP RequestThis 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

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

NameDescriptive name for this controller that is shown in the tree.

No

ServerDomain name or IP address of the web server. e.g. www.example.com. [Do not include the http:// prefix.]

No

Port Port the web server is listening to. No

Default: 80

Protocol HTTP, HTTPS or FILE. Default: HTTP No

MethodGET, POST, HEAD, TRACE, OPTIONS, PUT, DELETE

Yes

Content EncodingContent encoding to be used (for POST and FILE)

No

Redirect Automatically

Sets the underlying http protocol handler to automatically follow redirects, so they are not seen by JMeter, and thus will not appear as samples. Should only be used for GET and 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.

Yes

Follow Redirects

This only has any effect if "Redirect Automatically" is not enabled. If set, the JMeter sampler will check if the response is a redirect and follow it if so. The redirect response will appear as an additional sample. Note that the HttpClient sampler may log the following message: "Redirect requested but followRedirects is disabled" This can be ignored.

Yes

Use KeepAlive

JMeter sets the Connection: keep-alive header. This does not work properly with the default HTTP implementation, as connection re-use is not under user-control. It does work with the Jakarta httpClient implementation.

Yes

Use multipart/form-data for HTTP POST

Use a multipart/form-data or application/x-www-form-urlencoded post request

Yes

Path The path to resource (for example, /servlets/myServlet). If the resource requires query string parameters, add them below in the "Send Parameters With the Request" section. As a special case, if the path starts with "http://" or

Yes

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

Send Parameters With the Request

The query string will be generated from the list of parameters you provide. Each parameter has a name and value , the options to encode the parameter, and an option to include or exclude an equals sign (some applications don't expect an equals when the value is the empty string). The query string will be generated in the correct fashion, depending on the choice of "Method" you made (ie if you chose GET or DELETE, the query string will be appended to the URL, if POST or PUT, then it will be sent separately). Also, if you are sending a file using a multipart form, the query string will be created using the multipart form specifications. 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.

No

File Path:

Name of the file to send. If left blank, JMeter does not send a file, if filled in, JMeter automatically sends the request as a multipart form request. If it is a POST or PUT request and there is a single file whose 'name' attribute (below) is omitted, then the file is sent as the entire body of the request, i.e. no wrappers are added. This allows arbitrary bodies to be sent. This functionality is present for POST requests after version 2.2, and also for PUT requests after version 2.3. See below for some further information on parameter handling.

No

Parameter name:Value of the "name" web request parameter.

No

MIME Type

MIME type (for example, text/plain). If it is a POST or PUT request and either the 'name' atribute (below) are omitted or the request body is constructed from parameter values only, then the value of this field is used as the value of the content-type request header.

No

Retrieve All Embedded Resources from HTML Files

Tell JMeter to parse the HTML file and send HTTP/HTTPS requests for all images, Java applets, JavaScript files, CSSs, etc. referenced in the file. See below for more details.

No

Use as monitor For use with the Monitor Results listener. Yes

Save response as MD5 hash?

If this is selected, then the response is not stored in the sample result. Instead, the 32 character MD5 hash of the data is calculated and stored instead. This is intended for testing large amounts of data.

Yes

Embedded URLs must match:

If present, this must be a regular expression that is used to match against any embedded URLs found. So if you only want to download embedded resources from http://example.com/, use the expression: http://example\.com/.*

No

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 GET and DELETE request methods work similarly.

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

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

Control Panel

Parameters

Attribute Description Required

NameDescriptive name for this controller that is shown in the tree.

No

Variable Name

Name of the JMeter variable that the connection pool is bound to. This must agree with the 'Variable Name' field of a JDBC Connection Configuration.

Yes

Query Type

Set this according to the statement type: Select Statement Update Statement - use this for Inserts as

Yes

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

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 CALL

SYSCS_UTIL.SYSCS_EXPORT_TABLE (null,?, ?, null, null, null)

o Parameter values: tablename,filename

o Parameter types: VARCHAR,VARCHAR

The second example assumes you are using Apache Derby.

Yes

Parameter values

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".) There must be as many values as there are placeholders in the statement.

Yes, if a prepared or callable statement has parameters

Parameter types

Comma-separated list of SQL parameter types (e.g. INTEGER, DATE, VARCHAR, DOUBLE). 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". There must be as many values as there are placeholders in the statement.

Yes, if a prepared or callable statement has parameters

See Also:

Building a Database Test Plan

JDBC Connection Configuration

18.1.4 Java RequestThis sampler lets you control a java class that implements the JavaSamplerClient interface. By writing your own implementation of this interface, you can use JMeter to harness multiple threads, input parameter control, and data collection.

The pull-down menu provides the list of all such implementations found by JMeter in its classpath. The parameters can then be specified in the table below - as defined by your implementation. Two simple examples (JavaTest and SleepTest) are provided.

The JavaTest example sampler can be useful for checking test plans, because it allows one to set values in almost all the fields. These can then be used by Assertions, etc. The fields allow variables to be used, so the values of these can readily be seen.

Control Panel

The Add/Delete buttons don't serve any purpose at present.

Parameters

Attribute Description Required

NameDescriptive name for this sampler that is shown in the tree.

No

ClassnameThe specific implementation of the JavaSamplerClient interface to be sampled.

Yes

Send Parameters with Request

A list of arguments that will be passed to the sampled class. All arguments are sent as Strings.

No

The sleep time is calculated as follows:

SleepTime is in millisecondsSleepMask 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/html", 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 XML.

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 No

shown in the tree.

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 Data

The Soap XML message, or XML-RPC instructions. Not used if the filename is provided.

No

FilenameIf specified, then the contents of the file are sent, and the Data field is ignored

No

18.1.6 WebService(SOAP) RequestThis 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 it separately.

An important note on the sampler is it will automatically use the proxy host and port passed to JMeter from command line, if thoe 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 there

apache soap does 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>

Control Panel

18.2 Logic Controllers

Logic Controllers determine the order in which Samplers are processed.

18.2.1 Simple ControllerThe 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

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

NameDescriptive name for this controller that is shown in the tree.

No

Loop Count

The number of times the subelements of this controller will be iterated each time through a test run. Special Case: The Loop Controller embedded in the Thread Group element behaves slightly differently. Unless set to forever, it stops the test after the given number of iterations have been done.

Yes, unless "Forever" is checked

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

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

nameDescriptive name for this controller that is shown in the tree.

No

ignore sub-controller blocks

If checked, the interleave controller will treat sub-controllers like single request elements and only allow one request per controller at a time.

No

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.

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

NameDescriptive name for this controller that is shown in the tree.

No

18.2.6 Random Order ControllerThe 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

NameDescriptive name for this controller that is shown in the tree.

No

18.2.7 Throughput ControllerThis 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

NameDescriptive name for this controller that is shown in the tree.

No

Execution Whether the controller will run in percent Yes

Style executions or total executions mode.

Throughput

A number. for percent execution mode, a number from 0-100 that indicates the percentage of times the controller will execute. "50" means the controller will execute during half the iterations throught the test plan. for total execution mode, the number indicates the total number of times the controller will execute.

Yes

Per User

If checked, per user will cause the controller to calculate whether it should execute on a per user (per thread) basis. if unchecked, then the calculation will be global for all users. for example, if using total execution mode, and uncheck "per user", then the number given for throughput will be the total number of executions made. if "per user" is checked, then the total number of executions would be the number of users times the number given for throughput.

No

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

Control Panel

Parameters

Attribute Description Required

NameDescriptive name for this controller that is shown in the tree, and used to name the transaction.

Yes

Runtime (seconds)

Desired runtime in seconds Yes

18.2.9 If ControllerThe 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.

Control Panel

Parameters

Attribute Description Required

NameDescriptive name for this controller that is shown in the tree.

No

Condition Javascript code that returns "true" or "false" Yes

Evaluate for all children

Should condition be evaluated for all children? If not checked, then the condition is only evaluated on entry.

Yes

Examples:

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

18.2.10 While ControllerThe 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"

In contrast to the IfController, the condition is not evaluated as a JavaScript expression. 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,dummy)}

${__javaScript("${VAR2}"=="abcd",dummy)}

${_P(property)} - where property is set to "false" somewhere else

Control Panel

Parameters

Attribute Description Required

NameDescriptive name for this controller that is shown in the tree, and used to name the transaction.

Yes

Condition blank, LAST, or variable/function Yes

18.2.11 Switch ControllerThe 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

Name Descriptive name for this controller that is Yes

shown in the tree, and used to name the transaction.

Switch Value

The number (or name) of the subordinate element to be invoked. Elements are numbered from 0.

Yes

18.2.12 ForEach ControllerA 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

NameDescriptive name for this controller that is shown in the tree.

No

Input variable prefix

Prefix for the variable names to be used as input.

Yes

Output variable

The name of the variable which can be used in the loop for replacement in the samplers

Yes

Use Separator If not checked, the "_" separator is omitted. Yes

ForEach Example

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

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

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.

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

NameDescriptive name for this controller that is shown in the tree.

No

Module to Run

The module controller provides a list of all controllers loaded into the gui. Select the one you want to substitute in at runtime.

Yes

18.2.14 Include ControllerThe 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.

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.

Control Panel

Parameters

Attribute Description Required

Filename The file to include. Yes

18.2.15 Transaction ControllerThe Transaction Comntroller is used to group samplers by generating an additional sample which totals the nested 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

Name Descriptive name for this controller that is Yes

shown in the tree, and used to name the transaction.

Generate Parent Sample

If checked, then the sample is generated as a parent of the other samples, otherwise the sample is generated as an independent sample.

Yes

18.2.16 Recording ControllerThe 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

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

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 Listener

Assertion Results

Mailer Visualizer

Monitor Results

Summary Report

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

SuccessesSelect this to write/read only results without errors. If neither Errors nor Successes is selected, then all results are processed.

No

Configure Configure Button, see below No

18.3.1 Sample Result Save ConfigurationListeners 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) only apply to the CSV format; items wint (XML) only apply to XML format. CSV format cannot be used to

save any items that include line-breaks.

Control Panel

18.3.2 Graph Full ResultsNo Description

Control Panel

18.3.3 Graph ResultsThe 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 VisualizerThe 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.

Control Panel

18.3.5 Assertion ResultsThe 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 TreeThe 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 radio button.

Show text Render HTML

Render XML

Render JSON

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

text/application/javascriptapplication/jsonapplication/soap+xmlapplication/vnd.wap.xhtml+xmlapplication/xhtml+xmlapplication/xml

Additional types can be added by defining the JMeter property content-type_text as a comma-separated list of the content-type prefixes to be matched.

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

The HTML view attempts to render the response as HTML. The rendered HTML is likely to compare poorly to the view one would get in any web browser; however, it does provide a quick approximation that is helpful for initial result evaluation. If the "Download embedded resources" check-box is selected, the renderer may download images and style-sheets etc referenced by the HTML. If the checkbox is not selected, the renderer will not download images etc.

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

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

Control Panel

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

18.3.7 Aggregate ReportThe 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 a lot of memory as details of every Sample have to be saved. See the Summary Report for a similar Listener that does not need so much memory.

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 for the URL

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 of the given URL

Max - The longest time for the samples of the given URL

Error % - Percent of requests with errors

Throughput - Throughput measured in requests per second/minute/hour

Kb/sec - The throughput measured in Kilobytes per second

Times are in milliseonds.

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 TableThis 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 WriterThis 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 ResultsMonitor 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.

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

The Mailer Visualizer requires the optional Javamail jars. If these are not present in the lib directory, the element will not appear in the menus.

Parameters

Attribute Description Required

NameDescriptive name for this element that is shown in the tree.

No

From Email address to send messages from. Yes

Addressie(s) Email address to send messages to. Yes

SMTP HostIP address or host name of SMTP (email redirector) server.

No

Failure Subject

Email subject line for fail messages. No

Success Email subject line for success messages. No

Subject

Failure LimitOnce this number of failed responses are received, a failure email is sent.

Yes

Success Limit

Once this number of successful responses are received after previously reaching the failure limit , a success email is sent. The mailer will thus only send out messages in a sequence of failed-succeeded-failed-succeeded, etc.

Yes

Test Mail Press this button to send a test mail No

FailuresA field that keeps a running total of number of failures so far received.

No

18.3.14 BeanShell ListenerThe BeanShell Listener allows the use of BeanShell for processing samples for saving etc.

Please note that the BeanShell jar file is not included with JMeter; it needs to be separately downloaded. For full details on using BeanShell, please see the BeanShell web-site at http://www.beanshell.org/.

The test element supports the ThreadListener and TestListener methods. These should be defined in the initialisation file. See the file BeanShellListeners.bshrc for example definitions.

Control Panel

Parameters

Attribute Description Required

NameDescriptive name for this element that is shown in the tree.

No

Reset bsh.Interpreter before each call

If this option is selected, then the interpreter will be recreated for each sample. This may be necessary for some long running scripts. For further information, see Best Practices - BeanShell scripting .

Yes

Parameters

Parameters to pass to the BeanShell script. The parameters are stored in the following variables:

Parameters - string containing the parameters as a single variable

bsh.args - String array containing parameters, split on white-space

No

Script fileA file containing the BeanShell script to run

No

ScriptThe BeanShell script to run. The return value is ignored.

Yes (unless script file is provided)

The following variables are set up for use by the script:

log - (Logger) - can be used to write to the log file ctx - (JMeterContext) - gives access to the context

vars - (JMeterVariables) - gives read/write access to variables: vars.get(key); vars.put(key,val); vars.putObject("OBJ1",new Object());

props - JMeter Properties - e.g. props.get("START.HMS"); props.put("PROP1","1234");

sampleResult - (SampleResult) - gives access to the previous SampleResult

sampleEvent (SampleEvent) gives access to the current sample event

For details of all the methods available on each of the above variables, please check the Javadoc

If the property beanshell.listener.init is defined, this is used to load an initialisation file, which can be used to define methods etc for use in the BeanShell script.

18.3.15 Summary ReportThe summary report creates a table row for each differently named request in your test. This is similar to the Aggregate Report , except that it uses less memory.

The thoughput is calculated from the point of view of the sampler target (e.g. the remote server in the case of HTTP samples). JMeter takes into account the total time over which the requests have been generated. If other samplers and timers are in the same thread, these will increase the total time, and therefore reduce the throughput value. So two identical samplers with different names will have half the throughput of two samplers with the same name. It is important to choose the sampler labels correctly to get the best results from the Report.

Label - The label of the sample. If "Include group name in label?" is selected, then the name of the thread group is added as a prefix. This allows identical labels from different thread groups to be collated separately if required.

# Samples - The number of samples for the URL

Average - The average elapsed time of a set of results

Min - The lowest elapsed time for the samples of the given URL

Max - The longest elapsed time for the samples of the given URL

Std. Dev. - the standard deviation of the sample elapsed time

Error % - Percent of requests with errors

Throughput - Throughput measured in requests per second/minute/hour

Kb/sec - The throughput measured in Kilobytes per second

Avg. Bytes - average size of the sample response in bytes. (in JMeter 2.2 it wrongly showed the value in kB)

Times are in milliseonds.

Control Panel

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

Sample "Include group name" display

^

18.4 Configuration Elements

Configuration elements can be used to set up defaults and variables for later use by samplers. Note that these elements are processed at the start of the scope in which they are found, i.e. before any samplers in the same scope.

18.4.1 CSV Data Set ConfigCSV Data Set Config is used to read lines from a file, and split them into variables. It is easier to use than the __CSVRead() and _StringFromFile() functions. Versions of JMeter after 2.3.1 allow variables to be quoted; this allows the value to contain a delimiter. Previously it was necessary to choose a delimiter that was not used in any values.

By default, the file is only opened once, and each thread will use a different line from the file. See the description of the Share mode below for additional options (JMeter 2.3.2+). Lines are read at the start of each test iteration. The file name and mode are resolved in the first iteration.

CSV Dataset variables are defined at the start of each test iteration. As this is after configuration processing is completed, they cannot be used for some configuration items - such as JDBC Config - that process their contents at configuration time (see Bug 40394 ) However the variables do work in the HTTP Auth Manager, as the username etc are processed at run-time.

As a special case, the string "\t" (without quotes) in the delimiter field is treated as a Tab.

When the end of file (EOF) is reached, and the recycle option is true, reading starts again with the first line of the file.

If the recycle option is false, and stopThread is false, then all the variables are set to <EOF> when the end of file is reached. This value

can be changed by setting the JMeter property csvdataset.eofstring .

If the Recycle option is false, and Stop Thread is true, then reaching EOF will cause the thread to be stopped.

Control Panel

Parameters

Attribute Description Required

NameDescriptive name for this element that is shown in the tree.

No

Filename

Name of the file to be read. Relative file names are resolved with respect to the path of the active test plan. Absolute file names are also supported, but note that they are unlikely to work in remote mode, unless the remote server has the same directory structure. If the same physical file is referenced in two different ways - e.g. csvdata.txt and ./csvdata.txt - then these are treated as different files. If the OS does not distinguish between upper and lower case, csvData.TXT would also be opened separately.

Yes

File Encoding

The encoding to be used to read the file, if not the platform default.

No

Variable Names

List of variable names (comma-delimited) Yes

Delimiter

Delimiter to be used to split the records in the file. If there are fewer values on the line than there are variables the remaining variables are not updated - so they will retain their previous value (if any).

Yes

Allow quoted data?

Should the CSV file allow values to be quoted? Yes

Recycle on EOF?

Should the file be re-read from the beginning on reaching EOF? (default is true)

Yes

Stop thread on EOF?

Should the thread be stopped on EOF, if Recycle is false? (default is false)

Yes

Sharing mode

All threads - (the default) the file is shared between all the threads.

Current thread group - each file is opened once for each thread group in which the element appears

Current thread - each file is opened separately for each thread

Identifier - all threads sharing the same identifier share the same file. So for example if you have 4 thread groups, you could use a common id for two or more of the groups to share the file between them. Or you could use the thread number to share the file between the same thread numbers in different thread groups.

Yes

18.4.2 FTP Request DefaultsControl Panel

18.4.3 HTTP Authorization Manager

If there is more than one Authorization Manager in the scope of a Sampler, there is currently no way to sepcify which one is to be used.

The Authorization Manager lets you specify one or more user logins for web pages that are restricted using server authentication. You see this type of authentication when you use your browser to access a restricted page, and your browser displays a login dialog box. JMeter transmits the login information when it encounters this type of page.

In versions of JMeter after 2.2, the HttpClient sampler defaults to pre-emptive authentication if the setting has not been defined. To disable this, set the values as below, in which case authentication will only be performed in response to a challenge.

jmeter.properties:httpclient.parameters.file=httpclient.parameters

httpclient.parameters:http.authentication.preemptive$Boolean=false

Note: the above settings only apply to the HttpClient sampler (and the SOAP samplers, which use Httpclient).

When looking for a match against a URL, JMeter checks each entry in turn, and stops when it finds the first match. Thus the most specific

URLs should appear first in the list, followed by less specific ones. Duplicate URLs will be ignored. If you want to use different usernames/passwords for different threads, you can use variables. These can be set up using a CSV Data Set Config Element (for example).

Control Panel

Parameters

Attribute

DescriptionRequire

d

NameDescriptive name for this element that is shown in the tree.

No

Base URL

A partial or complete URL that matches one or more HTTP Request URLs. As an example, say you specify a Base URL of "http://jakarta.apache.org/restricted/" with a username of "jmeter" and a password of "jmeter". If you send an HTTP request to the URL "http://jakarta.apache.org/restricted/ant/myPage.html", the Authorization Manager sends the login information for the user named, "jmeter".

Yes

Username

The username to authorize. Yes

Password The password for the user. Yes

Domain The domain to use for NTLM. No

Realm The realm to use for NTLM. No

The Realm only applies to the HttpClient sampler. In JMeter 2.2, the domain and realm did not have separate columns, and were encoded as part of the user name in the form: [domain\]username[@realm]. This was an experimental feature and has been removed.

Controls: Add Button - Add an entry to the authorization table. Delete Button - Delete the currently selected table entry.

Load Button - Load a previously saved authorization table and add the entries to the existing authorization table entries.

Save As Button - Save the current authorization table to a file.

When you save the Test Plan, JMeter automatically saves all of the authorization table entries - including any passwords, which are not encrypted.

Authorization Example

Download this example. In this example, we created a Test Plan on a local server that sends three HTTP requests, two requiring a login and the other is open to everyone. See figure 10 to see the makeup of our Test Plan. On our server, we have a restricted directory named, "secret", which contains two files, "index.html" and "index2.html". We created a login id named, "kevin", which has a password of "spot". So, in our Authorization Manager, we created an entry for the restricted directory and a username and password (see figure 11). The two HTTP requests named "SecretPage1" and "SecretPage2" make requests to "/secret/index.html" and "/secret/index2.html". The other HTTP request, named "NoSecretPage" makes a request to "/index.html".

Figure 10 - Test Plan

Figure 11 - Authorization Manager Control Panel

When we run the Test Plan, JMeter looks in the Authorization table for the URL it is requesting. If the Base URL matches the URL, then JMeter passes this information along with the request.

You can download the Test Plan, but since it is built as a test for our local server, you will not be able to run it. However, you can use it as a reference in constructing your own Test Plan.

18.4.4 HTTP Cache Manager

This is a new element, and is liable to change

The HTTP Cache Manager is used to add caching functionality to HTTP requests within its scope.

If a sample is successful (i.e. has response code 2xx) then the Last-Modified and Etag values are saved for the URL. Before executing the next sample, the sampler checks to see if there is an entry in the cache, and if so, the If-Last-Modified and If-None-Match conditional headers are set for the request.

If the requested document has not changed since it was cached, then the response body will be empty. This may cause problems for Assertions.

Control Panel

18.4.4 HTTP Cookie Manager

If there is more than one Cookie Manager in the scope of a Sampler, there is currently no way to specify which one is to be used.

The Cookie Manager element has two functions: First, it stores and sends cookies just like a web browser. If you have an HTTP Request and the response contains a cookie, the Cookie Manager automatically stores that cookie and will use it for all future requests to that particular web site. Each JMeter thread has its own "cookie storage area". So, if you are testing a web site that uses a cookie for storing session information, each JMeter thread will have its own session.

Received Cookies are stored as JMeter thread variables. Thus the value of a cookie with the name TEST can be referred to as ${TEST}

Second, you can manually add a cookie to the Cookie Manager. However, if you do this, the cookie will be shared by all JMeter threads.

Note that such Cookies are created with an Expiration time far in the future

Since version 2.0.3, cookies with null values are ignored by default. This can be changed by setting the JMeter property: CookieManager.delete_null_cookies=false. Note that this also applies to manually defined cookies - any such cookies will be removed from the display when it is updated. Note also that the cookie name must be unique - if a second cookie is defined with the same name, it will replace the first.

Control Panel

Parameters

Attribute

Description Required

NameDescriptive name for this element that is shown in the tree.

No

Clear Cookies each Iteration

If selected, all server-defined cookies are cleared each time the main Thread Group loop is executed. In JMeter versions after 2.3, any cookies defined in the GUI are not cleared.

Yes

Cookie Policy

The cookie policy that will be used to manage the cookies. "compatibility" is the default, and should work in most cases. See http://jakarta.apache.org/httpcomponents/httpclient-3.x/cookies.html and http://jakarta.apache.org/httpcomponents/httpclient-3.x/apidocs/org/apache/commons/httpclient/cookie/CookiePolicy.html [Note: "ignoreCookies" is equivalent to omitting the CookieManager.]

Yes

Cookies Stored in the Cookie

This gives you the opportunity to use hardcoded cookies that will be used by all threads during the test execution. The "domain" is the hostname of the server (without http://); the port is currently ignored.

No (discouraged, unless you know

Manager

what you're doing)

Add Button

Add an entry to the cookie table. N/A

Delete Button

Delete the currently selected table entry. N/A

Load Button

Load a previously saved cookie table and add the entries to the existing cookie table entries.

N/A

Save As Button

Save the current cookie table to a file (does not save any cookies extracted from HTTP Responses).

N/A

18.4.5 HTTP Request DefaultsThis element lets you set default values that your HTTP Request controllers use. For example, if you are creating a Test Plan with 25 HTTP Request controllers and all of the requests are being sent to the same server, you could add a single HTTP Request Defaults element with the "Server Name or IP" field filled in. Then, when you add the 25 HTTP Request controllers, leave the "Server Name or IP" field empty. The controllers will inherit this field value from the HTTP Request Defaults element.

In JMeter 2.2 and earlier, port 80 was treated specially - it was ignored if the sampler used the https protocol. JMeter 2.3 and later treat all port values equally; a sampler that does not specify a port will use the HTTP Request Defaults port, if one is provided.

Control Panel

Parameters

Attribute Description Required

NameDescriptive name for this controller that is shown in the tree.

No

ServerDomain name or IP address of the web server. e.g. www.example.com. [Do not include the http:// prefix.

No

Port Port the web server is listening to. No

Protocol HTTP or HTTPS. Yes

Method HTTP GET or HTTP POST. No

Path

The path to resource (for example, /servlets/myServlet). If the resource requires query string parameters, add them below in the "Send Parameters With the Request" section. Note that the path is the default for the full path, not a prefix to be applied to paths specified on the HTTP Request screens.

No

Send Parameters

The query string will be generated from the list of parameters you provide. Each parameter

No

With the Request

has a name and value . The query string will be generated in the correct fashion, depending on the choice of "Method" you made (ie if you chose GET, the query string will be appended to the URL, if POST, then it will be sent separately). Also, if you are sending a file using a multipart form, the query string will be created using the multipart form specifications.

18.4.6 HTTP Header Manager

If there is more than one Header Manager in the scope of a Sampler, there is currently no way to sepcify which one is to be used.

The Header Manager lets you add or override HTTP request headers.

Control Panel

Parameters

Attribute Description Required

NameDescriptive name for this element that is shown in the tree.

No

Name (Header)

Name of the request header. Two common request headers you may want to experiment with are "User-Agent" and "Referer".

No (You should have at least one, however)

Value Request header value. No (You should have at least one, however)

Add Button

Add an entry to the header table. N/A

Delete Button

Delete the currently selected table entry. N/A

Load Button

Load a previously saved header table and add the entries to the existing header table entries.

N/A

Save As Button

Save the current header table to a file. N/A

Header Manager example

Download this example. In this example, we created a Test Plan that tells JMeter to override the default "User-Agent" request header and use a particular Internet Explorer agent string instead. (see figures 9 and 10).

Figure 12 - Test Plan

Figure 13 - Header Manager Control Panel

18.4.7 Java Request DefaultsThe Java Request Defaults component lets you set default values for Java testing. See the Java Request .

Control Panel

18.4.8 JDBC Connection ConfigurationCreates a database connection pool (used by JDBC Request Sampler) with JDBC Connection settings.

Control Panel

Parameters

Attribute Description Required

NameDescriptive name for the connection pool that is shown in the tree.

No

Variable Name

The name of the variable the connection pool is tied to. Multiple connection pools can be used, each tied to a different variable, allowing JDBC Samplers to select the pool to draw connections from. Each pool name must be different. If there are two configuration elements using the same pool name, only one will be saved. JMeter

Yes

versions after 2.3 log a message if a duplicate name is detected.

Max Number of Connections

Maximum number of connections allowed in the pool. To ensure that threads don't have to wait for connections, set the max count to the same as the number of threads. In versions of JMeter after 2.3, the value "0" is treated specially. Instead of sharing the pool between all threads in the test plan, a pool containing a single connection is created for each thread. This ensures that the same connection can be re-used for multiple samplers in the same thread. Multiple such pools can be used - e.g. for connecting to different databases - just give them different names.

Yes

Pool timeoutPool throws an error if the timeout period is exceeded in the process of trying to retrieve a connection

Yes

Idle Cleanup Interval (ms)

Uncertain what exactly this does. Yes

Auto CommitTurn auto commit on or off for the connections.

Yes

Keep-alive Uncertain what exactly this does. Yes

Max Connection Age (ms)

Uncertain what exactly this does. Yes

Validation Query

A simple query used to determine if the database is still responding.

Yes

Database URL

JDBC Connection string for the database. Yes

JDBC Driver class

Fully qualified name of driver class. (Must be in JMeter's classpath - easiest to copy .jar file into JMeter's /lib directory).

Yes

Username Name of user to connect as. No

Password Password to connect with. No

Different databases and JDBC drivers require different JDBC settings. The Database URL and JDBC Driver class are defined by the provider of the JDBC implementation.

Some possible settings are shown below. Please check the exact details in the JDBC driver documentation.

Database

Driver class Database URL

MySQL com.mysql.jdbc.Driver jdbc:mysql://host[:port]/dbname PostgreSQL

org.postgresql.Driver jdbc:postgresql:{dbname}

Oracle oracle.jdbc.driver.OracleDriver

jdbc:oracle:thin:user/pass@//host:port/service

Ingres (2006)

ingres.jdbc.IngresDriver jdbc:ingres://host:port/db[;attr=value]

SQL Server (MS JDBC driver)

com.microsoft.sqlserver.jdbc.SQLServerDriver

jdbc:sqlserver://host:port;DatabaseName=dbname

Apache Derby

org.apache.derby.jdbc.ClientDriver

jdbc:derby://server[:port]/databaseName[;URLAttributes=value[;...]]

The above may not be correct - please check the relevant JDBC driver documentation.

18.4.9 Login Config ElementThe Login Config Element lets you add or override username and password settings in samplers that use username and password as part of their setup.

Control Panel

Parameters

Attribute Description Required

NameDescriptive name for this element that is shown in the tree.

No

Username The default username to use. No

Password The default password to use. No

18.4.10 LDAP Request DefaultsThe LDAP Request Defaults component lets you set default values for LDAP testing. See the LDAP Request .

Control Panel

18.4.11 LDAP Extended Request DefaultsThe LDAP Extended Request Defaults component lets you set default values for extended LDAP testing. See the LDAP Extended Request .

Control Panel

18.4.12 TCP Sampler Config

ALPHA CODE

The TCP Sampler Config provides default data for the TCP Sampler

Control Panel

Parameters

Attribute Description Required

NameDescriptive name for this element that is shown in the tree.

No

ServerName or IP Name or IP of TCP server No

Port Number Port to be used No

Timeout (milliseconds)

Timeout for replies No

Set Nodelay Should the nodelay property be set? No

Text to Send Text to be sent No

18.4.13 User Defined VariablesThe User Defined Variables lets you define variables for use in other test elements, just as in the Test Plan . The variables in User Defined Variables components will take precedence over those defined closer to the tree root -- including those defined in the Test Plan. Note that all the UDV elements in a test plan - no matter where they are - are processed at the start.

For simplicity, it is suggested that UDVs are placed only at the start of a Thread Group (or perhaps under the Test Plan itself).

If a runtime element such as a User Parameters Pre-Processor or Regular Expression Extractor defines a variable with the same name as one of the global variables, then other test elements will see the local

local value of the variable. The global value is not affected.

Control Panel

If you have more than one Thread Group, make sure you use different names for different values, as UDVs are shared between Thread Groups. Also, the variables are not available for use until after the element has been processed, so you cannot use variables that are defined in the same element. You can reference variables defined in earlier UDVs or on the Test Plan.

Parameters

Attribute Description Required

NameDescriptive name for this element that is shown in the tree.

No

User Defined Variables

Variable name/value pairs. The string under the "Name" column is what you'll need to place inside the brackets in ${...} constructs to use the variables later on. The whole ${...} will then be replaced by the string in the "Value" column.

No

18.4.14 Simple Config ElementThe Simple Config Element lets you add or override arbitrary values in samplers. You can choose the name of the value and the value itself. Although some adventurous users might find a use for this element, it's here primarily for developers as a basic GUI that they can use while developing new JMeter components.

Control Panel

Parameters

Attribute Description Required

NameDescriptive name for this element that is shown in the tree.

No

Parameter Name

The name of each parameter. These values are internal to JMeter's workings and are not generally documented. Only those familiar with the code will know these values.

Yes

Parameter Value

The value to apply to that parameter. Yes

^

18.5 Assertions

Assertions are used to perform additional checks on samplers, and are processed after each sampler in the same scope.

The variable JMeterThread.last_sample_ok is set to "true" or "false" after all assertions for a sampler have been run.

18.5.1 Response AssertionThe response assertion control panel lets you add pattern strings to be compared against various fields of the response. The pattern strings are:

Contains, Matches: Perl5-style regular expressions Equals, Substring: plain text, case-sensitive

A summary of the pattern matching characters can be found at http://jakarta.apache.org/oro/api/org/apache/oro/text/regex/package-summary.html

You can also choose whether the strings will be expected to match the entire response, or if the response is only expected to contain the pattern. You can attach multiple assertions to any controller for additional flexibility.

Note that the pattern string should not include the enclosing delimiters, i.e. use Price: \d+ not /Price: \d+/ .

By default, the pattern is in multi-line mode, which means that the "." meta-character does not match newline. In multi-line mode, "^" and "$" match the start or end of any line anywhere within the string - not just the start and end of the entire string. Note that \s does match new-line. Case is also significant. To override these settings, one can use the extended regular expression syntax. For example:

(?i) - ignore case(?s) - treat target as single line, i.e. "."

matches new-line(?is) - both the above

These can be used anywhere within the expression and

remain in effect until overriden. e.g. (?i)apple(?-i) Pie - matches "ApPLe Pie", but not "ApPLe pIe" (?s)Apple.+?Pie - matches Apple followed by Pie, which may be on a subsequent line. Apple(?s).+?Pie - same as above, but it's probably clearer to use the (?s) at the start.

Control Panel

Parameters

Attribute Description Required

NameDescriptive name for this element that is shown in the tree.

No

Response Field to Test

Instructs JMeter which field of the Response to test. This may be the Response Text from the server, the URL string that was sampled, the Response Headers (JMeter version 2.3RC3 and earlier included the headers with the Text), the Response Code (e.g. 404) or the Response Message (e.g. Not Found).

Yes

The overall success of the sample is determined by combining the result of the assertion with the existing Response status. When the Ignore Status checkbox is selected, the Response status is forced to successful before evaluating the Assertion.

HTTP Responses with statuses in the 4xx and 5xx ranges are normally regarded as unsuccessful. The "Ignore status" checkbox can be used to set the status successful before performing further checks. Note that this will have the effect of clearing any previous assertion failures, so make sure that this is only set on the first assertion.

Pattern Matching Rules

Indicates how the text being tested is checked against the pattern.

Contains - true if the text contains the regular expression pattern

Matches - true if the whole text matches the regular expression pattern

Equals - true if the whole text equals the pattern string (case-sensitive)

Substring - true if the text contains the pattern string (case-sensitive)

Equals and Substring patterns are plain strings, not regular expressions. NOT may also be selected to invert the result of the check.

Yes

Patterns to Test

A list of patterns to be tested. Each pattern is tested separately. If a pattern fails, then further patterns are not checked. There is no difference between setting up one Assertion with multiple patterns and setting up multiple Assertions with one pattern each (assuming the other options are the same). However, when the Ignore Status checkbox is selected, this has the effect of cancelling any previous assertion failures - so make sure that the Ignore Status checkbox is only used on the first Assertion.

Yes

The pattern is a Perl5-style regular expression, but without the enclosing

brackets.

Assertion Examples

Figure 14 - Test Plan

Figure 15 - Assertion Control Panel with Pattern

Figure 16 - Assertion Listener Results (Pass)

Figure 17 - Assertion Listener Results (Fail)

18.5.2 Duration AssertionThe Duration Assertion tests that each response was received within a given amount of time. Any response that takes longer than the given number of milliseconds (specified by the user) is marked as a failed response.

Control Panel

Parameters

Attribute Description Required

NameDescriptive name for this element that is shown in the tree.

No

Duration in Milliseconds

The maximum number of milliseconds each response is allowed before being marked as failed.

Yes

18.5.3 Size AssertionThe Size Assertion tests that each response contains the right number of bytes in it. You can specify that the size be equal to, greater than, less than, or not equal to a given number of bytes.

Since JMeter 2.3RC3, an empty response is treated as being 0 bytes rather than reported as an error.

Control Panel

Parameters

Attribute Description Required

NameDescriptive name for this element that is shown in the tree.

No

Size in bytesThe number of bytes to use in testing the size of the response.

Yes

Type of Comparison

Whether to test that the response is equal to, greater than, less than, or not equal to, the number of bytes specified.

Yes

18.5.4 XML AssertionThe XML Assertion tests that the response data consists of a formally correct XML document. It does not validate the XML based on a DTD or schema or do any further validation.

Control Panel

Parameters

Attribute Description Required

NameDescriptive name for this element that is shown in the tree.

No

18.5.5 BeanShell AssertionThe BeanShell Assertion allows the user to perform assertion checking using a BeanShell script.

Please note that the BeanShell jar file is not included with JMeter; it needs to be downloaded separately and placed in the lib directory. For full details on using BeanShell, please see the BeanShell web-site at http://www.beanshell.org/.

Note that a different Interpreter is used for each independent occurence of the assertion in each thread in a test script, but the same Interpreter is used for subsequent invocations. This means that variables persist across calls to the assertion.

All Assertions are called from the same thread as the sampler.

If the property "beanshell.assertion.init" is defined, it is passed to the Interpreter as the name of a sourced file. This can be used to define common methods and variables. There is a sample init file in the bin directory: BeanShellAssertion.bshrc

The test element supports the ThreadListener and TestListener methods. These should be defined in the initialisation file. See the file BeanShellListeners.bshrc for example definitions.

Control Panel

Parameters

Attribute Description Required

NameDescriptive name for this element that is shown in the tree.

No

Reset bsh.Interpreter before each call

If this option is selected, then the interpreter will be recreated for each sample. This may be necessary for some long running scripts. For further information, see Best Practices - BeanShell scripting .

Yes

Parameters Parameters to pass to the BeanShell script. The parameters are stored in the following variables:

No

Parameters - string containing the parameters as a single variable

bsh.args - String array containing parameters, split on white-space

Script fileA file containing the BeanShell script to run. This overrides the script.

No

ScriptThe BeanShell script to run. The return value is ignored.

Yes (unless script file is provided)

There's a sample script you can try.

The following variables are defined to the script. These are strings unless otherwise noted:

log - the Logger Object. (e.g.) log.warn("Message"[,Throwable]) SampleResult - the SampleResult Object; read-write

Response - the response Object; read-write

Failure - boolean; read-write; used to set the Assertion status

FailureMessage - String; read-write; used to set the Assertion message

ResponseData - the response body (byte [])

ResponseCode - e.g. 200

ResponseMessage - e.g. OK

ResponseHeaders - contains the HTTP headers

RequestHeaders - contains the HTTP headers sent to the server

SampleLabel

SamplerData - data that was sent to the server

ctx - JMeterContext

vars - JMeterVariables - e.g. vars.get("VAR1"); vars.put("VAR2","value"); vars.putObject("OBJ1",new Object());

props - JMeter Properties - e.g. props.get("START.HMS"); props.put("PROP1","1234");

The following methods of the Response object may be useful:

setStopThread(boolean) setStopTest(boolean)

String getSampleLabel()

setSampleLabel(String)

18.5.6 MD5Hex AssertionThe MD5Hex Assertion allows the user to check the MD5 hash of the response data.

Control Panel

Parameters

Attribute Description Required

NameDescriptive name for this element that is shown in the tree.

No

MD5 sum32 hex digits representing the MD5 hash (case not significant)

Yes

18.5.7 HTML AssertionThe HTML Assertion allows the user to check the HTML syntax of the response data using JTidy.

Control Panel

Parameters

Attribute Description Required

NameDescriptive name for this element that is shown in the tree.

No

doctype omit/auto/strict/loose Yes

Format HTML, XHTML or XML Yes

Errors only Only take note of errors? Yes

Error threshold

Number of errors allowed before classing the response as failed

Yes

Warning threshold

Number of warnings allowed before classing the response as failed

Yes

Filename Name of file to which report is written No

18.5.8 XPath Assertion

The XPath Assertion tests a document for well formedness, has the option of validating against a DTD, or putting the document through JTidy and testing for an XPath. If that XPath exists, the Assertion is true. Using "/" will match any well-formed document, and is the default XPath Expression. The assertion also supports boolean expressions, such as "count(//*error)=2". See http://www.w3.org/TR/xpath for more information on XPath.

Control Panel

Parameters

Attribute Description Required

NameDescriptive name for this element that is shown in the tree.

No

Tolerant ParserBe tolerant of XML/HTML errors (i.e. use Tidy)

Yes

Quiet Sets the Tidy Quiet flag If tolerant is selected

Report ErrorsIf a Tidy error occurs, then set the Assertion accordingly

If tolerant is selected

Show warnings Sets the Tidy showWarnings option If tolerant is selected

Use Namespaces Should namespaces be honoured? No

Validate XMLCheck the document against its schema.

No

XPath Assertion XPath to match in the document. Yes

Ignore Whitespace

Ignore Element Whitespace. No

True if nothing matches

True if a XPath expression is not matched

No

The non-tolerant parser can be quite slow, as it may need to download the DTD etc.

18.5.9 XML Schema AssertionThe XML Schema Assertion allows the user to validate a response against an XML Schema.

Control Panel

Parameters

Attribute Description Required

NameDescriptive name for this element that is shown in the tree.

No

File Name Specify XML Schema File Name Yes

18.5.10 BSF AssertionThe BSF Assertion allows BSF script code to be used to check the status of the previous sample.

Control Panel

Parameters

Attribute Description Required

NameDescriptive name for this element that is shown in the tree.

No

Language The BSF language to be used Yes

Parameters

Parameters to pass to the script. The parameters are stored in the following variables:

Parameters - string containing the parameters as a single variable

args - String array containing parameters, split on white-space

No

Script file A file containing the script to run. No

Script The script to run. Yes (unless script file is provided)

The script (or file) is processed using the BSFEngine.exec() method,

which does not return a value.

The following variables are set up for use by the script:

log - (Logger) - can be used to write to the log file ctx - (JMeterContext) - gives access to the context

vars - (JMeterVariables) - gives read/write access to variables: vars.get(key); vars.put(key,val); vars.putObject("OBJ1",new Object());

props - JMeter Properties - e.g. props.get("START.HMS"); props.put("PROP1","1234");

prev - (SampleResult) - gives access to the previous SampleResult (if any)

sampler - (Sampler)- gives access to the current sampler

OUT - System.out - e.g. OUT.println("message")

SampleResult - the current sample result

AssertionResult - the assertion result

The script can check various aspects of the SampleResult. If an error is detected, the script should use AssertionResult.setFailureMessage("message") and AssertionResult.setFailure(true).

For futher details of all the methods available on each of the above variables, please check the Javadoc

^

18.6 Timers

Note that timers are processed before each sampler in the scope in which they are found; if there are several timers in the same scope, all the timers will be processed before each sampler. Timers are only processed in conjunction with a sampler. A timer which is not in the same scope as a sampler will not be processed at all. To apply a timer to a single sampler, add the timer as a child element of the sampler. The timer will be applied before the sampler is executed. To

apply a timer after a sampler, either add it to the next sampler, or add it as the child of a Test Action Sampler.

18.6.1 Constant TimerIf you want to have each thread pause for the same amount of time between requests, use this timer.

Control Panel

Parameters

Attribute Description Required

NameDescriptive name for this timer that is shown in the tree.

No

Thread Delay

Number of milliseconds to pause. Yes

18.6.2 Gaussian Random TimerThis timer pauses each thread request for a random amount of time, with most of the time intervals ocurring near a particular value. The total delay is the sum of the Gaussian distributed value (with mean 0.0 and standard deviation 1.0) times the deviation value you specify, and the offset value.

Control Panel

Parameters

Attribute Description Required

NameDescriptive name for this timer that is shown in the tree

No

Deviation Deviation in milliseconds. Yes

Constant Delay Offset

Number of milliseconds to pause in addition to the random delay.

Yes

18.6.3 Uniform Random TimerThis timer pauses each thread request for a random amount of time, with each time interval having the same probability of occurring. The total delay is the sum of the random value and the offset value.

Control Panel

Parameters

Attribute Description Required

NameDescriptive name for this timer that is shown in the tree.

No

Random Delay Maximum

Maxium random number of milliseconds to pause.

Yes

Constant Delay Offset

Number of milliseconds to pause in addition to the random delay.

Yes

18.6.4 Constant Throughput TimerThis timer introduces variable pauses, calculated to keep the total throughput (in terms of samples per minute) as close as possible to a give figure. Of course the throughput will be lower if the server is not capable of handling it, or if other timers or time-consuming test elements prevent it.

N.B. although the Timer is called the Constant Throughput timer, the throughput value does not need to be constant. It can be defined in terms of a variable or function call, and the value can be changed during a test. The value can be changed in various ways:

using a counter variable using a JavaScript or BeanShell function to provide a changing

value

using the remote BeanShell server to change a JMeter property

See Best Practices for further details. Note that the throughput value should not be changed too often during a test - it will take a while for the new value to take effect.

Control Panel

Parameters

Attribute Description Required

NameDescriptive name for this timer that is shown in the tree.

No

Target Throughput

Throughput we want the timer to try to generate.

Yes

Calculate Throughput based on

this thread only - each thread will try to maintain the target throughput. The overall throughput will be proportional to the number of active threads.

all active threads in current thread group - the target throughput is divided amongst all the active threads in the group. Each thread will delay as needed, based on when it last ran.

all active threads - the target throughput is divided amongst all the active threads in all Thread Groups. Each thread will delay as needed, based on when it last ran. In this case, each other Thread Group will need a Constant Throughput timer with the same settings.

all active threads in current thread group (shared) - as above, but each thread is delayed based on when any thread in the group last ran.

all active threads (shared) - as above; each thread is delayed based on when any thread last ran.

Yes

18.6.5 Synchronizing TimerThe purpose of the SyncTimer is to block threads until X number of threads have been blocked, and then they are all released at once. A SyncTimer can thus create large instant loads at various points of the test plan.

Control Panel

Parameters

Attribute Description Required

NameDescriptive name for this timer that is shown in the tree.

No

Number of Simultaneous Users to Group by

Number of threads to release at once.

Yes

18.6.6 BeanShell TimerThe BeanShell Timer can be used to generate a delay.

Please note that the BeanShell jar file is not included with JMeter; it needs to be separately downloaded. For full details on using BeanShell, please see the BeanShell web-site at http://www.beanshell.org/.

The test element supports the ThreadListener and TestListener methods. These should be defined in the initialisation file. See the file BeanShellListeners.bshrc for example definitions.

Control Panel

Parameters

Attribute Description Required

NameDescriptive name for this element that is shown in the tree.

No

Reset bsh.Interpreter before each call

If this option is selected, then the interpreter will be recreated for each sample. This may be necessary for some long running scripts. For further information, see Best Practices - BeanShell scripting .

Yes

Parameters

Parameters to pass to the BeanShell script. The parameters are stored in the following variables:

Parameters - string containing the parameters as a single variable

bsh.args - String array containing parameters, split on white-space

No

Script fileA file containing the BeanShell script to run. The return value is used as the number of milliseconds to wait.

No

ScriptThe BeanShell script. The return value is used as the number of milliseconds to wait.

Yes (unless script file is provided)

The following variables are set up for use by the script:

log - (Logger) - can be used to write to the log file ctx - (JMeterContext) - gives access to the context

vars - (JMeterVariables) - gives read/write access to variables: vars.get(key); vars.put(key,val); vars.putObject("OBJ1",new Object());

props - JMeter Properties - e.g. props.get("START.HMS"); props.put("PROP1","1234");

For details of all the methods available on each of the above variables, please check the Javadoc

If the property beanshell.timer.init is defined, this is used to load an initialisation file, which can be used to define methods etc for use in the BeanShell script.

^

18.7 Pre Processors

Preprocessors are used to modify the Samplers in their scope.

18.7.1 HTML Link ParserThis modifier parses HTML response from the server and extracts links and forms. A URL test sample that passes through this modifier will be examined to see if it "matches" any of the links or forms extracted from the immediately previous response. It would then replace the values in the URL test sample with appropriate values from the matching link or form. Perl-type regular expressions are used to find matches.

Matches are performed using protocol, host, path and parameter names. The target sampler cannot contain parameters that are not in the response links.

Spidering Example

Consider a simple example: let's say you wanted JMeter to "spider"

through your site, hitting link after link parsed from the HTML returned from your server (this is not actually the most useful thing to do, but it serves as a good example). You would create a Simple Controller , and add the "HTML Link Parser" to it. Then, create an HTTP Request, and set the domain to ".*", and the path likewise. This will cause your test sample to match with any link found on the returned pages. If you wanted to restrict the spidering to a particular domain, then change the domain value to the one you want. Then, only links to that domain will be followed.

Poll Example

A more useful example: given a web polling application, you might have a page with several poll options as radio buttons for the user to select. Let's say the values of the poll options are very dynamic - maybe user generated. If you wanted JMeter to test the poll, you could either create test samples with hardcoded values chosen, or you could let the HTML Link Parser parse the form, and insert a random poll option into your URL test sample. To do this, follow the above example, except, when configuring your Web Test controller's URL options, be sure to choose "POST" as the method. Put in hard-coded values for the domain, path, and any additional form parameters. Then, for the actual radio button parameter, put in the name (let's say it's called "poll_choice"), and then ".*" for the value of that parameter. When the modifier examines this URL test sample, it will find that it "matches" the poll form (and it shouldn't match any other form, given that you've specified all the other aspects of the URL test sample), and it will replace your form parameters with the matching parameters from the form. Since the regular expression ".*" will match with anything, the modifier will probably have a list of radio buttons to choose from. It will choose at random, and replace the value in your URL test sample. Each time through the test, a new random value will be chosen.

Figure 18 - Online Poll Example

One important thing to remember is that you must create a test sample immediately prior that will return an HTML page with the links and forms that are relevant to your dynamic test sample.

18.7.2 HTTP URL Re-writing Modifier

This modifier works similarly to the HTML Link Parser, except it has a specific purpose for which it is easier to use than the HTML Link Parser, and more efficient. For web applications that use URL Re-writing to store session ids instead of cookies, this element can be attached at the ThreadGroup level, much like the HTTP Cookie Manager . Simply give it the name of the session id parameter, and it will find it on the page and add the argument to every request of that ThreadGroup.

Alternatively, this modifier can be attached to select requests and it will modify only them. Clever users will even determine that this modifier can be used to grab values that elude the HTML Link Parser .

Control Panel

Parameters

Attribute Description Required

NameDescriptive name given to this element in the test tree.

No

Session Argument Name

The name of the parameter to grab from previous response. This modifier will find the parameter anywhere it exists on the page, and grab the value assigned to it, whether it's in an HREF or a form.

Yes

Path ExtensionSome web apps rewrite URLs by appending a semi-colon plus the session id parameter. Check this box if that is so.

No

Do not use equals Some web apps rewrite URLs without No

in path extensionusing an "=" sign between the parameter name and value (such as Intershop Enfinity).

Do not use questionmark in path extension

Prevents the query string to end up in the path extension (such as Intershop Enfinity).

No

Cache Session Id?Should the value of the session Id be saved for later use when the session Id is not present?

Yes

18.7.3 HTML Parameter Mask*** This element is deprecated. Use Counter instead ***

The HTML Parameter Mask is used to generate unique values for HTML arguments. By specifying the name of the parameter, a value prefix and suffix, and counter parameters, this modifier will generate values of the form " name=prefixcountersuffix ". Any HTTP Request that it modifies, it will replace any parameter with the same name or add the appropriate parameter to the requests list of arguments.

The value of the argument in your HTTP Request must be a '*' in order for the HTML Parameter Mask Modifier to replace it.

As an example, the username for a login script could be modified to send a series of values such as: user_1 user_2 user_3 user_4, etc.

Control Panel

Parameters

Attribute Description Required

NameDescriptive name given to this element in the test tree.

No

Name (second appearing)

The name of the parameter to modify or add to the HTTP Request.

Yes

ID PrefixA string value to prefix to every generated value.

No

Lower Bound A number value to start the counter at. Yes

Upper BoundA number value to end the counter, at which point it restarts with the Lower Bound value.

Yes

IncrementValue to increment the counter by each time through.

Yes

ID SuffixA string value to add as suffix to every generated vaue.

No

18.7.4 HTTP User Parameter Modifier*** This element is deprecated. Use User Parameters instead ***

See also the CSV Data Set Config element, which is more suitable for large numbers of parameters

The User Parameter Modifier uses an XML file get values for HTTP arguments. Any HTTP Request that this modifier modifies will be checked for the existence of the specified arguments. If found, the values for those arguments will be replaced by the values found in the

xml file. The XML file can have multiple sets of the same values. This modifier will iterate through these values in a round-robin style, thus each request will get a different set of values until the last set of values is reached, at which point it will begin again at the first set.

Control Panel

Parameters

Attribute Description Required

NameDescriptive name given to this element in the test tree.

No

File NameName of the XML file in JMeter's /bin directory that holds the value sets.

Yes

18.7.5 User ParametersAllows the user to specify values for User Variables specific to individual threads.

User Variables can also be specified in the Test Plan but not specific to individual threads. This panel allows you to specify a series of values for any User Variable. For each thread, the variable will be assigned one of the values from the series in sequence. If there are more threads than values, the values get re-used. For example, this can be used to assign a distinct user id to be used by each thread. User variables can be

referenced in any field of any jMeter Component.

The variable is specified by clicking the Add Variable button in the bottom of the panel and filling in the Variable name in the 'Name:' column. To add a new value to the series, click the 'Add User' button and fill in the desired value in the newly added column.

Values can be accessed in any test component in the same thread group, using the function syntax : ${variable}.

See also the CSV Data Set Config element, which is more suitable for large numbers of parameters

Control Panel

Parameters

Attribute Description Required

NameDescriptive name for this element that is shown in the tree.

No

Update Once Per Iteration

A flag to indicate whether the User Paramters element should update its variables only once per iteration. if you embed functions into the UP, then you may need greater control over how often the values of the variables are updated. Keep this box checked to ensure the values are updated each time through the UP's

Yes

parent controller. Uncheck the box, and the UP will update the parameters for every sample request made within its scope .

18.7.6 CounterAllows the user to create a counter that can be referenced anywhere in the Thread Group. The counter config lets the user configure a starting point, a maximum, and the increment. The counter will loop from the start to the max, and then start over with the start, continuing on like that until the test is ended.

From version 2.1.2, the counter now uses a long to store the value, so the range is from -2^63 to 2^63-1.

Control Panel

Parameters

Attribute Description Required

NameDescriptive name for this element that is shown in the tree.

No

StartThe starting number for the counter. The counter will equal this number during the first iteration.

Yes

IncrementHow much to increment the counter by after each iteration.

Yes

Maximum

If the counter exceeds the maximum, then it is reset to the Start value. For versions after 2.2 the default is Long.MAX_VALUE (previously it was 0).

No

Format

Optional format, e.g. 000 will format as 001, 002 etc. This is passed to DecimalFormat, so any valid formats can be used. If there is a problem interpreting the format, then it is ignored. [The default format is generated using Long.toString()]

No

Reference NameThis controls how you refer to this value in other elements. Syntax is as in user-defined values : $(reference_name} .

Yes

Track Counter Independently for each User

In other words, is this a global counter, or does each user get their own counter? If unchecked, the counter is global (ie, user #1 will get value "1", and user #2 will get value "2" on the first iteration). If checked, each user has an independent counter.

No

18.7.7 BeanShell PreProcessorThe BeanShell PreProcessor allows arbitrary code to be applied before taking a sample.

Please note that the BeanShell jar file is not included with JMeter; it needs to be separately downloaded. For full details on using BeanShell, please see the BeanShell web-site at http://www.beanshell.org/.

The test element supports the ThreadListener and TestListener methods. These should be defined in the initialisation file. See the file BeanShellListeners.bshrc for example definitions.

Control Panel

Parameters

Attribute Description Required

NameDescriptive name for this element that is shown in the tree.

No

Reset bsh.Interpreter before each call

If this option is selected, then the interpreter will be recreated for each sample. This may be necessary for some long running scripts. For further information, see Best Practices - BeanShell scripting .

Yes

Parameters

Parameters to pass to the BeanShell script. The parameters are stored in the following variables:

Parameters - string containing the parameters as a single variable

bsh.args - String array containing parameters, split on white-space

No

Script fileA file containing the BeanShell script to run.

No

ScriptThe BeanShell script. The return value is ignored.

Yes (unless script file is provided)

The following variables are set up for use by the script:

log - (Logger) - can be used to write to the log file ctx - (JMeterContext) - gives access to the context

vars - (JMeterVariables) - gives read/write access to variables: vars.get(key); vars.put(key,val); vars.putObject("OBJ1",new Object());

props - JMeter Properties - e.g. props.get("START.HMS"); props.put("PROP1","1234");

prev - (SampleResult) - gives access to the previous SampleResult (if any)

sampler - (Sampler)- gives access to the current sampler

For details of all the methods available on each of the above variables, please check the Javadoc

If the property beanshell.preprocessor.init is defined, this is used to load an initialisation file, which can be used to define methods etc for use in the BeanShell script.

18.7.8 BSF PreProcessorThe BSF PreProcessor allows BSF script code to be applied before taking a sample.

Control Panel

Parameters

Attribute Description Required

NameDescriptive name for this element that is shown in the tree.

No

Language The BSF language to be used Yes

Parameters

Parameters to pass to the script. The parameters are stored in the following variables:

Parameters - string containing the parameters as a single variable

args - String array containing parameters, split on white-space

No

Script file A file containing the script to run. No

Script The script to run. Yes (unless script file is provided)

The script (or file) is processed using the BSFEngine.exec() method,

which does not return a value.

The following variables are set up for use by the script:

log - (Logger) - can be used to write to the log file ctx - (JMeterContext) - gives access to the context

vars - (JMeterVariables) - gives read/write access to variables: vars.get(key); vars.put(key,val); vars.putObject("OBJ1",new Object());

props - JMeter Properties - e.g. props.get("START.HMS"); props.put("PROP1","1234");

prev - (SampleResult) - gives access to the previous SampleResult (if any)

sampler - (Sampler)- gives access to the current sampler

OUT - System.out - e.g. OUT.println("message")

For details of all the methods available on each of the above variables, please check the Javadoc

^

18.8 Post-Processors

As the name suggests, Post-Processors are applied after samplers. Note that they are applied to all the samplers in the same scope, so to ensure that a post-processor is applied only to a particular sampler, add it as a child of the sampler.

18.8.1 Regular Expression ExtractorAllows the user to extract values from a server response using a Perl-type regular expression. As a post-processor, this element will execute after each Sample request in its scope, applying the regular expression, extracting the requested values, generate the template string, and store the result into the given variable name.

Control Panel

Parameters

Attribute Description Required

NameDescriptive name for this element that is shown in the tree.

No

Response Field to check

Body, Headers, URL, Response Code, Response Message. These refer to the Sampler Response. Headers can be useful for HTTP samples; it may not be present for other sample types.

yes

Reference Name

The name of the JMeter variable in which to store the result. Also note that each group is stored as [refname]_g#, where [refname] is the string you entered as the reference name, and # is the group number, where group 0 is the entire match, group 1 is the match from the first set of parentheses, etc.

Yes

Regular Expression

The regular expression used to parse the response data. This must contain at least one set of parentheses "()" to capture a portion of the string, unless using the group $0$. Do not enclose the expression in / / - unless of course you want to match these characters as well.

Yes

Template The template used to create a string from the matches found. This is an arbitrary string with special elements to refer to groups within the regular expression. The syntax to refer to a group is: '$1$' to refer to group 1, '$2$' to refer

Yes

to group 2, etc. $0$ refers to whatever the entire expression matches.

Match No.

Indicates which match to use. The regular expression may match multiple times.

Use a value of zero to indicate JMeter should choose a match at random.

A positive number N means to select the nth match.

Negative numbers are used in conjunction with the ForEach controller - see below.

Yes

Default Value

If no matches are found - and a default is provided - the default value is stored in the variable.

No

If the match number is set to a non-negative number, and a match occurs, the variables are set as follows:

refName - the value of the template refName_gn, where n=0,1,2 - the groups for the match

refName_g - the number of groups in the Regex (excluding 0)

If no match occurs, then the refName variable is set to the default (unless this is absent). Also, the following variables are removed:

refName_g0 refName_g1

refName_g

If the match number is set to a negative number, then all the possible matches in the sampler data are processed. The variables are set as follows:

refName_matchNr - the number of matches found; could be 0 refName_n, where n = 1,2,3 etc - the strings as generated by the

template

refName_n_gm, where m=0,1,2 - the groups for match n

refName - always set to the default value

refName_gn - not set

Note that the refName variable is always set to the default value in this

case, and the associated group variables are not set. See also Response Assertion for some examples of how to specify modifiers, and for further information on JMeter regular expressions.

18.8.2 XPath ExtractorThis test element allows the user to extract value from structured response - XML or (X)HTML - using XPath query language.

Control Panel

Parameters

Attribute Description Required

NameDescriptive name for this element that is shown in the tree.

No

Use Tidy

If checked use Tidy to parse HTML response into XHTML.

"Use Tidy" should be checked on for HTML response. Such response is converted to valid XHTML (XML compatible HTML) using Tidy

"Use Tidy" should be unchecked for both XHTML or XML response (for example RSS)

Yes

Quiet Sets the Tidy Quiet flag If Tidy is selected

Report Errors

If a Tidy error occurs, then add an Assertion showing the details

If Tidy is selected

Show Sets the Tidy showWarnings option If Tidy is

warnings selected

Use Namespace?

If checked, then the XML parser will use namespace resolution. Note that currently only namespaces declared on the root element will be recognised. A later version of JMeter may support user-definition of additional workspace names. Meanwhile, a work-round is to replace: //mynamespace:tagname by //*[local-name()='tagname' and namespace-uri()='uri-for-namespace'] where "uri-for-namespace" is the uri for the "mynamespace" namespace. (not applicable if Tidy is selected)

Yes

Reference Name

The name of the JMeter variable in which to store the result.

Yes

XPath QueryElement query in XPath language. Can return more than one match.

Yes

Default Value

Default value returned when no match found No

To allow for use in a ForEach Controller, the following variables are set on return:

refName - set to first (or only) match; if no match, then set to default

refName_matchNr - set to number of matches (may be 0)

refName_n - n=1,2,3 etc. Set to the 1st, 2nd 3rd match etc.

Note: The next refName_n variable is set to null - e.g. if there are 2 matches, then refName_3 is set to null, and if there are no matches, then refName_1 is set to null.

XPath is query language targeted primarily for XSLT transformations. However it is usefull as generic query language for structured data too. See XPath Reference or XPath specification for more information. Here are few examples:

/html/head/title extracts title element from HTML response

/book/page[2] extracts 2nd page from a book

/book/page extracts all pages from a book

//form[@name='countryForm']//select[@name='country']/option[text()='Czech Republic'])/@value

extracts value attribute of option element that match text 'Czech Republic' inside of select element with name attribute 'country' inside of form with name attribute 'countryForm'

When "Use Tidy" is checked on - resulting XML document may slightly differ from original HTML response:

All elements and attribute names are converted to lowercase

Tidy attempts to correct improperly nested elements. For example - original (incorrect) ul/font/li becomes correct ul/li/font

See Tidy homepage for more information.

18.8.3 Result Status Action HandlerThis test element allows the user to stop the thread or the whole test if the relevant sampler failed.

Control Panel

Parameters

Attribute Description Required

Name Descriptive name for this element that is shown No

in the tree.

18.8.4 Save Responses to a fileThis test element can be placed anywhere in the test plan. For each sample in its scope, it will create a file of the response Data. The primary use for this is in creating functional tests. The file name is created from the specified prefix, plus a number. The file extension is created from the document type, if known. The generated file name is stored in the sample response, and can be saved in the test log output file if required.

Control Panel

Parameters

Attribute Description Required

NameDescriptive name for this element that is shown in the tree.

No

Filename PrefixPrefix for the generated file names; this can include a directory name.

Yes

Save Failed Responses only

If selected, then only failed responses are saved

Yes

Save Successful Responses only

If selected, then only successful responses are saved

Yes

18.8.5 Generate Summary ResultsThis test element can be placed anywhere in the test plan. Generates a summary of the test run so far to the log file and/or standard output. Both running and differential totals are shown. Output is generated

every n seconds (default 3 minutes) on the appropriate time boundary, so that multiple test runs on the same time will be synchronised. The interval is defined by the property "summariser.interval" - see jmeter.properties. This element is mainly intended for batch (non-GUI) runs. The output looks like the following:

label + 171 in 20.3s = 8.4/s Avg: 1129 Min: 1000 Max: 1250 Err: 0 (0.00%)label + 263 in 31.3s = 8.4/s Avg: 1138 Min: 1000 Max: 1250 Err: 0 (0.00%)label = 434 in 50.4s = 8.6/s Avg: 1135 Min: 1000 Max: 1250 Err: 0 (0.00%)label + 263 in 31.0s = 8.5/s Avg: 1138 Min: 1000 Max: 1250 Err: 0 (0.00%)label = 697 in 80.3s = 8.7/s Avg: 1136 Min: 1000 Max: 1250 Err: 0 (0.00%)label + 109 in 12.4s = 8.8/s Avg: 1092 Min: 47 Max: 1250 Err: 0 (0.00%)label = 806 in 91.6s = 8.8/s Avg: 1130 Min: 47 Max: 1250 Err: 0 (0.00%)

The "label" is the the name of the element. The "+" means that the line is a delta line, i.e. shows the changes since the last output. The "=" means that the line is a totals line, i.e. it shows the running total. Entries in the jmeter log file also include time-stamps. The example "806 in 91.6s = 8.8/s" means that there were 806 samples recorded in 91.6 seconds, and that works out at 8.8 samples per second. The Avg (Average), Min(imum) and Max(imum) times are in milliseonds. "Err" means number of errors (also shown as percentage). The last two lines will appear at the end of a test. They will not be synchronised to the appropriate time boundary. Note that the initial and final deltas may be for less than the interval (in the example above this is 30 seconds). The first delta will generally be lower, as JMeter synchronises to the interval boundary. The last delta will be lower, as the test will generally not finish on an exact interval boundary.

The label is used to group sample results together. So if you have multiple Thread Groups and want to summarize across them all, then use the same label - or add the summariser to the Test Plan (so all thread groups are in scope). Different summary groupings can be implemented by using suitable labels and adding the summarisers to appropriate parts of the test plan.

Control Panel

Parameters

Attribute Description Required

Name

Descriptive name for this element that is shown in the tree. It appears as the "label" in the output. Details for all elements with the same label will be added together.

Yes

18.8.6 BeanShell PostProcessorThe BeanShell PreProcessor allows arbitrary code to be applied after taking a sample.

For JMeter versions after 2.2 the BeanShell Post-Processor no longer ignores samples with zero-length result data

Please note that the BeanShell jar file is not included with JMeter; it needs to be separately downloaded. For full details on using BeanShell, please see the BeanShell web-site at http://www.beanshell.org/.

The test element supports the ThreadListener and TestListener methods. These should be defined in the initialisation file. See the file BeanShellListeners.bshrc for example definitions.

Control Panel

Parameters

Attribute Description Required

NameDescriptive name for this element that is shown in the tree.

No

Reset bsh.Interpreter before each call

If this option is selected, then the interpreter will be recreated for each sample. This may be necessary for some long running scripts. For further information, see Best Practices - BeanShell scripting .

Yes

Parameters

Parameters to pass to the BeanShell script. The parameters are stored in the following variables:

Parameters - string containing the parameters as a single variable

bsh.args - String array containing parameters, split on white-space

No

Script fileA file containing the BeanShell script to run.

No

ScriptThe BeanShell script. The return value is ignored.

Yes (unless script file is provided)

The following variables are set up for use by the script:

log - (Logger) - can be used to write to the log file ctx - (JMeterContext) - gives access to the context

vars - (JMeterVariables) - gives read/write access to variables: vars.get(key); vars.put(key,val); vars.putObject("OBJ1",new Object());

props - JMeter Properties - e.g. props.get("START.HMS"); props.put("PROP1","1234");

prev - (SampleResult) - gives access to the previous SampleResult

data - (byte [])- gives access to the current sample data

For details of all the methods available on each of the above variables, please check the Javadoc

If the property beanshell.postprocessor.init is defined, this is used to load an initialisation file, which can be used to define methods etc for use in the BeanShell script.

18.8.7 BSF PostProcessorThe BSF PostProcessor allows BSF script code to be applied after taking a sample.

Control Panel

Parameters

Attribute Description Required

NameDescriptive name for this element that is shown in the tree.

No

Language The BSF language to be used Yes

Parameters

Parameters to pass to the script. The parameters are stored in the following variables:

Parameters - string containing the parameters as a single variable

args - String array containing parameters, split on white-space

No

Script file A file containing the script to run. No

Script The script to run. Yes (unless script file is provided)

The script (or file) is processed using the BSFEngine.exec() method,

which does not return a value.

The following variables are set up for use by the script:

log - (Logger) - can be used to write to the log file ctx - (JMeterContext) - gives access to the context

vars - (JMeterVariables) - gives read/write access to variables: vars.get(key); vars.put(key,val); vars.putObject("OBJ1",new Object());

props - JMeter Properties - e.g. props.get("START.HMS"); props.put("PROP1","1234");

prev - (SampleResult) - gives access to the previous SampleResult (if any)

sampler - (Sampler)- gives access to the current sampler

OUT - System.out - e.g. OUT.println("message")

For details of all the methods available on each of the above variables, please check the Javadoc

^

18.9 Miscellaneous Features

18.9.1 Test PlanThe Test Plan is where the overall settings for a test are specified.

Static variables can be defined for values that are repeated throughout a test, such as server names. For example the variable SERVER could be defined as www.example.com, and the rest of the test plan could refer to it as ${SERVER}. This simplifies changing the name later.

If the same variable name is reused on one of more User Defined Variables Configuration elements, the value is set to the last definition in the test plan (reading from top to bottom). Such variables should be used for items that may change between test runs, but which remain the same during a test run.

Note that the Test Plan cannot refer to variables it defines. If you need to construct other variables from the Test Plan variables, use a User Defined Variables test element.

Selecting Functional Testing instructs JMeter to save the additional sample information - Response Data and Sampler Data - to all result files. This increases the resources needed to run a test, and may adversely impact JMeter performance. If more data is required for a particular sampler only, then add a Listener to it, and configure the fields as required. [The option does not affect CSV result files, which cannot currently store such information.]

Also, an option exists here to instruct JMeter to run the Thread Group serially rather than in parallel.

Test plan now provides an easy way to add classpath setting to a specific test plan. The feature is additive, meaning that you can add jar files or directories, but removing an entry requires restarting JMeter. In the past, users had to copy all the jar files to jmeter/lib/ directory. Now that is not necessary. JMeter properties also provides an entry for loading additional classpaths.

In jmeter.properties, edit "user.classpath" to include additional libraries. Note that paths with spaces may cause problems for Java.

Control Panel

18.9.2 Thread GroupA Thread Group defines a pool of users that will execute a particular test case against your server. In the Thread Group GUI, you can control the number of users simulated (num of threads), the ramp up time (how long it takes to start all the threads), the number of times to perform the test, and optionally, a start and stop time for the test.

Control Panel

Parameters

Attribute Description Required

NameDescriptive name for this element that is shown in the tree.

No

Number of Threads

Number of users to simulate. Yes

Ramp-up Period

How long JMeter should take to get all the threads started. If there are 10 threads and a ramp-up time of 100 seconds, then each thread will begin 10 seconds after the previous thread started, for a total time of 100 seconds to get the test fully up to speed.

Yes

Loop CountNumber of times to perform the test case. Alternatively, "forever" can be selected causing the test to run until manually stopped.

No

Start Time

If the scheduler checkbox is selected, one can choose an absolute start time. When you start your test, JMeter will wait until the specified start time to begin testing. Note: the Startup Delay field over-rides this - see below.

No

End Time

If the scheduler checkbox is selected, one can choose an absolute end time. When you start your test, JMeter will wait until the specified start time to begin testing, and it will stop at the specified end time. Note: the Duration field over-rides this - see below.

No

Duration (seconds)

If the scheduler checkbox is selected, one can choose a relative end time. JMeter will use this to calculate the End Time, and ignore the End Time value.

No

Startup delay (seconds)

If the scheduler checkbox is selected, one can choose a relative startup delay. JMeter will use this to calculate the Start Time, and ignore the Start Time value.

No

18.9.3 WorkBenchThe WorkBench simply provides a place to temporarily store test elements while not in use, for copy/paste purposes, or any other purpose you desire. When you save your test plan, WorkBench items are not saved with it. Your WorkBench can be saved independently, if you like (right-click on WorkBench and choose Save).

Certain test elements are only available on the WorkBench:

HTTP Proxy Server HTTP Mirror Server

Property Display

Control Panel

18.9.4 SSL ManagerThe SSL Manager is a way to select a client certificate so that you can test applications that use Public Key Infrastructure (PKI). It is only needed if you have not set up the appropriate System properties.

Choosing a Client Certificate

You may either use a Java Key Store (JKS) format key store, or a Public Key Certificate Standard #12 (PKCS12) file for your client certificates. There is a feature of the JSSE libraries that require you to have at least a six character password on your key (at least for the keytool utility that comes with your JDK).

To select the client certificate, choose Options->SSL Manager from the menu bar. You will be presented with a file finder that looks for PKCS12 files by default. Your PKCS12 file must have the extension '.p12' for SSL Manager to recognize it as a PKCS12 file. Any other file will be treated like an average JKS key store. If JSSE is correctly installed, you will be prompted for the password. The text box does not hide the characters you type at this point--so make sure no one is looking over your shoulder. The current implementation assumes that the password for the keystore is also the password for the private key of the client you want to authenticate as.

Or you can set the appropriate System properties - see the system.properties file.

The next time you run your test, the SSL Manager will examine your key store to see if it has at least one key available to it. If there is only one key, SSL Manager will select it for you. If there is more than one key, it currently selects the first key. There is currently no way to select other entries in the keystore, so the desired key must be the first.

Things to Look Out For You must have your Certificate Authority (CA) certificate installed properly if it is not signed by one of the five CA certificates that ships with your JDK. One method to install it is to import your CA certificate into a JKS file, and name the JKS file "jssecacerts". Place the file in your JRE's lib/security folder. This file will be read before the "cacerts" file in the same directory. Keep in mind that as long as the "jssecacerts" file exists, the certificates installed in "cacerts" will not be used. This may cause problems for you. If you don't mind importing your CA certificate into the "cacerts" file, then you can authenticate against all of the CA certificates installed.

18.9.5 HTTP Proxy Server

The Proxy Server can only record HTTP traffic. It is not possible to

record HTTPS (SSL) sessions; however there is an HTTPS spoofing mode - see below.

The Proxy Server allows JMeter to watch and record your actions while you browse your web application with your normal browser. JMeter will create test sample objects and store them directly into your test plan as you go (so you can view samples interactively while you make them).

To use the proxy server, add the HTTP Proxy Server element to the workbench. Select the WorkBench element in the tree, and right-click on this element to get the Add menu (Add --> Non-Test Elements --> HTTP Proxy Server).

You also need to set up your browser to use the JMeter proxy port as the proxy for HTTP requests. Do not use JMeter as the proxy for any other request types - HTTPS, FTP, etc. - as the JMeter proxy cannot handle them.

Control Panel

Parameters

Attribute Description Required

NameDescriptive name for this controller that is shown in the tree.

No

PortThe port that the Proxy Server listens to. 8080 is the default, but you can change it.

Yes

Attempt HTTPS Spoofing

When you enable HTTPS spoofing, the following happens:

All matching (see below) http

Yes

requests from the client are turned into https (between the proxy and the web server).

All text response data is scanned and any occurrence of the string "https://" is replaced with "http://"; the default HTTPS port (443) is also removed if present.

So if you want to use this feature, while you are browsing in your client, instead of typing "https://..." into the browser, type "http://...". JMeter will request and record everything that matches as https, whether it should be or not.

Optional URL match string

If this is specified, it must be a regular expression (java.util.regex) which matches the HTTP URL(s) to be spoofed. For example, if you want to spoof http://a.b.c/service/ but not http://a.b.c/images, then you could use the expression "http://a.b.c/service/.*". Note that the expression ends in ".*" because it must match the whole URL.

No

Target Controller

The controller where the proxy will store the generated samples. By default, it will look for a Recording Controller and store them there wherever it is.

Yes

Grouping Whether to group samplers for requests from a single "click" (requests received without significant time separation), and how to represent that grouping in the recording:

Do not group samplers: store all recorded samplers sequentially, without any grouping.

Add separators between groups: add a controller named "--------------" to create a visual separation between the groups. Otherwise the samplers are all stored sequentially.

Put each group in a new controller: create a new Simple Controller for

Yes

each group, and store all samplers for that group in it.

Store 1st sampler of each group only: only the first request in each group will be recorded. The "Follow Redirects" and "Retrieve All Embedded Resources..." flags will be turned on in those samplers.

The property proxy.pause determines the minimum gap that JMeter needs between requests to treat them as separate "clicks". The default is 1000 (milliseconds) i.e. 1 second. If you are using grouping, please ensure that you leave the required gap between clicks.

Capture HTTP Headers

Should headers be added to the plan? If specified, a Header Manager will be added to each HTTP Sampler. The Proxy server always removes Cookie and Authorization headers from the generated Header Managers. By default it also removes If-Modified-Since and If-None-Match headers. These are used to determine if the browser cache items are up to date; when recording one normally wants to download all the content. To change which additional headers are removed, define the JMeter property proxy.headers.remove as a comma-separated list of headers.

Yes

Add Assertions Add a blank assertion to each sampler? Yes

Regex Matching

Use Regex Matching when replacing variables?

Yes

TypeWhich type of sampler to generate (the Java default or HTTPClient)

Yes

Redirect Automatically

Set Redirect Automatically in the generated samplers?

Yes

Follow Redirects

Set Follow Redirects in the generated samplers?

Yes

Use Keep-Alive

Set Use Keep-Alive in the generated samplers?

Yes

Retrieve all Embedded Resources

Set Retrieve all Embedded Resources in the generated samplers?

Yes

Content Type filter

Filter the requests based on the content-type - e.g. "text/html [;charset=utf-8 ]". The fields are regular expressions which are checked to see if they are contained in the content-type. [Does not have to match the entire field]. The include filter is checked first, then the exclude filter. Samples which are filtered out will not be stored.

No

Patterns to Include

Regular expressions that are matched against the full URL that is sampled. Allows filtering of requests that are recorded. All requests pass through, but only those that meet the requirements of the Include/Exclude fields are recorded . If both Include and Exclude are left empty, then everything is recorded (which can result in dozens of samples recorded for each page, as images, stylesheets, etc are recorded). If there is at least one entry in the Include field, then only requests that match one or more Include patterns are recorded .

No

Patterns to Exclude

Regular expressions that are matched against the URL that is sampled. Any requests that match one or more Exclude pattern are not recorded .

No

Start Button

Start the proxy server. JMeter writes the following message to the console once the proxy server has started up and is ready to take requests: "Proxy up and running!".

N/A

Stop Button Stop the proxy server. N/A

Restart ButtonStops and restarts the proxy server. This is useful when you change/add/delete an include/exclude filter expression.

N/A

The include and exclude patterns are treated as regular expressions (using Jakarta ORO). They will be matched against the host name, port (actual or implied) path and query (if any) of each browser request. If the URL you are browsing is "http://jakarta.apache.org/jmeter/index.html?username=xxxx" , then the regular expression will be tested against the string:

"jakarta.apache.org:80/jmeter/index.html?username=xxxx" . Thus, if you want to include all .html files, your regular expression might look like: ".*\.html(\?.*)?" - or ".*\.html" if you know that there is no query string or you only want html pages without query strings.

If there are any include patterns, then the URL must match at least one of the patterns , otherwise it will not be recorded. If there are any exclude patterns, then the URL must not match any of the patterns , otherwise it will not be recorded. Using a combination of includes and excludes, you should be able to record what you are interested in and skip what you are not.

N.B. the string that is matched by the regular expression must be the same as the whole host+path string. Thus "\.html" will not match j.a.o/index.html

Versions of JMeter from 2.3.2 are able to capture binary POST data. To configure which content-types are treated as binary, update the JMeter property proxy.binary.types. The default settings are as follows:

# These content-types will be handled by saving the request in a file:proxy.binary.types=application/x-amf,application/x-java-serialized-object# The files will be saved in this directory:proxy.binary.directory=user.dir# The files will be created with this file filesuffix:proxy.binary.filesuffix=.binary

It is also possible to have the proxy add timers to the recorded script. To do this, create a timer directly within the HTTP Proxy Server component. The proxy will place a copy of this timer into each sample it records, or into the first sample of each group if you're using grouping. This copy will then be scanned for occurences of variable ${T} in its properties, and any such occurences will be replaced by the time gap from the previous sampler recorded (in milliseconds).

When you are ready to begin, hit "start".

You will need to edit the proxy settings of your browser to point at the appropriate server and port,

where the server is the machine JMeter is running on, and the port # is from the Proxy Control Panel shown above.

Where Do Samples Get Recorded?

JMeter places the recorded samples in the Target Controller you choose. If you choose the default option "Use Recording Controller", they will be stored in the first Recording Controller found in the test object tree (so be sure to add a Recording Controller before you start recording).

If the Proxy does not seem to record any samples, this could be because the browser is not actually using the proxy. To check if this is the case, try stopping the proxy. If the browser still downloads pages, then it was not sending requests via the proxy. Double-check the browser options. In particular check that the browser is not set to "Bypass proxy server for local addresses" (this example is from IE7, but there will be similar options for other browsers).

If the HTTP Proxy Server finds enabled HTTP Request Defaults directly within the controller where samples are being stored, or directly within any of its parent controllers, the recorded samples will have empty fields for the default values you specified. You may further control this behaviour by placing an HTTP Request Defaults element directly within the HTTP Proxy Server, whose non-blank values will override those in the other HTTP Request Defaults. See Best Practices with the Proxy Server for more info.

Similarly, if the HTTP Proxy Server finds User Defined Variables (UDV) directly within the controller where samples are being stored, or directly within any of its parent controllers, the recorded samples will have any occurences of the values of those variables replaced by the corresponding variable. Again, you can place User Defined Variables directly within the HTTP Proxy Server to override the values to be replaced. See Best Practices with the Proxy Server for more info.

Please note that matching is case-sensitive.

Replacement by Variables: by default, the Proxy server looks for all occurences of UDV values. If you define the variable "WEB" with the value "www", for example, the string "www" will be replaced by ${WEB} wherever it is found. To avoid this happening everywhere, set the "Regex Matching" check-box. This tells the proxy server to treat values as Regexes (using ORO).

If you want to match a whole string only, enclose it in ^$, e.g. "^thus$". If you want to match /images at the start of a string only, use the value "^/images". Jakarta ORO also supports zero-width look-ahead, so one can match /images/... but retain the trailing / in the output by using "^/images(?=/)". Note that the current version of Jakara ORO does not support look-behind - i.e. "(?<=...) or (?<!...)". If there are any problems interpreting any variables as patterns, these are reported in jmeter.log, so be sure to check this if UDVs are not working as expected.

When you are done recording your test samples, stop the proxy server (hit the "stop" button). Remember to reset your browser's proxy settings. Now, you may want to sort and re-order the test script, add timers, listeners, a cookie manager, etc.

How can I record the server's responses too? Just place a View Results Tree listener as a child of the Proxy Server and the responses will be displayed. You can also add a Save Responses to a file Post-Processor which will save the responses to files.

18.9.6 HTTP Mirror ServerThe HTTP Mirrror Server is a very simple HTTP server - it simply mirrors the data sent to it. This is useful for checking the content of HTTP requests.

Control Panel

18.9.7 Property DisplayThe Property Display shows the values of System or JMeter properties. Values can be changed by entering new text in the Value column. It is available only on the WorkBench.

Control Panel

Parameters

Attribute Description Required

NameDescriptive name for this element that is shown in the tree.

No

18.9.8 Debug SamplerThe Debug Sampler generates a sample containing the values of all JMeter variables and/or properties.

The values can be seen in the View Results Tree Listener Response

Data pane.

Control Panel

Parameters

Attribute Description Required

NameDescriptive name for this element that is shown in the tree.

No

JMeter Properties

Include JMeter properties ? Yes

JMeter Variables

Include JMeter variables ? Yes

System Properties

Include System properties ? Yes

18.9.8 Debug PostProcessorThe Debug PostProcessor creates a subSample with the details of the previous sampler properties. This is intended for developer use only.

Control Panel

Parameters

Attribute Description Required

NameDescriptive name for this element that is shown in the tree.

No

^

18.10 Reports

18.10.1 Report Plan

18.10.2 Report Table

18.10.3 HTML Report Writer

18.10.4 Report Page

18.10.5 Line Graph

18.10.6 Bar Chart

^

Index Next Prev

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

First argument

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 parentheses. Example: <a href="(.*)">. This will grab the value of the link and store it as the first group (there is only 1 group). Another example: <input type="hidden" name="(.*)" value="(.*)">. This will

Yes

grab the name as the first group, and the value as the second group. These values can be used in your template string

Second argument

This is the template string that will replace the function at run-time. To refer to a group captured in the regular expression, use the syntax: $[group_number]$. Ie: $1$, or $2$. Your template can be any string.

Yes

Third argument

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.

ALL - Tells JMeter to use all matches, and create a template string for each one and then append them all together. This option is little used.

A float number between 0 and 1 - tells JMeter to find the Xth match using the formula: (number_of_matches_found * float_number) rounded to nearest integer.

No, default=1

Fourth argument

If 'ALL' was selected for the above argument value, then this argument will be inserted between each appended copy of the template value.

No

Fifth argument

Default value returned if no match is found No

Sixth argument

A reference name for reusing the values parsed by this function. Stored values are ${refName} (the replacement template string) and ${refName_g#} where "#" is the group number from the regular expression ("0" can be used to refer to the entire match).

No

Seventh argument

Input variable name. If specified, then the value of the variable is used as the input instead of using the previous sample result.

No

19.5.2 __counterThe counter generates a new number each time it is called, starting with 1 and incrementing by +1 each time. The counter can be configured to keep each simulated user's values separate, or to use the same counter for all users. If each user's values is incremented separately, that is like counting the number of iterations through the test plan. A global counter is like counting how many times that request was run.

The counter uses an integer variable to hold the count, which therefore has a maximum of 2,147,483,647.

The counter function instances are now completely independent. [JMeter 2.1.1 and earlier used a fixed thread variable to keep track of the per-user count, so multiple counter functions operated

on the same value.] The global counter - "FALSE" - is separately maintained by each counter instance.

Parameters

Attribute Description Required

First argument

TRUE if you wish each simulated user's counter to be kept independent and separate from the other users. FALSE for a global counter.

Yes

Second argument

A reference name for reusing the value created by this function. Stored values are of the form ${refName}. This allows you to keep one counter and refer to its value in multiple places. [For JMeter 2.1.1 and earlier this parameter was required.]

No

19.5.3 __threadNumThe thread number function simply returns the number of the thread currently being executed. These numbers are independent of ThreadGroup, meaning thread #1 in one threadgroup is indistinguishable from thread #1 in another threadgroup, from the point of view of this function.

There are no arguments for this function.

This function does not work in any Configuration elements (e.g. User Defined Variables) as these are run from a separate thread. Nor does it make sense to use it on the Test Plan.

19.5.4a __intSumThe intSum function can be used to compute the sum of two or more integer values.

JMeter Versions 2.3.1 and earlier required the reference name to be present. The reference name is now optional, but it must not be a valid integer.

Parameters

Attribute Description Required

First argument

The first int value. Yes

Second argument

The second int value. Yes

nth argument

The nth int value. No

last argument

A reference name for reusing the value computed by this function. If specified, the reference name must contain at least one non-numeric character otherwise it will be treated as another int value to be added.

No

19.5.4b __longSumThe longSum function can be used to compute the sum of two or more long values.

Parameters

Attribute Description Required

First argument

The first long value. Yes

Second argument

The second long value. Yes

nth argument

The nth long value. No

last argument

A reference name for reusing the value computed by this function. If specified, the reference name must contain at least one non-numeric character otherwise it will be treated as another long value to be added.

No

19.5.5 __StringFromFileThe StringFromFile function can be used to read strings from a text file. This is useful for running tests that require lots of variable data. For example when testing a banking application, 100s or 1000s of different account numbers might be required.

See also the CSV Data Set Config test element which may be easier to use. However, that does not currently support multiple input files.

Each time it is called it reads the next line from the file. When the end of the file is reached, it will start reading again from the beginning, unless the maximum loop count has been reached. If

there are multiple references to the function in a test script, each will open the file independently, even if the file names are the same. [If the value is to be used again elsewhere, use different variable names for each function call.]

If an error occurs opening or reading the file, then the function returns the string "**ERR**"

Parameters

Attribute Description Required

File NamePath to the file name. (The path can be relative to the JMeter launch directory) If using optional sequence numbers, the path name should be suitable for passing to DecimalFormat. See below for examples.

Yes

Variable Name

A reference name - refName - for reusing the value created by this function. Stored values are of the form ${refName}. Defaults to "StringFromFile_".

No

Start sequence number

Initial Sequence number (if omitted, the End sequence number is treated as a loop count)

No

End sequence number

Final sequence number (if omitted, seqence numbers can increase without limit)

No

The file name parameter is resolved when the file is opened or re-opened.

The reference name parameter (if supplied) is resolved every time the function is executed.

Using sequence numbers:

When using the optional sequence numbers, the path name is used as the format string for java.text.DecimalFormat. The current sequence number is passed in as the only parameter. If the optional start number is not specified, the path name is used as is. Useful formatting sequences are:

# - insert the number, with no leading zeros or spaces 000 - insert the number packed out to 3 digits with leading zeros if necessary

Examples: pin#'.'dat -> pin1.dat, ... pin9.dat, pin10.dat, ... pin9999.dat pin000'.'dat -> pin001.dat ... pin099.dat ... pin999.dat ... pin9999.dat pin'.'dat# -> pin.dat1, ... pin.dat9 ... pin.dat999 If more digits are required than there are formatting characters, the number will be expanded as necessary. To prevent a formatting character from being interpreted, enclose it in single quotes. Note

that "." is a formatting character, and must be enclosed in single quotes (though #. and 000. work as expected in locales where the decimal point is also ".") In other locales (e.g. fr), the decimal point is "," - which means that "#." becomes "nnn,". See the documentation for DecimalFormat for full details. If the path name does not contain any special formatting characters, the current sequence number will be appended to the name, otherwise the number will be inserted aaccording to the fomatting instructions. If the start sequence number is omitted, and the end sequence number is specified, the sequence number is interpreted as a loop count, and the file will be used at most "end" times. In this case the filename is not formatted. ${_StringFromFile(PIN#'.'DAT,,1,2)} - reads PIN1.DAT, PIN2.DAT ${_StringFromFile(PIN.DAT,,,2)} - reads PIN.DAT twice

Note that the "." in PIN.DAT above should not be quoted. In this case the start number is omitted, so the file name is used exactly as is.

19.5.6 __machineNameThe machineName function returns the local host name

Parameters

Attribute Description Required

Variable Name A reference name for reusing the value computed by this function. No

19.5.7 __javaScriptThe javaScript function executes a piece of JavaScript (not Java!) code and returns its value

The JMeter Javascript function calls a standalone JavaScript interpreter. Javascript is used as a scripting language, so you can do calculations etc.

For details of the language, please see Mozilla Rhino Overview

The following variables are made available to the script:

ctx - JMeterContext object vars - JMeterVariables object

threadName - String

sampler - current Sampler object (if any)

sampleResult - previous SampleResult object (if any)

props - JMeter Properties object

JMeter is not a browser, and does not interpret the JavaScript in downloaded pages.

Parameters

Attribute Description Required

Expression

The JavaScript expression to be executed. For example: new Date() - return the current date and time Math.floor(Math.random()*(${maxRandom}+1)) - a random

number between 0 and the variable maxRandom

${minRandom}+Math.floor(Math.random()*(${maxRandom}-${minRandom}+1)) - a random number between the variables minRandom and maxRandom

"${VAR}"=="abcd"

Yes

Variable Name

A reference name for reusing the value computed by this function. No

Remember to include any necessary quotes for text strings and JMeter variables. Also, if the expression has commas, please make sure to escape them. For example in: ${__javaScript('${sp}'.slice(7\,99999))} the comma after 7 is escaped.

19.5.8 __RandomThe random function returns a random number that lies between the given min and max values.

Parameters

Attribute Description Required

Minimum value A number Yes

Maximum value A bigger number Yes

Variable Name A reference name for reusing the value computed by this function. No

19.5.8 __CSVReadThe CSVFile function returns a string from a CSV file (c.f. StringFromFile )

NOTE: versions up to 1.9.1 only supported a single file. JMeter versions since 1.9.1 support multiple file names.

In most cases, the newer CSV Data Set Config element is easier to use.

When a filename is first encountered, the file is opened and read into an internal array. If a blank line is detected, this is treated as end of file - this allows trailing comments to be used (N.B. this feature was introduced in versions after 1.9.1)

All subsequent references to the same file name use the same internal array. N.B. the filename case is significant to the function, even if the OS doesn't care, so CSVRead(abc.txt,0) and CSVRead(aBc.txt,0) would refer to different internal arrays.

The *ALIAS feature allows the same file to be opened more than once, and also allows for shorter file names.

Each thread has its own internal pointer to its current row in the file array. When a thread first refers to the file it will be allocated the next free row in the array, so each thread will access a different row from all other threads. [Unless there are more threads than there are rows in the array.]

Note: the function splits the line at every comma by default. If you want to enter columns containing commas, then you will need to change the delimiter to a character that does not appear in any column data, by setting the property: csvread.delimiter

Parameters

Attribute Description Required

File Name The file (or *ALIAS) to read from Yes

Column number

The column number in the file. 0 = first column, 1 = second etc. "next" - go to next line of file. *ALIAS - open a file and assign it to the alias

Yes

For example, you could set up some variables as follows:

COL1a ${__CSVRead(random.txt,0)} COL2a ${__CSVRead(random.txt,1)}${__CSVRead(random.txt,next)}

COL1b ${__CSVRead(random.txt,0)}

COL2b ${__CSVRead(random.txt,1)}${__CSVRead(random.txt,next)}

This would read two columns from one line, and two columns from the next available line. If all

the variables are defined on the same User Parameters Pre-Processor, then the lines will be consecutive. Otherwise, a different thread may grab the next line.

The function is not suitable for use with large files, as the entire file is stored in memory. For larger files, use CSV Data Set Config element or StringFromFile .

19.5.9 __propertyThe property function returns the value of a JMeter property. If the property value cannot be found, and no default has been supplied, it returns the property name. When supplying a default value, there is no need to provide a function name - the parameter can be set to null, and it will be ignored.

For example: ${__property(user.dir)} - return value of user.dir ${__property(user.dir,UDIR)} - return value of user.dir and save in UDIR

${__property(abcd,ABCD,atod)} - return value of property abcd (or "atod" if not defined) and save in ABCD

${__property(abcd,,atod)} - return value of property abcd (or "atod" if not defined) but don't save it

Parameters

Attribute Description Required

Property Name The property name to be retrieved. Yes

Variable Name A reference name for reusing the value computed by this function. No

Default Value The default value for the property. No

19.5.10 __PThis is a simplified property function which is intended for use with properties defined on the command line. Unlike the __property function, there is no option to save the value in a variable, and if no default value is supplied, it is assumed to be 1. The value of 1 was chosen because it is valid for common test variables such as loops, thread count, ramp up etc.

For example:

Define the property value: jmeter -Jgroup1.threads=7 -Jhostname1=www.realhost.edu Fetch the values:

${__P(group1.threads)} - return the value of group1.threads ${__P(group1.loops)} - return the value of group1.loops ${__P(hostname,www.dummy.org)} - return value of property hostname or www.dummy.org if not defined

In the examples above, the first function call would return 7, the second would return 1 and the last would return www.dummy.org (unless those properties were defined elsewhere!)

Parameters

Attribute Description Required

Property Name The property name to be retrieved. Yes

Default ValueThe default value for the property. If omitted, the default is set to "1".

No

19.5.11 __logThe log function logs a message, and returns its input string

Parameters

Attribute Description Required

String to be logged

A string Yes

Log Level OUT, ERR, DEBUG, INFO (default), WARN or ERROR No

Throwable text If non-empty, creates a Throwable to pass to the logger No

CommentIf present, it is displayed in the string. Useful for identifying what is being logged.

No

The OUT and ERR log level names are used to direct the output to System.out and System.err respectively. In this case, the output is always printed - it does not depend on the current log setting.

For example: ${__log(Message)} - written to the log file as "...thread Name : Message" ${__log(Message,OUT)} - written to console window ${__log(${VAR},,,VAR=)} - written to log file as "...thread Name VAR=value"

19.5.12 __lognThe logn function logs a message, and returns the empty string

Parameters

Attribute Description Required

String to be logged A string Yes

Log Level OUT, ERR, DEBUG, INFO (default), WARN or ERROR No

Throwable text If non-empty, creates a Throwable to pass to the logger No

The OUT and ERR log level names are used to direct the output to System.out and System.err respectively. In this case, the output is always printed - it does not depend on the current log setting.

For example: ${__logn(VAR1=${VAR1},OUT)} - write the value of the variable to the console window

19.5.13 __BeanShellThe BeanShell function evaluates the script passed to it, and returns the result.

Please note that the BeanShell jar file is not included with JMeter; it needs to be separately downloaded. For full details on using BeanShell, please see the BeanShell web-site at http://www.beanshell.org/

Note that a different Interpreter is used for each independent occurence of the function in a test script, but the same Interpreter is used for subsequent invocations. This means that variables persist across calls to the function.

A single instance of a function may be called from multiple threads. However the function execute() method is synchronised.

If the property "beanshell.function.init" is defined, it is passed to the Interpreter as the name of a sourced file. This can be used to define common methods and variables. There is a sample init file in the bin directory: BeanShellFunction.bshrc.

The following variables are set before the script is executed:

log - the logger for the BeanShell function (*) ctx - the current JMeter context variable

vars - the current JMeter variables

props - JMeter Properties object

threadName - the threadName

Sampler the current Sampler, if any

SampleResult - the current SampleResult, if any

(*) means that this is set before the init file, if any, is processed. Other variables vary from invocation to invocation.

Parameters

Attribute Description Required

BeanShell script A beanshell script (not a file name) Yes

Name of variable A reference name for reusing the value computed by this function. No

Example:

${__BeanShell(123*456)} - returns 56088${__BeanShell(source("function.bsh"))} - processes the script in function.bsh

Remember to include any necessary quotes for text strings and JMeter variables

19.5.14 __splitThe split function splits the string passed to it according to the delimiter, and returns the original string. If any delimiters are adjacent, "?" is returned as the value. The split strings are returned in the variables ${VAR_1}, ${VAR_2} etc. The count of variables is returned in ${VAR_n}. From JMeter 2.1.2 onwards, a trailing delimiter is treated as a missing variable, and "?" is returned. Also, to allow it to work better with the ForEach controller, __split now deletes the first unused variable in case it was set by a previous split.

Example:

Define VAR="a||c|" in the test plan. ${__split(${VAR},VAR),|} This will return the contents of VAR, i.e. "a||c|" and set the following variables: VAR_n=4 (3 in JMeter 2.1.1 and earlier) VAR_1=a VAR_2=? VAR_3=c VAR_4=? (null in JMeter 2.1.1 and earlier) VAR_5=null (in JMeter 2.1.2 and later)

Parameters

Attribute Description Required

String to split A delimited string, e.g. "a|b|c" Yes

Name of variable

A reference name for reusing the value computed by this function. Yes

DelimiterThe delimiter character, e.g. | . If omitted, , is used. Note that , would need to be specified as \, .

No

19.5.15 __XPathThe XPath function reads an XML file and matches the XPath. Each time the function is called, the next match will be returned. At end of file, it will wrap around to the start.

Note that the entire file is held in memory, so this function should not be used for very large files.

Example:

${__XPath(/path/to/build.xml, //target/@name)} This will match all targets in build.xml and return the contents of the next name attribute

Parameters

Attribute Description Required

XML file to parse a XML file to parse Yes

XPath a XPath expression to match nodes in the XML file Yes

19.5.16 __setProperty

The setProperty function sets the value of a JMeter property. The default return value from the function is the empty string, so the function call can be used anywhere functions are valid.

The original value can be returned by setting the optional 3rd parameter to "true".

Properties are global to JMeter, so can be used to communicate between threads and thread groups

Parameters

Attribute Description Required

Property Name The property name to be set. Yes

Property Value The value for the property. Yes

True/False Should the original value be returned? No

19.5.17 __timeThe time function returns the current time in various formats.

Parameters

Attribute Description Required

FormatThe format to be passed to SimpleDateFormat. The function supports various shorthand aliases, see below.

No

Name of variable

The name of the variable to set. No

If the format string is omitted, then the function returns the current time in milliseconds. Otherwise, the current time is passed to SimpleDateFormat. The following shorthand aliases are provided:

YMD = yyyyMMdd HMS = HHmmss

YMDHMS = yyyyMMdd-HHmmss

USER1 = whatever is in the Jmeter property time.USER1

USER2 = whatever is in the Jmeter property time.USER2

The defaults can be changed by setting the appropriate JMeter property, e.g. time.YMD=yyMMdd

19.5.18 __jexlThe jexl function returns the result of evaluating a Commons JEXL expression . See links below for more information on JEXL expressions.

JEXL syntax description JEXL examples

Parameters

Attribute Description Required

Expression The expression to be evaluated. For example, 6*(5+2) Yes

Name of variable The name of the variable to set. No

The following variables are made available to the script:

ctx - JMeterContext object vars - JMeterVariables object

props - JMeter Properties object

threadName - String

sampler - current Sampler object (if any)

sampleResult - previous SampleResult object (if any)

19.5.19 __VThe V (variable) function returns the result of evaluating a variable name expression. This can be used to evaluate nested variable references (which are not currently supported).

For example, if one has variables A1,A2 and N=1:

${A1} - works OK ${A${N}} - does not work (nested variable reference)

${__V(A${N})} - works OK. A${N} becomes A1, and the __V function returns the value of A1

Parameters

Attribute Description Required

Variable name The variable to be evaluated. Yes

19.5.20 __evalVarThe eval function returns the result of evaluating an expression stored in a variable.

This allows one to read a string from a file, and process any variable references in it. For example, if the variable "query" contains "select ${column} from ${table}" and "column" and "table" contain "name" and "customers", then ${__evalVar(query)} will evaluate as "select name from customers".

Parameters

Attribute Description Required

Variable name The variable to be evaluated. Yes

19.5.21 __evalThe eval function returns the result of evaluating a string expression.

This allows one to interpolate variable and function references in a string which is stored in a variable. For example, given the following variables:

name=Smith column=age

table=birthdays

SQL=select ${column} from ${table} where name='${name}'

then ${__eval(${SQL})} will evaluate as "select age from birthdays where name='Smith'".

This can be used in conjunction with CSV Dataset, for example where the both SQL statements and the values are defined in the data file.

Parameters

Attribute Description Required

Variable name The variable to be evaluated. Yes

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.