How to Use the While Controller in JMeter

When it comes to building an advanced JMeter load test scenario that assumes complex logic, depending on certain conditions it is sometimes required to change the Samplers execution order. Usually JMeter runs all the Samplers upside down, but there could be some scenarios when the default behaviour is not suitable.

This post covers the While Controller—JMeter’s implementation of while loop. For those not familiar with the while loop concept, to put it simply, it’s just a repeated “if->then” statement.

If something is true, then repeat the last action

In JMeter, the controller basically runs children Samplers, unless some predetermined “Condition” is “true” where “Condition” could be:

1. blank - in this case, the While Controller will exit when the last sampler in the loop fails.
2. LAST - the same as blank, but with an additional check for the last Sampler before the loop result. If the preceding Sampler is not successful, the While Controller and its children won’t be executed at all.
3. JMeter Function or Variable - the While Controller’s children will be run until a variable or function evaluation result is “true”.
4. JMeter Property  - the same as Function or Variable, but assumes the Property instead.

Both the Function/Variable and Property approaches assume that the “Condition” will be set to “false” somewhere in or outside the loop. In the case of Property, it can be done from another Thread Group or even outside JMeter, for example via the Beanshell Server.

The first two cases with “blank” and “LAST” are pretty straight-forward. If you leave the “Condition” blank or set it to LAST, the loop will break if the last sampler under the While Controller is not be successful. The same applies to the Variables and Properties. The While Controller will loop its children until the Variable or Property specified in “Condition” will result in “true”.

Using Functions in the While Controller

As per the line in parentheses in the While Controller GUI, the condition should be “function or variable”, as seen below.

This means that, unlike the If Controller, which automatically interprets the “Condition” as JavaScript, the While Controller expects it to be either “true” or “false”. Therefore:

• "${myVar}" != "some value" - doesn’t work, as it is neither a function nor a single variable.
• ${__javaScript("${myVar}" != "some value",)} - works OK as the expression resolves it to either be “true” or “false”.

Additionally, remember that in the absolute majority of cases, JMeter Variables are stored as Strings, so if you’re using __javaScript() or a similar function in order to compare the variable value to something, make sure that both counterparties are of the same type. For example, in JavaScript just surround both the variable and the expected value with quotation marks and they will be interpreted as strings.

Now that we’ve explained how the While Controller is used, let’s take a look at some use cases.

Potential Use Cases

Looping Until a Response Contains a Specified Line

If you’re testing a system built on, let’s say, the eventual consistency principle or a multi-component system where the response is not immediate, you might have to wait until something becomes available so you can proceed. In these scenarios, the While Controller is the most obvious choice to turn to to. If you need to decide whether to continue or not based on the presence of some text in the response—it can be done as follows:

1. Add the While Controller to your Test Plan
2. Put the HTTP Request sampler (or any other sampler if you’re using a different protocol) under the While Controller.
3. Save the partial or the whole response into a JMeter Variable. It can be done using the Regular Expression Extractor.
4. Use the following Condition in the While Controller:

${__javaScript("${response}".indexOf("string") == -1,)}

Where:

• ${response} - the JMeter Variable which holds partial or whole response
• string - the character sequence you’re looking for

Once the string will be found in the ${response} the loop will exit and the test will continue (or end).

If there won’t be any occurrences of the string in the ${response} the request will be repeated forever.

The above approach assumes the Regular Expression Extractor and __javaScript() function combination, and in the String.indexOf() the JavaScript method is used to determine whether the search criteria are present in the response or not.

Looping Until the Response Contains a Specified Line, But Not More Than X Times

This use case is similar to the previous one, with some extra “protection," in order to avoid an endless loop if the text you’re looking for never appears.

Let’s retry for five times and if the string will not be found in the response, then exit the loop. To implement, you just need to:

1. Add a Counter test element under the While Controller.
2. Configure the Counter to:
   • Start from 1
   • Increment by 1
   • Have a counter reference name
3. Change the While Controller Condition to consider the counter value as well, like:

${__javaScript(("${response}".indexOf("string") == -1 && ${counter} < 5),)}

As you can see, the while loop stopped after 5 attempts instead of running forever. 

Reading All Values From the CSV and Continue

This scenario assumes using the CSV Data Set Config for parametrization. In most cases, it is utilized for recycling or stopping the JMeter Thread when the end of the file is reached. Now we will see how to read all the values from the CSV file and continue the test afterwards.

Assuming that CSV file contains only five lines:

line 1
line 2
line 3
line 4
line 5

And the following CSV Data Set Configuration:

Let’s see what happens with the blank Condition in the While Controller.

As you can see, the test continues forever and returns the <EOF> value for each subsequent call. EOF stands for End Of File. If you don’t like it, you can change it for whatever you want to see instead via the csvdataset.eofstring property.

So given we have this “<EOF>” thing, now we can use it in the While Controller Condition as:

    ${__javaScript("${myVar}" != "<EOF>",)}

Let’s see what happens now:

Almost done. I assume you don’t want this <EOF> bit at all? It is there as the CSV data is being read in the loop before the While Controller condition is evaluated, so that the While Controller is always one step behind. You can get rid of it using the If Controller by the following steps:

1. Put the If Controller under the CSV Data Set Config.
2. Put all the samplers which use the ${myVar} variable under the If Controller.
3. Use "${myVar}" != "<EOF>" as the If Controller condition.

Let’s see how it looks now:

Seems to be exactly what we’re looking for.

The funny thing is that assuming you use the If Controller, you can even leave the While Controller’s Condition blank.

This is it on the While Controller, if anything remains unclear or your scenario is not covered, feel free to use comments form below.

Want to Learn More?

For experienced JMeter users, you'll want to view the on-demand webcast, How to Create Advanced Load Testing Scenarios with JMeter.

If you are new to JMeter, and you’d like to learn more, please sign up for our free online JMeter training course.