Latency is set to the time it takes to login.

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 (CSS) and resources referenced from those files
• external scripts
• frames, iframes
• background images (body, table, TD, TR)
• background sound

The default parser is org.apache.jmeter.protocol.http.parser.LagartoBasedHtmlParser. 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

(DEPRECATED SINCE 3.0) uses Apache Commons HttpClient 3.1. This is no longer being developed, and support for this will 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 supports only the following methods: GET, POST, HEAD, OPTIONS, PUT, DELETE and TRACE
• It does not support client based certificate testing with Keystore Config.

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.

A separate SSL context is used for each thread. If you want to use a single SSL context (not the standard behaviour of browsers), set the JMeter property:

https.sessioncontext.shared=true

https.use.cached.ssl.context=false

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 a JDBC Request (an SQL query) to a database.

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

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

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

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

Old variables are cleared if necessary - e.g. if the first select retrieves six rows and a second select returns only three rows, the additional variables for rows four, five and six will be removed.

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 HTTP Header Manager. Note that the sampler will use all the headers from the HTTP Header Manager. If a SOAP action is specified, that will override any SOAPaction in the HTTP Header Manager. 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.

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)

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.

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.

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
• 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 check Cache compiled script if available property.
  When using this feature, ensure your script code does not use JMeter variables directly in script code as caching would only cache first replacement. Instead use script parameters.
  To benefit from caching and compilation, the language engine used for scripting must implement JSR223 Compilable interface (Groovy is one of these, java, beanshell and javascript are not)
  When using Groovy as scripting language and not checking Cache compiled script if available (while caching is recommended), you should set this JVM Property -Dgroovy.use.classvalue=true due to a Groovy Memory leak as of version 2.4.6, see:

  • GROOVY-7683
  • GROOVY-7591
  • JDK-8136353

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

Usage of pre- and suffix¶

For example, if the prefix = "[" and the suffix = "]", then the following response:

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

JMeter 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. 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 Java Request. 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.

The SMTP Sampler can send mail messages using SMTP/SMTPS protocol. It is possible to set security protocols 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 a 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 (i.e. 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.

The Throughput Controller allows the user to control how often it is executed. There are two modes:

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

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.

By default, the condition is evaluated only once on initial entry, but you have the option to have it evaluated for every runnable element contained in the controller.

The script can 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: ${__jexl3(${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.

"${myVar}" == "\${myVar}"

"${myVar}" != "\${myVar}"

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.

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 (or controller) is executed one or more times, where during every loop the variable has a new value. The input should consist of several variables, each extended with an underscore and a number. Each such variable must have a value. So for example when the input variable has the name inputVar, the following variables should have been defined:

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

Note: the "_" separator is now optional.

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

It is especially suited for running with the regular expression post-processor. This can "create" the necessary input variables out of the result data of a previous request. By omitting the "_" separator, the ForEach Controller can be used to loop through the groups by using the input variable refName_g, and can also loop through all the groups in all the matches by using an input variable of the form refName_${C}_g, where C is a counter variable.

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

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.

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

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 excluding by default (since 2.11) timers and processing time of pre/post processors unless checkbox "Include duration of timer and pre-post processors in generated sample" is checked. 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 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 throughput 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.
• Received KB/sec - The throughput measured in received Kilobytes per second
• Sent KB/sec - The throughput measured in sent 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). JMeter has 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 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 throughput 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.
• Received KB/sec - The throughput measured in Kilobytes per second
• Sent KB/sec - The throughput measured in Kilobytes per second
• Avg. Bytes - average size of the sample response in bytes.

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.

# 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 +     16 in 0:00:12 =    1.3/s Avg:  1608 Min:  1163 Max:  2009 Err:     0 (0.00%) Active: 5 Started: 5 Finished: 0
label +     82 in 0:00:30 =    2.7/s Avg:  1518 Min:  1003 Max:  2020 Err:     0 (0.00%) Active: 5 Started: 5 Finished: 0
label =     98 in 0:00:42 =    2.3/s Avg:  1533 Min:  1003 Max:  2020 Err:     0 (0.00%)
label +     85 in 0:00:30 =    2.8/s Avg:  1505 Min:  1008 Max:  2005 Err:     0 (0.00%) Active: 5 Started: 5 Finished: 0
label =    183 in 0:01:13 =    2.5/s Avg:  1520 Min:  1003 Max:  2020 Err:     0 (0.00%)
label +     79 in 0:00:30 =    2.7/s Avg:  1578 Min:  1089 Max:  2012 Err:     0 (0.00%) Active: 5 Started: 5 Finished: 0
label =    262 in 0:01:43 =    2.6/s Avg:  1538 Min:  1003 Max:  2020 Err:     0 (0.00%)
label +     80 in 0:00:30 =    2.7/s Avg:  1531 Min:  1013 Max:  2014 Err:     0 (0.00%) Active: 5 Started: 5 Finished: 0
label =    342 in 0:02:12 =    2.6/s Avg:  1536 Min:  1003 Max:  2020 Err:     0 (0.00%)
label +     83 in 0:00:31 =    2.7/s Avg:  1512 Min:  1003 Max:  1982 Err:     0 (0.00%) Active: 5 Started: 5 Finished: 0
label =    425 in 0:02:43 =    2.6/s Avg:  1531 Min:  1003 Max:  2020 Err:     0 (0.00%)
label +     83 in 0:00:29 =    2.8/s Avg:  1487 Min:  1023 Max:  2013 Err:     0 (0.00%) Active: 5 Started: 5 Finished: 0
label =    508 in 0:03:12 =    2.6/s Avg:  1524 Min:  1003 Max:  2020 Err:     0 (0.00%)
label +     78 in 0:00:30 =    2.6/s Avg:  1594 Min:  1013 Max:  2016 Err:     0 (0.00%) Active: 5 Started: 5 Finished: 0
label =    586 in 0:03:43 =    2.6/s Avg:  1533 Min:  1003 Max:  2020 Err:     0 (0.00%)
label +     80 in 0:00:30 =    2.7/s Avg:  1516 Min:  1013 Max:  2005 Err:     0 (0.00%) Active: 5 Started: 5 Finished: 0
label =    666 in 0:04:12 =    2.6/s Avg:  1531 Min:  1003 Max:  2020 Err:     0 (0.00%)
label +     86 in 0:00:30 =    2.9/s Avg:  1449 Min:  1004 Max:  2017 Err:     0 (0.00%) Active: 5 Started: 5 Finished: 0
label =    752 in 0:04:43 =    2.7/s Avg:  1522 Min:  1003 Max:  2020 Err:     0 (0.00%)
label +     65 in 0:00:24 =    2.7/s Avg:  1579 Min:  1007 Max:  2003 Err:     0 (0.00%) Active: 0 Started: 5 Finished: 5
label =    817 in 0:05:07 =    2.7/s Avg:  1526 Min:  1003 Max:  2020 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 testing 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.

JMeter allows values to be quoted; this allows the value to contain a delimiter. 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

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

JMeter supports 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. 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 Authorization 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 (HC 4.5.X) implementation does not do pre-emptive auth (it is supported by the library but JMeter does not enable it)

The HttpClient3.1 implementation 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.

In the file jmeter.properties set httpclient.parameters.file=httpclient.parameters and in httpclient.parameters set 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 the -Xmx jvm 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.

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 checks that received cookies are valid for the URL. This means that cross-domain cookies are not stored. If you have bugged behaviour or want Cross-Domain cookies to be used, define the JMeter property "CookieManager.check.cookies=false".

Received Cookies can be stored as JMeter thread variables. 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

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.

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

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

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.

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.

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

You can then access com.mongodb.DB object in Beanshell or JSR223 Test Elements through the element MongoDBHolder using this code

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

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

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.