Jmeter 2.3.

4 Users Manual

1.
1.1 1.2

Introduction ........................................................................................ 9
History................................................................................................................. 9 The Future........................................................................................................... 9

2.

Getting Started.................................................................................. 10
2.1 Requirements .................................................................................................... 10 2.1.1 Java Version.............................................................................................. 11 2.1.2 Operating Systems .................................................................................... 11 2.2 Optional............................................................................................................. 11 2.2.1 Java Compiler ........................................................................................... 11 2.2.2 SAX XML Parser...................................................................................... 11 2.2.3 Email Support ........................................................................................... 11 2.2.4 SSL Encryption......................................................................................... 11 2.2.5 JDBC Driver ............................................................................................. 12 2.2.6 Apache SOAP ........................................................................................... 12 2.2.7 Libraries for ActiveMQ 3.0 ...................................................................... 12 2.3 Installation......................................................................................................... 12 2.4 Running JMeter................................................................................................. 13 2.4.1 JMeter's Classpath..................................................................................... 14 2.4.2 Using a Proxy Server ................................................................................ 14 2.4.3 Non-GUI Mode (Command Line mode) .................................................. 15 2.4.4 Server Mode.............................................................................................. 15 2.4.5 Overriding Properties Via The Command Line........................................ 16 2.4.6 Logging and error messages ..................................................................... 16 2.4.7 Full list of command-line options ............................................................. 17 2.5 Configuring JMeter........................................................................................... 18

3.
3.1 3.2 3.3 3.4 3.5 3.6 3.7

Building a Test Plan ......................................................................... 20

Adding and Removing Elements ...................................................................... 20 Loading and Saving Elements .......................................................................... 20 Configuring Tree Elements............................................................................... 20 Saving the Test Plan.......................................................................................... 20 Running a Test Plan .......................................................................................... 21 Stopping a Test ................................................................................................. 21 Error reporting .................................................................................................. 22

4.

Elements of a Test Plan.................................................................... 23

4.1 ThreadGroup ..................................................................................................... 23 4.2 Controllers......................................................................................................... 24 4.2.1 Samplers.................................................................................................... 24 4.2.2 Logic Controllers ...................................................................................... 25 4.3 Listeners............................................................................................................ 26 4.4 Timers ............................................................................................................... 27 4.5 Assertions.......................................................................................................... 27 4.6 Configuration Elements .................................................................................... 27

Jmeter 2.3.4 Users Manual

4.7 4.8 4.9 4.10 4.11 4.12

Pre-Processor Elements .................................................................................... 28 Post-Processor Elements................................................................................... 28 Execution order................................................................................................. 29 Scoping Rules ................................................................................................... 30 Properties and Variables ................................................................................... 31 Using Variables to parameterize tests............................................................... 32

5.
5.1 5.2 5.3 5.4 5.5 5.6

Building a Web Test Plan ................................................................ 34

Adding Users .................................................................................................... 34 Adding Default HTTP Request Properties ....................................................... 36 Adding Cookie Support .................................................................................... 37 Adding HTTP Requests .................................................................................... 38 Adding a Listener to View Store the Test Results............................................ 40 Logging in to a web-site ................................................................................... 41

6.
6.1 6.2

Building an Advanced Web Test Plan............................................ 43

Handling User Sessions with URL Rewriting .................................................. 43 Using a Header Manager .................................................................................. 44

7.
7.1 7.2 7.3

Building a Database Test Plan ........................................................ 45

Adding Users .................................................................................................... 45 Adding JDBC Requests .................................................................................... 47 Adding a Listener to View/Store the Test Results............................................ 50

8.
8.1 8.2 8.3 8.4

Building an FTP Test Plan .............................................................. 52

Adding Users .................................................................................................... 52 Adding Default FTP Request Properties........................................................... 54 Adding FTP Requests ....................................................................................... 55 Adding a Listener to View/Store the Test Results............................................ 57

9.
9.1 9.2 9.3 9.4 9.5

Building an LDAP Test Plan ........................................................... 58

Adding Users .................................................................................................... 58 Adding Login Config Element.......................................................................... 58 Adding LDAP Request Defaults....................................................................... 59 Adding LDAP Requests.................................................................................... 60 Adding a Listener to View/Store the Test Results............................................ 63

10.

Building an Extended LDAP Test Plan.......................................... 64

10.1 Adding Users .................................................................................................... 64 10.2 Adding LDAP Extended Request Defaults....................................................... 65 10.3 Adding LDAP Requests.................................................................................... 66 10.3.1 Adding a Thread bind Request ................................................................. 67 10.3.2 Adding a search Request........................................................................... 68 10.3.3 Adding a Compare Request ...................................................................... 69 10.3.4 Adding a Single bind/unbind .................................................................... 70 10.3.5 Adding an Add Request ............................................................................ 71

Jmeter 2.3.4 Users Manual

10.3.6 Adding a Modify Request......................................................................... 72 10.3.7 Adding a Delete Request .......................................................................... 73 10.3.8 Adding a Rename Request (moddn) ......................................................... 74 10.3.9 Adding an unbind Request........................................................................ 75 10.4 Adding a Listener to View/Store the Test Results............................................ 76

11.
11.1 11.2 11.3

Building a WebService Test Plan.................................................... 78

Adding Users .................................................................................................... 78 Adding WebService Requests........................................................................... 80 Adding a Listener to View Store the Test Results............................................ 82

12.
12.1 12.2 12.3

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

Adding a Thread Group .................................................................................... 84 Adding JMS Point-to-Point Sampler ................................................................ 85 Adding a Listener to View Store the Test Results............................................ 86

13.
13.1 13.2 13.3

Building a JMS Topic Test Plan ..................................................... 88

Adding Users .................................................................................................... 88 Adding JMS Subscriber and Publisher ............................................................. 90 Adding a Listener to View Store the Test Results............................................ 93

14.
14.1 14.2 14.3 14.4 14.5 14.6

Building a Monitor Test Plan .......................................................... 94

Adding a Server ................................................................................................ 94 HTTP Auth Manager ........................................................................................ 95 Adding HTTP Request...................................................................................... 95 Adding Constant Timer..................................................................................... 95 Adding a Listener to Store the Results ............................................................. 95 Adding Monitor Results.................................................................................... 96

15.

Introduction to listeners................................................................... 98

15.1 Default Configuration ....................................................................................... 98 15.1.1 Sample Variables .................................................................................... 100 15.1.2 Sample Result Save Configuration ......................................................... 101 15.2 Non-GUI (batch) test runs .............................................................................. 101 15.3 Resource usage................................................................................................ 102 15.4 CSV Log format.............................................................................................. 102 15.5 XML Log format 2.0....................................................................................... 103 15.6 XML Log format 2.1....................................................................................... 103 15.7 Sample Attributes............................................................................................ 105 15.8 Saving response data....................................................................................... 106 15.9 Loading (reading) response data..................................................................... 106 15.10 Saving Listener GUI data............................................................................ 106

16.
16.1 16.2

Remote Testing ............................................................................... 108

Doing it Manually ........................................................................................... 110 Tips ................................................................................................................. 110

Jmeter 2.3.4 Users Manual

16.3 16.4

Using a different port ...................................................................................... 111 Using sample batching.................................................................................... 112

17.

Best Practices .................................................................................. 113

17.1 Limit the Number of Threads ......................................................................... 113 17.2 Where to Put the Cookie Manager.................................................................. 113 17.3 Where to Put the Authorization Manager ....................................................... 113 17.4 Using the Proxy Server ................................................................................... 113 17.5 User variables.................................................................................................. 114 17.6 Reducing resource requirements..................................................................... 114 17.7 BeanShell server ............................................................................................. 115 17.8 BeanShell scripting ......................................................................................... 116 17.8.1 Overview................................................................................................. 116 17.8.2 Sharing Variables.................................................................................... 116 17.9 Developing script functions in BeanShell, Javascript or Jexl etc. .................. 117 17.10 Parameterising tests .................................................................................... 117

18.

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

18.1 Questions to ask .............................................................................................. 119 18.2 Resources ........................................................................................................ 119 18.2.1 Network................................................................................................... 119 18.2.2 Application.............................................................................................. 119 18.3 What platform should I use to run the benchmarks/load-tests?...................... 120 18.4 Tools ............................................................................................................... 120 18.4.1 ping ......................................................................................................... 121 18.4.2 nslookup/dig............................................................................................ 121 18.4.3 traceroute................................................................................................. 121 18.5 What other products are there? ....................................................................... 121 18.5.1 Apache 'ab' tool....................................................................................... 121 18.5.2 HttpUnit .................................................................................................. 121 18.5.3 Microsoft WAS....................................................................................... 121 18.5.4 JMeter ..................................................................................................... 122 18.6 Why Java?....................................................................................................... 122

19.

Component Reference .................................................................... 123

19.1 Samplers.............................................................................................................. 123 19.1.1 FTP Request............................................................................................ 123 19.1.2 HTTP Request......................................................................................... 124 19.1.3 JDBC Request......................................................................................... 131 19.1.4 Java Request............................................................................................ 134 19.1.5 SOAP/XML-RPC Request ..................................................................... 135 19.1.6 WebService(SOAP) Request .................................................................. 136 19.1.7 LDAP Request ........................................................................................ 139 19.1.8 LDAP Extended Request ........................................................................ 142 19.1.9 Access Log Sampler ............................................................................... 148 19.1.10 BeanShell Sampler.............................................................................. 150

Jmeter 2.3.4 Users Manual

19.1.11 BSF Sampler ....................................................................................... 152 19.1.12 TCP Sampler....................................................................................... 154 19.1.13 JMS Publisher ..................................................................................... 157 19.1.14 JMS Subscriber ................................................................................... 159 19.1.15 JMS Point-to-Point.............................................................................. 161 19.1.16 JUnit Request ...................................................................................... 164 19.1.17 Mail Reader Sampler .......................................................................... 167 19.1.18 Test Action.......................................................................................... 169 19.2 Logic Controllers ............................................................................................ 169 19.2.1 Simple Controller.................................................................................... 170 19.2.2 Loop Controller....................................................................................... 171 19.2.3 Once Only Controller.............................................................................. 172 19.2.4 Interleave Controller ............................................................................... 173 19.2.5 Random Controller.................................................................................. 175 19.2.6 Random Order Controller ....................................................................... 176 19.2.7 Throughput Controller ............................................................................ 176 19.2.8 Runtime Controller ................................................................................. 177 19.2.9 If Controller ............................................................................................ 178 19.2.10 hile Controller ..................................................................................... 179 19.2.11 Switch Controller ................................................................................ 180 19.2.12 ForEach Controller.............................................................................. 181 19.2.13 Module Controller............................................................................... 184 19.2.14 Include Controller ............................................................................... 185 19.2.15 Transaction Controller ........................................................................ 186 19.2.16 Recording Controller .......................................................................... 187 19.3 Listeners.......................................................................................................... 187 19.3.1 Sample Result Save Configuration ......................................................... 189 19.3.2 Graph Full Results .................................................................................. 190 19.3.3 Graph Results.......................................................................................... 190 19.3.4 Spline Visualizer..................................................................................... 192 19.3.5 Assertion Results .................................................................................... 192 19.3.6 View Results Tree................................................................................... 193 19.3.7 Aggregate Report .................................................................................... 196 19.3.8 View Results in Table............................................................................. 198 19.3.9 Simple Data Writer ................................................................................. 199 19.3.10 Monitor Results................................................................................... 200 19.3.11 Distribution Graph (alpha).................................................................. 201 19.3.12 Aggregate Graph ................................................................................. 202 19.3.13 Mailer Visualizer ................................................................................ 203 19.3.14 BeanShell Listener .............................................................................. 205 19.3.15 Summary Report ................................................................................. 206 19.3.16 Save Responses to a file...................................................................... 208 19.3.17 BSF Listener ....................................................................................... 209 19.3.18 Generate Summary Results................................................................. 211 19.4 Configuration Elements .................................................................................. 212 19.4.1 CSV Data Set Config .............................................................................. 212

Jmeter 2.3.4 Users Manual

19.4.2 FTP Request Defaults ............................................................................. 215 19.4.3 HTTP Authorization Manager ................................................................ 215 19.4.4 HTTP Cache Manager ............................................................................ 218 19.4.5 HTTP Cookie Manager........................................................................... 219 19.4.6 HTTP Request Defaults .......................................................................... 221 19.4.7 HTTP Header Manager........................................................................... 223 19.4.8 Java Request Defaults ............................................................................. 224 19.4.9 JDBC Connection Configuration............................................................ 225 19.4.10 Login Config Element......................................................................... 228 19.4.11 LDAP Request Defaults...................................................................... 228 19.4.12 LDAP Extended Request Defaults...................................................... 229 19.4.13 TCP Sampler Config........................................................................... 230 19.4.14 User Defined Variables....................................................................... 231 19.4.15 Random Variable ................................................................................ 233 19.4.16 Counter................................................................................................ 234 19.4.17 Simple Config Element....................................................................... 235 19.5 Assertions........................................................................................................ 236 19.5.1 Response Assertion................................................................................. 237 19.5.2 Duration Assertion .................................................................................. 241 19.5.3 Size Assertion ......................................................................................... 242 19.5.4 XML Assertion ....................................................................................... 242 19.5.5 BeanShell Assertion................................................................................ 243 19.5.6 MD5Hex Assertion ................................................................................. 245 19.5.7 HTML Assertion..................................................................................... 246 19.5.8 XPath Assertion ...................................................................................... 247 19.5.9 XML Schema Assertion.......................................................................... 248 19.5.10 BSF Assertion ..................................................................................... 248 19.6 Timers ............................................................................................................. 250 19.6.1 Constant Timer........................................................................................ 250 19.6.2 Gaussian Random Timer......................................................................... 251 19.6.3 Uniform Random Timer ......................................................................... 251 19.6.4 Constant Throughput Timer.................................................................... 252 19.6.5 Synchronizing Timer .............................................................................. 253 19.6.6 BeanShell Timer ..................................................................................... 254 19.7 Pre Processors ................................................................................................. 255 19.7.1 HTML Link Parser.................................................................................. 256 19.7.2 HTTP URL Re-writing Modifier ............................................................ 257 19.7.3 HTML Parameter Mask .......................................................................... 258 19.7.4 HTTP User Parameter Modifier.............................................................. 259 19.7.5 User Parameters ...................................................................................... 260 19.7.6 BeanShell PreProcessor .......................................................................... 261 19.7.7 BSF PreProcessor.................................................................................... 263 19.8 Post-Processors ............................................................................................... 264 19.8.1 Regular Expression Extractor ................................................................. 265 19.8.2 XPath Extractor....................................................................................... 267 19.8.3 Result Status Action Handler.................................................................. 269

Jmeter 2.3.4 Users Manual

19.8.4 BeanShell PostProcessor......................................................................... 270 19.8.5 BSF PostProcessor .................................................................................. 272 19.9 Miscellaneous Features................................................................................... 273 19.9.1 Test Plan.................................................................................................. 273 19.9.2 Thread Group .......................................................................................... 275 19.9.3 WorkBench ................................................................................................. 277 19.9.4 SSL Manager .............................................................................................. 278 19.9.5 HTTP Proxy Server................................................................................. 278 19.9.6 HTTP Mirror Server ............................................................................... 285 19.9.7 Property Display ..................................................................................... 286 19.9.8 Debug Sampler........................................................................................ 286 19.9.9 Debug PostProcessor .............................................................................. 287 19.10 Reports ........................................................................................................ 288 19.10.1 Report Plan.......................................................................................... 288 19.10.2 Report Table........................................................................................ 288 19.10.3 HTML Report Writer.......................................................................... 288 19.10.4 Report Page......................................................................................... 288 19.10.5 Line Graph .......................................................................................... 288 19.10.6 Bar Chart............................................................................................. 288

20.

Functions and Variables ................................................................ 289

20.1 What can functions do .................................................................................... 290 20.2 Where can functions and variables be used? .................................................. 291 20.3 How to reference variables and functions....................................................... 291 20.4 The Function Helper Dialog ........................................................................... 293 20.5 Functions......................................................................................................... 293 20.5.1 __regexFunction ..................................................................................... 293 20.5.2 __counter................................................................................................. 295 20.5.3 __threadNum........................................................................................... 295 20.5.4 __intSum ................................................................................................. 296 20.5.5 __longSum .............................................................................................. 296 20.5.6 __StringFromFile.................................................................................... 297 20.5.7 __machineName ..................................................................................... 299 20.5.8 __javaScript ............................................................................................ 299 20.5.9 __Random ............................................................................................... 300 20.5.10 __CSVRead......................................................................................... 301 20.5.11 __property ........................................................................................... 302 20.5.12 __P ...................................................................................................... 303 20.5.13 __log ................................................................................................... 303 20.5.14 __logn ................................................................................................. 304 20.5.15 __BeanShell ........................................................................................ 305 20.5.16 __split.................................................................................................. 306 20.5.17 __XPath............................................................................................... 307 20.5.18 __setProperty ...................................................................................... 307 20.5.19 __time ................................................................................................. 308 20.5.20 __jexl................................................................................................... 308

Jmeter 2.3.4 Users Manual

20.5.21 __V...................................................................................................... 309 20.5.22 __evalVar............................................................................................ 310 20.5.23 __eval.................................................................................................. 310 20.5.24 __char.................................................................................................. 311 20.5.25 __unescape.......................................................................................... 311 20.5.26 __unescapeHtml.................................................................................. 312 20.5.27 __escapeHtml...................................................................................... 312 20.6 Pre-defined Variables...................................................................................... 313 20.7 Pre-defined Properties..................................................................................... 313

21.
21.1 21.2 21.3 21.4 21.5 21.6

Regular Expressions....................................................................... 314

Overview......................................................................................................... 314 Examples......................................................................................................... 314 Line mode ....................................................................................................... 315 Meta characters ............................................................................................... 316 Placement of modifiers ................................................................................... 316 Testing Regular Expressions........................................................................... 317

22.

Glossary ........................................................................................... 318

. Introduction

Jmeter 2.3.4 Users Manual

1. Introduction
Apache JMeter is a 100% pure Java desktop application designed to load test client/server software (such as a web application ). It may be used to test performance both on static and dynamic resources such as static files, Java Servlets, CGI scripts, Java objects, databases , FTP servers , and more. JMeter can be used to simulate a heavy load on a server, network or object to test its strength or to analyze overall performance under different load types. Additionally, JMeter can help you regression test your application by letting you create test scripts with assertions to validate that your application is returning the results you expect. For maximum flexibility, JMeter lets you create these assertions using regular expressions. 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 loadtesting capabilities.

Jmeter 2.3.4 Users Manual

2. Getting Started
The easiest way to begin using JMeter is to first download the latest production release and install it. The release contains all of the files you need to build and run most types of tests, e.g. Web (HTTP/HTTPS), FTP, JDBC, LDAP, Java, and JUnit. If you want to perform JDBC testing, then you will, of course, need the appropriate JDBC driver from your vendor. JMeter does not come with any JDBC drivers. 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

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.

10

Jmeter 2.3.4 Users Manual

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, 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 POP3(S)/IMAP(S) 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

11

Jmeter 2.3.4 Users Manual

version of Java does not include SSL support, then it is possible to add an external implementation. Include the necessary encryption packages in JMeter's classpath . Also, update system.properties to register the SSL Provider. JMeter defaults to protocol level TLS. This can be changed by editting the JMeter property "https.default.protocol" in jmeter.properties or user.properties. 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 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

We recommend that most users run the latest release . To install a release build, simply unzip the zip/tar file into the directory where you want JMeter to be installed. Provided that you have a JRE/JDK correctly installed and the JAVA_HOME environment variable set, there is nothing more for you to do. Note: there can be problems (especially with client-server mode) if the directory path contains any spaces. The installation directory structure should look something like this (for version 2.3.1):

12

Jmeter 2.3.4 Users Manual

jakarta-jmeter-2.3.1 jakarta-jmeter-2.3.1/bin jakarta-jmeter-2.3.1/docs jakarta-jmeter-2.3.1/extras jakarta-jmeter-2.3.1/lib/ jakarta-jmeter-2.3.1/lib/ext jakarta-jmeter-2.3.1/lib/junit jakarta-jmeter-2.3.1/printable_docs

You can rename the parent directory (i.e. jakarta-jmeter-2.3.1) if you want, but do not change any of the sub-directory names.

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-nr.cmd and means the last test plan that was run interactively. The environment variable JVM_ARGS can be used to override JVM settings in the jmeter.bat script. For example:
set JVM_ARGS="-Xms1024m -Xmx1024m -Dpropname=propvalue" jmeter -t test.jmx ...

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

jmeter - run JMeter (in GUI mode by default). Defines some JVM settings which may not work for all JVMs. jmeter-server - start JMeter in server mode (calls jmeter script with appropriate parameters) jmeter.sh - very basic JMeter script with no JVM options specified.

It may be necessary to edit the jmeter shell script if some of the JVM options are not supported. The JVM_ARGS environment variable can be used to override or set additional JVM options, for example:
JVM_ARGS="-Xms1024m -Xmx1024m" jmeter -t test.jmx [etc.]

13

Jmeter 2.3.4 Users Manual

will override the HEAP settings in the script.

2.4.1 JMeter's Classpath

JMeter automatically finds classes from jars in the following directories:

JMETER_HOME/lib - used for utility jars JMETER_HOME/lib/ext - used for JMeter components and add-ons

If you have developed new JMeter components, then you should jar them and copy the jar into JMeter's lib/ext directory. JMeter will automatically find JMeter components in any jars found here. Support jars (libraries etc) should be placed in the lib directory. If you don't want to put JMeter extension jars in the lib/ext directory, then define the property search_paths in jmeter.properties. Do not use lib/ext for utility jars; it is only intended for JMeter components. Other jars (such as JDBC, JavaMail 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

14

Jmeter 2.3.4 Users Manual

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

Jmeter 2.3.4 Users Manual

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 misspell variable or function; instead the reference is just used as is. See Functions and Variables for more information . If JMeter detects an error during a test, a message will be written to the log file. The log file name is defined in the jmeter.properties file (or using the -j option, see below). It

16

Jmeter 2.3.4 Users Manual

defaults to jmeter.log , and will be found in the directory from which JMeter was launched. JMeter versions after 2.2 added a new command-line option, -j jmeterlogfile. This is processed after the initial properties file is read, and before any further properties are processed. It therefore allows the default of jmeter.log to be overridden. The jmeter scripts that take a test plan name as a parameter (e.g. jmeter-n.cmd) have been updated to define the log file using the test plan name, e.g. for the test plan Test27.jmx the log file is set to Test27.log. When running on Windows, the file may appear as just jmeter unless you have set Windows to show file extensions. [Which you should do anyway, to make it easier to detect viruses and other nasties that pretend to be text files...] As well as recording errors, the jmeter.log file records some information about the test run. For example:
10/17/2003 12:19:20 PM INFO 10/17/2003 12:19:45 PM INFO 10/17/2003 12:19:52 PM INFO 10/17/2003 12:19:52 PM INFO group BSH. Ramp up = 1. 10/17/2003 12:19:52 PM INFO 10/17/2003 12:19:52 PM INFO 10/17/2003 12:19:52 PM INFO 10/17/2003 12:19:52 PM INFO - jmeter.JMeter: Version 1.9.20031002 - jmeter.gui.action.Load: Loading file: c:\mytestfiles\BSH.jmx - jmeter.engine.StandardJMeterEngine: Running the test! - jmeter.engine.StandardJMeterEngine: Starting 1 threads for - jmeter.engine.StandardJMeterEngine: Continue on error - jmeter.threads.JMeterThread: Thread BSH1-1 started - jmeter.threads.JMeterThread: Thread BSH1-1 is done - 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

17

Jmeter 2.3.4 Users Manual

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.

18

Jmeter 2.3.4 Users Manual

Parameters Attribute ssl.provider xml.parser Description

You can specify the class for your SSL implementation if you don't want to use the built-in Java implementation. You can specify an implementation as your XML parser. The default value is: org.apache.xerces.parsers.SAXParser

Required No No

remote_hosts

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

not_in_menu

search_paths user.classpath user.properties system.properties

No No No No

The command line options and properties files are processed in the following order:

-p propfile jmeter.properties (or the file from the -p option) is then loaded -j logfile Logging is initialised user.properties is loaded system.properties is loaded all other command-line options are processed

See also the comments in the jmeter.properties, user.properties and system.properties files for further information on other settings you can change.

19

Jmeter 2.3.4 Users Manual

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

20

Jmeter 2.3.4 Users Manual

the elements located in a particular "branch" of the Test Plan tree, select the Test Plan element in the tree from which to start the "branch", and then click your right mouse button to access the Save As menu item. Alternatively, select the appropriate Test Plan element and then select Save As from the Edit menu.

3.5

Running a Test Plan

To run your test plan, choose "Start" (Control + r) from the "Run" menu item. When JMeter is running, it shows a small green box at the right hand end of the section just under the menu bar. You can also check the "Run" menu. If "Start" is disabled, and "Stop" is enabled, then JMeter is running your test plan (or, at least, it thinks it is). The numbers to the left of the green box are the number of active threads / total number of threads.

3.6

Stopping a Test

There are two types of stop command available from the menu:

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

Versions of JMeter after 2.3.2 allow a Stop to be initiated if Shutdown is taking too long. Close the Shutdown dialog box and select Run/Stop, or just press Control + '.'. When running JMeter in non-GUI mode, there is no Menu, and JMeter does not react to keystrokes such as Control + '.'. So in versions after 2.3.2, JMeter non-GUI mode will listen for commands on a specific port (default 4445, see the JMeter property jmeterengine.nongui.port ). The commands currently supported are:

Shutdown - graceful shutdown StopTestNow - immediate shutdown

These commands can be sent by using the shutdown[.cmd|.sh] or stoptest[.cmd|.sh] script respectively. The scripts are to be found in the JMeter bin directory.

21

Jmeter 2.3.4 Users Manual

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.

22

Jmeter 2.3.4 Users Manual

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 stresstesting (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 23

Jmeter 2.3.4 Users Manual

of the run. When the test is started, JMeter will wait if necessary until the start-time has been reached. At the end of each cycle, JMeter checks if the end-time has been reached, and if so, the run is stopped, otherwise the test is allowed to continue until the iteration limit is reached. Alternatively, one can use the relative delay and duration fields. Note that delay overrides start-time, and duration over-rides end-time.

4.2

Controllers

JMeter has two types of Controllers: Samplers and Logical Controllers. These drive the processing of a test. Samplers tell JMeter to send requests to a server. For example, add an HTTP Request Sampler if you want JMeter to send an HTTP request. You can also customize a request by adding one or more Configuration Elements to a Sampler. For more information, see Samplers . Logical Controllers let you customize the logic that JMeter uses to decide when to send requests. For example, you can add an Interleave Logic Controller to alternate between two HTTP Request Samplers. For more information, see Logical Controllers .

4.2.1 Samplers
Samplers tell JMeter to send requests to a server and wait for a response. They are processed in the order they appear in the tree. Controllers can be used to modify the number of repetitions of a sampler. 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).

24

Jmeter 2.3.4 Users Manual

Remember to add a Listener to your test plan to view and/or store the results of your requests to disk. If you are interested in having JMeter perform basic validation on the response of your request, add an Assertion to the sampler. For example, in stress testing a web application, the server may return a successful "HTTP Response" code, but the page may have errors on it or may be missing sections. You could add assertions to check for certain HTML tags, common error strings, and so on. JMeter lets you create these assertions using regular expressions. 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, causing JMeter to repeat requests, etc. To understand the effect of Logic Controllers on a test plan, consider the following test tree:

Test Plan o Thread Group Once Only Controller Login Request (an HTTP Request ) Load Search Page (HTTP Sampler) Interleave Controller Search "A" (HTTP Sampler) Search "B" (HTTP Sampler) HTTP default request (Configuration Element) HTTP default request (Configuration Element) Cookie Manager (Configuration Element)

The first thing about this test is that the login request will be executed only the first time through. Subsequent iterations will skip it. This is due to the effects of the Once Only Controller . After the login, the next Sampler loads the search page (imagine a web application where the user logs in, and then goes to a search page to do a search). This is just a simple request, not filtered through any Logic Controller. After loading the search page, we want to do a search. Actually, we want to do two different searches. However, we want to re-load the search page itself between each search. We could do this by having 4 simple HTTP request elements (load search, search "A", load search, search "B"). Instead, we use the Interleave Controller which passes on

25

Jmeter 2.3.4 Users Manual

one child request each time through the test. It keeps the ordering (ie - it doesn't pass one on at random, but "remembers" its place) of its child elements. Interleaving 2 child requests may be overkill, but there could easily have been 8, or 20 child requests. Note the HTTP Request Defaults that belongs to the Interleave Controller. Imagine that "Search A" and "Search B" share the same PATH info (an HTTP request specification includes domain, port, method, protocol, path, and arguments, plus other optional items). This makes sense - both are search requests, hitting the same back-end search engine (a servlet or cgi-script, let's say). Rather than configure both HTTP Samplers with the same information in their PATH field, we can abstract that information out to a single Configuration Element. When the Interleave Controller "passes on" requests from "Search A" or "Search B", it will fill in the blanks with values from the HTTP default request Configuration Element. So, we leave the PATH field blank for those requests, and put that information into the Configuration Element. In this case, this is a minor benefit at best, but it demonstrates the feature. The next element in the tree is another HTTP default request, this time added to the Thread Group itself. The Thread Group has a built-in Logic Controller, and thus, it uses this Configuration Element exactly as described above. It fills in the blanks of any Request that passes through. It is extremely useful in web testing to leave the DOMAIN field blank in all your HTTP Sampler elements, and instead, put that information into an HTTP default request element, added to the Thread Group. By doing so, you can test your application on a different server simply by changing one field in your Test Plan. Otherwise, you'd have to edit each and every Sampler. The last element is a HTTP Cookie Manager . A Cookie Manager should be added to all web tests - otherwise JMeter will ignore cookies. By adding it at the Thread Group level, we ensure that all HTTP requests will share the same cookies. Logic Controllers can be combined to achieve various results. See the list of built-in Logic Controllers .

4.3

Listeners

Listeners provide access to the information JMeter gathers about the test cases while JMeter runs. The Graph Results listener plots the response times on a graph. The "View Results Tree" Listener shows details of sampler requests and responses, and can display basic HTML and XML representations of the response. Other listeners provide summary or aggregation information. Additionally, listeners can direct the data to a file for later use. Every listener in JMeter provides a field to indicate the file to store data to. There is also a Configuration button which can be used to choose which fields to save, and whether to use CSV or XML format. Note that all Listeners save the same data; the only difference is in the way the data is presented on the screen.

26

Jmeter 2.3.4 Users Manual

Listeners can be added anywhere in the test, including directly under the test plan. They will collect data only from elements at or below their level. 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 or modify requests.

27

Jmeter 2.3.4 Users Manual

A configuration element is accessible from only inside the tree branch where you place the element. For example, if you place an HTTP Cookie Manager inside a Simple Logic Controller, the Cookie Manager will only be accessible to HTTP Request Controllers you place inside the Simple Logic Controller (see figure 1). The Cookie Manager is accessible to the HTTP requests "Web Page 1" and "Web Page 2", but not "Web Page 3". Also, a configuration element inside a tree branch has higher precedence than the same element in a "parent" branch. For example, we defined two HTTP Request Defaults elements, "Web Defaults 1" and "Web Defaults 2". Since we placed "Web Defaults 1" inside a Loop Controller, only "Web Page 2" can access it. The other HTTP requests will use "Web Defaults 2", since we placed it in the Thread Group (the "parent" of all other branches).

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 PreProcessor 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 PostProcessor 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. 28

Jmeter 2.3.4 Users Manual

4.9
1. 2. 3. 4. 5. 6. 7.

Execution order
Configuration elements Pre-Processors Timers Sampler Post-Processors (unless SampleResult is null) Assertions (unless SampleResult is null) Listeners (unless SampleResult is null)

Please note that Timers, Assertions, Pre- and Post-Processors are only processed if there is a sampler to which they apply. Logic Controllers and Samplers are processed in the order in which they appear in the tree. Other test elements are processed according to the scope in which they are found, and the type of test element. [Within a type, elements are processed in the order in which they appear in the tree]. For example, in the following test plan:

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

The order of execution would be:

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

29

Jmeter 2.3.4 Users Manual

4.10 Scoping Rules

The JMeter test tree contains elements that are both hierarchical and ordered. Some elements in the test trees are strictly hierarchical (Listeners, Config Elements, PostProcesors, 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:

30

Jmeter 2.3.4 Users Manual

complex example

In this example, the requests are named to reflect the order in which they will be executed. Timer #1 will apply to Requests Two, Three, and Four (notice how order is irrelevant for hierarchical elements). Assertion #1 will apply only to Request Three. Timer #2 will affect all the requests. Hopefully these examples make it clear how configuration (hierarchical) elements are applied. If you imagine each Request being passed up the tree branches, to its parent, then to its parent's parent, etc, and each time collecting all the configuration elements of that parent, then you will see how it works. The Configuration elements Header Manager, Cookie Manager and Authorization manager are treated differently from the Configuration Default elements. The settings from the Configuration Default elements are merged into a set of values that the Sampler has access to. However, the settings from the Managers are not merged. If more than one Manager is in the scope of a Sampler, only one Manager is used, but there is currently no way to specify which is used.

4.11 Properties and Variables

JMeter properties are defined in jmeter.properties (see Gettting Started - Configuring JMeter for more details). Properties are global to jmeter, and are mostly used to define some of the defaults JMeter uses. For example the property remote_hosts defines the servers that JMeter will try to run remotely. Properties can be referenced in test plans - see Functions - read a property but cannot be used for thread-specific values. JMeter variables are local to each thread. The values may be the same for each thread, or they may be different.

31

Jmeter 2.3.4 Users Manual

If a variable is updated by a thread, only the thread copy of the variable is changed. For example the Regular Expression Extractor Post-Processor will set its variables according to the sample that its thread has read, and these can be used later by the same thread. For details of how to reference variables and functions, see Functions and Variables Note that the values defined by the Test Plan and the User Defined Variables configuration element are made available to the whole test plan at startup. If the same variable is defined by multiple UDV elements, then the last one takes effect. Once a thread has started, the initial set of variables is copied to each thread. Other elements such as the User Parameters Pre-Processor or Regular Expression Extractor Post-Processor may be used to redefine the same variables (or create new ones). These redefinitions only apply to the current thread. The setProperty function can be used to define a JMeter property. These are global to the test plan, so can be used to pass information between threads - should that be needed. Both variables and properties are case-sensitive.

4.12 Using Variables to parameterize tests

Variables don't have to vary - they can be defined once, and if left alone, will not change value. So you can use them as short-hand for expressions that appear frequently in a test plan, or for items which are constant during a run, but which may vary between runs, for example, the name of a host, or the number of threads in a thread group. When deciding how to structure a Test Plan, make a note of which items are constant for the run, but which may change between runs. Decide on some variable names for these perhaps use a naming convention such as prefixing them with C_ or K_ or using uppercase only to distinguish them from variables that need to change during the test. Also consider which items need to be local to a thread - for example counters or values extracted with the Regular Expression Post-Processor. You may wish to use a different naming convention for these. For example, you might define the following on the Test Plan:
HOST THREADS LOOPS www.example.com 10 20

You can refer to these in the test plan as ${HOST} ${THREADS} etc. If you later want to change the host, just change the value of the HOST variable. This works fine for small numbers of tests, but becomes tedious when testing lots of different combinations. One solution is to use a property to define the value of the variables, for example:
HOST ${__P(host,www.example.com)}

32

Jmeter 2.3.4 Users Manual

THREADS LOOPS

${__P(threads,10)} ${__P(loops,20)}

You can then change some or all of the values on the command-line as follows:
jmeter ... -Jhost=www3.example.org -Jloops=13

33

Jmeter 2.3.4 Users Manual

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

34

Jmeter 2.3.4 Users Manual

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

35

Jmeter 2.3.4 Users Manual

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.

36

Jmeter 2.3.4 Users Manual

The HTTP Request Defaults element does not tell JMeter to send an HTTP request. It simply defines the default values that the HTTP Request elements use. See Figure 5.4 for the completed HTTP Request Defaults element

Figure 5.4. HTTP Defaults for our Test Plan

5.3

Adding Cookie Support

Nearly all web testing should use cookie support, unless your application specifically doesn't use cookies. To add cookie support, simply add an HTTP Cookie Manager to each Thread Group in your test plan. This will ensure that each thread gets its own cookies, but shared across all HTTP Request objects. To add the HTTP Cookie Manager , simply select the Thread Group , and choose Add --> Config Element --> HTTP Cookie Manager, either from the Edit Menu, or from the rightclick pop-up menu.

37

Jmeter 2.3.4 Users Manual

5.4

Adding HTTP Requests

In our Test Plan, we need to make two HTTP requests. The first one is for the Jakarta home page (http://jakarta.apache.org/), and the second one is for the Project Guidelines page (http://jakarta.apache.org/site/guidelines.html). JMeter sends requests in the order that they appear in the tree. Start by adding the first HTTP Request to the Jakarta Users element (Add --> Sampler -> HTTP Request). Then, select the HTTP Request element in the tree and edit the following properties (see Figure 5.5): 1. Change the Name field to "Home Page". 2. Set the Path field to "/". Remember that you do not have to set the Server Name field because you already specified this value in the HTTP Request Defaults element.

38

Jmeter 2.3.4 Users Manual

Figure 5. Figure 5.5. HTTP Request for Jakarta Home Page

Next, add the second HTTP Request and edit the following properties (see Figure 5.6: 1. Change the Name field to "Project Guidelines". 2. Set the Path field to "/site/guidelines.html".

39

Jmeter 2.3.4 Users Manual

Figure 5.6. HTTP Request for Jakarta Project Guidelines Page

5.5

Adding a Listener to View Store the Test Results

The final element you need to add to your Test Plan is a Listener . This element is responsible for storing all of the results of your HTTP requests in a file and presenting a visual model of the data. Select the Jakarta Users element and add a Graph Results listener (Add --> Listener --> Graph Results). Next, you need to specify a directory and filename of the output file. You can either type it into the filename field, or select the Browse button and browse to a directory and then enter a filename.

40

Jmeter 2.3.4 Users Manual

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.

41

Jmeter 2.3.4 Users Manual

Figure 5.8. Sample HTTP login request

42

Jmeter 2.3.4 Users Manual

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

43

Jmeter 2.3.4 Users Manual

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.

44

Jmeter 2.3.4 Users Manual

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

45

Jmeter 2.3.4 Users Manual

Start by providing a more descriptive name for our Thread Group. In the name field, enter JDBC Users. You will need a valid database, database table, and user-level access to that table. In the example shown here, the database is 'mydb' and the table name is 'Stocks'. Next, increase the number of users to 10. In the next field, the Ramp-Up Period, leave the default value of 0 seconds. This property tells JMeter how long to delay between starting each user. For example, if you enter a Ramp-Up Period of 5 seconds, JMeter will finish starting all of your users by the end of the 5 seconds. So, if we have 5 users and a 5 second Ramp-Up Period, then the delay between starting users would be 1 second (5 users / 5 seconds = 1 user per second). If you set the value to 0, then JMeter will immediately start all of your users. Finally, enter a value of 3 in the Loop Count field. This property tells JMeter how many times to repeat your test. To have JMeter repeatedly run your Test Plan, select the Forever checkbox. In most applications, you have to manually accept changes you make in a Control Panel. However, in JMeter, the Control Panel automatically accepts your changes as you make them. If you change the name of an element, the tree will be updated with the new text after you leave the Control Panel (for example, when selecting another tree element). See Figure 7.2 for the completed JDBC Users Thread Group.

Figure 7.2. JDBC Users Thread Group

46

Jmeter 2.3.4 Users Manual

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.

47

Jmeter 2.3.4 Users Manual

Figure 7.3. JDBC Configuration

Select the JDBC Users element again. Click your right mouse button to get the Add menu, and then select Add --> Sampler --> JDBC Request. Then, select this new element to view its Control Panel (see Figure 7.4).

48

Jmeter 2.3.4 Users Manual

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.

49

Jmeter 2.3.4 Users Manual

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

50

Jmeter 2.3.4 Users Manual

Figure 7.7. Graph results Listener

51

Jmeter 2.3.4 Users Manual

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

52

Jmeter 2.3.4 Users Manual

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

53

Jmeter 2.3.4 Users Manual

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.

54

Jmeter 2.3.4 Users Manual

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. 2. 3. 4. Change the Name to "README". Change the File to Retrieve From Server field to "pub/msql/java/README". Change the Username field to "anonymous". 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.

55

Jmeter 2.3.4 Users Manual

Figure 8.5. FTP Request for O'Reilly mSQL Java README file

Next, add the second FTP Request and edit the following properties (see Figure 8.6: 1. 2. 3. 4. Change the Name to "tutorial". Change the File to Retrieve From Server field to "pub/msql/java/tutorial.txt". Change the Username field to "anonymous". Change the Password field to "anonymous".

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

56

Jmeter 2.3.4 Users Manual

8.4

Adding a Listener to View/Store the Test Results

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

Figure 8.7. Spline Visualizer Listener

57

Jmeter 2.3.4 Users Manual

9. Building an LDAP Test Plan

In this section, you will learn how to create a basic Test Plan to test an LDAP server. You will create four users that send requests for four tests on the LDAP server.Also, you will tell the users to run their tests twice. So, the total number of requests is (4 users) x (4 requests) x repeat 2 times) = 32 LDAP requests. To construct the Test Plan, you will use the following elements: Thread Group , LDAP Request , LDAP Request Defaults , and View Results in Table . This example assumes that the LDAP Server is installed in your Local machine.

9.1

Adding Users

The first step you want to do with every JMeter Test Plan is to add a Thread Group element. The Thread Group tells JMeter the number of users you want to simulate, how often the users should send requests, and the how many requests they should send. Go ahead and add the ThreadGroup element by first selecting the Test Plan, clicking your right mouse button to get the Add menu, and then select Add-->ThreadGroup. You should now see the Thread Group element under Test Plan. If you do not see the element, then "expand" the Test Plan tree by clicking on the Test Plan element.

Figure 9a.1. Thread Group with Default Values

9.2

Adding Login Config Element

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

58

Jmeter 2.3.4 Users Manual

Like most JMeter elements, the Login Config Element Control Panel has a name field that you can modify. In this example, leave this field with the default value.

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

Enter Username field to "your Server Username", The password field to "your Server Passowrd" These values are default for the LDAP Requests.

9.3

Adding LDAP Request Defaults

Begin by selecting the Siptech Users element. Click your right mouse button to get the Add menu, and then select Add --> Config Element -->LDAP Request Defaults. Then, select this new element to view its Control Panel. Like most JMeter elements, the LDAP Request Defaults Control Panel has a name field that you can modify. In this example, leave this field with the default value.

59

Jmeter 2.3.4 Users Manual

Figure 9a.3 LDAP Defaults for our Test Plan

Enter DN field to "your Server Root Dn". Enter LDAP Server's Servername field to "localhost". The port to 389. These values are default for the LDAP Requests.

9.4

Adding LDAP Requests

In our Test Plan, we need to make four LDAP requests. 1. 2. 3. 4. Inbuilt Add Test Inbuilt Modify Test Inbuilt Delete Test 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

60

Jmeter 2.3.4 Users Manual

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

61

Jmeter 2.3.4 Users Manual

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

62

Jmeter 2.3.4 Users Manual

2. Select the Search test Radio button

Figure 9a.4.4 LDAP Request for Inbuilt Search test

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

63

Jmeter 2.3.4 Users Manual

10. 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 test plan. You can however tune it exactly up to your needs. You will create four users that send requests for four tests on the LDAP server. Also, you will tell the users to run their tests twice. So, the total number of requests is (4 users) x (4 requests) x repeat 2 times) = 32 LDAP requests. To construct the Test Plan, you will use the following elements: Thread Group , Adding LDAP Extended Request Defaults , Adding LDAP Requests , and Adding a Listener to View/Store the Test Results This example assumes that the LDAP Server is installed in your Local machine. For the less experienced LDAP users, I build a small LDAP tutorial which shortly explains the several LDAP operations that can be used in building a complex test plan. Take care when using LDAP special characters in the distinguished name, in that case (eg, you want to use a + sign in a distinguished name) you need to escape the character by adding a "\" sign before that character. Extra exception: if you want to add a \ character in a distinguished name (in an add or rename operation), you need to use 4 backslashes. Examples: cn=dolf\+smits to add/search an entry with the name like cn=dolf+smits cn=dolf \\ smits to search an entry with the name cn=dolf \ smits cn=c:\\\\log.txt to add an entry with a name like cn=c:\log.txt

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.

64

Jmeter 2.3.4 Users Manual

Figure 9b.1. Thread Group with Default Values

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

65

Jmeter 2.3.4 Users Manual

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!

10.3 Adding LDAP Requests

In our Test Plan, we want to use all 8 LDAP requests. 1. 2. 3. 4. 5. 6. 7. 8. 9. Thread bind Search Test Compare Test Single bind/unbind Test Add Test Modify Test Delete Test Rename entry (moddn) Thread unbind

JMeter sends requests in the order that you add them to the tree. Adding a request always start by: Adding the LDAP Extended Request to the Thread Group element (Add --> Sampler -->

66

Jmeter 2.3.4 Users Manual

LDAP Ext Request). Then, select the LDAP Ext Request element in the tree and edit the following properties.

10.3.1
1. 2. 3. 4.

Adding a Thread bind Request

Select the "Thread bind" button. enter the hostname value from the LDAP server in the Servername field Enter the portnumber from the LDAP server (389) in the port field (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

67

Jmeter 2.3.4 Users Manual

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

68

Jmeter 2.3.4 Users Manual

Figure 9b.3.2. search request example

10.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 "[email protected]"

69

Jmeter 2.3.4 Users Manual

Figure 9b.3.3. Compare example

10.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 separate operations but cannot easily be split!

70

Jmeter 2.3.4 Users Manual

Figure 9b.3.4. Single bind/unbind example

10.3.5

Adding an Add Request

1. Select the "Add" button. 2. Enter the distinguished 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.

71

Jmeter 2.3.4 Users Manual

Figure 9b.3.5. Add request example

10.3.6
1. 2. 3. 4.

Adding a Modify Request

Select the "Modify test" button. Enter the distinghuised name for the object to modify, relative to the basedn. Add a line in the "modify test" table, with the "add" button. 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) will be 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.

72

Jmeter 2.3.4 Users Manual

3. delete When no value is given, all values will be removed When a value is given, only that value will be removed when the given value is not existing, the test will fail 5. (Optional) Add more modifications in the "modify test" table. All modifications which are specified must succeed, to let the modification test pass. When one modification fails, NO modifications at all will be made and the entry will remain unchanged.

Figure 9b.3.6. Modify example

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

73

Jmeter 2.3.4 Users Manual

Figure 9b.3.7. Delete example

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

74

Jmeter 2.3.4 Users Manual

Figure 9b.3.8. Rename example

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

75

Jmeter 2.3.4 Users Manual

Figure 9b.3.9. Unbind example

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

76

Jmeter 2.3.4 Users Manual

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.

77

Jmeter 2.3.4 Users Manual

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

11.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 11.1 below)

78

Jmeter 2.3.4 Users Manual

Figure 11.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 default value of 0 seconds. This property tells JMeter how long to delay between starting each user. For example, if you enter a Ramp-Up Period of 5 seconds, JMeter will finish starting all of your users by the end of the 5 seconds. So, if we have 5 users and a 5 second Ramp-Up Period, then the delay between starting users would be 1 second (5 users / 5 seconds = 1 user per second). If you set the value to 0, then JMeter will immediately start all of your users. Finally, clear the checkbox labeled "Forever", and enter a value of 2 in the Loop Count field. This property tells JMeter how many times to repeat your test. If you enter a loop count value of 0, then JMeter will run your test only once. To have JMeter repeatedly run your Test Plan, select the Forever checkbox. In most applications, you have to manually accept changes you make in a Control Panel. However, in JMeter, the Control Panel automatically accepts your changes as you make them. If you change the name of an element, the tree will be updated with the new text after you leave the Control Panel (for example, when selecting another tree element). See Figure 11.2 for the completed Jakarta Users Thread Group.

79

Jmeter 2.3.4 Users Manual

Figure 11.2. Jakarta Users Thread Group

11.2 Adding WebService Requests

In our Test Plan, we will use a .NET web service. Since you're using the web service sampler, we won't go into the details of writing a web service. If you don't know how to write a web service, google for web service and familiarize yourself with writing web services for Java and .NET. It should be noted there is a significant difference between how .NET and Java implement web services. 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 11.5): 1. Change the Name field to "WebService(SOAP) Request (Beta Code)". 2. Enter the WSDL URL and click "Load WSDL".

80

Jmeter 2.3.4 Users Manual

81
Figure 10.3. Webservice Request

Jmeter 2.3.4 Users Manual

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.

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

82

Jmeter 2.3.4 Users Manual

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

83

Jmeter 2.3.4 Users Manual

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

12.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 12.1 below)

84

Jmeter 2.3.4 Users Manual

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

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

Jmeter 2.3.4 Users Manual

Name Value JMS Resources QueueuConnectionFactory ConnectionFactory

Description This is the default JNDI entry for the connection factory within active mq. This is equal to the JNDI name defined in the JNDI properties. This is equal to the JNDI name defined in the JNDI properties. This means that you need at least a service that responds to the requests. This is just the content of the message. Nothing needed for active mq.

JNDI Name Request Queue

Q.REQQ

JNDI Name Reply Queue Q.RPL

Message Properties Communication Style

Request Response

Content

test

JMS Properties JNDI Properties InitialContextFactory

org.activemq.jndi.ActiveMQInitialContextFactory The standard InitialContextFactory for Active MQ tcp://localhost:61616 This defines the URL of the active mq messaging system. This defines a JNDI name Q.REQ for the request queue that points to the queue example.Q.REQ. This defines a JNDI name Q.RPL for the reply queue that points to the queue example.Q.RPL.

Properties providerURL

queue.Q.REQ

example.Q.REQ

queue.Q.RPL

example.Q.RPL

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 JMS requests in a file and presenting a visual model of the data.

86

Jmeter 2.3.4 Users Manual

Select the Thread Group element and add a Graph Results listener (Add --> Listener --> Graph Results). Next, you need to specify a directory and filename of the output file. You can either type it into the filename field, or select the Browse button and browse to a directory and then enter a filename.

Figure 12.2. Graph Results Listener

87

Jmeter 2.3.4 Users Manual

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

13.1 Adding Users

The first step is adding 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 13.1 below)

88

Jmeter 2.3.4 Users Manual

Figure 13.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 RampUp Period of 5 seconds, JMeter will finish starting all of your users by the end of the 5 seconds. So, if we have 5 users and a 5 second Ramp-Up Period, then the delay between starting users would be 1 second (5 users / 5 seconds = 1 user per second). If you set the value to 0, JMeter will immediately start all users. Clear the checkbox labeled "Forever", and enter a value of 10 in the Loop Count field. This property tells JMeter how many times to repeat your test. If you enter a loop count value of 0, then JMeter will run your test only once. To have JMeter repeatedly run your Test Plan, select the Forever checkbox. Repeat the process and add another thread group. For the second thread group, enter "Publisher" in the name field, set the number of threads to 1, and set the iteration to 10. In most applications, you have to manually accept changes you make in a Control Panel. However, in JMeter, the Control Panel automatically accepts your changes as you make them. If you change the name of an element, the tree will be updated with the new text after you leave the Control Panel (for example, when selecting another tree element).

89

Jmeter 2.3.4 Users Manual

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

90

Jmeter 2.3.4 Users Manual

Figure 13.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. 2. 3. 4. 5. Change the Name field to "sample publisher". If the JMS provider uses the jndi.properties file, check the box Enter the name of the InitialContextFactory class. Enter the provider URL. This is the URL for the JNDI server, if there is one 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. 91

Jmeter 2.3.4 Users Manual

Figure 13.3. JMS Publisher

92

Jmeter 2.3.4 Users Manual

13.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 13.4. Graph Results Listener

93

Jmeter 2.3.4 Users Manual

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

14.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 14.1. Thread Group with Default Values

94

Jmeter 2.3.4 Users Manual

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

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

14.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. 2. 3. 4. 5. Change the Name field to "Server Status". Enter the IP address or Hostname Enter the port number Set the Path field to "/manager/status" if you're using Tomcat. 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

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

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

95

Jmeter 2.3.4 Users Manual

14.6 Adding Monitor Results

Add the Listener by selecting the test plan element (Add --> Listener -- > Monitor Results). By default, the Listener will select the results from the first connector in the sample response. The Connector prefix field can be used to select a different connector. If specified, the Listener will choose the first connector which matches the prefix. If no match is found, then the first connector is selected. There are two tabs in the monitor results listener. The first is the "Health", which displays the status of the last sample the monitor received. The second tab is "Performance", which shows a historical view of the server's performance.

A quick note about how health is calculated. Typically, a server will crash if it runs out of memory, or reached the maximum number of threads. In the case of Tomcat 5, once the threads are maxed out, requests are placed in a queue until a thread is available. The relative importance of threads vary between containers, so the current implementation uses 50/50 to be conservative. A container that is more efficient with thread management might not see any performance degradation, but the used memory definitely will show an impact.

96

Jmeter 2.3.4 Users Manual

The performance graph shows for different lines. The free memory line shows how much free memory is left in the current allocated block. Tomcat 5 returns the maximum memory, but it is not graphed. In a well tuned environment, the server should never reach the maximum memory. Note the graph has captions on both sides of the graph. On the left is percent and the right is dead/healthy. If the memory line spikes up and down rapidly, it could indicate memory thrashing. In those situations, it is a good idea to profile the application with Borland OptimizeIt or JProbe. What you want to see is a regular pattern for load, memory and threads. Any erratic behavior usually indicates poor performance or a bug of some sort.

97

Jmeter 2.3.4 Users Manual

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

15.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 nonGUI test runs). To change the default format, find the following line in jmeter.properties: jmeter.save.saveservice.output_format= The information to be saved is configurable. For maximum information, choose "xml" as the format and specify "Functional Test Mode" on the Test Plan element. If this box is not checked, the default saved data includes a time stamp (the number of milliseconds since midnight, January 1, 1970 UTC), the data type, the thread name, the label, the response time, message, and code, and a success indicator. If checked, all information, including the full response data will be logged. The following example indicates how to set properties to get a vertical bar ("|") delimited format that will output results like:.
timeStamp|time|label|responseCode|threadName|dataType|success|failureMessage 02/06/03 08:21:42|1187|Home|200|Thread Group-1|text|true| 02/06/03 08:21:42|47|Login|200|Thread Group-1|text|false|Test Failed:

98

Jmeter 2.3.4 Users Manual

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 commaseparated values. However, the default_delimiter was set to be a vertical bar instead of a comma, so the csv tag is a misnomer in this case. (Think of CSV as meaning character separated values)
jmeter.save.saveservice.output_format=csv jmeter.save.saveservice.assertion_results_failure_message=true jmeter.save.saveservice.default_delimiter=|

The full set of properties that affect result file output is shown below.
#--------------------------------------------------------------------------# Results file configuration #--------------------------------------------------------------------------# This section helps determine how result data will be saved. # The commented out values are the defaults. # legitimate values: xml, csv, db. Only xml and csv are currently supported. #jmeter.save.saveservice.output_format=xml # true when field should be saved; false otherwise # assertion_results_failure_message only affects CSV output #jmeter.save.saveservice.assertion_results_failure_message=false # #jmeter.save.saveservice.data_type=true #jmeter.save.saveservice.label=true #jmeter.save.saveservice.response_code=true # response_data is not currently supported for CSV output #jmeter.save.saveservice.response_data=false # Save ResponseData for failed samples #jmeter.save.saveservice.response_data.on_error=false #jmeter.save.saveservice.response_message=true #jmeter.save.saveservice.successful=true #jmeter.save.saveservice.thread_name=true #jmeter.save.saveservice.time=true #jmeter.save.saveservice.subresults=true #jmeter.save.saveservice.assertions=true #jmeter.save.saveservice.latency=true #jmeter.save.saveservice.samplerData=false #jmeter.save.saveservice.responseHeaders=false #jmeter.save.saveservice.requestHeaders=false #jmeter.save.saveservice.encoding=false #jmeter.save.saveservice.bytes=true #jmeter.save.saveservice.url=false

99

Jmeter 2.3.4 Users Manual

#jmeter.save.saveservice.filename=false #jmeter.save.saveservice.hostname=false #jmeter.save.saveservice.thread_counts=false #jmeter.save.saveservice.sample_count=false # Timestamp format # legitimate values: none, ms, or a format suitable for SimpleDateFormat #jmeter.save.saveservice.timestamp_format=ms #jmeter.save.saveservice.timestamp_format=MM/dd/yy HH:mm:ss # Put the start time stamp in logs instead of the end sampleresult.timestamp.start=true # legitimate values: none, first, all #jmeter.save.saveservice.assertion_results=none # For use with Comma-separated value (CSV) files or other formats # where the fields' values are separated by specified delimiters. # Default: #jmeter.save.saveservice.default_delimiter=, # For TAB, since JMeter 2.3 one can use: #jmeter.save.saveservice.default_delimiter=\t #jmeter.save.saveservice.print_field_names=false # Optional list of JMeter variable names whose values are to be saved in the result data files. # Use commas to separate the names. For example: #sample_variables=SESSION_ID,REFERENCE # N.B. The current implementation saves the values in XML as attributes, # so the names must be valid XML names. # Versions of JMeter after 2.3.2 send the variable to all servers # to ensure that the correct data is available at the client. # Optional xml processing instruction for line 2 of the file: #jmeter.save.saveservice.xml_pi=<?xml-stylesheet type="text/xsl" href="sample.xsl"?>

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

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

100

Jmeter 2.3.4 Users Manual

15.1.2

Sample Result Save Configuration

Listeners can be configured to save different items to the result log files (JTL) by using the Config popup as shown below. The defaults are defined as described in the Listener Default Configuration section above. Items with (CSV) after the name only apply to the CSV format; items with (XML) only apply to XML format. CSV format cannot currently be used to save any items that include line-breaks.

Configuration dialogue

Note that cookies, method and the query string are saved as part of the "Sampler Data" option.

15.2 Non-GUI (batch) test runs

When running in non-GUI mode, the -l flag can be used to create a top-level listener for the test run. This is in addition to any Listeners defined in the test plan. The configuration of this listener is controlled by entries in the file jmeter.properties as described in the previous section. This feature can be used to specify different data and log files for each test run, for example:
jmeter -n -t testplan.jmx -l testplan_01.jtl -j testplan_01.log jmeter -n -t testplan.jmx -l testplan_02.jtl -j testplan_02.log

Note that JMeter logging messages are written to the file jmeter.log by default. This file is recreated each time, so if you want to keep the log files for each run, you will need to rename it using the -j option as above. The -j option was added in version 2.3.

101

Jmeter 2.3.4 Users Manual

Versions of JMeter after 2.3.1 support variables in the log file name. If the filename contains paired single-quotes, then the name is processed as a SimpleDateFormat format applied to the current date, for example: log_file='jmeter_'yyyyMMddHHmmss'.tmp' . This can be used to generate a unique name for each test run.

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

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

102

Jmeter 2.3.4 Users Manual

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

15.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 OK Date: Fri, 07 Apr 2006 00:50:14 GMT ... Content-Type: text/css </responseHeader> <requestHeader class="java.lang.String">MyHeader: MyValue</requestHeader> <responseData class="java.lang.String">body, td, th {

103

Jmeter 2.3.4 Users Manual

font-size: 95%; font-family: Arial, Geneva, Helvetica, sans-serif; color: black; background-color: white; } ... </responseData> <cookies class="java.lang.String"></cookies> <method class="java.lang.String">GET</method> <queryString class="java.lang.String"></queryString> <url>http://www.apache.org/style/style.css</url> </httpSample> <httpSample t="200" lt="180" ts="1144371015641" s="true" lb="http://www.apache.org/images/asf_logo_wide.gif" rc="200" rm="OK" tn="Listen 1-1" dt="bin" de="ISO-8859-1" by="5866"> <responseHeader class="java.lang.String">HTTP/1.1 200 OK Date: Fri, 07 Apr 2006 00:50:14 GMT ... Content-Type: image/gif </responseHeader> <requestHeader class="java.lang.String">MyHeader: MyValue</requestHeader> <responseData class="java.lang.String">http://www.apache.org/asf.gif</responseData> <responseFile class="java.lang.String">Mixed1.html</responseFile> <cookies class="java.lang.String"></cookies> <method class="java.lang.String">GET</method> <queryString class="java.lang.String"></queryString> <url>http://www.apache.org/asf.gif</url> </httpSample> <responseHeader class="java.lang.String">HTTP/1.1 200 OK Date: Fri, 07 Apr 2006 00:50:13 GMT ... Content-Type: text/html; charset=ISO-8859-1 </responseHeader> <requestHeader class="java.lang.String">MyHeader: MyValue</requestHeader> <responseData class="java.lang.String"> ... &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>

104

Jmeter 2.3.4 Users Manual

<requestHeader class="java.lang.String"></requestHeader> <responseData class="java.lang.String">Listen 1-1</responseData> <responseFile class="java.lang.String">Mixed2.unknown</responseFile> <samplerData class="java.lang.String">ssssss</samplerData> </sample> </testResults>

Note that the sample node name may be either "sample" or "httpSample".

15.7 Sample Attributes

The sample attributes have the following meaning:
Attribute by de dt ec hn lb lt na ng rc rm s sc t tn ts varname Content Bytes Data encoding Data type Error count (0 or 1, unless multiple samples are aggregated) Hostname where the sample was generated Label Latency = time to initial response (milliseconds) - not all samplers support this Number of active threads for all thread groups Number of active threads in this group Response Code (e.g. 200) Response Message (e.g. OK) Success flag (true/false) Sample count (1, unless multiple samples are aggregated) Elapsed time (milliseconds) Thread Name timeStamp (milliseconds since midnight Jan 1, 1970 UTC) Value of the named variable (versions of JMeter after 2.3.1)

Versions 2.1 and 2.1.1 of JMeter saved the Response Code as "rs", but read it back expecting to find "rc". This has been corrected so that it is always saved as "rc"; either "rc" or "rs" can be read. Versions of JMeter after 2.3.1 allow additional variables to be saved with the test plan. Currently, the variables are saved as additional attributes. The testplan variable name is used as the attribute name. See Sample variables (above) for more information.

105

Jmeter 2.3.4 Users Manual

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

15.9 Loading (reading) response data

To view an existing results file, you can use the File "Browse..." button to select a file. If necessary, just create a dummy testplan with the appropriate Listener in it. Results can be read from XML or CSV format files. When reading from CSV results files, the header (if present) is used to determine which fields were saved. In order to interpret a header-less CSV file correctly, the appropriate JMeter properties must be set. Versions of JMeter up to 2.3.2 used to clear any current data before loading the new file. This is no longer done, thus allowing files to be merged. If the previous behaviour is required, use the menu item Run/Clear (Ctrl+Shift+E) or Run/Clear All (Ctrl+E) before loading the file.

15.10 Saving Listener GUI data

JMeter is capable of saving any listener as a PNG file. To do so, select the listener in the left panel. Click edit -> Save As Image. A file dialog will appear. Enter the desired name and save the listener. The Listeners which generate output as tables can also be saved using Copy/Paste. Select the desired cells in the table, and use the OS Copy short-cut (normally Control+C). The data will be saved to the clipboard, from where it can be pasted into another application, e.g. a spreadsheet or text editor.

106

Jmeter 2.3.4 Users Manual

Figure 1 - Edit -> Save As Image

107

Jmeter 2.3.4 Users Manual

16. 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 nonGUI tests independently. If many server instances are used, the client JMeter can become overloaded, as can the client network connection. Note that while you can execute the JMeterEngine on your application server, you need to be mindful of the fact that this will be adding processing overhead on the application server and thus your testing results will be somewhat tainted. The recommended approach is to have one or more machines on the same Ethernet segment as your application server that you configure to run the JMeter Engine. This will minimize the impact of the network on the test results without impacting the performance of the application serer itself. Step 1: Start the servers To run JMeter in remote node, start the JMeter server component on all machines you wish to run on by running the JMETER_HOME/bin/jmeter-server (unix) or JMETER_HOME/bin/jmeter-server.bat (windows) script. Note that there can only be one JMeter server on each node unless different RMI ports are used. Since JMeter 2.3.1, the JMeter server application starts the RMI registry itself; there is no need to start RMI registry separately. To revert to the previous behaviour, define the JMeter property server.rmi.create=false on the server host systems. By default, RMI uses a dynamic port for the JMeter server engine. This can cause problems for firewalls, so versions of JMeter after 2.3.2 will check for the JMeter property server.rmi.localport . If this is non-zero, it will be used as the local port number for the server engine. Step 2: Add the server IP to your client's Properties File

108

Jmeter 2.3.4 Users Manual

Edit the properties file on the controlling JMeter machine . In /bin/jmeter.properties, find the property named, "remote_hosts", and add the value of your running JMeter server's IP address. Multiple such servers can be added, comma-delimited. Note that you can use the -R command line option instead to specify the remote host(s) to use. This has the same effect as using -r and -Jremote_hosts={serverlist}. E.g. jmeter Rhost1,127.0.0.1,host2 If you define the JMeter property server.exitaftertest=true, then the server will exit after it runs a single test. See also the -X flag (described below) Step 3a: Start the JMeter Client from a GUI client Now you are ready to start the controlling JMeter client. For MS-Windows, start the client with the script "bin/jmeter.bat". For UNIX, use the script "bin/jmeter". You will notice that the Run menu contains two new sub-menus: "Remote Start" and "Remote Stop" (see figure 1). These menus contain the client that you set in the properties file. Use the remote start and stop instead of the normal JMeter start and stop menu items.

Figure 1 - Run Menu

Step 3b: Start the JMeter from a non-GUI Client As an alternative, you can start the remote server(s) from a non-GUI (command-line) client. The command to do this is:
jmeter -n -t script.jmx -r or jmeter -n -t script.jmx -R server1,server2... Other flags that may be useful: -Gproperty=value - define a property in all the servers (may appear more than once) -Z - Exit remote servers at the end of the test.

The first example will start whatever servers are defined in the JMeter property remote_hosts; the second example will define remote_hosts from the list of servers and then run the remote servers. The command-line client will exit when all the remote servers have stopped. 109

Jmeter 2.3.4 Users Manual

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

16.2 Tips
JMeter/RMI requires a connection from the client to the server. This will use the port you chose, default 1099. JMeter/RMI also requires a reverse connection in order to return sample results from the server to the client. This will use a high-numbered port. If there are any firewalls or other network filters between JMeter client and server, you will need to make sure that they are set up to allow the connections through. If necessary, use monitoring software to show what traffic is being generated. If you're running Suse Linux, these tips may help. The default installation may enable the firewall. In that case, remote testing will not work properly. The following tips were contributed by Sergey Ten. If you see connections refused, turn on debugging by passing the following options.

110

Jmeter 2.3.4 Users Manual

Since JMeter 2.3.1, the RMI registry is started by the server; however the options can still be passed in from the JMeter command line. For example: "jmeter -s Dsun.rmi.loader.logLevel=verbose" (i.e. omit the -J prefixes). Alternatively the properties can be defined in the system.properties file. The solution to the problem is to remove the loopbacks 127.0.0.1 and 127.0.0.2 from etc/hosts. What happens is jmeter-server can't connect to rmiregistry if 127.0.0.2 loopback is not available. Use the following settings to fix the problem. Replace

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

16.3 Using a different port

By default, JMeter uses the standard RMI port 1099. It is possible to change this. For this to work successfully, all the following need to agree:

On the server, start rmiregistry using the new port number On the server, start JMeter with the property server_port defined On the client, update the remote_hosts property to include the new remote host:port settings

Since Jmeter 2.1.1, the jmeter-server scripts provide support for changing the port. For example, assume you want to use port 1664 (perhaps 1099 is already used).
On Windows (in a DOS box) C:\JMETER> SET SERVER_PORT=1664 C:\JMETER> JMETER-SERVER [other options] On Unix: $ SERVER_PORT=1664 jmeter-server [other options] [N.B. use upper case for the environment variable]

In both cases, the script starts rmiregistry on the specified port, and then starts JMeter in server mode, having defined the "server_port" property.

111

Jmeter 2.3.4 Users Manual

The chosen port will be logged in the server jmeter.log file (rmiregistry does not create a log file).

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

1. 2.

num_sample_threshold - number of samples in a batch (default 100) time_threshold - number of milliseconds to wait (default 60 seconds)

112

Jmeter 2.3.4 Users Manual

17. Best Practices

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

17.2 Where to Put the Cookie Manager

See Building a Web Test for information.

17.3 Where to Put the Authorization Manager

See Building an Advanced Web Test for information.

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

113

Jmeter 2.3.4 Users Manual

the Test Plan level or in User Defined Variables elements, you can have JMeter automatically replace values in you recorded samples. For instance, if you are testing an app on server "xxx.example.com", then you can define a variable called "server" with the value of "xxx.example.com", and anyplace that value is found in your recorded samples will be replaced with "${server}". Please note that matching is case-sensitive. If JMeter does not record any samples, check that the brower really is using the proxy. If the browser works OK even if JMeter is not running, then the browser cannot be using the proxy. Some browsers ignore proxy settings for localhost or 127.0.0.1; try using the local hostname or IP instead.

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

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

114

Jmeter 2.3.4 Users Manual

If your test needs large amounts of data - particularly if it needs to be randomised - create the test data in a file that can be read with CSV Dataset. This avoids wasting resources at run-time.

17.7 BeanShell server

The BeanShell interpreter has a very useful feature - it can act as a server, which is accessible by telnet or http. There is no security. Anyone who can connect to the port can issue any BeanShell commands. These can provide unrestricted access to the JMeter application and the host. Do not enable the server unless the ports are protected against access, e.g. by a firewall. If you do wish to use the server, define the following in jmeter.properties:
beanshell.server.port=9000 beanshell.server.file=../extras/startup.bsh

In the above example, the server will be started, and will listen on ports 9000 and 9001. Port 9000 will be used for http access. Port 9001 will be used for telnet access. The startup.bsh file will be processed by the server, and can be used to define various functions and set up variables. The startup file defines methods for setting and printing JMeter and system properties. This is what you should see in the JMeter console:
Startup script running Startup script completed Httpd started on port: 9000 Sessiond started on port: 9001

As a practical example, assume you have a long-running JMeter test running in non-GUI mode, and you want to vary the throughput at various times during the test. The test-plan includes a Constant Throughput Timer which is defined in terms of a property, e.g. ${__P(throughput)}. The following BeanShell commands could be used to change the test:
printprop("throughput"); curr=Integer.decode(args[0]); // Start value inc=Integer.decode(args[1]); // Increment end=Integer.decode(args[2]); // Final value secs=Integer.decode(args[3]); // Wait between changes while(curr <= end){ setprop("throughput",curr.toString()); // Needs to be a string here Thread.sleep(secs*1000);

115

Jmeter 2.3.4 Users Manual

curr += inc; } printprop("throughput");

The script can be stored in a file (throughput.bsh, say), and sent to the server using bshclient.jar. For example:
java -jar ../lib/bshclient.jar localhost 9000 throughput.bsh 70 5 100 60

17.8 BeanShell scripting

17.8.1 Overview

Each BeanShell test element has its own copy of the interpreter (for each thread). If the test element is repeatedly called, e.g. within a loop, then the interpreter is retained between invocations unless the "Reset bsh.Interpreter before each call" option is selected. Some long-running tests may cause the interpreter to use lots of memory; if this is the case try using the reset option. You can test BeanShell scripts outside JMeter by using the command-line interpreter:
$ java -cp bsh-xxx.jar[;other jars as needed] bsh.Interperter file.bsh [parameters] or $ java -cp bsh-xxx.jar bsh.Interperter bsh% source("file.bsh"); bsh% exit(); // or use EOF key (e.g. ^Z or ^D)

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

116

Jmeter 2.3.4 Users Manual

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.

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

It's quite hard to write and test scripts as functions. However, JMeter has the BSF (and BeanShell) samplers which can be used instead. Create a simple Test Plan containing the BSF Sampler and Tree View Listener. Code the script in the sampler script pane, and test it by running the test. If there are any errors, these will show up in the Tree View. Also the result of running the script will show up as the response. Once the script is working properly, it can be stored as a variable on the Test Plan. The script variable can then be used to create the function call. For example, suppose a BeanShell script is stored in the variable RANDOM_NAME. The function call can then be coded as ${__BeanShell(${RANDOM_NAME})} . There is no need to escape any commas in the script, because the function call is parsed before the variable's value is interpolated.

17.10 Parameterising tests

Often it is useful to be able to re-run the same test with different settings. For example, changing the number of threads or loops, or changing a hostname. One way to do this is to define a set of variables on the Test Plan, and then use those variables in the test elements. For example, one could define the variable LOOPS=10, and refer to that in the Thread Group as ${LOOPS}. To run the test with 20 loops, just change the value of the LOOPS variable on the Test Plan. This quickly becomes tedious if you want to run lots of tests in non-GUI mode. One solution to this is to define the Test Plan variable in terms of a property, for example LOOPS=${__P(loops,10))} . This uses the value of the property "loops", defaulting to 117

Jmeter 2.3.4 Users Manual

10 if the property is not found. The "loops" property can then be defined on the JMeter command-line: jmeter ... -Jloops=12 ... . If there are a lot of properties that need to be changed together, then one way to achieve this is to use a set of property files. The appropriate property file can be passed in to JMeter using the -q command-line option.

118

Jmeter 2.3.4 Users Manual

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

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

18.2 Resources
The following resources will prove very helpful. Bear in mind that if you cannot locate these resources, you will become these resources. As you already have your work cut out for you, it is worth knowing who the following people are, so that you can ask them for help if you need it.

18.2.1

Network

Who knows our network topology? If you run into any firewall or proxy issues, this will become very important. As well, a private testing network (which will therefore have very low network latency) would be a very nice thing. Knowing who can set one up for you (if you feel that this is necessary) will be very useful. If the application doesn't scale as expected, who can add additional hardware?

18.2.2

Application

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

119

Jmeter 2.3.4 Users Manual

The test process may progress from black-box testing to white-box testing (the difference is that the first requires no knowledge of the application [it is treated as a "black box"] while the second requires some knowledge of the application). It is not uncommon to discover problems with the application during this process, so be prepared to defend your work.

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

18.4 Tools
The following tools will all prove useful. It is definitely worthwhile to become familiar with them. This should include trying them out, and reading the appropriate documentation (man-pages, info-files, application --help messages, and any supplied documentation).

120

Jmeter 2.3.4 Users Manual

18.4.1

ping

This can be used to establish whether or not you can reach your target site. Options can be specified so that 'ping' provides the same type of route reporting as 'traceroute'.

18.4.2

nslookup/dig

While the user will normally use a human-readable internet address, you may wish to avoid the overhead of DNS lookups when performing benchmarking/load-testing. These can be used to determine the unique address (dotted quad) of your target site.

18.4.3

traceroute

If you cannot "ping" your target site, this may be used to determine the problem (possibly a firewall or a proxy). It can also be used to estimate the overall network latency (running locally should give the lowest possible network latency - remember that your users will be running over a possibly busy internet). Generally, the fewer hops the better.

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

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

18.5.2

HttpUnit

This is worth a look. It is a library (and therefore of more interest to developers) that can be used to perform HTTP tests/benchmarks. It is intended to be used instead of a web browser (therefore no GUI) in conjunction with JUnit.

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

121

Jmeter 2.3.4 Users Manual

18.5.4

JMeter

If you have non-standard requirements, then this solution offers an open-source community to provide them (of course, if you are reading this , you are probably already committed to this one). This product is free to evolve along with your requirements.

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

122

Jmeter 2.3.4 Users Manual

19. Component Reference

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

19.1.1

FTP Request

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

Parameters Attribute Name Server Name or IP Port Description Required

Descriptive name for this controller that is shown in the No tree. Domain name or IP address of the FTP server. Port to use. If this is >0, then this specific port is used, Yes No

123

Jmeter 2.3.4 Users Manual

otherwise JMeter uses the default FTP port. Remote File: Local File: Local File Contents: get(RETR) / put(STOR) Use Binary mode ? Save File in Response ? Username Password See Also:

File to retrieve or name of destination file to upload.

Yes

File to upload, or destination for downloads (defaults to Yes, if remote file name). uploading (*) Provides the contents for the upload, overrides the Local File property. Whether to retrieve or upload a file. Check this to use Binary mode (default Ascii) 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. FTP account username. FTP account password. N.B. This will be visible in the test plan. Yes, if uploading (*) Yes Yes Yes, if downloading Usually Usually

Assertions FTP Request Defaults Building an FTP Test Plan

19.1.2

HTTP Request

This sampler lets you send an HTTP/HTTPS request to a web server. It also lets you control whether or not JMeter parses HTML files for images and other embedded resources and sends HTTP requests to retrieve them. The following types of embedded resource are retrieved:

images applets stylesheets external scripts frames background images (body, table, TD, TR) background sound

The default parser is htmlparser. This can be changed by using the property "htmlparser.classname" - see jmeter.properties for details.

124

Jmeter 2.3.4 Users Manual

If you are going to send multiple requests to the same web server, consider using an HTTP Request Defaults Configuration Element so you do not have to enter the same information for each HTTP Request. Or, instead of manually adding HTTP Requests, you may want to use JMeter's HTTP Proxy Server to create them. This can save you time if you have a lot of HTTP requests or requests with many parameters. 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: 125

Jmeter 2.3.4 Users Manual

https.default.protocol=SSLv3

JMeter also allows one to enable additional protocols, by changing the property https.socket.protocols . If the request uses cookies, then you will also need an HTTP Cookie Manager . You can add either of these elements to the Thread Group or the HTTP Request. If you have more than one HTTP Request that needs authorizations or cookies, then add the elements to the Thread Group. That way, all HTTP Request controllers will share the same Authorization Manager and Cookie Manager elements. If the request uses a technique called "URL Rewriting" to maintain sessions, then see section 6.1 Handling User Sessions With URL Rewriting for additional configuration steps. Control Panel

126

Jmeter 2.3.4 Users Manual

Parameters Attribute Name Description Descriptive name for this controller that is shown in the tree. Domain name or IP address of the web server. e.g. www.example.com. [Do not include the http:// prefix.] Port the web server is listening to. Default: 80 Required No Yes, unless provided by HTTP Request Defaults No

Server

Port Connect Timeout

Connection Timeout. Number of milliseconds to wait No for a connection to open. Requires Java 1.5 or later

127

Jmeter 2.3.4 Users Manual

when using the default Java HTTP implementation. Response Timeout. Number of milliseconds to wait Response Timeout for a response. Requires Java 1.5 or later when using the default Java HTTP implementation. Protocol Method HTTP, HTTPS or FILE. Default: HTTP GET, POST, HEAD, TRACE, OPTIONS, PUT, DELETE No No Yes No

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

Redirect Automatically

Follow Redirects

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 Yes HttpClient sampler will reject attempts to use it for POST or PUT. Warning: see below for information on cookie and header handling. This only has any effect if "Redirect Automatically" is not enabled. If set, the JMeter sampler will check if the response is a redirect and follow it if so. The redirect response will appear as an additional sample. Yes Note that the HttpClient sampler may log the following message: "Redirect requested but followRedirects is disabled" This can be ignored. 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. Use a multipart/form-data or application/x-wwwform-urlencoded post request The path to resource (for example, /servlets/myServlet). If the resource requires query string parameters, add them below in the "Send Parameters With the Request" section. As a special case, if the path starts with "http://" or "https://" then this is used as the full URL. In this case, the server, port and protocol are ignored; parameters are also ignored for GET and DELETE methods. The query string will be generated from the list of parameters you provide. Each parameter has a name and value , the options to encode the parameter, and

Use KeepAlive

Yes

Use multipart/formdata for HTTP POST

Yes

Path

Yes

Send Parameters With the Request

No

128

Jmeter 2.3.4 Users Manual

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. 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 No 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. Value of the "name" web request parameter. No MIME type (for example, text/plain). If it is a POST or PUT request and either the 'name' atribute (below) are omitted or the request body is constructed from No parameter values only, then the value of this field is used as the value of the content-type request header. 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. For use with the Monitor Results listener. No Yes

File Path:

Parameter name:

MIME Type

Retrieve All Embedded Resources from HTML Files Use as monitor 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 Yes the data is calculated and stored instead. This is intended for testing large amounts of data.

129

Jmeter 2.3.4 Users Manual

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 No from http://example.com/, use the expression: http://example\.com/.*

N.B. when using Automatic Redirection, cookies are only sent for the initial URL. This can cause unexpected behaviour for web-sites that redirect to a local server. E.g. if www.example.com redirects to www.example.co.uk. In this case the server will probably return cookies for both URLs, but JMeter will only see the cookies for the last host, i.e. www.example.co.uk. If the next request in the test plan uses www.example.com, rather than www.example.co.uk, it will not get the correct cookies. Likewise, Headers are sent for the initial request, and won't be sent for the redirect. This is generally only a problem for manually created test plans, as a test plan created using a recorder would continue from the redirected URL. Parameter Handling: For the POST and PUT method, if there is no file to send, and the name(s) of the parameter(s) are omitted, then the body is created by concatenating all the value(s) of the parameters. This allows arbitrary bodies to be sent. The values are encoded if the encoding flag is set (versions of JMeter after 2.3). See also the MIME Type above how you can control the content-type request header that is sent. For other methods, if the name of the parameter is missing, then the parameter is ignored. This allows the use of optional parameters defined by variables. (versions of JMeter after 2.3) Method Handling: The POST and PUT request methods work similarly, except that the PUT method does not support multipart requests. The PUT method body must be provided as one of the following:

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

If you define any parameters with a name in either the sampler or Http defaults then nothing is sent. The GET and DELETE request methods work similarly to each other. Upto and including JMeter 2.1.1, only responses with the content-type "text/html" were scanned for embedded resources. Other content-types were assumed to be something other than HTML. JMeter 2.1.2 introduces the a new property HTTPResponse.parsers , which is a list of parser ids, e.g. htmlParser and wmlParser . For each id found, JMeter checks two further properties:

id.types - a list of content types id.className - the parser to be used to extract the embedded resources

130

Jmeter 2.3.4 Users Manual

See jmeter.properties file for the details of the settings. If the HTTPResponse.parser property is not set, JMeter reverts to the previous behaviour, i.e. only text/html responses will be scanned Emulating slow connections:
# Define characters per second > 0 to emulate slow connections #httpclient.socket.http.cps=0 #httpclient.socket.https.cps=0

See Also:

Assertion Building a Web Test Plan Building an Advanced Web Test Plan HTTP Authorization Manager HTTP Cookie Manager HTTP Header Manager HTML Link Parser HTTP Proxy Server HTTP Request Defaults HTTP Requests and Session ID's: URL Rewriting

19.1.3

JDBC Request

This sampler lets you send an JDBC Request (an SQL query) to a database. Before using this you need to set up a JDBC Connection Configuration Configuration element If the Variable Names list is provided, then for each row returned by a Select statement, the variables are set up with the value of the corresponding column (if a variable name is provided), and the count of rows is also set up. For example, if the Select statement returns 2 rows of 3 columns, and the variable list is A,,C , then the following variables will be set up:
A_#=2 (number A_1=column 1, A_2=column 1, C_#=2 (number C_1=column 3, C_2=column 3, of rows) row 1 row 2 of rows) row 1 row 2

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

131

Jmeter 2.3.4 Users Manual

Old variables are cleared if necessary - e.g. if the first select retrieves 6 rows and a second select returns only 3 rows, the additional variables for rows 4, 5 and 6 will be removed. Control Panel

Parameters Description Attribute Name Descriptive name for this controller that is shown in the tree. Variable Name Required No

Name of the JMeter variable that the connection pool is bound to. This must agree with the 'Variable Name' field of a JDBC Yes Connection Configuration. Set this according to the statement type:

Query Type

Select Statement Update Statement - use this for Inserts as well Callable Statement Prepared Select Statement Yes Prepared Update Statement - use this for Inserts as well Commit Rollback Autocommit(false) Autocommit(true) Edit - this should be a variable reference that evaluates

132

Jmeter 2.3.4 Users Manual

to one of the above SQL query. Do not enter a trailing semi-colon. There is generally no need to use { and } to enclose Callable statements; however they mey be used if the database uses a non-standard syntax. [The JDBC driver automatically converts the statement if necessary when it is enclosed in {}]. For example: SQL Query

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

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".) Parameter The list must be enclosed in double-quotes if any of the values contain a comma or double-quote, and any embedded doublevalues quotes must be doubled-up, for example:
"Dbl-Quote: "" and Comma: ,"

Yes, if a prepared or callable statement has parameters

There must be as many values as there are placeholders in the statement. Comma-separated list of SQL parameter types (e.g. INTEGER, DATE, VARCHAR, DOUBLE). These are defined as fields in the class java.sql.Types, see for example: Javadoc for java.sql.Types . [Note: JMeter will use whatever types are defined by the runtime JVM, so if you are running on a different JVM, be sure to check the appropriate document] If the callable statement has INOUT or OUT parameters, then these must be indicated by prefixing the appropriate parameter Parameter types, e.g. instead of "INTEGER", use "INOUT INTEGER". If types not specified, "IN" is assumed, i.e. "DATE" is the same as "IN DATE". If the type is not one of the fields found in java.sql.Types, versions of JMeter after 2.3.2 also accept the corresponding integer number, e.g. since INTEGER == 4, you can use "INOUT 4". There must be as many types as there are placeholders in the statement. Variable Names Comma-separated list of variable names to hold values returned by Select statements

Yes, if a prepared or callable statement has parameters

No

133

Jmeter 2.3.4 Users Manual

See Also:

Building a Database Test Plan JDBC Connection Configuration

Versions of JMeter after 2.3.2 use UTF-8 as the character encoding. Previously the platform default was used.

19.1.4

Java Request

This sampler lets you control a java class that implements the JavaSamplerClient interface. By writing your own implementation of this interface, you can use JMeter to harness multiple threads, input parameter control, and data collection. The pull-down menu provides the list of all such implementations found by JMeter in its classpath. The parameters can then be specified in the table below - as defined by your implementation. Two simple examples (JavaTest and SleepTest) are provided. The JavaTest example sampler can be useful for checking test plans, because it allows one to set values in almost all the fields. These can then be used by Assertions, etc. The fields allow variables to be used, so the values of these can readily be seen. Control Panel

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

134

Jmeter 2.3.4 Users Manual

Attribute Name Classname Send Parameters with Request

Description Descriptive name for this sampler that is shown in the tree. The specific implementation of the JavaSamplerClient interface to be sampled. A list of arguments that will be passed to the sampled class. All arguments are sent as Strings.

Required No Yes No

The sleep time is calculated as follows:

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

19.1.5

SOAP/XML-RPC Request

This sampler lets you send a SOAP request to a webservice. It can also be used to send XML-RPC over HTTP. It creates an HTTP POST request, with the specified XML as the POST content. To change the "Content-type" from the default of "text/xml", use a HeaderManager. Note that the sampler will use all the headers from the HeaderManager. If a SOAP action is specified, that will override any SOAPaction in the HeaderManager. The primary difference between the soap sampler and webservice sampler, is the soap sampler uses raw post and does not require conformance to SOAP 1.1. For versions of JMeter later than 2.2, the sampler no longer uses chunked encoding by default. For screen input, it now always uses the size of the data. File input uses the file length as determined by Java. On some OSes this may not work for all files, in which case add a child Header Manager with Content-Length set to the actual length of the file. Or set Content-Length to -1 to force chunked encoding. Control Panel

135

Jmeter 2.3.4 Users Manual

Parameters Attribute Name URL Send SOAP action Description The URL to direct the SOAP request to. Send a SOAP action header? (overrides the Header Manager) Required Yes No No No

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

Soap/XML-RPC The Soap XML message, or XML-RPC instructions. Not Data used if the filename is provided. Filename If specified, then the contents of the file are sent, and the Data field is ignored

19.1.6

WebService(SOAP) Request

This sampler has been tested with IIS Webservice running .NET 1.0 and .NET 1.1. It has been tested with SUN JWSDP, IBM webservices, Axis and gSoap toolkit for C/C++. The sampler uses Apache SOAP driver to serialize the message and set the header with the correct SOAPAction. Right now the sampler doesn't support automatic WSDL handling, since Apache SOAP currently does not provide support for it. Both IBM and SUN provide WSDL drivers. There are 3 options for the post data: text area, external file, or directory. If you want the sampler to randomly select a message, use the directory. Otherwise, use the text area or a file. The if either the file or path are set, it will not use the message in the text area. If you need to test a soap service that uses different encoding, use the file or path. If you paste the message in to text area, it will not retain the encoding and will result in errors. Save your message to a file with the proper encoding, and the sampler will read it as java.io.FileInputStream. The sampler requires mail.jar and activation.jar. This is because Apache SOAP requires the libs. Because mail.jar and activation.jar are distributed by Sun, you have to download them separately.

136

Jmeter 2.3.4 Users Manual

An important note on the sampler is it will automatically use the proxy host and port passed to JMeter from command line, if those fields in the sampler are left blank. If a sampler has values in the proxy host and port text field, it will use the ones provided by the user. This behavior may not be what users expect. By default, the webservice sampler sets SOAPHTTPConnection.setMaintainSession (true). If you need to maintain the session, add a blank Header Manager. The sampler uses the Header Manager to store the SOAPHTTPConnection object, since the version of apache soap does not provide a easy way to get and set the cookies. Note: If you are using CSVDataSet, do not check "Memory Cache". If memory cache is checked, it will not iterate to the next value. That means all the requests will use the first value. Make sure you use <soap:Envelope rather than <Envelope. For example:
<?xml version="1.0" encoding="utf-8"?> <soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Body> <foo xmlns="http://clients-xlmns"/> </soap:Body> </soap:Envelope>

The SOAP library that is used does not support SOAP 1.2, only SOAP 1.1. Also the library does not provide access to the HTTP response code (e.g. 200) or message (e.g. OK). To get round this, versions of JMeter after 2.3.2 check the returned message length. If this is zero, then the request is marked as failed. Control Panel

137

Jmeter 2.3.4 Users Manual

138

Jmeter 2.3.4 Users Manual

Parameters Attribute Name WSDL URL Description Descriptive name for this sampler that is shown in the tree. The WSDL URL with the service description. Versions of JMeter after 2.3.1 support the file: protocol for local WSDL files. Required No No

Will be populated from the WSDL when the Load WSDL button is pressed. Select one of the methods and press the Web Methods Configure button to populate the Protocol, Server, Port, Path and SOAPAction fields. Protocol Server Name or IP Port Number Path SOAPAction Soap/XMLRPC Data Soap file Message Folder HTTP or HTTPS are acceptable protocol. The hostname or IP address. Port Number. Path for the webservice. The SOAPAction defined in the webservice description or WSDL. The Soap XML message File containing soap message Folder containing soap files

No Yes Yes Yes Yes Yes Yes No No Yes No No No

When using external files, setting this causes the file to be Memory cache processed once and caches the result. This may use a lot of memory if there are many different large files. Use HTTP Proxy Proxy Host Proxy Port Check box if http proxy should be used Proxy hostname Proxy host port

19.1.7

LDAP Request

This Sampler lets you send a different Ldap request(Add, Modify, Delete and Search) to an LDAP server. If you are going to send multiple requests to the same LDAP server, consider using an LDAP Request Defaults Configuration Element so you do not have to enter the same information for each LDAP Request. The same way the Login Config Element also using for Login and password.

139

Jmeter 2.3.4 Users Manual

Control Panel

There are two ways to create test cases for testing an LDAP Server. 1. Inbuilt Test cases. 2. User defined Test cases. There are four test scenarios of testing LDAP. The tests are given below: 1. Add Test 1. Inbuilt test : This will add a pre-defined entry in the LDAP Server and calculate the execution time. After execution of the test, the created entry will be deleted from the LDAP Server. 2. User defined test :

140

Jmeter 2.3.4 Users Manual

This will add the entry in the LDAP Server. User has to enter all the attributes in the table.The entries are collected from the table to add. The execution time is calculated. The created entry will not be deleted after the test. 2. Modify Test 1. Inbuilt test : This will create a pre-defined entry first, then will modify the created entry in the LDAP Server.And calculate the execution time. After execution of the test, the created entry will be deleted from the LDAP Server. 2. User defined test This will modify the entry in the LDAP Server. User has to enter all the attributes in the table. The entries are collected from the table to modify. The execution time is calculated. The entry will not be deleted from the LDAP Server. 3. Search Test 1. Inbuilt test : This will create the entry first, then will search if the attributes are available. It calculates the execution time of the search query. At the end of the execution,created entry will be deleted from the LDAP Server. 2. User defined test This will search the user defined entry(Search filter) in the Search base (again, defined by the user). The entries should be available in the LDAP Server. The execution time is calculated. 4. Delete Test 1. Inbuilt test : This will create a pre-defined entry first, then it will be deleted from the LDAP Server. The execution time is calculated. 2. User defined test This will delete the user-defined entry in the LDAP Server. The entries should be available in the LDAP Server. The execution time is calculated. Parameters

141

Jmeter 2.3.4 Users Manual

Attribute Name

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

Required No

Server Domain name or IP address of the LDAP server. JMeter assumes Yes Name or IP the LDAP server is listening on the default port(389). Port root DN Username Password Entry DN Delete default port(389). DN for the server to communicate LDAP server username. LDAP server password. the name of the context to create or Modify; may not be empty Example: do you want to add cn=apache,ou=test you have to add in table name=cn, value=apache the name of the context to Delete; may not be empty Yes Yes Usually Usually yes yes yes yes yes yes

Search base the name of the context or object to search Search filter the filter expression to use for the search; may not be null add test modify test See Also:

this name, value pair to added in the given context object this name, value pair to add or modify in the given context object

Building an Ldap Test Plan LDAP Request Defaults

19.1.8

LDAP Extended Request

This Sampler can send all 8 different LDAP request to an LDAP server. It is an extended version of the LDAP sampler, therefore it is harder to configure, but can be made much closer resembling a real LDAP session. If you are going to send multiple requests to the same LDAP server, consider using an LDAP Extended Request Defaults Configuration Element so you do not have to enter the same information for each LDAP Request. Control Panel

142

Jmeter 2.3.4 Users Manual

There are nine test operations defined. These operations are given below: 1. Thread bind Any LDAP request is part of an LDAP session, so the first thing that should be done is starting a session to the LDAP server. For starting this session a thread bind is used, which is equal to the LDAP "bind" operation. The user is requested to give a username (Distinguished name) and password, which will be used to initiate a session. When no password, or the wrong password is specified, an anonymous session is started. Take care, omitting the password will not fail this test, a wrong password will. Parameters Attribute Description Required

143

Jmeter 2.3.4 Users Manual

Name

Descriptive name for this sampler that is shown in the tree. The port number that the LDAP server is listening to. If this is omitted JMeter assumes the LDAP server is listening on the default port(389). The distinguished name of the base object that will be used for any subsequent operation. It can be used as a starting point for all operations. You cannot start any operation on a higher level than this DN! Full distinguished name of the user as which you want to bind.

No Yes No

Servername The name (or IP-address) of the LDAP server. Port

DN

No

Username Password

No

Password for the above user. If omitted it will result in an anonymous bind. If is is incorrect, the sampler will return No an error and revert to an anonymous bind.

2. Thread unbind This is simply the operation to end a session. It is equal to the LDAP "unbind" operation. Parameters Attribute Name Description Required

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

3. Single bind/unbind This is a combination of the LDAP "bind" and "unbind" operations. It can be used for an authentication request/password check for any user. It will open an new session, just to check the validity of the user/password combination, and end the session again. Parameters Attribute Name Username Description Descriptive name for this sampler that is shown in the tree. Full distinguished name of the user as which you want to bind. Required No Yes No

Password Password for the above user. If omitted it will result in an

144

Jmeter 2.3.4 Users Manual

anonymous bind. If is is incorrect, the sampler will return an error.

4. Rename entry This is the LDAP "moddn" operation. It can be used to rename an entry, but also for moving an entry or a complete subtree to a different place in the LDAP tree. Parameters Attribute Name Old entry name New distinguished name Description Descriptive name for this sampler that is shown in the tree. Required No

The current distinguished name of the object you want to rename or move, relative to the given DN in Yes the thread bind operation. The new distinguished name of the object you want to rename or move, relative to the given DN in the thread bind operation. Yes

5. Add test This is the ldap "add" operation. It can be used to add any kind of object to the LDAP server. Parameters Attribute Description Name Descriptive name for this sampler that is shown in the tree. Entry DN Distinguished name of the object you want to add, relative to the given DN in the thread bind operation. A list of attributes and their values you want to use for the object. If you need to add a multiple value attribute, you need to add the same attribute with their respective values several times to the list. Required No Yes

Add test

Yes

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

145

Jmeter 2.3.4 Users Manual

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

7. Search test This is the LDAP "search" operation, and will be used for defining searches. Parameters Attribute Name Search base Description Descriptive name for this sampler that is shown in the tree. Required No

Distinguished name of the subtree you want your search to look in, relative to the given DN in the thread bind No operation. Yes Use 0 for baseobject-, 1 for onelevel- and 2 for a subtree No search. (Default=0) Specify the maximum number of results you want back from the server. (default=0, which means no limit.) No When the sampler hits the maximum number of results, it will fail with errorcode 4 Specify the maximum amount of (cpu)time (in miliseconds) that the server can spend on your search. Take care, this does not say anything about the responsetime. (default is 0, which means no limit) No

Search Filter searchfilter, must be specified in LDAP syntax. Scope

Size Limit

Time Limit

Attributes Return object Dereference aliases

Specify the attributes you want to have returned, seperated by a semicolon. An empty field will return all No attributes Whether the object will be returned (true) or not (false). No Default=false If true, it will dereference aliases, if false, it will not follow them (default=false) No

8. Modification test

146

Jmeter 2.3.4 Users Manual

This is the LDAP "modify" operation. It can be used to modify an object. It can be used to add, delete or replace values of an attribute. Parameters Attribute Name Entry name Description Descriptive name for this sampler that is shown in the tree. Distinguished name of the object you want to modify, relative to the given DN in the thread bind operation Required No Yes

The attribute-value-opCode triples. The opCode can be any valid LDAP operationCode (add, delete/remove or replace). If you don't specify a value with a delete Modification operation, all values of the given attribute will be Yes test deleted. If you do specify a value in a delete operation, only the given value will be deleted. If this value is nonexistent, the sampler will fail the test.

9. Compare This is the LDAP "compare" operation. It can be used to compare the value of a given attribute with some already known value. In reality this is mostly used to check whether a given person is a member of some group. In such a case you can compare the DN of the user as a given value, with the values in the attribute "member" of an object of the type groupOfNames. If the compare operation fails, this test fails with errorcode 49. Parameters Attribute Name Entry DN Compare filter See Also:
1. 2.

Description

Required

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

Building an LDAP Test Plan LDAP Extended Request Defaults

147

Jmeter 2.3.4 Users Manual

19.1.9
(Alpha Code)

Access Log Sampler

AccessLogSampler was designed to read access logs and generate http requests. For those not familiar with the access log, it is the log the webserver maintains of every request it accepted. This means the every image and html file. The current implementation is complete, but some features have not been enabled. There is a filter for the access log parser, but I haven't figured out how to link to the pre-processor. Once I do, changes to the sampler will be made to enable that functionality. Tomcat uses the common format for access logs. This means any webserver that uses the common log format can use the AccessLogSampler. Server that use common log format include: Tomcat, Resin, Weblogic, and SunOne. Common log format looks like this: 127.0.0.1 - - [21/Oct/2003:05:37:21 -0500] "GET /index.jsp?%2Findex.jsp= HTTP/1.1" 200 8343 The current implemenation of the parser only looks at the text within the quotes. Everything else is stripped out and igored. For example, the response code is completely ignored by the parser. For the future, it might be nice to filter out entries that do not have a response code of 200. Extending the sampler should be fairly simple. There are two interfaces you have to implement. org.apache.jmeter.protocol.http.util.accesslog.LogParser org.apache.jmeter.protocol.http.util.accesslog.Generator The current implementation of AccessLogSampler uses the generator to create a new HTTPSampler. The servername, port and get images are set by AccessLogSampler. Next, the parser is called with integer 1, telling it to parse one entry. After that, HTTPSampler.sample() is called to make the request.
samp = (HTTPSampler) GENERATOR.generateRequest(); samp.setDomain(this.getDomain()); samp.setPort(this.getPort()); samp.setImageParser(this.isImageParser()); PARSER.parse(1); res = samp.sample(); res.setSampleLabel(samp.toString());

The required methods in LogParser are: setGenerator(Generator) and parse(int). Classes implementing Generator interface should provide concrete implementation for all the methods. For an example of how to implement either interface, refer to StandardGenerator and TCLogParser. Control Panel

148

Jmeter 2.3.4 Users Manual

Parameters Attribute Name Server Port Log parser class Filter Location of log file Description Descriptive name for this controller that is shown No in the tree. Domain name or IP address of the web server. Port the web server is listening to. Yes No (defaults to 80) Required

The log parser class is responsible for parsing the Yes (default logs. provided) The filter class is used to filter out certain lines. The location of the access log file. No Yes

The TCLogParser processes the access log independently for each thread. The SharedTCLogParser and OrderPreservingLogParser share access to the file, i.e. each thread gets the next entry in the log. The SessionFilter is intended to handle Cookies across threads. It does not filter out any entries, but modifies the cookie manager so that the cookies for a given IP are processed by a single thread at a time. If two threads try to process samples from the same client IP address, then one will be forced to wait until the other has completed. The LogFilter is intended to allow access log entries to be filtered by filename and regex, as well as allowing for the replacement of file extensions. However, it is not currently possible to configure this via the GUI, so it cannot really be used.

149

Jmeter 2.3.4 Users Manual

19.1.10

BeanShell Sampler

This sampler allows you to write a sampler using the BeanShell scripting language. For full details on using BeanShell, please see the BeanShell 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 Name Reset bsh.Interpreter before each call Description Required

Descriptive name for this controller that is shown in the No tree. If this option is selected, then the interpreter will be recreated for each sample. This may be necessary for Yes some long running scripts. For further information, see Best Practices - BeanShell scripting . Parameters to pass to the BeanShell script. This is intended for use with script files; for scripts defined in the GUI, you can use whatever variable and function references you need within the script itself. The parameters are stored in the following variables:

Parameters

No

150

Jmeter 2.3.4 Users Manual

Parameters - string containing the parameters as a single variable bsh.args - String array containing parameters, split on white-space No Yes (unless script file is provided)

Script file Script

A file containing the BeanShell script to run. The BeanShell script to run. The return value (if not null) is stored as the sampler result.

N.B. Each Sampler instance has its own BeanShell interpeter, and Samplers are only called from a single thread If the property "beanshell.sampler.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: BeanShellSampler.bshrc. If a script file is supplied, that will be used, otherwise the script will be used. Before invoking the script, some variables are set up in the BeanShell interpreter: The contents of the Parameters field is put into the variable "Parameters". The string is also split into separate tokens using a single space as the separator, and the resulting list is stored in the String array bsh.args. The full list of BeanShell variables that is set up is as follows:

log - the Logger Label - the Sampler label FileName - the file name, if any Parameters - text from the Parameters field bsh.args - the parameters, split as described above SampleResult - pointer to the current SampleResult ResponseCode = 200 ResponseMessage = "OK" IsSuccess = true ctx - JMeterContext vars - JMeterVariables - e.g. vars.get("VAR1"); vars.put("VAR2","value"); vars.remove("VAR3"); vars.putObject("OBJ1",new Object()); props - JMeter Properties - e.g. props.get("START.HMS"); props.put("PROP1","1234");

When the script completes, control is returned to the Sampler, and it copies the contents of the following script variables into the corresponding variables in the SampleResult:

151

Jmeter 2.3.4 Users Manual

ResponseCode - for example 200 ResponseMessage - for example "OK" IsSuccess - true/false

The SampleResult ResponseData is set from the return value of the script. Since version 2.1.2, if the script returns null, it can set the response directly, by using the method SampleResult.setResponseData(data), where data is either a String or a byte array. The data type defaults to "text", but can be set to binary by using the method SampleResult.setDataType(SampleResult.BINARY). The SampleResult variable gives the script full access to all the fields and methods in the SampleResult. For example, the script has access to the methods setStopThread(boolean) and setStopTest(boolean). Here is a simple (not very useful!) example script:
if (bsh.args[0].equalsIgnoreCase("StopThread")) { log.info("Stop Thread detected!"); SampleResult.setStopThread(true); } return "Data from sample with Label "+Label; //or, since version 2.1.2 SampleResult.setResponseData("My data"); return null;

Another example: ensure that the property beanshell.sampler.init=BeanShellSampler.bshrc is defined in jmeter.properties. The following script will show the values of all the variables in the ResponseData field:
return getVariables();

For details on the methods available for the various classes (JMeterVariables, SampleResult etc) please check the Javadoc or the source code. Beware however that misuse of any methods can cause subtle faults that may be difficult to find ...

19.1.11

BSF Sampler

This sampler allows you to write a sampler using a BSF scripting language. See the Apache Bean Scripting Framework website for details of the languages supported. You may need to download the appropriate jars for the language; they should be put in the JMeter lib directory. By default, JMeter supports the following languages:

javascript jexl (JMeter version 2.3.2 and later)

152

Jmeter 2.3.4 Users Manual

xslt

Control Panel

Parameters Attribute Name Description Descriptive name for this controller that is shown in the tree. Required No

Scripting Language Script File Parameters Script

Name of the BSF scripting language to be used. N.B. Not all the languages in the drop-down list are supported by default. The following are supported: jexl, javascript, xslt. Yes Others may be available if the appropriate jar is installed in the JMeter lib directory. Name of a file to be used as a BSF script List of parameters to be passed to the script file or the script. Script to be passed to BSF language No No Yes (unless script file is provided)

If a script file is supplied, that will be used, otherwise the script will be used. Before invoking the script, some variables are set up. Note that these are BSF variables i.e. they can be used directly in the script.

log - the Logger Label - the Sampler label FileName - the file name, if any

153

Jmeter 2.3.4 Users Manual

Parameters - text from the Parameters field args - the parameters, split as described above SampleResult - pointer to the current SampleResult ctx - JMeterContext vars - JMeterVariables - e.g. vars.get("VAR1"); vars.put("VAR2","value"); vars.remove("VAR3"); vars.putObject("OBJ1",new Object()); props - JMeter Properties - e.g. props.get("START.HMS"); props.put("PROP1","1234"); OUT - System.out - e.g. OUT.println("message")

The SampleResult ResponseData is set from the return value of the script. If the script returns null, it can set the response directly, by using the method SampleResult.setResponseData(data), where data is either a String or a byte array. The data type defaults to "text", but can be set to binary by using the method SampleResult.setDataType(SampleResult.BINARY). The SampleResult variable gives the script full access to all the fields and methods in the SampleResult. For example, the script has access to the methods setStopThread(boolean) and setStopTest(boolean). Unlike the Beanshell Sampler, the BSF Sampler does not set the ResponseCode, ResponseMessage and sample status via script variables. Currently the only way to changes these is via the SampleResult methods:

SampleResult.setSuccessful(true/false) SampleResult.setResponseCode("code") SampleResult.setResponseMessage("message")

19.1.12

TCP Sampler

The TCP Sampler opens a TCP/IP connection to the specified server. It then sends the text, and waits for a response. If "Re-use connection" is selected, connections are shared between Samplers in the same thread, provided that the exact same host name string and port are used. Different hosts/port combinations will use different connections, as will different threads. If an error is detected - or "Re-use connection" is not selected - the socket is closed. Another socket will be reopened on the next sample. The following properties can be used to control its operation:

tcp.status.prefix - text that precedes a status number tcp.status.suffix - text that follows a status number tcp.status.properties - name of property file to convert status codes to messages tcp.handler - Name of TCP Handler class (default TCPClientImpl) - only used if not specified on the GUI

154

Jmeter 2.3.4 Users Manual

The class that handles the connection is defined by the GUI, failing that the property tcp.handler. If not found, the class is then searched for in the package org.apache.jmeter.protocol.tcp.sampler. Users can provide their own implementation. The class must extend org.apache.jmeter.protocol.tcp.sampler.TCPClient. The following implementations are currently provided.

TCPClientImpl BinaryTCPClientImpl LengthPrefixedBinaryTCPClientImpl

The implementations behave as follows: TCPClientImpl This implementation is fairly basic. When reading the response, it reads until the end of line byte, if this is defined by setting the property tcp.eolByte , otherwise until the end of the input stream. BinaryTCPClientImpl This implementation converts the GUI input, which must be a hex-encoded string, into binary, and performs the reverse when reading the response. When reading the response, it reads until the end of message byte, if this is defined by setting the property tcp.BinaryTCPClient.eomByte , otherwise until the end of the input stream. LengthPrefixedBinaryTCPClientImpl This implementation extends BinaryTCPClientImpl by prefixing the binary message data with a binary length byte. The length prefix defaults to 2 bytes. This can be changed by setting the property tcp.binarylength.prefix.length . Timeout handling If the timeout is set, the read will be terminated when this expires. So if you are using an eolByte/eomByte, make sure the timeout is sufficiently long, otherwise the read will be terminated early. Response handling If tcp.status.prefix is defined, then the response message is searched for the text following that up to the suffix. If any such text is found, it is used to set the response code. The response message is then fetched from the properties file (if provided). For example, if the prefix = "[" and the suffix = "]", then the following repsonse: [J28] XI123,23,GBP,CR would have the response code J28. Response codes in the range "400"-"499" and "500"-"599" are currently regarded as failures; all others are successful. [This needs to be made configurable!] The login name/password are not used by

155

Jmeter 2.3.4 Users Manual

the supplied TCP implementations. Sockets are disconnected at the end of a test run. Control Panel

Parameters Attribute Name TCPClient classname ServerName or IP Port Number Re-use connection Timeout (milliseconds) Set Nodelay Text to Send Description Descriptive name for this element that is shown in the tree. Name of the TCPClient class. Defaults to the property tcp.handler, failing that TCPClientImpl. Name or IP of TCP server Port to be used If selected, the connection is kept open. Otherwise it is closed when the data has been read. Timeout for replies. See java.net.Socket.setTcpNoDelay(). If selected, this will disable Nagle's algorithm, otherwise Nagle's algorithm will be used. Text to be sent Required No No Yes Yes Yes No Yes Yes

156

Jmeter 2.3.4 Users Manual

Login User Password

User Name - not used by default implementation Password - not used by default implementation

No No

19.1.13

JMS Publisher

ALPHA CODE JMS Publisher will publish messages to a given pub/sub topic. For those not familiar with JMS, it is the J2EE specification for messaging. There are numerous JMS servers on the market and several open source options.

JMeter does not include the JMS jar; this must be downloaded and put in the lib directory Control Panel

157

Jmeter 2.3.4 Users Manual

Parameters Attribute Name Description Descriptive name for this element that is shown Required No

158

Jmeter 2.3.4 Users Manual

in the tree. use JNDI properties file JNDI Initial Context Factory Provider URL Topic Authentication User Password Number of samples to aggregate configuration Message type use jndi.properties to create topic Name of the context factory The URL for the jms provider the message topic User Name Password number of samples to aggregate setting for the message text or object message Yes No No Yes No No Yes Yes Yes

Authentication requirement for the JMS provider Yes

19.1.14

JMS Subscriber

ALPHA CODE JMS Publisher will subscribe to messages in a given pub/sub topic. For those not familiar with JMS, it is the J2EE specification for messaging. There are numerous JMS servers on the market and several open source options.

JMeter does not include the JMS jar; this must be downloaded and put in the lib directory Control Panel

159

Jmeter 2.3.4 Users Manual

Parameters Attribute Name use JNDI properties file JNDI Initial Context Factory Provider URL Topic Authentication User Password Number of samples to aggregate Read response Client Description Descriptive name for this element that is shown in the tree. use jndi.properties to create topic Name of the context factory The URL for the jms provider the message topic User Name Password number of samples to aggregate should the sampler read the response Which client to use Required No Yes No No Yes No No Yes Yes Yes

Authentication requirement for the JMS provider Yes

160

Jmeter 2.3.4 Users Manual

19.1.15

JMS Point-to-Point

ALPHA CODE This sampler sends and optionally receives JMS Messages through point-to-point connections (queues). It is different from pub/sub messages and is generally used for handling transactions. Versions of JMeter after 2.3.2 use the properties java.naming.security.[principal|credentials] - if present - when creating the Queue Connection. If this behaviour is not desired, set the JMeter property JMSSampler.useSecurity.properties=false

JMeter does not include the JMS jar; this must be downloaded and put in the lib directory Control Panel

161

Jmeter 2.3.4 Users Manual

Parameters Attribute Name Description Descriptive name for this element that is shown in the tree. Required No

162

Jmeter 2.3.4 Users Manual

QueueConnection Factory JNDI Name Request queue

The JNDI name of the queue connection factory to use for connecting to the messaging system. This is the JNDI name of the queue to which the messages are sent.

Yes Yes

The JNDI name of the receiving queue. If a value is JNDI Name Reply provided here and the communication style is Request queue Response this queue will be monitored for responses to the requests sent.

No

Communication style

The Communication style can be Request Only (also known as Fire and Forget) or Request Reply. Request Only will only sent messages and will not monitor replies. As such it can be used to put load on a system. Request Reply will sent messages and monitor the replies it receives. Behaviour is depended on the value of the JNDI Name Reply Queue. If JNDI Name Reply Queue has a value, this queue is used to monitor the results. Yes Matching of request and reply is done with the message id of the request with the correlation id of the reply. If the JNDI Name Reply Queue is empty, then temporary queues will be used for the communication between the requestor and the server. This is very different from the fixed reply queue. With temporary queues the diffent threads will block until the reply message has been received. If this is selected, then the request message id is used as the correlation id. Otherwise, the correlation id needs to be specified in the request. Yes

Use Request Message Id As Correlation Id Timeout

The timeout in milliseconds for the reply-messages. If a reply has not been received within the specified time, the Yes specific testcase failes and the specific reply message received after the timeout is discarded. Yes No

Use non-persistent Whether to set DeliveryMode.NON_PERSISTENT. delivery mode? Content JMS Properties Initial Context Factory JNDI properties The content of the message.

The JMS Properties are properties specific for the underlying messaging system. For example: for No WebSphere 5.1 web services you will need to set the JMS Property targetService to test webservices through JMS. The Initial Context Factory is the factory to be used to look up the JMS Resources. The JNDI Properties are the specific properties for the underlying JNDI implementation. No No

163

Jmeter 2.3.4 Users Manual

Provider URL

The URL for the jms provider.

No

19.1.16

JUnit Request

The current implementation supports standard Junit convention and extensions. It also includes extensions like oneTimeSetUp and oneTimeTearDown. The sampler works like the JavaSampler with some differences. 1. Rather than use Jmeter's test interface, it scans the jar files for classes extending junit's TestCase class. That includes any class or subclass. 2. Junit test jar files should be placed in jmeter/lib/junit instead of /lib directory. In versions of JMeter after 2.3.1, you can also use the "user.classpath" property to specify where to look for TestCase classes. 3. Junit sampler does not use name/value pairs for configuration like the JavaSampler. The sampler assumes setUp and tearDown will configure the test correctly. 4. The sampler measures the elapsed time only for the test method and does not include setUp and tearDown. 5. Each time the test method is called, Jmeter will pass the result to the listeners. 6. Support for oneTimeSetUp and oneTimeTearDown is done as a method. Since Jmeter is multi-threaded, we cannot call oneTimeSetUp/oneTimeTearDown the same way Maven does it. 7. The sampler reports unexpected exceptions as errors. There are some important differences between standard JUnit test runners and JMeter's implementation. Rather than make a new instance of the class for each test, JMeter creates 1 instance per sampler and reuses it. The current implementation of the sampler will try to create an instance using the string constructor first. If the test class does not declare a string constructor, the sampler will look for an empty constructor. Example below: Empty Constructor: public class myTestCase { public myTestCase() {} } String Constructor: public class myTestCase { public myTestCase(String text) { super(text); } }

164

Jmeter 2.3.4 Users Manual

By default, Jmeter will provide some default values for the success/failure code and message. Users should define a set of unique success and failure codes and use them uniformly across all tests. General Guidelines If you use setUp and tearDown, make sure the methods are declared public. If you do not, the test may not run properly. Here are some general guidelines for writing Junit tests so they work well with Jmeter. Since Jmeter runs multi-threaded, it is important to keep certain things in mind. 1. Write the setUp and tearDown methods so they are thread safe. This generally means avoid using static memebers. 2. Make the test methods discrete units of work and not long sequences of actions. By keeping the test method to a descrete operation, it makes it easier to combine test methods to create new test plans. 3. Avoid making test methods depend on each other. Since Jmeter allows arbitrary sequencing of test methods, the runtime behavior is different than the default Junit behavior. 4. If a test method is configurable, be careful about where the properties are stored. Reading the properties from the Jar file is recommended. 5. Each sampler creates an instance of the test class, so write your test so the setup happens in oneTimeSetUp and oneTimeTearDown. Control Panel

165

Jmeter 2.3.4 Users Manual

Parameters Attribute Name Package filter Class name Constructor string Description Descriptive name for this element that is shown in the tree. Comma separated list of packages to show. Example, org.apache.jmeter,junit.framework. Fully qualified name of the JUnit test class. String pass to the string constructor. If a string is set, the sampler will use the string constructor instead of the empty constructor. Required No No Yes No Yes No No No

Test method The method to test. Success message Failure message A descriptive message indicating what success means.

Success code An unique code indicating the test was successful. A descriptive message indicating what failure means.

166

Jmeter 2.3.4 Users Manual

Failure code An unique code indicating the test failed. Error message Error code Do not call setUp and tearDown Append assertion errors Append runtime exceptions A description for errors. Some code for errors. Does not need to be unique.

No No No

Set the sampler not to call setUp and tearDown. By default, setUp and tearDown should be called. Not calling those methods could affect the test and make it inaccurate. This Yes option should only be used with calling oneTimeSetUp and oneTimeTearDown. If the selected method is oneTimeSetUp or oneTimeTearDown, this option should be checked. Whether or not to append assertion errors to the response message. Whether or not to append runtime exceptions to the response message. Only applies if "Append assertion errors" is not selected. Yes

19.1.17

Mail Reader Sampler

The Mail Reader Sampler can read (and optionally delete) mail messages using POP3(S) or IMAP(S) protocols. The sampler requires the JavaMail and JAF jars to be available on the classpath. To use POP3S or IMAPS requires a recent version of JavaMail (e.g. JavaMail 1.4.1 and JAF 1.1.1). Control Panel

167

Jmeter 2.3.4 Users Manual

Parameters Attribute Name Server Type Server Username Password Folder Description Descriptive name for this element that is shown in the tree. The protocol used by the server: POP3, POP3S, IMAP, IMAPS Hostname or IP address of the server User login name User login password (N.B. this is stored unencrypted in the test plan) The IMAP(S) folder to use Required No Yes Yes No No Yes, if using IMAP(S) Yes Yes

Number of Set this to retrieve all or some messages messages to retrieve Delete messages from the server Store the message using MIME If set, messages will be deleted after retrieval

Whether to store the message as MIME. If not, Yes fewer headers are stored (Date, To, From, Subject).

168

Jmeter 2.3.4 Users Manual

19.1.18

Test Action

The Test Action sampler is a sampler that is intended for use in a conditional controller. Rather than generate a sample, the test element eithers pauses or stops the selected target. This sampler can also be useful in conjunction with the Transaction Controller, as it allows pauses to be included without needing to generate a sample. For variable delays, set the pause time to zero, and add a Timer as a child. The "Stop" action stops the thread or test after completing any samples that are in progress. The "Stop Now" action stops the test without waiting for samples to complete; it will interrupt any active samples. If some threads fail to stop within the 5 second timelimit, a message will be displayed in GUI mode. You can try using the Stop command to see if this will stop the threads, but if not, you should exit JMeter. In non-GUI mode, JMeter will exit if some threads fail to stop within the 5 second time limit. [This can be changed using the JMeter property jmeterengine.threadstop.wait] Control Panel

Parameters Attribute Name Target Action Description Descriptive name for this element that is shown in the No tree. Current Thread / All Threads (ignored for Pause) Pause / Stop / Stop Now Yes Yes Yes, if Pause is selected Required

Duration How long to pause for (milliseconds)

19.2 Logic Controllers

Logic Controllers determine the order in which Samplers are processed.

169

Jmeter 2.3.4 Users Manual

19.2.1

Simple Controller

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

Parameters Attribute Name Description Required

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

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

Figure 6 Simple Controller Example

170

Jmeter 2.3.4 Users Manual

19.2.2

Loop Controller

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

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

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

171

Jmeter 2.3.4 Users Manual

We configured the Thread Group for a single thread and a loop count value of one. Instead of letting the Thread Group control the looping, we used a Loop Controller. You can see that we added one HTTP Request to the Thread Group and another HTTP Request to a Loop Controller. We configured the Loop Controller with a loop count value of five. JMeter will send the requests in the following order: Home Page, News Page, News Page, News Page, News Page, and News Page. Note, the File Reporter is configured to store the results in a file named "loop-test.dat" in the current directory.

19.2.3

Once Only Controller

The Once Only Logic Controller tells JMeter to process the controller(s) inside it only once, and pass over any requests under it during further iterations through the test plan. The Once Only Controller will now execute always during the first iteration of any looping parent controller. Thus, if the Once Only Controller is placed under a Loop Controller specified to loop 5 times, then the Once Only Controller will execute only on the first iteration through the Loop Controller (ie, every 5 times). Note this means the Once Only Controller will still behave as previously expected if put under a Thread Group (runs only once per test), but now the user has more flexibility in the use of the Once Only Controller. For testing that requires a login, consider placing the login request in this controller since each thread only needs to login once to establish a session. Control Panel

Parameters Attribute Name Description Required

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

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

172

Jmeter 2.3.4 Users Manual

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.

19.2.4

Interleave Controller

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

Parameters Attribute name Description Required

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

If checked, the interleave controller will treat sub-controllers ignore sublike single request elements and only allow one request per No controller blocks controller at a time. Simple Interleave Example Download this example (see Figure 1). In this example, we configured the Thread Group to have two threads and a loop count of five, for a total of ten requests per thread. See the table below for the sequence JMeter sends the HTTP Requests.

173

Jmeter 2.3.4 Users Manual

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

174

Jmeter 2.3.4 Users Manual

will send the requests in the following order: Home Page, Interleaved, Bug Page, Interleaved, CVS Page, Interleaved, and FAQ Page, Interleaved. Note, the File Reporter is configured to store the results in a file named "interleave-test2.dat" in the current directory.

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.

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

175

Jmeter 2.3.4 Users Manual

Attribute Name

Description

Required

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

19.2.6

Random Order Controller

The Random Order Controller is much like a Simple Controller in that it will execute each child element at most once, but the order of execution of the nodes will be random. Control Panel

Parameters Attribute Name Description Required

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

19.2.7

Throughput Controller

This controller is badly named, as it does not control throughput. Please refer to the Constant Throughput Timer for an element that can be used to adjust the throughput. The Throughput Controller allows the user to control how often it is executed. There are two modes - percent execution and total executions. Percent executions cause the controller to execute a certain percentage of the iterations through the test plan. Total executions cause the controller to stop executing after a certain number of executions have occurred. Like the Once Only Controller, this setting is reset when a parent Loop Controller restarts. Control Panel

176

Jmeter 2.3.4 Users Manual

The Throughput Controller can yield very complex behavior when combined with other controllers - in particular with interleave or random controllers as parents (also very useful). Parameters Attribute Name Execution Style Description Descriptive name for this controller that is shown in the tree. Whether the controller will run in percent executions or total executions mode. Required No Yes

A number. for percent execution mode, a number from 0-100 that indicates the percentage of times the controller will execute. Throughput "50" means the controller will execute during half the iterations Yes throught the test plan. for total execution mode, the number indicates the total number of times the controller will execute. If checked, per user will cause the controller to calculate whether it should execute on a per user (per thread) basis. if unchecked, then the calculation will be global for all users. for example, if using total execution mode, and uncheck "per user", then the No 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.

Per User

19.2.8

Runtime Controller

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

177

Jmeter 2.3.4 Users Manual

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

19.2.9

If Controller

The If Controller allows the user to control whether the test elements below it (its children) are run or not. Prior to JMeter 2.3RC3, the condition was evaluated for every runnable element contained in the controller. This sometimes caused unexpected behaviour, so 2.3RC3 was changed to evaluate the condition only once on initial entry. However, the original behaviour is also useful, so versions of JMeter after 2.3RC4 have an additional option to select the original behaviour. Versions of JMeter after 2.3.2 allow the script to be processed as a variable expression, rather than requiring Javascript. It was always possible to use functions and variables in the Javascript condition, so long as they evaluated to "true" or "false"; now this can be done without the overhead of using Javascript as well. For example, previously one could use the condition: ${__jexl(${VAR} == 23)} and this would be evaluated as true/false, the result would then be passed to Javascript which would then return true/false. If the Variable Expression option is selected, then the expression is evaluated and compared with "true", without needing to use Javascript. Also, variable expressions can return any value, whereas the Javascript condition must return "true"/"false" or an error is logged. No variables are made available to the script when the condition is interpreted as Javascript. If you need access to such variables, then select "Interpret Condition as Variable Expression?" and use a __javaScript() function call. You can then use the objects "vars", "log", "ctx" etc. in the script. Control Panel

178

Jmeter 2.3.4 Users Manual

Parameters Attribute Name Condition (default Javascript) Interpret Condition as Variable Expression? Evaluate for all children Description Descriptive name for this controller that is shown in the tree. By default the condition is interpreted as Javascript code that returns "true" or "false", but this can be overriden (see below) Required No Yes

If this is selected, then the condition must be an expression that evaluates to "true" (case is ignored). For example, Yes ${FOUND} or ${__jexl(${VAR} > 100)} . Unlike the Javascript case, the condition is only checked to see if it matches "true" (case is ignored). Should condition be evaluated for all children? If not checked, then the condition is only evaluated on entry. Yes

Examples (Javascript):

${COUNT} < 10 "${VAR}" == "abcd" ${JMeterThread.last_sample_ok} (check if last sample succeeded)

If there is an error interpreting the code, the condition is assumed to be false, and a message is logged in jmeter.log. Examples (Variable Expression):

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

19.2.10

hile Controller

The While Controller runs its children until the condition is "false". Possible condition values:

179

Jmeter 2.3.4 Users Manual

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

The condition can be any variable or function that eventually evaluates to the string "false". This allows the use of JavaScript, BeanShell, properties or variables as needed. For example:

${VAR} - where VAR is set to false by some other test element ${__javaScript(${C}==10)} ${__javaScript("${VAR2}"=="abcd")} ${_P(property)} - where property is set to "false" somewhere else

Control Panel

Parameters Attribute Name Description Descriptive name for this controller that is shown in the tree, and used to name the transaction. Required Yes Yes

Condition blank, LAST, or variable/function

19.2.11

Switch Controller

The Switch Controller acts like the Interleave Controller in that it runs one of the subordinate elements on each iteration, but rather than run them in sequence, the controller runs the element defined by the switch value. Note: In versions of JMeter after 2.3.1, the switch value can also be a name. If the switch value is out of range, it will run the zeroth element, which therefore acts as the default for the numeric case. It also runs the zeroth element if the value is the empty string.

180

Jmeter 2.3.4 Users Manual

If the value is non-numeric (and non-empty), then the Switch Controller looks for the element with the same name (case is significant). If none of the names match, then the element named "default" (case not significant) is selected. If there is no default, then no element is selected, and the controller will not run anything. Control Panel

Parameters Attribute Name Switch Value Description Required

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

19.2.12

ForEach Controller

A ForEach controller loops through the values of a set of related variables. When you add samplers (or controllers) to a ForEach controller, every sample sample (or controller) is executed one or more times, where during every loop the variable has a new value. The input should consist of several variables, each extended with an underscore and a number. Each such variable must have a value. So for example when the input variable has the name inputVar, the following variables should have been defined:

inputVar_1 = wendy inputVar_2 = charles inputVar_3 = peter inputVar_4 = john

Note: the "_" separator is now optional. When the return variable is given as "returnVar", the collection of samplers and controllers under the ForEach controller will be executed 4 consecutive times, with the return variable having the respective above values, which can then be used in the samplers.

181

Jmeter 2.3.4 Users Manual

It is especially suited for running with the regular expression post-processor. This can "create" the necessary input variables out of the result data of a previous request. By omitting the "_" separator, the ForEach Controller can be used to loop through the groups by using the input variable refName_g, and can also loop through all the groups in all the matches by using an input variable of the form refName_${C}_g, where C is a counter variable. The ForEach Controller does not run any samples if inputVar_1 is null. This would be the case if the Regular Expression returned no matches. Control Panel

Parameters Attribute Name Input variable prefix Output variable Use Separator Description Required

Descriptive name for this controller that is shown in the tree. No Prefix for the variable names to be used as input. The name of the variable which can be used in the loop for replacement in the samplers If not checked, the "_" separator is omitted. Yes Yes 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.

182

Jmeter 2.3.4 Users Manual

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

183

Jmeter 2.3.4 Users Manual

The Regex Extractor uses the expression (\w)\s which matches a letter followed by a space, and returns the letter (not the space). Any matches are prefixed with the string "inputVar". The ForEach Controller extracts all variables with the prefix "inputVar_", and executes its sample, passing the value in the variable "returnVar". In this case it will set the variable to the values "a" "b" and "c" in turn. The For 1 Sampler is another Java Sampler which uses the return variable "returnVar" as part of the sample Label and as the sampler Data. Sample 2, Regex 2 and For 2 are almost identical, except that the Regex has been changed to "(\w)\sx", which clearly won't match. Thus the For 2 Sampler will not be run.

19.2.13

Module Controller

The Module Controller provides a mechanism for substituting test plan fragments into the current test plan at run-time. A test plan fragment consists of a Controller and all the test elements (samplers etc) contained in it. The fragment can be located in any Thread Group, or on the WorkBench . If the fragment is located in a Thread Group, then its Controller can be disabled to prevent the fragment being run except by the Module Controller. Or you can store the fragments in a dummy Thread Group, and disable the entire Thread Group. There can be multiple fragments, each with a different series of samplers under them. The module controller can then be used to easily switch between these multiple test cases simply by choosing the appropriate controller in its drop down box. This provides convenience for running many alternate test plans quickly and easily. A fragment name is made up of the Controller name and all its parent names. For example:
Test Plan / Protocol: JDBC / Control / Interleave Controller (Module1)

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

184

Jmeter 2.3.4 Users Manual

The Module Controller should not be used with remote testing or non-gui testing in conjunction with Workbench components since the Workbench test elements are not part of test plan .jmx files. Any such test will fail. Parameters Attribute Name Module to Run Description Descriptive name for this controller that is shown in the tree. The module controller provides a list of all controllers loaded into the gui. Select the one you want to substitute in at runtime. Required No Yes

19.2.14

Include Controller

The include controller is designed to use an external jmx file. To use it, add samples to a simple controller, then save the simple controller as a jmx file. The file can then be used in a test plan. The included test plan must not include a Thread Group. It should only contain the Simple Controller and any samplers, controllers etc below it. If the test uses a Cookie Manager or User Defined Variables, these should be placed in the top-level test plan, not the included file, otherwise they are not guaranteed to work. This element does not support variables/functions in the filename field. However, if the property includecontroller.prefix is defined, the contents are used to prefix the pathname. Control Panel

185

Jmeter 2.3.4 Users Manual

Parameters Attribute Description Required

Filename The file to include. Yes

19.2.15

Transaction Controller

The Transaction Controller generates an additional sample which measures the overall time taken to perform the nested test elements. Note that this time includes all processing within the controller scope, not just the samples. For JMeter versions after 2.3, there are two modes of operation

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

The generated sample time includes all the times for the nested samplers, and any timers etc. Depending on the clock resolution, it may be slightly longer than the sum of the individual samplers plus timers. The clock might tick after the controller recorded the start time but before the first sample starts. Similarly at the end. The generated sample is only regarded as successful if all its sub-samples are successful. In parent mode, the individual samples can still be seen in the Tree View Listener, but no longer appear as separate entries in other Listeners. Also, the sub-samples do not appear in CSV log files, but they can be saved to XML files. In parent mode, Assertions (etc) can be added to the Transaction Controller. However by default they will be applied to both the individual samples and the overall transaction sample. To limit the scope of the Assertions, use a Simple Controller to contain the samples, and add the Assertions to the Simple Controller. Parent mode controllers do not currently properly support nested transaction controllers of either type. Control Panel

186

Jmeter 2.3.4 Users Manual

Parameters Attribute Name Description Descriptive name for this controller that is shown in the tree, and used to name the transaction. Required Yes

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

19.2.16

Recording Controller

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

Parameters Description Required Attribute Name Descriptive name for this controller that is shown in the tree. No

19.3 Listeners
Most of the listeners perform several roles in addition to "listening" to the test results. They also provide means to view, save, and read saved test results. Note that Listeners are processed at the end of the scope in which they are found. The saving and reading of test results is generic. The various listeners have a panel whereby one can specify the file to which the results will be written (or read from). By

187

Jmeter 2.3.4 Users Manual

default, the results are stored as XML files, typically with a ".jtl" extension. Storing as CSV is the most efficient option, but is less detailed than XML (the other available option). Listeners do not process sample data in non-GUI mode, but the raw data will be saved if an output file has been configured. In order to analyse the data generated by a non-GUI test run, you need to load the file into the appropriate Listener. To read existing results and display them, use the file panel Browse button to open the file. Versions of JMeter up to 2.3.2 used to clear any current data before loading the new file. This is no longer done, thus allowing files to be merged . If the previous behaviour is required, use the menu item Run/Clear (Ctrl+Shift+E) or Run/Clear All (Ctrl+E) before loading the file. Results can be read from XML or CSV format files. When reading from CSV results files, the header (if present) is used to determine which fields are present. In order to interpret a header-less CSV file correctly, the appropriate properties must be set in jmeter.properties. The file name can contain function and/or variable references. However variable references do not work in client-server mode (functions work OK). Listeners can use a lot of memory if there are a lot of samples. Most of the listeners currently keep a copy of every sample in their scope, apart from:

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.

188

Jmeter 2.3.4 Users Manual

The entries in jmeter.properties are used to define the defaults; these can be overriden for individual listeners by using the Configure button, as shown below. The settings in jmeter.properties also apply to the listener that is added by using the -l commandline flag. The figure below shows an example of the result file configuration panel

Result file configuration panel

Parameters Attribute File Name Errors Successes Description Name of the file containing sample results Required No No No No No

Browse... File Browse Button Select this to write/read only results with errors Select this to write/read only results without errors. If neither Errors nor Successes is selected, then all results are processed.

Configure Configure Button, see below

19.3.1

Sample Result Save Configuration

Listeners can be configured to save different items to the result log files (JTL) by using the Config popup as shown below. The defaults are defined as described in the Listener Default Configuration documentation. Items with (CSV) after the name only apply to the CSV format; items with (XML) only apply to XML format. CSV format cannot currently be used to save any items that include line-breaks. Note that cookies, method and the query string are saved as part of the "Sampler Data" option. Control Panel

189

Jmeter 2.3.4 Users Manual

19.3.2

Graph Full Results

No Description Control Panel

19.3.3

Graph Results

The Graph Results listener generates a simple graph that plots all sample times. Along the bottom of the graph, the current sample (black), the current average of all samples

190

Jmeter 2.3.4 Users Manual

(blue), the current standard deviation (red), and the current throughput rate (green) are displayed in milliseconds. The throughput number represents the actual number of requests/minute the server handled. This calculation includes any delays you added to your test and JMeter's own internal processing time. The advantage of doing the calculation like this is that this number represents something real - your server in fact handled that many requests per minute, and you can increase the number of threads and/or decrease the delays to discover your server's maximum throughput. Whereas if you made calculations that factored out delays and JMeter's processing, it would be unclear what you could conclude from that number. Control Panel

The following table briefly describes the items on the graph. Further details on the precise meaning of the statistical terms can be found on the web - e.g. Wikipedia - or by consulting a book on statistics.

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

Jmeter 2.3.4 Users Manual

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

19.3.4

Spline Visualizer

The Spline Visualizer provides a view of all sample times from the start of the test till the end, regardless of how many samples have been taken. The spline has 10 points, each representing 10% of the samples, and connected using spline logic to show a single continuous line. The graph is automatically scaled to fit within the window. This needs to be borne in mind when comparing graphs. Control Panel

19.3.5

Assertion Results

The Assertion Results visualizer shows the Label of each sample taken. It also reports failures of any Assertions that are part of the test plan.

192

Jmeter 2.3.4 Users Manual

Control Panel

See Also:

Response Assertion

19.3.6

View Results Tree

The View Results Tree shows a tree of all sample responses, allowing you to view the response for any sample. In addition to showing the response, you can see the time it took to get this response, and some response codes. Note that the Request panel only shows the headers added by JMeter. It does not show any headers (such as Host) that may be added by the HTTP protocol implementation. There are several ways to view the response, selectable by a 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 contenttype begins with any of the following, it is considered as binary, otherwise it is considered to be text.
image/ audio/ video/

193

Jmeter 2.3.4 Users Manual

If there is no content-type provided, then the content will not be displayed in the any of the Response Data panels. You can use Save Responses to a file to save the data in this case. Note that the response data will still be available in the sample result, so can still be accessed using Post-Processors. If the response data is larger than 200K, then it won't be displayed. To change this limit, set the JMeter property view.results.tree.max_size . You can also use save the entire response to a file using Save Responses to a file . The HTML view attempts to render the response as HTML. The rendered HTML is likely to compare poorly to the view one would get in any web browser; however, it does provide a quick approximation that is helpful for initial result evaluation. If the "Download embedded resources" check-box is selected, the renderer may download images and style-sheets etc referenced by the HTML. If the checkbox is not selected, the renderer will not download images etc. The Render XML view will show response in tree style. Any DTD nodes or Prolog nodes will not show up in tree; however, response may contain those nodes. The Render JSON view will show the response in tree style (also handles JSON embedded in JavaScript). Control Panel

194

Jmeter 2.3.4 Users Manual

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

195

Jmeter 2.3.4 Users Manual

Figure 9 Sample XML display

19.3.7

Aggregate Report

The aggregate report creates a table row for each differently named request in your test. For each request, it totals the response information and provides request count, min, max, average, error rate, approximate throughput (request/second) and Kilobytes per second throughput. Once the test is done, the throughput is the actual through for the duration of the entire test. The thoughput is calculated from the point of view of the sampler target (e.g. the remote server in the case of HTTP samples). JMeter takes into account the total time over which the requests have been generated. If other samplers and timers are in the same thread, these will increase the total time, and therefore reduce the throughput value. So two identical samplers with different names will have half the throughput of two samplers with the same name. It is important to choose the sampler names correctly to get the best results from the Aggregate Report. Calculation of the Median and 90% Line (90 th percentile ) values requires a lot of memory as details of every Sample have to be saved. See the Summary Report for a similar Listener that does not need so much memory.

196

Jmeter 2.3.4 Users Manual

Label - The label of the sample. If "Include group name in label?" is selected, then the name of the thread group is added as a prefix. This allows identical labels from different thread groups to be collated separately if required. # Samples - The number of samples with the same label Average - The average time of a set of results Median - The median is the time in the middle of a set of results. 50% of the samples took no more than this time; the remainder took at least as long. 90% Line - 90% of the samples took no more than this time. The remaining samples at least as long as this. (90 th percentile ) Min - The shortest time for the samples with the same label Max - The longest time for the samples with the same label Error % - Percent of requests with errors Throughput - the Throughput is measured in requests per second/minute/hour. The time unit is chosen so that the displayed rate is at least 1.0. When the throughput is saved to a CSV file, it is expressed in requests/second, i.e. 30.0 requests/minute is saved as 0.5. Kb/sec - The throughput measured in Kilobytes per second

Times are in milliseconds. Control Panel

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

197

Jmeter 2.3.4 Users Manual

Sample "Include group name" display

19.3.8

View Results in Table

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

198

Jmeter 2.3.4 Users Manual

19.3.9

Simple Data Writer

This listener can record results to a file but not to the UI. It is meant to provide an efficient means of recording data by eliminating GUI overhead. When running in nonGUI 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 199

Jmeter 2.3.4 Users Manual

19.3.10

Monitor Results

Monitor Results is a new Visualizer for displaying server status. It is designed for Tomcat 5, but any servlet container can port the status servlet and use this monitor. There are two primary tabs for the monitor. The first is the "Health" tab, which will show the status of one or more servers. The second tab labled "Performance" shows the performance for one server for the last 1000 samples. The equations used for the load calculation is included in the Visualizer. Currently, the primary limitation of the monitor is system memory. A quick benchmark of memory usage indicates a buffer of 1000 data points for 100 servers would take roughly 10Mb of RAM. On a 1.4Ghz centrino laptop with 1Gb of ram, the monitor should be able to handle several hundred servers. As a general rule, monitoring production systems should take care to set an appropriate interval. Intervals shorter than 5 seconds are too aggressive and have a potential of impacting the server. With a buffer of 1000 data points at 5 second intervals, the monitor would check the server status 12 times a minute or 720 times a hour. This means the buffer shows the performance history of each machine for the last hour. The monitor requires Tomcat 5 or above. Use a browser to check that you can access the Tomcat status servlet OK. For a detailed description of how to use the monitor, please refer to Building a Monitor Test Plan Control Panel

200

Jmeter 2.3.4 Users Manual

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

201

Jmeter 2.3.4 Users Manual

the 50% and 90% line were within the width of the graph. A performant application will generally produce results that clump together. A poorly written application that has memory leaks may result in wild fluctuations. In those situations, the threshold lines may be beyond the width of the graph. The recommended solution to this specific problem is fix the webapp so it performs well. If your test plan produces distribution graphs with no apparent clumping or pattern, it may indicate a memory leak. The only way to know for sure is to use a profiling tool. Control Panel

19.3.12

Aggregate Graph

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

202

Jmeter 2.3.4 Users Manual

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

203

Jmeter 2.3.4 Users Manual

The Mailer Visualizer requires the optional Javamail jars (activation.jar and mail.jar). If these are not present in the lib directory, the element will not appear in the menus. Parameters Attribute Name From SMTP Host Failure Subject Success Subject Description Descriptive name for this element that is shown in the tree. Email address to send messages from. IP address or host name of SMTP (email redirector) server. Email subject line for fail messages. Email subject line for success messages. Required No Yes Yes No No No Yes

Addressee(s) Email address to send messages to, comma-separated.

Once this number of failed responses is exceeded, a failure Failure Limit email is sent - i.e. set the count to 0 to send an e-mail on the first failure. Success Limit Test Mail Failures 204

Once this number of successful responses is exceeded after previously reaching the failure limit , a success email is sent. Yes The mailer will thus only send out messages in a sequence of failed-succeeded-failed-succeeded, etc. Press this button to send a test mail A field that keeps a running total of number of failures so far No No

Jmeter 2.3.4 Users Manual

received.

19.3.14

BeanShell Listener

The BeanShell Listener allows the use of BeanShell for processing samples for saving etc. For full details on using BeanShell, please see the BeanShell 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 Name Reset bsh.Interpreter before each call Parameters Description Required Descriptive name for this element that is shown in the No tree. If this option is selected, then the interpreter will be recreated for each sample. This may be necessary for Yes some long running scripts. For further information, see Best Practices - BeanShell scripting . Parameters to pass to the BeanShell script. The parameters are stored in the following variables: No

205

Jmeter 2.3.4 Users Manual

Parameters - string containing the parameters as a single variable bsh.args - String array containing parameters, split on white-space No Yes (unless script file is provided)

Script file Script

A file containing the BeanShell script to run The BeanShell script to run. The return value is ignored.

Before invoking the script, some variables are set up in the BeanShell interpreter:

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.

19.3.15

Summary Report

The summary report creates a table row for each differently named request in your test. This is similar to the Aggregate Report , except that it uses less memory. The thoughput is calculated from the point of view of the sampler target (e.g. the remote server in the case of HTTP samples). JMeter takes into account the total time over which the requests have been generated. If other samplers and timers are in the same thread, these will increase the total time, and therefore reduce the throughput value. So two identical samplers with different names will have half the throughput of two samplers with the same name. It is important to choose the sampler labels correctly to get the best results from the Report.

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

206

Jmeter 2.3.4 Users Manual

Average - The average elapsed time of a set of results Min - The lowest elapsed time for the samples with the same label Max - The longest elapsed time for the samples with the same label Std. Dev. - the Standard Deviation of the sample elapsed time Error % - Percent of requests with errors Throughput - the Throughput is measured in requests per second/minute/hour. The time unit is chosen so that the displayed rate is at least 1.0. When the throughput is saved to a CSV file, it is expressed in requests/second, i.e. 30.0 requests/minute is saved as 0.5. Kb/sec - The throughput measured in Kilobytes per second Avg. Bytes - average size of the sample response in bytes. (in JMeter 2.2 it wrongly showed the value in kB)

Times are in milliseconds. Control Panel

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

207

Jmeter 2.3.4 Users Manual

Sample "Include group name" display

19.3.16

Save Responses to a file

This test element can be placed anywhere in the test plan. For each sample in its scope, it will create a file of the response Data. The primary use for this is in creating functional tests, but it can also be useful where the response is too large to be displayed in the View Results Tree Listener. The file name is created from the specified prefix, plus a number (unless this is disabled, see below). The file extension is created from the document type, if known. If not known, the file extension is set to 'unknown'. If numbering is disabled, and adding a suffix is disabled, then the file prefix is taken as the entire file name. This allows a fixed file name to be generated if required. The generated file name is stored in the sample response, and can be saved in the test log output file if required. The current sample is saved first, followed by any sub-samples (child samples). If a variable name is provided, then the names of the files are saved in the order that the subsamples appear. See below. Control Panel

208

Jmeter 2.3.4 Users Manual

Parameters Attribute Name Filename Prefix Description Descriptive name for this element that is shown in the tree. Required No

Prefix for the generated file names; this can include a directory Yes name. Name of a variable in which to save the generated file name (so it can be used later in the test plan). If there are sub-samples then a numeric suffix is added to the variable name. E.g. if the No variable name is FILENAME, then the parent sample file name is saved in the variable FILENAME, and the filenames for the child samplers are saved in FILENAME1, FILENAME2 etc. If selected, then only failed responses are saved Yes

Variable Name

Save Failed Responses only Save Successful Responses only Don't add number to prefix Don't add suffix

If selected, then only successful responses are saved

Yes

If selected, then no number is added to the prefix. If you select this option, make sure that the prefix is unique or the file may Yes be overwritten. If selected, then no suffix is added. If you select this option, make sure that the prefix is unique or the file may be overwritten. Yes

19.3.17

BSF Listener

The BSF Listener allows BSF script code to be applied to sample results. Control Panel 209

Jmeter 2.3.4 Users Manual

Parameters Attribute Name Description Descriptive name for this element that is shown in the No tree. Yes Parameters to pass to the script. The parameters are stored in the following variables: Parameters

Required

Language The BSF language to be used

Parameters - string containing the parameters No as a single variable args - String array containing parameters, split on white-space No Yes (unless script file is provided)

Script file A file containing the script to run. Script The script to run.

The script (or file) is processed using the BSFEngine.exec() method, which does not return a value. Before invoking the script, some variables are set up. Note that these are BSF variables i.e. they can be used directly in the script.

210

Jmeter 2.3.4 Users Manual

log - (Logger) - can be used to write to the log file Label - the String Label Filename - the script file name (if any) Parameters - the parameters (as a String) args[] - the parameters as a String array (split on whitespace) ctx - (JMeterContext) - gives access to the context vars - (JMeterVariables) - gives read/write access to variables: vars.get(key); vars.put(key,val); vars.putObject("OBJ1",new Object()); vars.getObject("OBJ2"); props - JMeter Properties - e.g. props.get("START.HMS"); props.put("PROP1","1234"); sampleResult, prev - (SampleResult) - gives access to the SampleResult sampleEvent - (SampleEvent) - gives access to the SampleEvent sampler - (Sampler)- gives access to the last 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

19.3.18

Generate Summary Results

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

The "label" is the the name of the element. The "+" means that the line is a delta line, i.e. shows the changes since the last output. The "=" means that the line is a totals line, i.e. it shows the running total. Entries in the jmeter log file also include time-stamps. The example "806 in 91.6s = 8.8/s" means that there were 806 samples recorded in 91.6 seconds, and that works out at 8.8 samples per second. The Avg (Average), Min(imum) and Max(imum) times are in milliseconds. "Err" means number of errors (also shown as

211

Jmeter 2.3.4 Users Manual

percentage). The last two lines will appear at the end of a test. They will not be synchronised to the appropriate time boundary. Note that the initial and final deltas may be for less than the interval (in the example above this is 30 seconds). The first delta will generally be lower, as JMeter synchronises to the interval boundary. The last delta will be lower, as the test will generally not finish on an exact interval boundary. The label is used to group sample results together. So if you have multiple Thread Groups and want to summarize across them all, then use the same label - or add the summariser to the Test Plan (so all thread groups are in scope). Different summary groupings can be implemented by using suitable labels and adding the summarisers to appropriate parts of the test plan. Control Panel

Parameters Attribute Name Description Required

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 Yes same label will be added together.

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

19.4.1

CSV Data Set Config

CSV Data Set Config is used to read lines from a file, and split them into variables. It is easier to use than the __CSVRead() and _StringFromFile() functions. It is well suited to handling large numbers of variables, and is also useful for tesing with "random" and unique values. Generating unique random values at run-time is expensive in terms of CPU and memory, so just create the data in advance of the test. If necessary, the "random" data from the file can be used in conjunction with a run-time parameter to create different sets of values from each run - e.g. using concatenation - which is much cheaper than generating everything at run-time.

212

Jmeter 2.3.4 Users Manual

Versions of JMeter after 2.3.1 allow variables to be quoted; this allows the value to contain a delimiter. Previously it was necessary to choose a delimiter that was not used in any values. By default, the file is only opened once, and each thread will use a different line from the file. However the order in which lines are passed to threads depends on the order in which they execute, which may vary between iterations. Lines are read at the start of each test iteration. The file name and mode are resolved in the first iteration. See the description of the Share mode below for additional options (JMeter 2.3.2+). If you want each thread to have its own set of values, then you will need to create a set of files, one for each thread. For example test1.csv, test2.csv,... testn.csv. Use the filename test${__threadNum}.csv and set the "Sharing mode" to "Current thread". CSV Dataset variables are defined at the start of each test iteration. As this is after configuration processing is completed, they cannot be used for some configuration items - such as JDBC Config - that process their contents at configuration time (see Bug 40394 ) However the variables do work in the HTTP Auth Manager, as the username etc are processed at run-time. As a special case, the string "\t" (without quotes) in the delimiter field is treated as a Tab. When the end of file (EOF) is reached, and the recycle option is true, reading starts again with the first line of the file. If the recycle option is false, and stopThread is false, then all the variables are set to <EOF> when the end of file is reached. This value can be changed by setting the JMeter property csvdataset.eofstring . If the Recycle option is false, and Stop Thread is true, then reaching EOF will cause the thread to be stopped. Control Panel

213

Jmeter 2.3.4 Users Manual

Parameters Attribute Name Description Descriptive name for this element that is shown in the tree. Required 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 Yes 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. The encoding to be used to read the file, if not the platform default. List of variable names (comma-delimited) No Yes

File Encoding Variable Names Delimiter Allow quoted data?

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 Yes variables are not updated - so they will retain their previous value (if any). Should the CSV file allow values to be quoted? Yes Yes

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

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

214

Jmeter 2.3.4 Users Manual

on EOF?

is false)

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

19.4.2
Control Panel

FTP Request Defaults

19.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 specify which one is to be used. The Authorization Manager lets you specify one or more user logins for web pages that are restricted using server authentication. You see this type of authentication when you use your browser to access a restricted page, and your browser displays a login dialog box. JMeter transmits the login information when it encounters this type of page. The Authorisation headers are not shown in the Tree View Listener. 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. 215

Jmeter 2.3.4 Users Manual

jmeter.properties: httpclient.parameters.file=httpclient.parameters httpclient.parameters: http.authentication.preemptive$Boolean=false

Note: the above settings only apply to the HttpClient sampler (and the SOAP samplers, which use Httpclient). When looking for a match against a URL, JMeter checks each entry in turn, and stops when it finds the first match. Thus the most specific URLs should appear first in the list, followed by less specific ones. Duplicate URLs will be ignored. If you want to use different usernames/passwords for different threads, you can use variables. These can be set up using a CSV Data Set Config Element (for example). Control Panel

Parameters Description Attribute Name Descriptive name for this element that is shown in the tree. 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". Required No

Base URL

Yes

Username The username to authorize. Password The password for the user.

Yes Yes

216

Jmeter 2.3.4 Users Manual

Domain Realm

The domain to use for NTLM. The realm to use for NTLM.

No 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

217

Jmeter 2.3.4 Users Manual

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.

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

218

Jmeter 2.3.4 Users Manual

19.4.5

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. Also, a cookie stored in one cookie manager is not available to any other manager, so use multiple Cookie Managers with care. 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. Note that such cookies do not appear on the Cookie Manager display, but they can be seen using the View Results Tree Listener. JMeter version 2.3.2 and earlier did not check that received cookies were valid for the URL. This meant that cross-domain cookies were stored, and might be used later. This has been fixed in later versions. To revert to the earlier behaviour, define the JMeter property "CookieManager.check.cookies=false". Received Cookies can be stored as JMeter thread variables (versions of JMeter after 2.3.2 no longer do this by default). To save cookies as variables, define the property "CookieManager.save.cookies=true". Also, cookies names are prefixed with "COOKIE_" before they are stored (this avoids accidental corruption of local variables) To revert to the original behaviour, define the property "CookieManager.name.prefix= " (one or more spaces). If enabled, the value of a cookie with the name TEST can be referred to as ${COOKIE_TEST}. Second, you can manually add a cookie to the Cookie Manager. However, if you do this, the cookie will be shared by all JMeter threads. Note that such Cookies are created with an Expiration time far in the future Since version 2.0.3, cookies with null values are ignored by default. This can be changed by setting the JMeter property: CookieManager.delete_null_cookies=false. Note that this also applies to manually defined cookies - any such cookies will be removed from the

219

Jmeter 2.3.4 Users Manual

display when it is updated. Note also that the cookie name must be unique - if a second cookie is defined with the same name, it will replace the first. Control Panel

Parameters Attribut e Name Description Descriptive name for this element that is shown in the tree. Required No

Clear If selected, all server-defined cookies are cleared each time the Cookies main Thread Group loop is executed. In JMeter versions after 2.3, Yes each any cookies defined in the GUI are not cleared. Iteration The cookie policy that will be used to manage the cookies. "compatibility" is the default, and should work in most cases. See http://jakarta.apache.org/httpcomponents/httpclient3.x/cookies.html and Yes http://jakarta.apache.org/httpcomponents/httpclient3.x/apidocs/org/apache/commons/httpclient/cookie/CookiePolicy. html [Note: "ignoreCookies" is equivalent to omitting the CookieManager.] No (discourage d, unless you know

Cookie Policy

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

220

Jmeter 2.3.4 Users Manual

what you're doing) Add Button Delete Button Load Button Add an entry to the cookie table. Delete the currently selected table entry. Load a previously saved cookie table and add the entries to the existing cookie table entries. N/A N/A N/A

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

19.4.6

HTTP Request Defaults

This element lets you set default values that your HTTP Request controllers use. For example, if you are creating a Test Plan with 25 HTTP Request controllers and all of the requests are being sent to the same server, you could add a single HTTP Request Defaults element with the "Server Name or IP" field filled in. Then, when you add the 25 HTTP Request controllers, leave the "Server Name or IP" field empty. The controllers will inherit this field value from the HTTP Request Defaults element. In JMeter 2.2 and earlier, port 80 was treated specially - it was ignored if the sampler used the https protocol. JMeter 2.3 and later treat all port values equally; a sampler that does not specify a port will use the HTTP Request Defaults port, if one is provided. Control Panel

221

Jmeter 2.3.4 Users Manual

Parameters Attribute Name Server Port Connect Timeout Response Timeout Protocol Method Description Descriptive name for this controller that is shown in the tree. Domain name or IP address of the web server. e.g. www.example.com. [Do not include the http:// prefix. Port the web server is listening to. Connection Timeout. Number of milliseconds to wait for a connection to open. Requires Java 1.5 or later when using the default Java HTTP implementation. Response Timeout. Number of milliseconds to wait for a response. Requires Java 1.5 or later when using the default Java HTTP implementation. HTTP or HTTPS. HTTP GET or HTTP POST. Required No No No No

No Yes 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 No path is the default for the full path, not a prefix to be applied to paths specified on the HTTP Request screens. The query string will be generated from the list of parameters No

Send 222

Jmeter 2.3.4 Users Manual

Parameters With the Request

you provide. Each parameter has a name and value . The query string will be generated in the correct fashion, depending on the choice of "Method" you made (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.

19.4.7

HTTP Header Manager

The Header Manager lets you add or override HTTP request headers. Versions of JMeter up to 2.3.2 supported only one Header Manager per sampler; if there were more in scope, then only the last one would be used. JMeter now supports multiple Header Managers. The header entries are merged to form the list for the sampler. If an entry to be merged matches an existing header name, it replaces the previous entry, unless the entry value is empty, in which case any existing entry is removed. This allows one to set up a default set of headers, and apply adjustments to particular samplers. Control Panel

Parameters Attribute Name Name (Header) Value Description Descriptive name for this element that is shown in the tree. No Required

Name of the request header. Two common request No (You should have headers you may want to experiment with are "Userat least one, however) Agent" and "Referer". Request header value. No (You should have at least one, however) N/A N/A N/A N/A

Add Button Add an entry to the header table. Delete Button Load Button Save As Button Delete the currently selected table entry. Load a previously saved header table and add the entries to the existing header table entries. Save the current header table to a file.

223

Jmeter 2.3.4 Users Manual

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

19.4.8

Java Request Defaults

The Java Request Defaults component lets you set default values for Java testing. See the Java Request . Control Panel

224

Jmeter 2.3.4 Users Manual

19.4.9

JDBC Connection Configuration

Create a database connection pool (used by JDBC Request Sampler) with JDBC Connection settings. Control Panel

225

Jmeter 2.3.4 Users Manual

Parameters Attribute Name Description Required

Descriptive name for the connection pool that is shown in the No tree. 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 Yes there are two configuration elements using the same pool name, only one will be saved. JMeter versions after 2.3 log a message if a duplicate name is detected. 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. Yes 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 pools can

Variable Name

Max Number of Connections

226

Jmeter 2.3.4 Users Manual

be used - e.g. for connecting to different databases - just give them different names. Pool timeout Idle Cleanup Interval (ms) Keep-alive Max Connection Age (ms) Validation Query JDBC Driver class Username Password Pool throws an error if the timeout period is exceeded in the process of trying to retrieve a connection Uncertain what exactly this does. Yes Yes Yes Yes Yes Yes Yes

Auto Commit Turn auto commit on or off for the connections. Uncertain what exactly this does. Uncertain what exactly this does. A simple query used to determine if the database is still responding.

Database URL JDBC Connection string for the database.

Fully qualified name of driver class. (Must be in JMeter's Yes classpath - easiest to copy .jar file into JMeter's /lib directory). Name of user to connect as. Password to connect with. No 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. If JMeter reports No suitable driver, then this could mean either:

The driver class was not found. In this case, there will be a log message such as
DataSourceElement: Could not load driver: {classname} java.lang.ClassNotFoundException: {classname}

The driver class was found, but the class does not support the connection string. This could be because of a syntax error in the connection string, or because the the wrong classname was used.

If the database server is not running or is not accessible, then JMeter will report a java.net.ConnectException.
Databas e MySQL PostgreS QL Oracle Driver class com.mysql.jdbc.Driver org.postgresql.Driver oracle.jdbc.driver.OracleDriver Database URL jdbc:mysql://host[:port]/dbname jdbc:postgresql:{dbname} jdbc:oracle:thin:@//host:port/service OR

227

Jmeter 2.3.4 Users Manual

Ingres (2006) SQL Server (MS JDBC driver) Apache Derby

ingres.jdbc.IngresDriver

jdbc:oracle:thin:@(description=(address=(host={m c-name})(protocol=tcp)(port={portno}))(connect_data=(sid={sid}))) jdbc:ingres://host:port/db[;attr=value]

com.microsoft.sqlserver.jdbc.SQLS jdbc:sqlserver://host:port;DatabaseName=dbname erverDriver

org.apache.derby.jdbc.ClientDriver jdbc:derby://server[:port]/databaseName[;URLAttri butes=value[;...]]

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

19.4.10

Login Config Element

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

Parameters Attribute Name Description Required No No

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

Username The default username to use. Password The default password to use.

19.4.11

LDAP Request Defaults

The LDAP Request Defaults component lets you set default values for LDAP testing. See the LDAP Request . Control Panel

228

Jmeter 2.3.4 Users Manual

19.4.12

LDAP Extended Request Defaults

The LDAP Extended Request Defaults component lets you set default values for extended LDAP testing. See the LDAP Extended Request . Control Panel

229

Jmeter 2.3.4 Users Manual

19.4.13

TCP Sampler Config

The TCP Sampler Config provides default data for the TCP Sampler Control Panel

230

Jmeter 2.3.4 Users Manual

Parameters Attribute Name TCPClient classname Port Number Re-use connection Timeout (milliseconds) Set Nodelay Text to Send Description Descriptive name for this element that is shown in the tree. Name of the TCPClient class. Defaults to the property tcp.handler, failing that TCPClientImpl. Port to be used If selected, the connection is kept open. Otherwise it is closed when the data has been read. Timeout for replies Should the nodelay property be set? Text to be sent Required No No No No Yes No No No

ServerName or IP Name or IP of TCP server

19.4.14

User Defined Variables

The User Defined Variables element lets you define an initial set of variables , just as in the Test Plan . Note that all the UDV elements in a test plan - no matter where they are - are processed at the start. So you cannot reference variables which are defined as part of a test run, e.g. in a Post-Processor. UDVs should not be used with functions that generate different results each time they are called. Only the result of the first function call will be saved in the variable. However, UDVs can be used with functions such as __P(), for example:

231

Jmeter 2.3.4 Users Manual

HOST

${__P(host,localhost)}

which would define the variable "HOST" to have the value of the JMeter property "host", defaulting to "localhost" if not defined. For defining variables during a test run, see User Parameters . UDVs are processed in the order they appear in the Plan, from top to bottom. For simplicity, it is suggested that UDVs are placed only at the start of a Thread Group (or perhaps under the Test Plan itself). Once the Test Plan and all UDVs have been processed, the resulting set of variables is copied to each thread to provide the initial set of variables. 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 UDV variables, then this will replace the initial value, and all other test elements in the thread will see the updated value. Control Panel

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

232

Jmeter 2.3.4 Users Manual

on the Test Plan. Parameters Attribute Name User Defined Variables Description Descriptive name for this element that is shown in the tree. Required No

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

19.4.15

Random Variable

The Random Variable Config Element is used to generate random numeric strings and store them in variable for use later. It's simpler than using User Defined Variables together with the __Random() function. The output variable is constructed by using the random number generator, and then the resulting number is formatted using the format string. The number is calculated using the formula minimum+Random.nextInt(maximum-minimum+1) . Random.nextInt() requires a positive integer. This means that maximum-minimum - i.e. the range - must be less than 2147483647, however the minimum and maximum values can be any long values so long as the range is OK. Control Panel

Parameters

233

Jmeter 2.3.4 Users Manual

Attribute Name Variable Name

Description Descriptive name for this element that is shown in the tree. The name of the variable in which to store the random string.

Required Yes Yes

The java.text.DecimalFormat format string to be used. For example "000" which will generate numbers with at least 3 Format String digits, or "USER_000" which will generate output of the form No USER_nnn. If not specified, the default is to generate the number using Long.toString() Minimum Value Maximum Value Random Seed The minimum value (long) of the generated random number. The maximum value (long) of the generated random number. The seed for the random number generator. Default is the current time in milliseconds. Yes Yes No Yes

If False, the generator is shared between all threads in the Per thread group. If True, then each thread has its own random Thread(User)? generator.

19.4.16

Counter

Allows the user to create a counter that can be referenced anywhere in the Thread Group. The counter config lets the user configure a starting point, a maximum, and the increment. The counter will loop from the start to the max, and then start over with the start, continuing on like that until the test is ended. From version 2.1.2, the counter now uses a long to store the value, so the range is from 2^63 to 2^63-1. Control Panel

234

Jmeter 2.3.4 Users Manual

Parameters Attribute Name Start Increment Maximum Description The starting number for the counter. The counter will equal this number during the first iteration. How much to increment the counter by after each iteration. Required

Descriptive name for this element that is shown in the tree. No Yes Yes

If the counter exceeds the maximum, then it is reset to the Start value. For versions after 2.2 the default is No Long.MAX_VALUE (previously it was 0). 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 No is ignored. [The default format is generated using Long.toString()] This controls how you refer to this value in other elements. Syntax is as in user-defined values : $(reference_name} . Yes

Format

Reference Name

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

19.4.17

Simple Config Element

The Simple Config Element lets you add or override arbitrary values in samplers. You can choose the name of the value and the value itself. Although some adventurous users

235

Jmeter 2.3.4 Users Manual

might find a use for this element, it's here primarily for developers as a basic GUI that they can use while developing new JMeter components. Control Panel

Parameters Attribute Name Parameter Name Parameter Value Description Descriptive name for this element that is shown in the tree. Required Yes

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

19.5 Assertions
Assertions are used to perform additional checks on samplers, and are processed after every sampler in the same scope. To ensure that an Assertion is applied only to a particular sampler, add it as a child of the sampler. Note: Unless documented otherwise, Assertions are not applied to sub-samples (child samples) - only to the parent sample. In the case of BSF and BeanShell Assertions, the script can retrieve sub-samples using the method prev.getSubResults() which returns an array of SampleResults. The array will be empty if there are none. Versions of JMeter after 2.3.2 include the option to apply certain assertions to either the main sample, the sub-samples or both. The default is to apply the assertion to the main sample only. If the Assertion supports this option, then there will be an entry on the GUI which looks like the following:

236

Jmeter 2.3.4 Users Manual

Assertion Scope

If a sub-sampler fails and the main sample is successful, then the main sample will be set to failed status and an Assertion Result will be added. The variable JMeterThread.last_sample_ok is set to "true" or "false" after all assertions for a sampler have been run.

19.5.1

Response Assertion

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

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

237

Jmeter 2.3.4 Users Manual

Parameters Attribute Name Description Descriptive name for this element that is shown in the tree. This is for use with samplers that can generate sub-samples, e.g. HTTP Sampler with embedded resources, Mail Reader or samples generated by the Transaction Controller. Which samples to test

Required No

Main sample only - assertion only applies to the main Yes sample Sub-samples only - assertion only applies to the subsamples Main sample and sub-samples - assertion applies to both.

Instructs JMeter which field of the Response to test. Response Field to Test

Text Response - the response text from the server, i.e. the Yes body, excluing any HTTP headers. URL sampled Response Code - e.g. 200 Response Message - e.g. OK

238

Jmeter 2.3.4 Users Manual

Response Headers, including Set-Cookie headers (if any)

Instructs JMeter to set the status to success initially. 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. Yes 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. Indicates how the text being tested is checked against the pattern.

Ignore status

Pattern Matching Rules

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)

Yes

Equals and Substring patterns are plain strings, not regular expressions. NOT may also be selected to invert the result of the check. 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 to patterns and setting up multiple Assertions with one pattern each Yes Test (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. The pattern is a Perl5-style regular expression, but without the enclosing brackets. Assertion Examples

239

Jmeter 2.3.4 Users Manual

Figure 14 - Test Plan

Figure 15 - Assertion Control Panel with Pattern

Figure 16 - Assertion Listener Results (Pass)

240

Jmeter 2.3.4 Users Manual

Figure 17 - Assertion Listener Results (Fail)

19.5.2

Duration Assertion

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

Parameters Attribute Name Duration in Milliseconds Description Descriptive name for this element that is shown in the tree. The maximum number of milliseconds each response is allowed before being marked as failed. Required No Yes

241

Jmeter 2.3.4 Users Manual

19.5.3

Size Assertion

The Size Assertion tests that each response contains the right number of bytes in it. You can specify that the size be equal to, greater than, less than, or not equal to a given number of bytes. Since JMeter 2.3RC3, an empty response is treated as being 0 bytes rather than reported as an error. Control Panel

Parameters Attribute Name Size in bytes Type of Comparison Description Descriptive name for this element that is shown in the tree. Required No

The number of bytes to use in testing the size of the response. Yes Whether to test that the response is equal to, greater than, less Yes than, or not equal to, the number of bytes specified.

19.5.4

XML Assertion

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

242

Jmeter 2.3.4 Users Manual

Control Panel

Parameters Attribute Name Description Required

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

19.5.5

BeanShell Assertion

The BeanShell Assertion allows the user to perform assertion checking using a BeanShell script. For full details on using BeanShell, please see the BeanShell 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

243

Jmeter 2.3.4 Users Manual

Parameters Attribute Name Reset bsh.Interpreter before each call Description Required

Descriptive name for this element that is shown in the No tree. If this option is selected, then the interpreter will be recreated for each sample. This may be necessary for Yes some long running scripts. For further information, see Best Practices - BeanShell scripting . Parameters to pass to the BeanShell script. The parameters are stored in the following variables:

Parameters

Parameters - string containing the parameters No as a single variable bsh.args - String array containing parameters, split on white-space No Yes (unless script file is provided)

Script file Script

A file containing the BeanShell script to run. This overrides the script. The BeanShell script to run. The return value is ignored.

There's a sample script you can try. Before invoking the script, some variables are set up in the BeanShell interpreter. These are strings unless otherwise noted: 244

Jmeter 2.3.4 Users Manual

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)

19.5.6

MD5Hex Assertion

The MD5Hex Assertion allows the user to check the MD5 hash of the response data. Control Panel

Parameters Attribute Name Description Descriptive name for this element that is shown in the tree. Required No

MD5 sum 32 hex digits representing the MD5 hash (case not significant) Yes

245

Jmeter 2.3.4 Users Manual

19.5.7

HTML Assertion

The HTML Assertion allows the user to check the HTML syntax of the response data using JTidy. Control Panel

Parameters Attribute Name doctype Format Errors only Error threshold Warning threshold Filename omit/auto/strict/loose HTML, XHTML or XML Only take note of errors? Number of errors allowed before classing the response as failed Number of warnings allowed before classing the response as failed Name of file to which report is written Description Descriptive name for this element that is shown in the tree. Required No Yes Yes Yes Yes Yes No

246

Jmeter 2.3.4 Users Manual

19.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 Name Tolerant Parser Quiet Report Errors Show warnings Use Namespaces Validate XML XPath Assertion Ignore Whitespace True if nothing matches Description Descriptive name for this element that is shown No in the tree. Be tolerant of XML/HTML errors (i.e. use Tidy) Sets the Tidy Quiet flag If a Tidy error occurs, then set the Assertion accordingly Sets the Tidy showWarnings option Should namespaces be honoured? Check the document against its schema. XPath to match in the document. Ignore Element Whitespace. True if a XPath expression is not matched Yes If tolerant is selected If tolerant is selected If tolerant is selected No No Yes No No Required

247

Jmeter 2.3.4 Users Manual

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

19.5.9

XML Schema Assertion

The XML Schema Assertion allows the user to validate a response against an XML Schema. Control Panel

Parameters Attribute Name Description Required Yes

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

File Name Specify XML Schema File Name

19.5.10

BSF Assertion

The BSF Assertion allows BSF script code to be used to check the status of the previous sample. Control Panel

248

Jmeter 2.3.4 Users Manual

Parameters Attribute Name Description Descriptive name for this element that is shown in the No tree. Yes Parameters to pass to the script. The parameters are stored in the following variables: Parameters

Required

Language The BSF language to be used

Parameters - string containing the parameters No as a single variable args - String array containing parameters, split on white-space No Yes (unless script file is provided)

Script file A file containing the script to run. Script The script to run.

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:

249

Jmeter 2.3.4 Users Manual

log - (Logger) - can be used to write to the log file Label - the String Label Filename - the script file name (if any) Parameters - the parameters (as a String) args[] - the parameters as a String array (split on whitespace) ctx - (JMeterContext) - gives access to the context vars - (JMeterVariables) - gives read/write access to variables: vars.get(key); vars.put(key,val); vars.putObject("OBJ1",new Object()); vars.getObject("OBJ2"); props - 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 (same as prev) 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

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

19.6.1

Constant Timer

If you want to have each thread pause for the same amount of time between requests, use this timer. Control Panel

250

Jmeter 2.3.4 Users Manual

Parameters Attribute Name Description Required Descriptive name for this timer that is shown in the tree. No Yes

Thread Delay Number of milliseconds to pause.

19.6.2

Gaussian Random Timer

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

Parameters Attribute Name Deviation Constant Delay Offset Description Descriptive name for this timer that is shown in the tree Deviation in milliseconds. Number of milliseconds to pause in addition to the random delay. Required No Yes Yes

19.6.3

Uniform Random Timer

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

251

Jmeter 2.3.4 Users Manual

Parameters Attribute Name Random Delay Maximum Constant Delay Offset Description Descriptive name for this timer that is shown in the tree. Maxium random number of milliseconds to pause. Number of milliseconds to pause in addition to the random delay. Required No Yes Yes

19.6.4

Constant Throughput Timer

This timer introduces variable pauses, calculated to keep the total throughput (in terms of samples per minute) as close as possible to a give figure. Of course the throughput will be lower if the server is not capable of handling it, or if other timers or time-consuming test elements prevent it. N.B. although the Timer is called the Constant Throughput timer, the throughput value does not need to be constant. It can be defined in terms of a variable or function call, and the value can be changed during a test. The value can be changed in various ways:

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

252

Jmeter 2.3.4 Users Manual

Parameters Attribute Name Target Throughput Description Descriptive name for this timer that is shown in the tree. Throughput we want the timer to try to generate.

Required No 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. Yes 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.

19.6.5

Synchronizing Timer

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

253

Jmeter 2.3.4 Users Manual

Parameters Attribute Name Description Descriptive name for this timer that is shown in the tree. Required No Yes

Number of Simultaneous Users to Number of threads to release at once. Group by

19.6.6

BeanShell Timer

The BeanShell Timer can be used to generate a delay. For full details on using BeanShell, please see the BeanShell web-site at http://www.beanshell.org/. The test element supports the ThreadListener and TestListener methods. These should be defined in the initialisation file. See the file BeanShellListeners.bshrc for example definitions. Control Panel

254

Jmeter 2.3.4 Users Manual

Parameters Attribute Name Reset bsh.Interpreter before each call Description Required Descriptive name for this element that is shown in the No tree. If this option is selected, then the interpreter will be recreated for each sample. This may be necessary for Yes some long running scripts. For further information, see Best Practices - BeanShell scripting . Parameters to pass to the BeanShell script. The parameters are stored in the following variables: Parameters

Parameters - string containing the parameters No as a single variable bsh.args - String array containing parameters, split on white-space

Script file

A file containing the BeanShell script to run. The return value is used as the number of milliseconds to No wait. Yes (unless The BeanShell script. The return value is used as the script file is number of milliseconds to wait. provided)

Script

Before invoking the script, some variables are set up in the BeanShell interpreter:

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.

19.7 Pre Processors

Preprocessors are used to modify the Samplers in their scope.

255

Jmeter 2.3.4 Users Manual

19.7.1

HTML Link Parser

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

Matches are performed using protocol, host, path and parameter names. The target sampler cannot contain parameters that are not in the response links. Spidering Example Consider a simple example: let's say you wanted JMeter to "spider" through your site, hitting link after link parsed from the HTML returned from your server (this is not actually the most useful thing to do, but it serves as a good example). You would create a Simple Controller , and add the "HTML Link Parser" to it. Then, create an HTTP Request, and set the domain to ".*", and the path likewise. This will cause your test sample to match with any link found on the returned pages. If you wanted to restrict the spidering to a particular domain, then change the domain value to the one you want. Then, only links to that domain will be followed. Poll Example A more useful example: given a web polling application, you might have a page with several poll options as radio buttons for the user to select. Let's say the values of the poll options are very dynamic - maybe user generated. If you wanted JMeter to test the poll, you could either create test samples with hardcoded values chosen, or you could let the HTML Link Parser parse the form, and insert a random poll option into your URL test sample. To do this, follow the above example, except, when configuring your Web Test controller's URL options, be sure to choose "POST" as the method. Put in hard-coded values for the domain, path, and any additional form parameters. Then, for the actual radio button parameter, put in the name (let's say it's called "poll_choice"), and then ".*" for the value of that parameter. When the modifier examines this URL test sample, it will find that it "matches" the poll form (and it shouldn't match any other form, given that you've specified all the other aspects of the URL test sample), and it will replace your form parameters with the matching parameters from the form. Since the regular 256

Jmeter 2.3.4 Users Manual

expression ".*" will match with anything, the modifier will probably have a list of radio buttons to choose from. It will choose at random, and replace the value in your URL test sample. Each time through the test, a new random value will be chosen.

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.

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

257

Jmeter 2.3.4 Users Manual

Parameters Attribute Name Session Argument Name Description Descriptive name given to this element in the test tree. 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. Some web apps rewrite URLs by appending a semicolon plus the session id parameter. Check this box if that is so. Required No Yes

Path Extension

No

Some web apps rewrite URLs without using an "=" sign Do not use equals in between the parameter name and value (such as No path extension Intershop Enfinity). Do not use questionmark in path extension Cache Session Id? Prevents the query string to end up in the path extension No (such as Intershop Enfinity). Should the value of the session Id be saved for later use when the session Id is not present? Yes

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

258

Jmeter 2.3.4 Users Manual

The value of the argument in your HTTP Request must be a '*' in order for the HTML Parameter Mask Modifier to replace it. As an example, the username for a login script could be modified to send a series of values such as: user_1 user_2 user_3 user_4, etc. Control Panel

Parameters Attribute Name Name (second appearing) ID Prefix Lower Bound Upper Bound Increment ID Suffix Description Descriptive name given to this element in the test tree. Required No

The name of the parameter to modify or add to the HTTP Yes Request. A string value to prefix to every generated value. A number value to start the counter at. A number value to end the counter, at which point it restarts with the Lower Bound value. Value to increment the counter by each time through. A string value to add as suffix to every generated vaue. No Yes Yes Yes No

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

259

Jmeter 2.3.4 Users Manual

The User Parameter Modifier uses an XML file get values for HTTP arguments. Any HTTP Request that this modifier modifies will be checked for the existence of the specified arguments. If found, the values for those arguments will be replaced by the values found in the xml file. The XML file can have multiple sets of the same values. This modifier will iterate through these values in a round-robin style, thus each request will get a different set of values until the last set of values is reached, at which point it will begin again at the first set. Control Panel

Parameters Attribute Name File Name Description Descriptive name given to this element in the test tree. Name of the XML file in JMeter's /bin directory that holds the value sets. Required No Yes

19.7.5

User Parameters

Allow the user to specify values for User Variables specific to individual threads. User Variables can also be specified in the Test Plan but not specific to individual threads. This panel allows you to specify a series of values for any User Variable. For each thread, the variable will be assigned one of the values from the series in sequence. If there are more threads than values, the values get re-used. For example, this can be used to assign a distinct user id to be used by each thread. User variables can be referenced in any field of any jMeter Component. The variable is specified by clicking the Add Variable button in the bottom of the panel and filling in the Variable name in the 'Name:' column. To add a new value to the series, click the 'Add User' button and fill in the desired value in the newly added column. 260

Jmeter 2.3.4 Users Manual

Values can be accessed in any test component in the same thread group, using the function syntax : ${variable}. See also the CSV Data Set Config element, which is more suitable for large numbers of parameters Control Panel

Parameters Attribute Name Description Descriptive name for this element that is shown in the tree. Required 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 Yes checked to ensure the values are updated each time through the UP's parent controller. Uncheck the box, and the UP will update the parameters for every sample request made within its scope .

19.7.6

BeanShell PreProcessor

The BeanShell PreProcessor allows arbitrary code to be applied before taking a sample. For full details on using BeanShell, please see the BeanShell web-site at http://www.beanshell.org/.

261

Jmeter 2.3.4 Users Manual

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

Parameters Attribute Name Reset bsh.Interpreter before each call Description Required

Descriptive name for this element that is shown in the No tree. If this option is selected, then the interpreter will be recreated for each sample. This may be necessary for Yes some long running scripts. For further information, see Best Practices - BeanShell scripting . Parameters to pass to the BeanShell script. The parameters are stored in the following variables:

Parameters

Parameters - string containing the parameters No as a single variable bsh.args - String array containing parameters, split on white-space No Yes (unless script file is provided)

Script file Script

A file containing the BeanShell script to run. The BeanShell script. The return value is ignored.

262

Jmeter 2.3.4 Users Manual

Before invoking the script, some variables are set up in the BeanShell interpreter:

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.

19.7.7

BSF PreProcessor

The BSF PreProcessor allows BSF script code to be applied before taking a sample. Control Panel

Parameters

263

Jmeter 2.3.4 Users Manual

Attribute Name

Description Descriptive name for this element that is shown in the No tree. Yes Parameters to pass to the script. The parameters are stored in the following variables:

Required

Language The BSF language to be used

Parameters

Parameters - string containing the parameters No as a single variable args - String array containing parameters, split on white-space No Yes (unless script file is provided)

Script file A file containing the script to run. Script The script to run.

The script (or file) is processed using the BSFEngine.exec() method, which does not return a value. The following BSF variables are set up for use by the script:

log - (Logger) - can be used to write to the log file Label - the String Label Filename - the script file name (if any) Parameters - the parameters (as a String) args[] - the parameters as a String array (split on whitespace) ctx - (JMeterContext) - gives access to the context vars - (JMeterVariables) - gives read/write access to variables: vars.get(key); vars.put(key,val); vars.putObject("OBJ1",new Object()); vars.getObject("OBJ2"); props - 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

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

264

Jmeter 2.3.4 Users Manual

Note: Unless documented otherwise, Post-Processors are not applied to sub-samples (child samples) - only to the parent sample. In the case of BSF and BeanShell postprocessors, the script can retrieve sub-samples using the method prev.getSubResults() which returns an array of SampleResults. The array will be empty if there are none. Post-Processors are run before Assertions, so they do not have access to any Assertion Results, nor will the sample status reflect the results of any Assertions. If you require access to Assertion Results, try using a Listener instead. Also note that the variable JMeterThread.last_sample_ok is set to "true" or "false" after all Assertions have been run.

19.8.1

Regular Expression Extractor

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

Parameters Attribute Description Required Name Descriptive name for this element that is shown in the tree. No The following response fields can be checked: Response Field to check

Body - the body of the response, e.g. the content of yes a web-page (excluding headers) Body (unescaped) - the body of the response, with all Html escape codes replaced. Note that Html escapes are processed without regard to context, so

265

Jmeter 2.3.4 Users Manual

some incorrect substitutions may be made. Headers - may not be present for non-HTTP samples URL Response Code - e.g. 200 Response Message - e.g. OK

Headers can be useful for HTTP samples; it may not be present for other sample types. 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 Yes 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. 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$. Yes Do not enclose the expression in / / - unless of course you want to match these characters as well. 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 Yes refer to a group is: '$1$' to refer to group 1, '$2$' to refer to group 2, etc. $0$ refers to whatever the entire expression matches. Indicates which match to use. The regular expression may match multiple times.

Reference Name

Regular Expression

Template

Match No.

Use a value of zero to indicate JMeter should choose a match at random. Yes A positive number N means to select the nth match. Negative numbers are used in conjunction with the ForEach controller - see below.

Default Value

If the regular expression does not match, then the reference variable will be set to the default value. This is particularly useful for debugging tests. If no default is provided, then it is difficult to tell whether the regular expression did not No, but match, or the RE element was not processed or maybe the recommended wrong variable is being used. However, if you have several test elements that set the same variable, you may wish to leave the variable

266

Jmeter 2.3.4 Users Manual

unchanged if the expression does not match. In this case, remove the default value once debugging is complete. If the match number is set to a non-negative number, and a match occurs, the variables are set as follows:

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.

19.8.2

XPath Extractor

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

267

Jmeter 2.3.4 Users Manual

Parameters Attribute Name Description Descriptive name for this element that is shown in the tree. If checked use Tidy to parse HTML response into XHTML.

Required No

Use Tidy

"Use Tidy" should be checked on for HTML response. Such response is converted to valid XHTML (XML Yes compatible HTML) using Tidy "Use Tidy" should be unchecked for both XHTML or XML response (for example RSS) If Tidy is selected If Tidy is selected If Tidy is selected

Quiet Report Errors Show warnings

Sets the Tidy Quiet flag If a Tidy error occurs, then add an Assertion showing the details Sets the Tidy showWarnings option

If checked, then the XML parser will use namespace resolution. Note that currently only namespaces declared on the root element will be recognised. A later version of JMeter may support user-definition of additional workspace names. Meanwhile, a work-round is to replace: Use //mynamespace:tagname Namespace? by //*[local-name()='tagname' and namespace-uri()='uri-fornamespace'] where "uri-for-namespace" is the uri for the "mynamespace" namespace. (not applicable if Tidy is selected) Reference Name XPath Query The name of the JMeter variable in which to store the result. Element query in XPath language. Can return more than one match.

Yes

Yes Yes

268

Jmeter 2.3.4 Users Manual

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.

19.8.3

Result Status Action Handler

This test element allows the user to stop the thread or the whole test if the relevant sampler failed. Control Panel

269

Jmeter 2.3.4 Users Manual

Parameters Attribute Name Description Descriptive name for this element that is shown in the tree. Determines what happens if a sampler error occurs, either because the sample itself failed or an assertion failed. The possible choices are:

Required No

Action to be taken after a Sampler error

Continue - ignore the error and continue with the test No Stop Thread - current thread exits Stop Test - the entire test is stopped at the end of any current samples. Stop Test Now - the entire test is stopped abruptly. Any current samplers are interrupted if possible.

19.8.4

BeanShell PostProcessor

The BeanShell PreProcessor allows arbitrary code to be applied after taking a sample. For JMeter versions after 2.2 the BeanShell Post-Processor no longer ignores samples with zero-length result data For full details on using BeanShell, please see the BeanShell web-site at http://www.beanshell.org/. The test element supports the ThreadListener and TestListener methods. These should be defined in the initialisation file. See the file BeanShellListeners.bshrc for example definitions. Control Panel

270

Jmeter 2.3.4 Users Manual

Parameters Attribute Name Reset bsh.Interpreter before each call Description Required

Descriptive name for this element that is shown in the No tree. If this option is selected, then the interpreter will be recreated for each sample. This may be necessary for Yes some long running scripts. For further information, see Best Practices - BeanShell scripting . Parameters to pass to the BeanShell script. The parameters are stored in the following variables:

Parameters

Parameters - string containing the parameters No as a single variable bsh.args - String array containing parameters, split on white-space No Yes (unless script file is provided)

Script file Script

A file containing the BeanShell script to run. The BeanShell script. The return value is ignored.

The following BeanShell 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

271

Jmeter 2.3.4 Users Manual

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.

19.8.5

BSF PostProcessor

The BSF PostProcessor allows BSF script code to be applied after taking a sample. Control Panel

Parameters Attribute Name Description Descriptive name for this element that is shown in the No tree. Required

272

Jmeter 2.3.4 Users Manual

Language The BSF language to be used Parameters to pass to the script. The parameters are stored in the following variables: Parameters

Yes

Parameters - string containing the parameters No as a single variable args - String array containing parameters, split on white-space No Yes (unless script file is provided)

Script file A file containing the script to run. Script The script to run.

The script (or file) is processed using the BSFEngine.exec() method, which does not return a value. Before invoking the script, some variables are set up. Note that these are BSF variables i.e. they can be used directly in the script.

log - (Logger) - can be used to write to the log file Label - the String Label Filename - the script file name (if any) Parameters - the parameters (as a String) args[] - the parameters as a String array (split on whitespace) ctx - (JMeterContext) - gives access to the context vars - (JMeterVariables) - gives read/write access to variables: vars.get(key); vars.put(key,val); vars.putObject("OBJ1",new Object()); vars.getObject("OBJ2"); props - 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

19.9 Miscellaneous Features

19.9.1 Test Plan

The Test Plan is where the overall settings for a test are specified. Static variables can be defined for values that are repeated throughout a test, such as server names. For example the variable SERVER could be defined as

273

Jmeter 2.3.4 Users Manual

www.example.com, and the rest of the test plan could refer to it as ${SERVER}. This simplifies changing the name later. If the same variable name is reused on one of more User Defined Variables Configuration elements, the value is set to the last definition in the test plan (reading from top to bottom). Such variables should be used for items that may change between test runs, but which remain the same during a test run. Note that the Test Plan cannot refer to variables it defines. If you need to construct other variables from the Test Plan variables, use a User Defined Variables test element. Selecting Functional Testing instructs JMeter to save the additional sample information Response Data and Sampler Data - to all result files. This increases the resources needed to run a test, and may adversely impact JMeter performance. If more data is required for a particular sampler only, then add a Listener to it, and configure the fields as required. [The option does not affect CSV result files, which cannot currently store such information.] Also, an option exists here to instruct JMeter to run the Thread Group serially rather than in parallel. Test plan now provides an easy way to add classpath setting to a specific test plan. The feature is additive, meaning that you can add jar files or directories, but removing an entry requires restarting JMeter. In the past, users had to copy all the jar files to jmeter/lib/ directory. Now that is not necessary. JMeter properties also provides an entry for loading additional classpaths. In jmeter.properties, edit "user.classpath" to include additional libraries. Control Panel

274

Jmeter 2.3.4 Users Manual

19.9.2

Thread Group

A Thread Group defines a pool of users that will execute a particular test case against your server. In the Thread Group GUI, you can control the number of users simulated (num of threads), the ramp up time (how long it takes to start all the threads), the number of times to perform the test, and optionally, a start and stop time for the test. When using the scheduler, JMeter runs the thread group until either the number of loops is reached or the duration/end-time is reached - whichever occurs first. Note that the condition is only checked between samples; when the end condition is reached, that thread will stop. JMeter does not interrupt samplers which are waiting for a response, so the end time may be delayed arbitrarily. Control Panel

275

Jmeter 2.3.4 Users Manual

Parameters Attribute Name Description Determines what happens if a sampler error occurs, either because the sample itself failed or an assertion failed. The possible choices are: Action to be taken after a Sampler error

Required

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

Continue - ignore the error and continue with the test No Stop Thread - current thread exits Stop Test - the entire test is stopped at the end of any current samples. Stop Test Now - the entire test is stopped abruptly. Any current samplers are interrupted if possible. Yes

Number of Threads Ramp-up Period

Number of users to simulate.

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

276

Jmeter 2.3.4 Users Manual

thread started, for a total time of 100 seconds to get the test fully up to speed. Loop Count Number of times to perform the test case. Alternatively, "forever" can be selected causing the test to run until manually stopped. 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. Yes, unless forever is selected No

Start Time

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 No will stop at the specified end time. Note: the Duration field over-rides this - see below. If the scheduler checkbox is selected, one can choose a relative end time. JMeter will use this to calculate the End No Time, and ignore the End Time value. 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

Duration (seconds) Startup delay (seconds)

19.9.3

WorkBench

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

HTTP Proxy Server HTTP Mirror Server Property Display

Control Panel

277

Jmeter 2.3.4 Users Manual

19.9.4

SSL Manager

The SSL Manager is a way to select a client certificate so that you can test applications that use Public Key Infrastructure (PKI). It is only needed if you have not set up the appropriate System properties. 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.

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

278

Jmeter 2.3.4 Users Manual

The Proxy Server allows JMeter to watch and record your actions while you browse your web application with your normal browser. JMeter will create test sample objects and store them directly into your test plan as you go (so you can view samples interactively while you make them). To use the proxy server, add the HTTP Proxy Server element to the workbench. Select the WorkBench element in the tree, and right-click on this element to get the Add menu (Add --> Non-Test Elements --> HTTP Proxy Server). You also need to set up your browser to use the JMeter proxy port as the proxy for HTTP requests. Do not use JMeter as the proxy for any other request types - HTTPS, FTP, etc. as the JMeter proxy cannot handle them. If your browser currently uses a proxy (e.g. a company intranet may route all external requests via a proxy), then you need to tell JMeter to use that proxy before starting JMeter, using the command-line options -H and -P. This setting will also be needed when running the generated test plan. Control Panel

279

Jmeter 2.3.4 Users Manual

Parameters Attribute Name Port Description Required

Descriptive name for this controller that is shown in the tree. No The port that the Proxy Server listens to. 8080 is the default, Yes but you can change it. When you enable HTTPS spoofing, the following happens:

Attempt HTTPS Spoofing

All matching (see below) http requests from the Yes 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

280

Jmeter 2.3.4 Users Manual

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. 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 No could use the expression "http://a.b.c/service/.*". Note that the expression ends in ".*" because it must match the whole URL. 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. 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:

Optional URL match string

Target Controller

Yes

Grouping

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 Yes Simple Controller for 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. 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

Capture HTTP Headers

Yes

281

Jmeter 2.3.4 Users Manual

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. Add Assertions Add a blank assertion to each sampler? Regex Matching Use Regex Matching when replacing variables? Type Redirect Automatically Follow Redirects Retrieve all Embedded Resources Which type of sampler to generate (the Java default or HTTPClient) Set Redirect Automatically in the generated samplers? Set Follow Redirects in the generated samplers? Yes Yes Yes Yes Yes Yes Yes

Use Keep-Alive Set Use Keep-Alive in the generated samplers? Set Retrieve all Embedded Resources in the generated samplers?

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. No [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. 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 No 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 . Regular expressions that are matched against the URL that is sampled. Any requests that match one or more Exclude No pattern are not recorded . 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!". Stop the proxy server. Stops and restarts the proxy server. This is useful when you change/add/delete an include/exclude filter expression. N/A N/A N/A

Patterns to Include

Patterns to Exclude Start Button Stop Button Restart Button

282

Jmeter 2.3.4 Users Manual

The include and exclude patterns are treated as regular expressions (using Jakarta ORO). They will be matched against the host name, port (actual or implied) path and query (if any) of each browser request. If the URL you are browsing is "http://jakarta.apache.org/jmeter/index.html?username=xxxx" , then the regular expression will be tested against the string: "jakarta.apache.org:80/jmeter/index.html?username=xxxx" . Thus, if you want to include all .html files, your regular expression might look like: ".*\.html(\?.*)?" - or ".*\.html" if you know that there is no query string or you only want html pages without query strings. If there are any include patterns, then the URL must match at least one of the patterns , otherwise it will not be recorded. If there are any exclude patterns, then the URL must not match any of the patterns , otherwise it will not be recorded. Using a combination of includes and excludes, you should be able to record what you are interested in and skip what you are not. N.B. the string that is matched by the regular expression must be the same as the whole host+path string. Thus "\.html" will not match j.a.o/index.html Versions of JMeter from 2.3.2 are able to capture binary POST data. To configure which content-types are treated as binary, update the JMeter property proxy.binary.types. The default settings are as follows:
# These content-types will be handled by saving the request in a file: proxy.binary.types=application/x-amf,application/x-java-serializedobject # 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? 283

Jmeter 2.3.4 Users Manual

JMeter places the recorded samples in the Target Controller you choose. If you choose the default option "Use Recording Controller", they will be stored in the first Recording Controller found in the test object tree (so be sure to add a Recording Controller before you start recording). If the Proxy does not seem to record any samples, this could be because the browser is not actually using the proxy. To check if this is the case, try stopping the proxy. If the browser still downloads pages, then it was not sending requests via the proxy. Doublecheck the browser options. If you are trying to record from a server running on the same host, then check that the browser is not set to "Bypass proxy server for local addresses" (this example is from IE7, but there will be similar options for other browsers). If JMeter does not record browser URLs such as http://localhost/ or http://127.0.0.1/, try using the non-loopback hostname or IP address, e.g. http://myhost/ or http://192.168.0.2/. Handling of HTTP Request Defaults 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. User Defined Variable replacement 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.

284

Jmeter 2.3.4 Users Manual

When you are done recording your test samples, stop the proxy server (hit the "stop" button). Remember to reset your browser's proxy settings. Now, you may want to sort and re-order the test script, add timers, listeners, a cookie manager, etc. 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. Cookie Manager If the server you are testing against uses cookies, remember to add an HTTP Cookie Manager to the test plan when you have finished recording it. During recording, the browser handles any cookies, but JMeter needs a Cookie Manager to do the cookie handling during a test run. The JMeter Proxy server passes on all cookies sent by the browser during recording, but does not save them to the test plan because they are likely to change between runs. Authorization Manager The Proxy server passes on any Authorization headers sent by the browser, but does not save them in the test plan. If the site requires Authorization, you will need to add an Authorization Manager and fill it in with the necessary entries. Uploading files Some browsers (e.g. Firefox and Opera) don't include the full name of a file when uploading files. This can cause the JMeter proxy server to fail. One solution is to ensure that any files to be uploaded are in the JMeter working directory, either by copying the files there or by starting JMeter in the directory containing the files.

19.9.6

HTTP Mirror Server

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

285

Jmeter 2.3.4 Users Manual

19.9.7

Property Display

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

Parameters Attribute Name Description Required

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

19.9.8

Debug Sampler

The Debug Sampler generates a sample containing the values of all JMeter variables and/or properties. The values can be seen in the View Results Tree Listener Response Data pane.

286

Jmeter 2.3.4 Users Manual

Control Panel

Parameters Attribute Name Description Required Descriptive name for this element that is shown in the tree. No Yes Yes Yes

JMeter Properties Include JMeter properties ? JMeter Variables Include JMeter variables ? System Properties Include System properties ?

19.9.9

Debug PostProcessor

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

Parameters Attribute Name Description Required

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

287

Jmeter 2.3.4 Users Manual

19.10 Reports
19.10.1 19.10.2 19.10.3 19.10.4 19.10.5 19.10.6 Report Plan Report Table HTML Report Writer Report Page Line Graph Bar Chart

288

Jmeter 2.3.4 Users Manual

20. 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 Information Information Information Information Information Input Input Name threadNum machineName time log logn StringFromFile CSVRead Comment get thread number get the local machine name return current time in various formats log (or display) a message (and return the value) log (or display) a message (empty return value) read a line from a file read from CSV delimited file

289

Jmeter 2.3.4 Users Manual

Input Calculation Calculation Calculation Calculation Scripting Scripting Scripting Properties Properties Properties Variables Variables Variables Variables String String String String String

XPath counter intSum longSum Random BeanShell javaScript jexl property P setProperty split V eval evalVar regexFunction char unescape unescapeHtml escapeHtml

Use an XPath expression to read from a file generate an incrementing number add int numbers add long numbers generate a random number run a BeanShell script process JavaScript (Mozilla Rhino) evaluate a Commons Jexl expression read a property read a property (shorthand method) set a JMeter property Split a string into variables evaluate a variable name evaluate a variable expression evaluate an expression stored in a variable parse previous response using a regular expression generate Unicode char values from a list of numbers Process strings containing Java escapes (e.g. \n & \t) Decode HTML-encoded strings Encode strings using HTML encoding

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

290

Jmeter 2.3.4 Users Manual

Functions are shared between threads. Each occurrence of a function call in a test plan is handled by a separate function instance.

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

20.3 How to reference variables and functions

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

291

Jmeter 2.3.4 Users Manual

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

Alternatively, you can define your script as a variable, e.g. on the Test Plan:
SCRIPT vars.put("name","value")

The script can then be referenced as follows:

${__BeanShell(${SCRIPT})}

There is no need to escape commas in the SCRIPT variable because the function call is parsed before the variable is replaced with its value. This works well in conjunction with the BSF or BeanShell Samplers, as these can be used to test Javascript, Jexl and BeanShell scripts. 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. If a string contains a backslash('\') and also contains a function or variable reference, the backslash will be removed if it appears before '$' or ',' or '\'. This behaviour is necessary to allow for nested functions that include commas or the string ${. Backslashes before '$' or ',' or '\' are not removed if the string does not contain a function or variable reference. The value of a variable or function can be reported using the __logn() function. The __logn() function reference can be used anywhere in the test plan after the variable has been defined. Alternatively, the Java Request sampler can be used to create a sample containing variable references; the output will be shown in the appropriate Listener. For versions of JMeter later than 2.3, there is a Debug Sampler that can be used to display the values of variables etc in the Tree View Listener.

292

Jmeter 2.3.4 Users Manual

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

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

20.5 Functions
20.5.1 __regexFunction

The Regex Function is used to parse the previous response (or the value of a variable) using any regular expression (provided by user). The function returns the template string with variable values filled in. The __regexFunction can also store values for future use. In the sixth parameter, you can specify a reference name. After this function executes, the same values can be retrieved at later times using the syntax for user-defined values. For instance, if you enter "refName" as the sixth parameter you will be able to use:

293

Jmeter 2.3.4 Users Manual

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

Control Panel

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 Yes group). Another example: <input type="hidden" name="(.*)" value="(.*)">. This will grab the name as the first group, and the value as the second group. These values can be used in your template string This is the template string that will replace the function at runtime. To refer to a group captured in the regular expression, use Yes the syntax: $[group_number]$. Ie: $1$, or $2$. Your template can be any string. The third argument tells JMeter which match to use. Your regular expression might find numerous matches. You have four choices:

Second argument

Third argument

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. No, ALL - Tells JMeter to use all matches, and create a default=1 template string for each one and then append them all together. This option is little used. A float number between 0 and 1 - tells JMeter to find the Xth match using the formula: (number_of_matches_found * float_number) rounded to nearest integer.

Fourth argument Fifth 294

If 'ALL' was selected for the above argument value, then this argument will be inserted between each appended copy of the template value. Default value returned if no match is found

No No

Jmeter 2.3.4 Users Manual

argument Sixth argument Seventh 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

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

20.5.2

__counter

The counter generates a new number each time it is called, starting with 1 and incrementing by +1 each time. The counter can be configured to keep each simulated user's values separate, or to use the same counter for all users. If each user's values is incremented separately, that is like counting the number of iterations through the test plan. A global counter is like counting how many times that request was run. The counter uses an integer variable to hold the count, which therefore has a maximum of 2,147,483,647. The counter function instances are now completely independent. [JMeter 2.1.1 and earlier used a fixed thread variable to keep track of the per-user count, so multiple counter functions operated on the same value.] The global counter - "FALSE" - is separately maintained by each counter instance. Control Panel

Parameters Attribute First argument Second argument Description TRUE if you wish each simulated user's counter to be kept independent and separate from the other users. FALSE for a global counter. 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.] Required Yes

No

20.5.3

__threadNum

The thread number function simply returns the number of the thread currently being executed. These numbers are independent of ThreadGroup, meaning thread #1 in one

295

Jmeter 2.3.4 Users Manual

threadgroup is indistinguishable from thread #1 in another threadgroup, from the point of view of this function. There are no arguments for this function. Control Panel

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

20.5.4

__intSum

The intSum function can be used to compute the sum of two or more integer values. JMeter Versions 2.3.1 and earlier required the reference name to be present. The reference name is now optional, but it must not be a valid integer. Control Panel

Parameters Attribute First argument Second argument nth argument last argument The first int value. The second int value. The nth int value. Description Required Yes Yes No

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

20.5.5

__longSum

The longSum function can be used to compute the sum of two or more long values. Control Panel

296

Jmeter 2.3.4 Users Manual

Parameters Attribute First argument Second argument nth argument last argument The first long value. The second long value. The nth long value. Description Required Yes Yes No

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

20.5.6

__StringFromFile

The StringFromFile function can be used to read strings from a text file. This is useful for running tests that require lots of variable data. For example when testing a banking application, 100s or 1000s of different account numbers might be required. See also the CSV Data Set Config test element which may be easier to use. However, that does not currently support multiple input files. Each time it is called it reads the next line from the file. When the end of the file is reached, it will start reading again from the beginning, unless the maximum loop count has been reached. If there are multiple references to the function in a test script, each will open the file independently, even if the file names are the same. [If the value is to be used again elsewhere, use different variable names for each function call.] If an error occurs opening or reading the file, then the function returns the string "**ERR**" Control Panel

Parameters Attribute File Name Description Path to the file name. (The path can be relative to the JMeter Required Yes

297

Jmeter 2.3.4 Users Manual

launch directory) If using optional sequence numbers, the path name should be suitable for passing to DecimalFormat. See below for examples. Variable Name Start sequence number End sequence number A reference name - refName - for reusing the value created by this function. Stored values are of the form ${refName}. Defaults to "StringFromFile_". Initial Sequence number (if omitted, the End sequence number is treated as a loop count) Final sequence number (if omitted, seqence numbers can increase without limit) No

No

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

298

Jmeter 2.3.4 Users Manual

number will be appended to the name, otherwise the number will be inserted aaccording to the fomatting instructions. If the start sequence number is omitted, and the end sequence number is specified, the sequence number is interpreted as a loop count, and the file will be used at most "end" times. In this case the filename is not formatted.
${_StringFromFile(PIN#'.'DAT,,1,2)} - reads PIN1.DAT, PIN2.DAT ${_StringFromFile(PIN.DAT,,,2)} - reads PIN.DAT twice

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

20.5.7

__machineName

The machineName function returns the local host name Control Panel

Parameters Attribute Variable Name Description A reference name for reusing the value computed by this function. Required No

20.5.8

__javaScript

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

log - the logger for the function ctx - JMeterContext object vars - JMeterVariables object threadName - String containing the current thread name (in 2.3.2 it was misspelt as "theadName") sampler - current Sampler object (if any) sampleResult - previous SampleResult object (if any) 299

Jmeter 2.3.4 Users Manual

props - JMeter Properties object

Rhinoscript allows access to static methods via its Packages object. See the Scripting Java documentation. For example one can access the JMeterContextService static methods thus:
Packages.org.apache.jmeter.threads.JMeterContextService.getTotalThreads ()

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

Parameters Attribute Description The JavaScript expression to be executed. For example:

Require d

Expressio n

new Date() - return the current date and time Math.floor(Math.random()*(${maxRandom}+1)) - a random number between 0 and the variable maxRandom Yes ${minRandom}+Math.floor(Math.random()*(${maxRando m}-${minRandom}+1)) - a random number between the variables minRandom and maxRandom "${VAR}"=="abcd"

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.

20.5.9

__Random

The random function returns a random number that lies between the given min and max values. Control Panel

300

Jmeter 2.3.4 Users Manual

Parameters Attribute Minimum value Maximum value Variable Name Description A number A bigger number A reference name for reusing the value computed by this function. Required Yes Yes No

20.5.10

__CSVRead

The CSVRead function returns a string from a CSV file (c.f. StringFromFile ) NOTE: versions up to 1.9.1 only supported a single file. JMeter versions since 1.9.1 support multiple file names. In most cases, the newer CSV Data Set Config element is easier to use. When a filename is first encountered, the file is opened and read into an internal array. If a blank line is detected, this is treated as end of file - this allows trailing comments to be used (N.B. this feature was introduced in versions after 1.9.1) All subsequent references to the same file name use the same internal array. N.B. the filename case is significant to the function, even if the OS doesn't care, so CSVRead(abc.txt,0) and CSVRead(aBc.txt,0) would refer to different internal arrays. The *ALIAS feature allows the same file to be opened more than once, and also allows for shorter file names. Each thread has its own internal pointer to its current row in the file array. When a thread first refers to the file it will be allocated the next free row in the array, so each thread will access a different row from all other threads. [Unless there are more threads than there are rows in the array.] Note: the function splits the line at every comma by default. If you want to enter columns containing commas, then you will need to change the delimiter to a character that does not appear in any column data, by setting the property: csvread.delimiter Control Panel

Parameters

301

Jmeter 2.3.4 Users Manual

Attribute File Name Column number

Description The file (or *ALIAS) to read from

Required Yes

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 Yes to the alias

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 .

20.5.11

__property

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

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

Control Panel

Parameters Attribute Property Description The property name to be retrieved. Required Yes

302

Jmeter 2.3.4 Users Manual

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

Default Value The default value for the property.

20.5.12

__P

This is a simplified property function which is intended for use with properties defined on the command line. Unlike the __property function, there is no option to save the value in a variable, and if no default value is supplied, it is assumed to be 1. The value of 1 was chosen because it is valid for common test variables such as loops, thread count, ramp up etc. For example:
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!) Control Panel

Parameters Attribute Property Name Default Value Description The property name to be retrieved. Required Yes

The default value for the property. If omitted, the default is set No to "1".

20.5.13

__log

The log function logs a message, and returns its input string Control Panel

303

Jmeter 2.3.4 Users Manual

Parameters Attribute String to be logged Log Level A string OUT, ERR, DEBUG, INFO (default), WARN or ERROR Description Required Yes No No

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

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

The OUT and ERR log level names are used to direct the output to System.out and System.err respectively. In this case, the output is always printed - it does not depend on the current log setting.
For example: ${__log(Message)} - written to the log file as "...thread Name : Message" ${__log(Message,OUT)} - written to console window ${__log(${VAR},,,VAR=)} - written to log file as "...thread Name VAR=value"

20.5.14

__logn

The logn function logs a message, and returns the empty string Control Panel

Parameters Attribute String to be logged A string Log Level Throwable text If non-empty, creates a Throwable to pass to the logger Description Required Yes No

OUT, ERR, DEBUG, INFO (default), WARN or ERROR 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.

304

Jmeter 2.3.4 Users Manual

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

20.5.15

__BeanShell

The BeanShell function evaluates the script passed to it, and returns the result. For full details on using BeanShell, please see the BeanShell web-site at http://www.beanshell.org/ Note that a different Interpreter is used for each independent occurence of the function in a test script, but the same Interpreter is used for subsequent invocations. This means that variables persist across calls to the function. A single instance of a function may be called from multiple threads. However the function execute() method is synchronised. 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 (String) 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. Control Panel

Parameters Attribute Description Required Yes

BeanShell script A beanshell script (not a file name)

305

Jmeter 2.3.4 Users Manual

Name of variable Example:

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

No

${__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 that represent text strings.

20.5.16

__split

The split function splits the string passed to it according to the delimiter, and returns the original string. If any delimiters are adjacent, "?" is returned as the value. The split strings are returned in the variables ${VAR_1}, ${VAR_2} etc. The count of variables is returned in ${VAR_n}. From JMeter 2.1.2 onwards, a trailing delimiter is treated as a missing variable, and "?" is returned. Also, to allow it to work better with the ForEach controller, __split now deletes the first unused variable in case it was set by a previous split. Example:
Define VAR="a||c|" in the test plan. ${__split(${VAR},VAR),|} This will return the contents of VAR, i.e. "a||c|" and set the following variables: VAR_n=4 (3 in JMeter 2.1.1 and earlier) VAR_1=a VAR_2=? VAR_3=c VAR_4=? (null in JMeter 2.1.1 and earlier) VAR_5=null (in JMeter 2.1.2 and later)

Control Panel

Parameters Attribute Description String to split A delimited string, e.g. "a|b|c" Name of variable Delimiter A reference name for reusing the value computed by this function. Required Yes Yes

The delimiter character, e.g. | . If omitted, , is used. Note that , No

306

Jmeter 2.3.4 Users Manual

would need to be specified as \, .

20.5.17

__XPath

The XPath function reads an XML file and matches the XPath. Each time the function is called, the next match will be returned. At end of file, it will wrap around to the start. If no nodes matched, then the function will return the empty string, and a warning message will be written to the JMeter log file. Note that the entire NodeList is held in memory. Example:
${__XPath(/path/to/build.xml, //target/@name)} This will match all targets in build.xml and return the contents of the next name attribute

Control Panel

Parameters Attribute XPath Description Required Yes

XML file to parse a XML file to parse

a XPath expression to match nodes in the XML file Yes

20.5.18

__setProperty

The setProperty function sets the value of a JMeter property. The default return value from the function is the empty string, so the function call can be used anywhere functions are valid. The original value can be returned by setting the optional 3rd parameter to "true". Properties are global to JMeter, so can be used to communicate between threads and thread groups Control Panel

Parameters

307

Jmeter 2.3.4 Users Manual

Attribute

Description

Required Yes Yes

Property Name The property name to be set. Property Value The value for the property. True/False

Should the original value be returned? No

20.5.19

__time

The time function returns the current time in various formats. Control Panel

Parameters Attribute Format Name of variable Description The format to be passed to SimpleDateFormat. The function supports various shorthand aliases, see below. The name of the variable to set. Required No 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

20.5.20

__jexl

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

JEXL syntax description JEXL examples

Control Panel

308

Jmeter 2.3.4 Users Manual

Parameters Attribute Expression Description Required No

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

Name of variable The name of the variable to set. The following variables are made available to the script:

log - the logger for the function ctx - JMeterContext object vars - JMeterVariables object props - JMeter Properties object threadName - String containing the current thread name (in 2.3.2 it was misspelt as "theadName") sampler - current Sampler object (if any) sampleResult - previous SampleResult object (if any) OUT - System.out - e.g. OUT.println("message")

Jexl can also create classes and call methods on them, for example:
Systemclass=log.class.forName("java.lang.System"); now=Systemclass.currentTimeMillis(); Note that the Jexl

documentation on the web-site wrongly suggests that "div" does integer division. In fact "div" and "/" both perform normal division. One can get the same effect as follows: i= 5 / 2;

i.intValue(); // or use i.longValue()

Versions of JMeter after 2.3.2 allow the expression to contain multiple statements. JMeter 2.3.2 and earlier only processed the first statement (if there were multiple statements a warning was logged).

20.5.21

__V

The V (variable) function returns the result of evaluating a variable name expression. This can be used to evaluate nested variable references (which are not currently supported). 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

309

Jmeter 2.3.4 Users Manual

Control Panel

Parameters Attribute Description Required

Variable name The variable to be evaluated. Yes

20.5.22

__evalVar

The eval function returns the result of evaluating an expression stored in a variable. This allows one to read a string from a file, and process any variable references in it. For example, if the variable "query" contains "select ${column} from ${table}" and "column" and "table" contain "name" and "customers", then ${__evalVar(query)} will evaluate as "select name from customers". Control Panel

Parameters Attribute Description Required

Variable name The variable to be evaluated. Yes

20.5.23

__eval

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

310

Jmeter 2.3.4 Users Manual

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

Parameters Attribute Description Required

Variable name The variable to be evaluated. Yes

20.5.24

__char

The char function returns the result of evaluating a list of numbers as Unicode characters. See also __unescape(), below. This allows one to add arbitrary character values into fields. Control Panel

Parameters Attribute Description Required Yes

Unicode character number The decimal number (or hex number, if prefixed (decimal or 0xhex) by 0x) to be converted to a Unicode character. Examples: ${__char(0xC,0xA)} = CRLF ${__char(165)} = (yen)

20.5.25

__unescape

The unescape function returns the result of evaluating a Java-escaped string. See also __char() above. This allows one to add characters to fields which are otherwise tricky (or impossible) to define via the GUI. Control Panel

311

Jmeter 2.3.4 Users Manual

Parameters Attribute Description Required

String to unescape The string to be unescaped. Yes Examples: ${__unescape(\r\n)} = CRLF ${__unescape(1\t2)} = 1[tab]2

20.5.26

__unescapeHtml

Function to unescape a string containing HTML entity escapes to a string containing the actual Unicode characters corresponding to the escapes. Supports HTML 4.0 entities. For example, the string "&lt;Fran&ccedil;ais&gt;" will become "<Franais>" . If an entity is unrecognized, it is left alone, and inserted verbatim into the result string. e.g. ">&zzzz;x" will become ">&zzzz;x" . Uses StringEscapeUtils#unescapeHtml(String) from Commons Lang. Control Panel

Parameters Attribute Description Required

String to unescape The string to be unescaped. Yes

20.5.27

__escapeHtml

Function which escapes the characters in a String using HTML entities. Supports HTML 4.0 entities. For example, "bread" & "butter" becomes: &quot;bread&quot; &amp; &quot;butter&quot; . Uses StringEscapeUtils#escapeHtml(String) from Commons Lang. Control Panel

312

Jmeter 2.3.4 Users Manual

Parameters Attribute Description Required

String to escape The string to be escaped. Yes

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

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

313

Jmeter 2.3.4 Users Manual

21. Regular Expressions

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

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

Jmeter 2.3.4 Users Manual

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

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

315

Jmeter 2.3.4 Users Manual

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.

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

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

316

Jmeter 2.3.4 Users Manual

21.6 Testing Regular Expressions

There is a demo applet for Apache JMeter ORO. Another approach is to use a simple test plan to test the regular expressions. The Java Request sampler can be used to generate a sample, or the HTTP Sampler can be used to load a file. Add a Debug Sampler and a Tree View Listener and changes to the regular expression can be tested quickly, without needing to access any external servers.

317

Jmeter 2.3.4 Users Manual

22. Glossary
Elapsed time JMeter measures the elapsed time from just before sending the request to just after the last response has been received. JMeter does not include the time needed to render the response, nor does JMeter process any client code, for example Javascript. Latency JMeter measures the latency from just before sending the request to just after the first response has been received. Thus the time includes all the processing needed to assemble the request as well as assembling the first part of the response, which in general will be longer than one byte. Protocol analysers (such as Wireshark) measure the time when bytes are actually sent/received over the interface. The JMeter time should be closer to that which is experienced by a browser or other application client. Median is a number which divides the samples into two equal halves. Half of the samples are smaller than the median, and half are larger. [Some samples may equal the median.] This is a standard statistical measure. See, for example: Median entry at Wikipedia. The Median is the same as the 50 th Percentile 90% Line (90 th Percentile) is the value below which 90% of the samples fall. The remaining samples too at least as long as the value. This is a standard statistical measure. See, for example: Percentile entry at Wikipedia. Standard Deviation is a measure of the variability of a data set. This is a standard statistical measure. See, for example: Standard Deviation entry at Wikipedia. The Thread Name as it appears in Listeners and logfiles is derived from the Thread Group name and the thread within the group. The name has the format groupName + " " + groupIndex + "-" + threadIndex where:

groupName - name of the Thread Group element groupIndex - number of the Thread Group in the Test Plan, starting from 1 threadIndex - number of the thread within the Thread Group, starting from 1

A test plan with two Thread Groups each with two threads would use the names:
Thread Thread Thread Thread Group Group Group Group 1-1 1-2 2-1 2-2

Throughput is calculated as requests/unit of time. The time is calculated from the start of the first sample to the end of the last sample. This includes any intervals between

318

Jmeter 2.3.4 Users Manual

samples, as it is supposed to represent the load on the server. The formula is: Throughput = (number of requests) / (total time).

319