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

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, iframes
• background images (body, table, TD, TR)
• background sound

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

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

Or, instead of manually adding HTTP Requests, you may want to use JMeter's HTTP(S) Test Script Recorder to create them. This can save you time if you have a lot of HTTP requests or requests with many parameters.

There are two different test elements used to define the samplers:

• 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.
• HTTP Request - this has an implementation drop-down box, which selects the HTTP protocol implementation to be used:
• Java - uses the HTTP implementation provided by the JVM. This has some limitations in comparison with the HttpClient implementations - see below.
• HTTPClient3.1 - uses Apache Commons HttpClient 3.1. This is no longer being developed, and support for this may be dropped in a future JMeter release.
• HTTPClient4 - uses Apache HttpComponents HttpClient 4.x.
• Blank Value - does not set implementation on HTTP Samplers, so relies on HTTP Request Defaults if present or on jmeter.httpsampler property defined in jmeter.properties

The Java HTTP 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 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.
• It does not support virtual hosts.
• It does not support the following methods: COPY, LOCK, MKCOL, MOVE, PATCH, PROPFIND, PROPPATCH, UNLOCK, REPORT, MKCALENDAR.
• It does not support client based certificate testing with Keystore Config.

Note: the FILE protocol is intended for testing purposes 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

https.use.cached.ssl.context=false

JMeter defaults to the SSL protocol level TLS. If the server needs a different level, e.g. SSLv3, change the JMeter property, for example:

https.default.protocol=SSLv3

JMeter also allows one to enable additional protocols, by changing the property https.socket.protocols.

If the request uses cookies, then you will also need an HTTP Cookie Manager. You can add either of these elements to the Thread Group or the HTTP Request. If you have more than one HTTP Request that needs authorizations or cookies, then add the elements to the Thread Group. That way, all HTTP Request controllers will share the same Authorization Manager and Cookie Manager elements.

If the request uses a technique called "URL Rewriting" to maintain sessions, then see section 6.1 Handling User Sessions With URL Rewriting for additional configuration steps.

This sampler lets you send an JDBC Request (an SQL query) to a database.

Before using this you need to set up a JDBC Connection Configuration Configuration element

If the Variable Names list is provided, then for each row returned by a Select statement, the variables are set up with the value of the corresponding column (if a variable name is provided), and the count of rows is also set up. For example, if the Select statement returns 2 rows of 3 columns, and the variable list is A,,C, then the following variables will be set up:

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

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.

Note: The latency time is set from the time it took to acquire a connection.

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

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

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

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.

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.

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>

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.

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.

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 every image, css file, javascript file, 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

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

• setGenerator(Generator)
• parse(int)

This sampler allows you to write a sampler using the BeanShell scripting language.

For full details on using BeanShell, please see the BeanShell website.

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

From JMeter version 2.5.1, the BeanShell sampler also supports the Interruptible interface. The interrupt() method can be defined in the script or the init file.

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)
• xslt

The JSR223 Sampler allows JSR223 script code to be used to perform a sample.

The JSR223 test elements have a feature (compilation) that can significantly increase performance. To benefit from this feature:

• Use Script files instead of inlining them. This will make JMeter compile them if this feature is available on ScriptEngine and cache them.
• Or Use Script Text and fill in script cache key property, ensure it is unique across Test Plan as JMeter will use it to cache result of compilation.
  When using this feature, ensure you script code does not use JMeter variables directly in script code as caching would only cache first replacement. Instead use script parameters.
  To benefit fomr Caching and compilation, language engine used for scripting must implement JSR223 Compilable interface (Groovy is one of these, java, beanshell and javascript are not)

• jsr223.compiled_scripts_cache_size=100

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 both of "Re-use connection" and "Close connection" are selected, the socket will be closed after running the sampler. On the next sampler, another socket will be created. You may want to close a socket at the end of each thread loop.
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

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

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. You can control charset encoding by setting tcp.charset, which will default to Platform default encoding.

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

JMS Publisher will publish messages to a given destination (topic/queue). 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.

JMS Publisher will subscribe to messages in a given destination (topic or queue). 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.

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.

Request Only will typically used to put load on a JMS System.
Request Response will be used when you want to test response time of a JMS service that processes messages sent to the Request Queue as this mode will wait for the response on the Reply queue sent by this service.

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

• 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.
• 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.
• Junit sampler does not use name/value pairs for configuration like the JavaSampler. The sampler assumes setUp and tearDown will configure the test correctly.
• The sampler measures the elapsed time only for the test method and does not include setUp and tearDown.
• Each time the test method is called, Jmeter will pass the result to the listeners.
• 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.
• 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. This can be changed with checkbox "Create a new instance per sample".

public class myTestCase {
  public myTestCase() {}
}

public class myTestCase {
  public myTestCase(String text) {
    super(text);
  }
}

The Mail Reader Sampler can read (and optionally delete) mail messages using POP3(S) or IMAP(S) protocols.

This sampler can also be useful in conjunction with the Transaction Controller, as it allows pauses to be included without needing to generate a sample. For variable delays, set the pause time to zero, and add a Timer as a child.

The "Stop" action stops the thread or test after completing any samples that are in progress. The "Stop Now" action stops the test without waiting for samples to complete; it will interrupt any active samples. If some threads fail to stop within the 5 second time-limit, a message will be displayed in GUI mode. You can try using the Stop command to see if this will stop the threads, but if not, you should exit JMeter. In non-GUI mode, JMeter will exit if some threads fail to stop within the 5 second time limit. [This can be changed using the JMeter property jmeterengine.threadstop.wait]

The SMTP Sampler can send mail messages using SMTP/SMTPS protocol. It is possible to set security propocols for the connection (SSL and TLS), as well as user authentication. If a security protocol is used a verification on the server certificate will occur.
Two alternatives to handle this verification are available:

• Trust all certificates. This will ignore certificate chain verification
• Use a local truststore. With this option the certificate chain will be validated against the local truststore file.

The OS Process Sampler is a sampler that can be used to execute commands on the local machine.
It should allow execution of any command that can be run from the command line.
Validation of the return code can be enabled, and the expected return code can be specified.

Note that OS shells generally provide command-line parsing. This varies between OSes, but generally the shell will split parameters on white-space. Some shells expand wild-card file names; some don't. The quoting mechanism also varies between OSes. The sampler deliberately does not do any parsing or quote handling. The command and its parameters must be provided in the form expected by the executable. This means that the sampler settings will not be portable between OSes.

Many OSes have some built-in commands which are not provided as separate executables. For example the Windows DIR command is part of the command interpreter (CMD.EXE). These built-ins cannot be run as independent programs, but have to be provided as arguments to the appropriate command interpreter.

For example, the Windows command-line: DIR C:\TEMP needs to be specified as follows:

command:   CMD
Param 1:   /C
Param 2:   DIR
Param 3:   C:\TEMP

This sampler lets you send an Request to a MongoDB.

Before using this you need to set up a MongoDB Source Config Configuration element

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.

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.

The Once Only Logic Controller tells JMeter to process the controller(s) inside it only once per Thread, 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 per Thread), 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.

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

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.

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.

This controller is badly named, as it does not control throughput. Please refer to the Constant Throughput Timer for an element that can be used to adjust the throughput.

The Throughput Controller allows the user to control how often it is executed. There are two modes - percent execution and total executions. Percent executions causes the controller to execute a certain percentage of the iterations through the test plan. Total executions causes the controller to stop executing after a certain number of executions have occurred. Like the Once Only Controller, this setting is reset when a parent Loop Controller restarts.

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

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.

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

Possible condition values:

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

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

The Switch Controller acts like the Interleave Controller in that it runs one of the subordinate elements on each iteration, but rather than run them in sequence, the controller runs the element defined by the switch value.

Note: In versions of JMeter after 2.3.1, the switch value can also be a name.

If the switch value is out of range, it will run the zeroth element, which therefore acts as the default for the numeric case. It also runs the zeroth element if the value is the empty string.

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

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.

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

The include controller is designed to use an external jmx file. To use it, create a Test Fragment underneath the Test Plan and add any desired samplers, controllers etc. below it. Then save the Test Plan. The file is now ready to be included as part of other Test Plans.

For convenience, a Thread Group can also be added in the external JMX file for debugging purposes. A Module Controller can be used to reference the Test Fragment. The Thread Group will be ignored during the include process.

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.

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

The Transaction Controller generates an additional sample which measures the overall time taken to perform the nested test elements.

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.

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(S) Test Script Recorder, all recorded samples will by default be saved under the Recording Controller.

The Critical Section Controller ensures that its children elements (samplers/controllers, etc) will be executed by only one thread as a named lock will be taken before executing children of controller.

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.

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

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

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.

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.

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

Match count: 74
Match[1]=#functions
Match[2]=#what_can_do
Match[3]=#where
Match[4]=#how
Match[5]=#function_helper
Match[6]=#functions
Match[7]=#__regexFunction
Match[8]=#__regexFunction_parms
Match[9]=#__counter
... and so on ...

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

image/
audio/
video/

Scroll automatically? option permit to have last node display in tree selection

With Search option, most of the views also allow the displayed data to be searched; the result of the search will be high-lighted in the display above. For example the Control panel screenshot below shows one result of searching for "Java". Note that the search operates on the visible text, so you may get different results when searching the Text and HTML views.
Note: The regular expression uses the Java engine (not ORO engine like the Regular Expression Extractor or Regexp Tester view).

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.

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

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

Calculation of the Median and 90% Line (90^th percentile) values requires additional memory. JMeter now combines samples with the same elapsed time, so far less memory is used. However, for samples that take more than a few seconds, the probability is that fewer samples will have identical times, in which case more memory will be needed. Note you can use this listener afterwards to reload a CSV or XML results file which is the recommended way to avoid performance impacts. See the Summary Report for a similar Listener that does not store individual samples and so needs constant memory.

• Label - The label of the sample. If "Include group name in label?" is selected, then the name of the thread group is added as a prefix. This allows identical labels from different thread groups to be collated separately if required.
• # Samples - The number of samples with the same label
• Average - The average time of a set of results
• Median - The median is the time in the middle of a set of results. 50% of the samples took no more than this time; the remainder took at least as long.
• 90% Line - 90% of the samples took no more than this time. The remaining samples took at least as long as this. (90^th percentile)
• 95% Line - 95% of the samples took no more than this time. The remaining samples took at least as long as this. (95^th percentile)
• 99% Line - 99% of the samples took no more than this time. The remaining samples took at least as long as this. (99^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.

By default, it only displays the main (parent) samples; it does not display the sub-samples (child samples). Versions of JMeter after 2.5.1 have a "Child Samples?" check-box. If this is selected, then the sub-samples are displayed instead of the main samples.

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.

For a detailed description of how to use the monitor, please refer to Building a Monitor Test Plan

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

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

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

For full details on using BeanShell, please see the BeanShell website.

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.

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

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

The current sample is saved first, followed by any sub-samples (child samples). If a variable name is provided, then the names of the files are saved in the order that the sub-samples appear. See below.

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

The JSR223 Listener allows JSR223 script code to be applied to sample results. For details, see BSF Listener.

# Define the following property to automatically start a summariser with that name
# (applies to non-GUI mode only)
#summariser.name=summary
#
# interval between summaries (in seconds) default 3 minutes
#summariser.interval=30
#
# Write messages to log file
#summariser.log=true
#
# Write messages to System.out
#summariser.out=true

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

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

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.

Versions of JMeter after 2.3.1 allow values 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. If "allow quoted data" is enabled, a value may be enclosed in double-quotes. These are removed. To include double-quotes within a quoted field, use two double-quotes. For example:

1,"2,3","4""5" =>
1
2,3
4"5

Versions of JMeter after 2.3.4 support CSV files which have a header line defining the column names. To enable this, leave the "Variable Names" field empty. The correct delimiter must be provided.

Versions of JMeter after 2.7 support CSV files with quoted data that includes new-lines.

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

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.

The DNS Cache Manager element allows to test applications, which have several servers behind load balancers (CDN, etc), when user receives content from different IP's. By default JMeter uses JVM DNS cache. That's why only one server from the cluster receives load. DNS Cache Manager resolves name for each thread separately each iteration and saves results of resolving to its internal DNS Cache, which independent from both JVM and OS DNS caches.

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 may not be shown in the Tree View Listener "Request" tab. The Java implementation does pre-emptive authentication, but it does not return the Authorization header when JMeter fetches the headers. The Commons HttpClient (3.1) implementation defaults to pre-emptive and the header will be shown. The HttpComponents implementation does not do pre-emptive auth (it is supported by the library but JMeter does not enable it)

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

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

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

The HTTP Cache Manager is used to add caching functionality to HTTP requests within its scope to simulate browser cache feature. Each Virtual User thread has its own Cache. By default, Cache Manager will store up to 5000 items in cache per Virtual User thread, using LRU algorithm. Use property "maxSize" to modify this value. Note that the more you increase this value the more HTTP Cache Manager will consume memory, so be sure to adapt -Xmx option accordingly.

If a sample is successful (i.e. has response code 2xx) then the Last-Modified and Etag (and Expired if relevant) 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.

Additionally, if the "Use Cache-Control/Expires header" option is selected, then the Cache-Control/Expires value is checked against the current time. If the request is a GET request, and the timestamp is in the future, then the sampler returns immediately, without requesting the URL from the remote server. This is intended to emulate browser behaviour. Note that if Cache-Control header is "no-cache", the response will be stored in cache as pre-expired, so will generate a conditional GET request. If Cache-Control has any other value, the "max-age" expiry option is processed to compute entry lifetime, if missing then expire header will be used, if also missing entry will be cached as specified in RFC 2616 section 13.2.4. using Last-Modified time and response Date.

If the requested document has not changed since it was cached, then the response body will be empty. Likewise if the Expires date is in the future. This may cause problems for Assertions.

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

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.

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.

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

The Keystore Config Element lets you configure how Keystore will be loaded and which keys it will use. This component is typically used in HTTPS scenarios where you don't want to take into account keystore initialization into account in response time.

To use this element, you need to setup first a Java Key Store with the client certificates you want to test, to do that:

1. Create your certificates either with Java keytool utility or through your PKI
2. If created by PKI, import your keys in Java Key Store by converting them to a format acceptable by JKS
3. Then reference the keystore file through the 2 JVM properties (or add them in system.properties):
   • -Djavax.net.ssl.keyStore=path_to_keystore
   • -Djavax.net.ssl.keyStorePassword=password_of_keystore

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.

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

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

The TCP Sampler Config provides default data for the TCP Sampler

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:

HOST      ${__P(host,localhost)} 

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.

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.

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.

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

import com.mongodb.DB;
import org.apache.jmeter.protocol.mongodb.config.MongoDBHolder;
DB db = MongoDBHolder.getDBFromSource("value of property MongoDB Source",
            "value of property Database Name");
...
    

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 ORO Perl5 regular expressions.

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

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

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.

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.

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.

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

For full details on using BeanShell, please see the BeanShell website.

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.

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

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

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.

• //title[text()='Text to match'] - matches <text>Text to match</text> anywhere in the response
• /title[text()='Text to match'] - matches <text>Text to match</text> at root level in the response

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

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

The JSR223 Assertion allows JSR223 script code to be used to check the status of the previous sample. For details, see BSF Assertion.

• bcmail-xxx.jar (BouncyCastle SMIME/CMS)
• bcprov-xxx.jar (BouncyCastle Provider)

If using the Mail Reader Sampler, please ensure that you select "Store the message using MIME (raw)" otherwise the Assertion won't be able to process the message correctly.

If you want to have each thread pause for the same amount of time between requests, use this 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. Another way to explain it, in Gaussian Random Timer, the variation around constant offset has a gaussian curve distribution.

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.

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.

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.

The BeanShell Timer can be used to generate a delay.

For full details on using BeanShell, please see the BeanShell website.

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.

The BSF Timer can be used to generate a delay using a BSF scripting language.

The JSR223 Timer can be used to generate a delay using a JSR223 scripting language, For details, see BSF 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 Poisson distributed value, and the offset value.

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.

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.

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.

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.

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

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

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

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

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

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

For full details on using BeanShell, please see the BeanShell website.

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.

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

The JSR223 PreProcessor allows JSR223 script code to be applied before taking a sample. For details, see BSF PreProcessor.

The JDBC PreProcessor enables you to run some SQL statement just before a sample runs. This can be useful if your JDBC Sample requires some data to be in DataBase and you cannot compute this in a setup Thread group. For details, see JDBC Request.

See the following Test plan:

In the linked test plan,"Create Price Cut-Off" JDBC PreProcessor calls a stored procedure to create a Price Cut-Off in Database, this one will be used by "Calculate Price cut off".

Allows to specify dynamic values for HTTP parameters extracted from another HTTP Request using regular expressions. RegEx User Parameters are specific to individual threads.

This component allows you to specify reference name of a regular expression that extracts names and values of HTTP request parameters. Regular expression group numbers must be specified for parameter's name and also for parameter's value. Replacement will only occur for parameters in the Sampler that uses this RegEx User Parameters which name matches

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

Allows the user to extract values from a server response using a CSS/JQuery selector like syntax. As a post-processor, this element will execute after each Sample request in its scope, applying the CSS/JQuery expression, extracting the requested nodes, extracting the node as text or attribute value and store the result into the given variable name.

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

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.

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

The JSR223 PostProcessor allows JSR223 script code to be applied after taking a sample. For details, see the BSF PostProcessor.

The JDBC PostProcessor enables you to run some SQL statement just after a sample has run. This can be useful if your JDBC Sample changes some data and you want to reset state to what it was before the JDBC sample run.

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

Run tearDown Thread Groups after shutdown of main threads: if selected, the tearDown groups (if any) will be run after graceful shutdown of the main threads. The tearDown threads won't be run if the test is forcibly stopped.

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. Note that this cannot be used to add JMeter GUI plugins, because they are processed earlier. However it can be useful for utility jars such as JDBC drivers. The jars are only added to the search path for the JMeter loader, not for the system class loader.

JMeter properties also provides an entry for loading additional classpaths. In jmeter.properties, edit "user.classpath" or "plugin_dependency_paths" to include additional libraries. See JMeter's Classpath and Configuring JMeter for details.

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.

See also tearDown Thread Group and setUp Thread Group.

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.

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 by default unless you check "Save Workbench" option. 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(S) Test Script Recorder
• HTTP Mirror Server
• Property Display

The HTTP(S) Test Script Recorder allows JMeter to intercept 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).
Ensure you read this wiki page to setup correctly JMeter.

To use the recorder, add the HTTP(S) Test Script Recorder 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(S) Test Script Recorder).

The recorder is implemented as an HTTP(S) proxy server. You need to set up your browser use the proxy for all HTTP and HTTPS requests. [Do not use JMeter as the proxy for any other request types - FTP, etc. - as JMeter cannot handle them.]

Ideally use private browsing mode when recording the session. This should ensure that the browser starts with no stored cookies, and prevents certain changes from being saved. For example, Firefox does not allow certificate overrides to be saved permanently.

HTTPS recording and certificates

HTTPS connections use certificates to authenticate the connection between the browser and the web server. When connecting via HTTPS, the server presents the certificate to the browser. To authenticate the certificate, the browser checks that the server certificate is signed by a Certificate Authority (CA) that is linked to one of its in-built root CAs. [Browsers also check that the certificate is for the correct host or domain, and that it is valid and not expired.] If any of the browser checks fail, it will prompt the user who can then decided whether to allow the connection to proceed.

JMeter needs to use its own certificate to enable it to intercept the HTTPS connection from the browser. Effectively JMeter has to pretend to be the target server.

For versions of JMeter from 2.10, JMeter will generate its own certificate(s). These are generated with a validity period defined by the property proxy.cert.validity, default 7 days, and random passwords. If JMeter detects that it is running under Java 7 or later, it will generate certificates for each target server as necessary (dynamic mode) unless the following property is defined: proxy.cert.dynamic_keys=false. When using dynamic mode, the certificate will be for the correct host name, and will be signed by a JMeter-generated CA certificate. By default, this CA certificate won't be trusted by the browser, however it can be installed as a trusted certificate. Once this is done, the generated server certificates will be accepted by the browser. This has the advantage that even embedded HTTPS resources can be intercepted, and there is no need to override the browser checks for each new server. (Browsers don't prompt for embedded resources. So with earlier versions, embedded resources would only be downloaded for servers that were already 'known' to the browser)

Unless a keystore is provided (and you define the property proxy.cert.alias), JMeter needs to use the keytool application to create the keystore entries. Versions of JMeter after 2.10 include code to check that keytool is available by looking in various standard places. If JMeter is unable to find the keytool application, it will report an error. If necessary, the systen property keytool.directory can be used to tell JMeter where to find keytool. This should be defined in the file system.properties.

The JMeter certificates are generated (if necessary) when the Start button is pressed. Certificate generation can take some while, during which time the GUI will be unresponsive. The cursor is changed to an hour-glass whilst this is happening. When certificate generation is complete, the GUI will display a pop-up dialogue containing the details of the certificate for the root CA. This certificate needs to be installed by the browser in order for it to accept the host certificates generated by JMeter; see below for details.

If necessary, you can force JMeter to regenerate the keystore (and the exported certificates - ApacheJMeterTemporaryRootCA[.usr|.crt]) by deleting the keystore file proxyserver.jks from the JMeter directory.

With versions of JMeter up to 2.9, it used a single certificate for all target servers. [Likewise if JMeter is not being run under Java 7 or later] This certificate is not one of the certificates that browsers normally trust, and will not be for the correct host.
As a consequence:

• The browser should display a dialogue asking if you want to accept the certificate or not. For example:

  1) The server's name "www.example.com" does not match the certificate's name
     "JMeter Proxy (DO NOT TRUST)". Somebody may be trying to eavesdrop on you.
  2) The certificate for "JMeter Proxy (DO NOT TRUST)" is signed by the unknown Certificate Authority
     "JMeter Proxy (DO NOT TRUST)". It is not possible to verify that this is a valid certificate.
  

  You will need to accept the certificate in order to allow the JMeter Proxy to intercept the SSL traffic in order to record it. However, do not accept this certificate permanently; it should only be accepted temporarily. Browsers only prompt this dialogue for the certificate of the main url, not for the resources loaded in the page, such as images, css or javascript files hosted on a secured external CDN. If you have such resources (gmail has for example), you'll have to first browse manually to these other domains in order to accept JMeter's certificate for them. Check in jmeter.log for secure domains that you need to register certificate for.
• If the browser has already registered a validated certificate for this domain, the browser will detect JMeter as a security breach and will refuse to load the page. If so, you have to remove the trusted certificate from your browser's keystore.

Versions of JMeter from 2.10 onwards still support this method, and will continue to do so if the you define the following property: proxy.cert.alias The following properties can be used to change the certificate that is used:

• proxy.cert.directory - the directory in which to find the certificate (default = JMeter bin/)
• proxy.cert.file - name of the keystore file (default "proxyserver.jks")
• proxy.cert.keystorepass - keystore password (default "password") [Ignored if using JMeter certificate]
• proxy.cert.keypassword - certificate key password (default "password") [Ignored if using JMeter certificate]
• proxy.cert.type - the certificate type (default "JKS") [Ignored if using JMeter certificate]
• proxy.cert.factory - the factory (default "SunX509") [Ignored if using JMeter certificate]
• proxy.cert.alias - the alias for the key to be used. If this is defined, JMeter does not attempt to generate its own certificate(s).
• proxy.ssl.protocol - the protocol to be used (default "SSLv3")

Installing the JMeter CA certificate for HTTPS recording

As mentioned above, when run under Java 7, JMeter can generate certificates for each server. For this to work smoothly, the root CA signing certificate used by JMeter needs to be trusted by the browser. The first time that the recorder is started, it will generate the certificates if necessary. The root CA certificate is exported into a file with the name ApacheJMeterTemporaryRootCA in the current launch directory. When the certificates have been set up, JMeter will show a dialog with the current certificate details. At this point, the certificate can be imported into the browser, as per the instructions below.

Note that once the root CA certificate has been installed as a trusted CA, the browser will trust any certificates signed by it. Until such time as the certificate expires or the certificate is removed from the browser, it will not warn the user that the certificate is being relied upon. So anyone that can get hold of the keystore and password can use the certificate to generate certificates which will be accepted by any browsers that trust the JMeter root CA certificate. For this reason, the password for the keystore and private keys are randomly generated and a short validity period used. The passwords are stored in the local preferences area. Please ensure that only trusted users have access to the host with the keystore.

Installing the certificate in Firefox

Choose the following options:

• Tools / Options
• Advanced / Certificates
• View Certificates
• Authorities
• Import ...
• Browse to the JMeter launch directory, and click on the file ApacheJMeterTemporaryRootCA.crt, press Open
• Click View and check that the certificate details agree with the ones displayed by the JMeter Test Script Recorder
• If OK, select "Trust this CA to identify web sites", and press OK
• Close dialogs by pressing OK as necessary

Installing the certificate in Chrome or Internet Explorer

Both Chrome and Internet Explorer use the same trust store for certificates.

• Browse to the JMeter launch directory, and click on the file ApacheJMeterTemporaryRootCA.crt, and open it
• Click on the "Details" tab and check that the certificate details agree with the ones displayed by the JMeter Test Script Recorder
• If OK, go back to the "General" tab, and click on "Install Certificate ..." and follow the Wizard prompts

Installing the certificate in Opera

• Tools / Preferences / Advanced / Security
• Manage Certificates...
• Select "Intermediate" tab, click "Import..."
• Browse to the JMeter launch directory, and click on the file ApacheJMeterTemporaryRootCA.usr, and open it

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.

It uses default port 8081 since 2.6.

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.

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.

The Debug PostProcessor creates a subSample with the details of the previous Sampler properties, JMeter variables, properties and/or System Properties.

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

The Test Fragment is used in conjunction with the Include Controller and Module Controller.

A special type of ThreadGroup that can be utilized to perform Pre-Test Actions. The behavior of these threads is exactly like a normal Thread Group element. The difference is that these type of threads execute before the test proceeds to the executing of regular Thread Groups.

A special type of ThreadGroup that can be utilized to perform Post-Test Actions. The behavior of these threads is exactly like a normal Thread Group element. The difference is that these type of threads execute after the test has finished executing its regular Thread Groups.