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

Latency is set to the time it takes to login.

Parameters ¶

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

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

GraphQL HTTP Request

this is a GUI variation of the HTTP Request to provide more convenient UI elements to view or edit GraphQL Query, Variables and Operation Name, while converting them into HTTP Arguments automatically under the hood using the same sampler. This hides or customizes the following UI elements as they are less convenient for or irrelevant to GraphQL over HTTP/HTTPS requests:

• Method: Only POST and GET methods are available conforming the GraphQL over HTTP specification. POST method is selected by default.
• Parameters and Post Body tabs: you may view or edit parameter content through Query, Variables and Operation Name UI elements instead.
• File Upload tab: irrelevant to GraphQL queries.
• Embedded Resources from HTML Files section in the Advanced tab: irrelevant in GraphQL JSON responses.

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.
• No support of Kerberos authentication
• It does not support client based certificate testing with Keystore Config.
• Better control of Retry mechanism
• It does not support virtual hosts.
• It supports only the following methods: GET, POST, HEAD, OPTIONS, PUT, DELETE and TRACE
• Better control on DNS Caching with DNS Cache Manager

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

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

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

By default, since version 5.0, the SSL context is retained during a Thread Group iteration and reset for each test iteration. If in your test plan the same user iterates multiple times, then you should set this to false.

httpclient.reset_state_on_thread_group_iteration=true

Note: this does not apply to the Java HTTP implementation.

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

https.default.protocol=SSLv3

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

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

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

Parameters ¶

"Redirect requested but followRedirects is disabled"

Parameters ¶

With HC4 Implementation, retry will be done on Idempotent Http Methods by default. If you want to retry for all methods, then set property

httpclient4.request_sent_retry_enabled=true

See also:

• Assertion
• Building a Web Test Plan
• Building an Advanced Web Test Plan
• HTTP Authorization Manager
• HTTP Cookie Manager
• HTTP Header Manager
• HTML Link Parser
• HTTP(S) Test Script Recorder
• HTTP Request Defaults
• HTTP Requests and Session ID's: URL Rewriting

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.

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

Parameters ¶

"Dbl-Quote: "" and Comma: ,"

columnValue = vars.getObject("resultObject").get(0).get("Column Name");

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.

Parameters ¶

Parameters ¶

totalSleepTime = SleepTime + (System.currentTimeMillis() % SleepMask)

Parameters ¶

This Sampler lets you send a different LDAP request(Add, Modify, Delete and Search) to an LDAP server.

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

The same way the Login Config Element also using for Login and password.

Parameters ¶

This Sampler can send all 8 different LDAP requests to an LDAP server. It is an extended version of the LDAP sampler, therefore it is harder to configure, but can be made much closer resembling a real LDAP session.

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

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

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 implementation of the parser only looks at the text within the quotes that contains one of the HTTP protocol methods (GET, PUT, POST, DELETE, …). Everything else is stripped out and ignored. For example, the response code is completely ignored by the parser.

For the future, it might be nice to filter out entries that do not have a response code of 200. Extending the sampler should be fairly simple. There are two interfaces you have to implement:

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

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

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

The required methods in LogParser are:

• setGenerator(Generator)
• 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.

Parameters ¶

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

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

Migration to JSR223 Sampler+Groovy is highly recommended for performance, support of new Java features and limited maintenance of the BeanShell library.

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.

Parameters ¶

The JSR223 Sampler allows JSR223 script code to be used to perform a sample or some computation required to create/update variables.

SampleResult.setIgnore();

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 or JMeter function calls 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

Cache size is controlled by the following JMeter property (jmeter.properties):

jsr223.compiled_scripts_cache_size=100

Unlike the BeanShell Sampler, the interpreter is not saved between invocations.

JSR223 Test Elements using Script file or Script text + checked Cache compiled script if available are now compiled if ScriptEngine supports this feature, this enables great performance enhancements.

JMeter processes function and variable references before passing the script field to the interpreter, so the references will only be resolved once. Variable and function references in script files will be passed verbatim to the interpreter, which is likely to cause a syntax error. In order to use runtime variables, please use the appropriate props methods, e.g.

props.get("START.HMS");
props.put("PROP1","1234");

Parameters ¶

$log.debug("Hello " + $vars.get("a"));

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

The class that handles the connection is defined by the GUI, failing that the property tcp.handler. If not found, the class is then searched for in the package org.apache.jmeter.protocol.tcp.sampler.

Users can provide their own implementation. The class must extend org.apache.jmeter.protocol.tcp.sampler.TCPClient.

The following implementations are currently provided.

• TCPClientImpl
• BinaryTCPClientImpl
• LengthPrefixedBinaryTCPClientImpl

The implementations behave as follows:

TCPClientImpl

This implementation is fairly basic. When reading the response, it reads until the end of line byte, if this is defined by setting the property tcp.eolByte, otherwise until the end of the input stream. 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!]

The login name/password are not used by the supplied TCP implementations.

Sockets are disconnected at the end of a test run.

Parameters ¶

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.

JMeter does not include any JMS implementation jar; this must be downloaded from the JMS provider and put in the lib directory

Parameters ¶

The Object message is implemented and works as follow:

• Put the JAR that contains your object and its dependencies in jmeter_home/lib/ folder
• Serialize your object as XML using XStream
• Either put result in a file suffixed with .txt or .obj or put XML content directly in Text Area

Note that if message is in a file, replacement of properties will not occur while it will if you use Text Area.

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

JMeter does not include any JMS implementation jar; this must be downloaded from the JMS provider and put in the lib directory

Parameters ¶

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_reply 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.
browse returns the current queue depth, i.e. the number of messages on the queue.
read reads a message from the queue (if any).
clear clears the queue, i.e. remove all messages from the queue.

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

JMeter does not include any JMS implementation jar; this must be downloaded from the JMS provider and put in the lib directory

Parameters ¶

The current implementation supports standard JUnit convention and extensions. It also includes extensions like oneTimeSetUp and oneTimeTearDown. The sampler works like the Java Request with some differences.

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

The current implementation of the sampler will try to create an instance using the string constructor first. If the test class does not declare a string constructor, the sampler will look for an empty constructor. Example below:

public class myTestCase {
  public myTestCase() {}
}

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

By default, JMeter will provide some default values for the success/failure code and message. Users should define a set of unique success and failure codes and use them uniformly across all tests.

Parameters ¶

Parameters ¶

The Flow Control Action sampler is a sampler that is intended for use in a conditional controller. Rather than generate a sample, the test element either pauses or stops the selected target.

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

The "Stop" action stops the thread or test after completing any samples that are in progress. The "Stop Now" action stops the test without waiting for samples to complete; it will interrupt any active samples. If some threads fail to stop within the 5 second 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 CLI mode, JMeter will exit if some threads fail to stop within the 5 second time limit.

The time to wait can be changed using the JMeter property jmeterengine.threadstop.wait. The time is given in milliseconds.

Parameters ¶

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.

Parameters ¶

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

Parameters ¶

This sampler lets you send a Request to a MongoDB.

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

This Element currently uses com.mongodb.DB#eval which takes a global write lock causing a performance impact on the database, see db.eval(). So it is better to avoid using this element for load testing and use JSR223+Groovy scripting using MongoDBHolder instead. MongoDB Script is more suitable for functional testing or test setup (setup/teardown threads)

Parameters ¶

This sampler allows you to run Cypher queries through the Bolt protocol.

Before using this you need to set up a Bolt Connection Configuration

Every request uses a connection acquired from the pool and returns it to the pool when the sampler completes. The connection pool size defaults to 100 and is configurable.

The measured response time corresponds to the "full" query execution, including both the time to execute the cypher query AND the time to consume the results sent back by the database.

Parameters ¶

Parameters ¶

Using the Simple Controller¶

Download this example (see Figure 6). In this example, we created a Test Plan that sends two Ant HTTP requests and two Log4J HTTP requests. We grouped the Ant and Log4J requests by placing them inside Simple Logic Controllers. Remember, the Simple Logic Controller has no effect on how JMeter processes the controller(s) you add to it. So, in this example, JMeter sends the requests in the following order: Ant Home Page, Ant News Page, Log4J Home Page, Log4J History Page.

Note, the File Reporter is configured to store the results in a file named "simple-test.dat" in the current directory.

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.

JMeter will expose the looping index as a variable named __jm__<Name of your element>__idx. So for example, if your Loop Controller is named LC, then you can access the looping index through ${__jm__LC__idx}. Index starts at 0

Parameters ¶

Looping Example¶

Download this example (see Figure 4). In this example, we created a Test Plan that sends a particular HTTP Request only once and sends another HTTP Request five times.

We configured the Thread Group for a single thread and a loop count value of one. Instead of letting the Thread Group control the looping, we used a Loop Controller. You can see that we added one HTTP Request to the Thread Group and another HTTP Request to a Loop Controller. We configured the Loop Controller with a loop count value of five.

JMeter will send the requests in the following order: Home Page, News Page, News Page, News Page, News Page, and News Page.

Note, the File Reporter is configured to store the results in a file named "loop-test.dat" in the current directory.

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.

Parameters ¶

Once Only Example¶

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

Each JMeter thread will send the requests in the following order: Home Page, Bug Page, Bug Page, Bug Page.

Note, the File Reporter is configured to store the results in a file named "loop-test.dat" in the current directory.

Parameters ¶

Simple Interleave Example¶

Download this example (see Figure 1). In this example, we configured the Thread Group to have two threads and a loop count of five, for a total of ten requests per thread. See the table below for the sequence JMeter sends the HTTP Requests.

Useful Interleave Example¶

Download another example (see Figure 2). In this example, we configured the Thread Group to have a single thread and a loop count of eight. Notice that the Test Plan has an outer Interleave Controller with two Interleave Controllers inside of it.

The outer Interleave Controller alternates between the two inner ones. Then, each inner Interleave Controller alternates between each of the HTTP Requests. Each JMeter thread will send the requests in the following order: Home Page, Interleaved, Bug Page, Interleaved, CVS Page, Interleaved, and FAQ Page, Interleaved.

Note, the File Reporter is configured to store the results in a file named "interleave-test2.dat" in the current directory.

If the two interleave controllers under the main interleave controller were instead simple controllers, then the order would be: Home Page, CVS Page, Interleaved, Bug Page, FAQ Page, Interleaved.

However, if "ignore sub-controller blocks" was checked on the main interleave controller, then the order would be: Home Page, Interleaved, Bug Page, Interleaved, CVS Page, Interleaved, and FAQ Page, Interleaved.

The Random Logic Controller acts similarly to the Interleave Controller, except that instead of going in order through its sub-controllers and samplers, it picks one at random at each pass.

Interactions between multiple controllers can yield complex behavior. This is particularly true of the Random Controller. Experiment before you assume what results any given interaction will give

Parameters ¶

Parameters ¶

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.

Like the Once Only Controller, this setting is reset when a parent Loop Controller restarts.

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

Parameters ¶

Parameters ¶

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 best option (default one) is to check Interpret Condition as Variable Expression?, then in the condition field you have 2 options:

• Option 1: Use a variable that contains true or false

  If you want to test if last sample was successful, you can use ${JMeterThread.last_sample_ok}

  

• Option 2: Use a function (${__jexl3()} is advised) to evaluate an expression that must return true or false

  

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.

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

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

If you uncheck Interpret Condition as Variable Expression?, If Controller will internally use javascript to evaluate the condition which has a performance penalty that can be very big and make your test less scalable.

Parameters ¶

Examples (JavaScript)¶

• ${COUNT} < 10
• "${VAR}" == "abcd"

If there is an error interpreting the code, the condition is assumed to be false, and a message is logged in jmeter.log.

Examples (Variable Expression)¶

• ${__groovy(vars.get("myVar") != "Invalid" )} (Groovy check myVar is not equal to Invalid)
• ${__groovy(vars.get("myInt").toInteger() <=4 )} (Groovy check myInt is less then or equal to 4)
• ${__groovy(vars.get("myMissing") != null )} (Groovy check if the myMissing variable is not set)
• ${__jexl3(${COUNT} < 10)}
• ${RESULT}
• ${JMeterThread.last_sample_ok} (check if the last sample succeeded)

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

JMeter will expose the looping index as a variable named __jm__<Name of your element>__idx. So for example, if your While Controller is named WC, then you can access the looping index through ${__jm__WC__idx}. Index starts at 0

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"

The condition can be any variable or function that eventually evaluates to the string "false". This allows the use of __jexl3, __groovy function, properties or variables as needed.

Note that the condition is evaluated twice, once before starting sampling children and once at end of children sampling, so putting non idempotent functions in Condition (like __counter) can introduce issues.

For example:

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

Parameters ¶

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.

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.

Parameters ¶

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.

JMeter will expose the looping index as a variable named __jm__<Name of your element>__idx. So for example, if your Loop Controller is named FEC, then you can access the looping index through ${__jm__FEC__idx}. Index starts at 0

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

The ForEach Controller does not run any samples if inputVar_1 is null. This would be the case if the Regular Expression returned no matches.

Parameters ¶

ForEach Example¶

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

We configured the Thread Group for a single thread and a loop count value of one. You can see that we added one HTTP Request to the Thread Group and another HTTP Request to the ForEach Controller.

After the first HTTP request, a regular expression extractor is added, which extracts all the html links out of the return page and puts them in the inputVar variable

In the ForEach loop, a HTTP sampler is added which requests all the links that were extracted from the first returned HTML page.

ForEach Example¶

Here is another example you can download. This has two Regular Expressions and ForEach Controllers. The first RE matches, but the second does not match, so no samples are run by the second ForEach Controller

The Thread Group has a single thread and a loop count of two.

Sample 1 uses the JavaTest Sampler to return the string "a b c d".

The Regex Extractor uses the expression (\w)\s which matches a letter followed by a space, and returns the letter (not the space). Any matches are prefixed with the string "inputVar".

The ForEach Controller extracts all variables with the prefix "inputVar_", and executes its sample, passing the value in the variable "returnVar". In this case it will set the variable to the values "a" "b" and "c" in turn.

The For 1 Sampler is another Java Sampler which uses the return variable "returnVar" as part of the sample Label and as the sampler Data.

Sample 2, Regex 2 and For 2 are almost identical, except that the Regex has been changed to "(\w)\sx", which clearly won't match. Thus the For 2 Sampler will not be run.

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

Parameters ¶

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.

This element does not support variables/functions in the filename field.
However, if the property includecontroller.prefix is defined, the contents are used to prefix the pathname.

When using Include Controller and including the same JMX file, ensure you name the Include Controller differently to avoid facing known issue Bug 50898.

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.

Parameters ¶

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

Note: when the check box "Include duration of timer and pre-post processors in generated sample" is checked, the time includes all processing within the controller scope, not just the samples.

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.

In parent mode, Assertions (etc.) can be added to the Transaction Controller. However by default they will be applied to both the individual samples and the overall transaction sample. To limit the scope of the Assertions, use a Simple Controller to contain the samples, and add the Assertions to the Simple Controller. Parent mode controllers do not currently properly support nested transaction controllers of either type.

Parameters ¶

Parameters ¶

Parameters ¶

Parameters

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.

Graph Results MUST NOT BE USED during load test as it consumes a lot of resources (memory and CPU). Use it only for either functional testing or during Test Plan debugging and Validation.

The Graph Results listener generates a simple graph that plots all sample