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

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

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

If you are going to send multiple requests to the same web server, consider using an 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 to create them. This can save you time if you have a lot of HTTP requests or requests with many parameters.

There are three versions of the sampler:

• HTTP Request - uses the default Java HTTP implementation
• HTTP Request HTTPClient - uses Apache Commons HttpClient
• AJP/1.3 Sampler - uses the Tomcat mod_jk protocol (allows testing of Tomcat in AJP mode without needing Apache httpd) The AJP Sampler does not support multiple file upload; only the first file will be used.

The default (Java) implementation has some limitations:

• There is no control over how connections are re-used. When a connection is released by JMeter, it may or may not be re-used by the same thread.
• The API is best suited to single-threaded usage - various settings (e.g. proxy) are defined via system properties, and therefore apply to all connections.
• There is a bug in the handling of HTTPS via a Proxy (the CONNECT is not handled correctly). See Java bugs 6226610 and 6208335.

Note: the FILE protocol is intended for testing puposes only. It is handled by the same code regardless of which HTTP Sampler is used.

If the request requires server or proxy login authorization (i.e. where a browser would create a pop-up dialog box), you will also have to add an Configuration Element. For normal logins (i.e. where the user enters login information in a form), you will need to work out what the form submit button does, and create an HTTP request with the appropriate method (usually POST) and the appropriate parameters from the form definition. If the page uses HTTP, you can use the JMeter Proxy to capture the login sequence.

In versions of JMeter up to 2.2, only a single SSL context was used for all threads and samplers. This did not generate the proper load for multiple users. A separate SSL context is now used for each thread. To revert to the original behaviour, set the JMeter property:

https.sessioncontext.shared=true

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

https.default.protocol=SSLv3

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

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

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

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

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 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 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 the every image and html file. The current implementation is complete, but some features have not been enabled. There is a filter for the access log parser, but I haven't figured out how to link to the pre-processor. Once I do, changes to the sampler will be made to enable that functionality.

Tomcat uses the common format for access logs. This means any webserver that uses the common log format can use the AccessLogSampler. Server that use common log format include: Tomcat, Resin, Weblogic, and SunOne. Common log format looks like this:

127.0.0.1 - - [21/Oct/2003:05:37:21 -0500] "GET /index.jsp?%2Findex.jsp= HTTP/1.1" 200 8343

The current implemenation of the parser only looks at the text within the quotes. Everything else is stripped out and igored. For example, the response code is completely ignored by the parser. For the future, it might be nice to filter out entries that do not have a response code of 200. Extending the sampler should be fairly simple. There are two interfaces you have to implement.

org.apache.jmeter.protocol.http.util.accesslog.LogParser

org.apache.jmeter.protocol.http.util.accesslog.Generator

The current implementation of AccessLogSampler uses the generator to create a new HTTPSampler. The servername, port and get images are set by AccessLogSampler. Next, the parser is called with integer 1, telling it to parse one entry. After that, HTTPSampler.sample() is called to make the request.

            samp = (HTTPSampler) GENERATOR.generateRequest();
            samp.setDomain(this.getDomain());
            samp.setPort(this.getPort());
            samp.setImageParser(this.isImageParser());
            PARSER.parse(1);
            res = samp.sample();
            res.setSampleLabel(samp.toString());

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

For full details on using BeanShell, please see the BeanShell web-site at http://www.beanshell.org/.

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

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 TCP Sampler opens a TCP/IP connection to the specified server. It then sends the text, and waits for a response.

If "Re-use connection" is selected, connections are shared between Samplers in the same thread, provided that the exact same host name string and port are used. Different hosts/port combinations will use different connections, as will different threads.

If an error is detected - or "Re-use connection" is not selected - the socket is closed. Another socket will be reopened on the next sample.

The following properties can be used to control its operation:

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

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.

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 pub/sub topic. For those not familiar with JMS, it is the J2EE specification for messaging. There are numerous JMS servers on the market and several open source options.

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

This sampler sends and optionally receives JMS Messages through point-to-point connections (queues). It is different from pub/sub messages and is generally used for handling transactions.

Versions of JMeter after 2.3.2 use the properties java.naming.security.[principal|credentials] - if present - when creating the Queue Connection. If this behaviour is not desired, set the JMeter property JMSSampler.useSecurity.properties=false

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 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, and pass over any requests under it during further iterations through the test plan.

The Once Only Controller will now execute always during the first iteration of any looping parent controller. Thus, if the Once Only Controller is placed under a Loop Controller specified to loop 5 times, then the Once Only Controller will execute only on the first iteration through the Loop Controller (ie, every 5 times). Note this means the Once Only Controller will still behave as previously expected if put under a Thread Group (runs only once per test), but now the user has more flexibility in the use of the Once Only Controller.

For testing that requires a login, consider placing the login request in this controller since each thread only needs to login once to establish a session.

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 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 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 . 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, add samples to a simple controller, then save the simple controller as a jmx file. The file can then be used in a test plan. The included test plan must not include a Thread Group. It should only contain the Simple Controller and any samplers, controllers etc below it.

If the test uses a Cookie Manager or User Defined Variables, these should be placed in the top-level test plan, not the included file, otherwise they are not guaranteed to work.

The Transaction Controller generates an additional sample which measures the overall time taken to perform the nested test elements. Note that this time includes all processing within the controller scope, not just the samples.

For JMeter versions after 2.3, there are two modes of operation

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

The generated sample time includes all the times for the nested samplers, and any timers etc. Depending on the clock resolution, it may be slightly longer than the sum of the individual samplers plus timers. The clock might tick after the controller recorded the start time but before the first sample starts. Similarly at the end.

The generated sample is only regarded as successful if all its sub-samples are successful.

In parent mode, the individual samples can still be seen in the Tree View Listener, but no longer appear as separate entries in other Listeners. Also, the sub-samples do not appear in CSV log files, but they can be saved to XML files.

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 , all recorded samples will by default be saved under the Recording 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 radio button.

• Show text
• Render HTML
• Render XML
• Render JSON

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

image/
audio/
video/

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.

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

Times are in milliseconds.

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 web-site at http://www.beanshell.org/.

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

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

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 variables to be quoted; this allows the value to contain a delimiter. Previously it was necessary to choose a delimiter that was not used in any values.

By default, the file is only opened once, and each thread will use a different line from the file. However the order in which lines are passed to threads depends on the order in which they execute, which may vary between iterations. Lines are read at the start of each test iteration. The file name and mode are resolved in the first iteration.

See the description of the Share mode below for additional options (JMeter 2.3.2+). If you want each thread to have its own set of values, then you will need to create a set of files, one for each thread. For example test1.csv, test2.csv,... testn.csv. Use the filename test${__threadNum}.csv and set the "Sharing mode" to "Current thread".

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

The Authorisation headers are not shown in the Tree View Listener.

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

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.

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

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

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

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 .

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

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

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

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

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

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

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

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

	(?i) - ignore case
	(?s) - treat target as single line, i.e. "." matches new-line
	(?is) - both the above
    These can be used anywhere within the expression and remain in effect until overriden.  e.g.
    (?i)apple(?-i) Pie - matches "ApPLe Pie", but not "ApPLe pIe"
    (?s)Apple.+?Pie - matches Apple followed by Pie, which may be on a subsequent line.
    Apple(?s).+?Pie - same as above, but it's probably clearer to use the (?s) at the start.  

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 web-site at http://www.beanshell.org/.

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

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

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

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

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.

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.

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.

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 web-site at http://www.beanshell.org/.

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

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

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.

See also the element, which is more suitable for large numbers of parameters

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

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 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 web-site at http://www.beanshell.org/.

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

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

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.

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

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

For full details on using BeanShell, please see the BeanShell web-site at http://www.beanshell.org/.

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

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

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 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 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 serially rather than in parallel.

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

In jmeter.properties, edit "user.classpath" to include additional libraries.

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

When using the scheduler, JMeter runs the thread group until either the number of loops is reached or the duration/end-time is reached - whichever occurs first. Note that the condition is only checked between samples; when the end condition is reached, that thread will stop. JMeter does not interrupt samplers which are waiting for a response, so the end time may be delayed arbitrarily.

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

Certain test elements are only available on the WorkBench:

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

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

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

When recording HTTPS, the JMeter proxy server uses a dummy certificate to enable it to accept the SSL connection from the browser. This certificate is not one of the certificates that browsers normally trust, and will not be for the correct host, so 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". Somebody may be trying to eavesdrop on you. 2) The certificate for "JMeter Proxy" is signed by the unknown Certificate Authority "JMeter Proxy". 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. You should only accept the certificate temporarily.

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.

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 Listener Response Data pane.

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