JMeter Scoping Rules - The Ultimate Guide
Apache JMeter™ is a very powerful performance testing framework, which makes performance testing easy for everyone. Even relatively inexperienced engineers are able to create performance tests from scratch by using JMeter’s GUI mode, or even just record performance scripts by using a built-in recorder. When you open the JMeter GUI desktop client, you might find it pretty simple at first glance. Yes, it is. But do not be so naive as to think that observable simplicity doesn’t have any hidden secrets, because of course, it has.
In this article, we will present an explanation of JMeter's scoping rules. When speaking of the scope of an element, we mean the section of the JMeter tree (and the elements in it), which this element has access to and it can be accessed from itself. In other words, scoping tells us which elements have access to a specific element, and which do not.
When you open JMeter for the first time and implement a few tests, scoping seems to be very straightforward. All elements are located under one organized tree. Everything seems to be clear until the moment you realize that scoping rules and even execution order are based not only on elements’ hierarchy, but also on elements themselves. That’s why in the next few paragraphs we will try to explain the basic principles of JMeter scoping rules with examples based on different JMeter elements.
Scoping Basic Principles
While some elements are only hierarchical (like assertions or timers), others are both hierarchical and ordered (like samplers or controllers). But the main principle is based on tree branch levels. Usually, the scope of the element is based on which tree branch it is located on. Let’s make a basic elements tree to show this in an action.
Based on these elements and basic scoping principles, we can decouple the whole tree into several branches. Yes… it doesn’t look like a real tree at all. But to make it simpler, just think that if an element has a parent, it is in the scope of the branch created by the element’s parent.
For example, you can see that all elements under the ‘Thread Group’ form a separate scope and if we add a JMeter element like a timer inside the Thread Group (on the first level) it will be applied to the all samplers inside the blue rectangle. But if we put a timer inside the red rectangle, which has another (much smaller) scope, then this timer will be available only for the samplers inside. In this case, only for Sampler№7.
Assertions Scoping Rules
Assertions are always applied to all the elements from the same scope (or - “tree branch”). It is important to know that this rule is valid regardless of the location of the assertion element. This means that it doesn’t matter where an assertion element is located. It will always be applied for all the elements within its scope.
Now let’s add a few assertions to the same tree and highlight the scope of the assertion in each particular case. In the pictures below we are showing the group (with an orange rectangle) of all samplers that will be affected by the highlighted (using red line) assertion. We need to keep in mind that assertions are applicable for parent samplers as well, and that’s why we need to include them in the same rectangle as well.
You get the main idea. You can also notice that ‘Response Assertion “B”’ and ‘Response Assertion “D”’ have an absolutely different location but at the same time, they are applied to exactly the same JMeter sampler (all of them in this case).
But what if we have several thread groups? The answer is simple - the rules are the same. Each thread group forms a different tree branch. Therefore, the scope will be different for each one and the assertions from different threads groups would not impact each other. In the current example, ‘Response Assertion “E”’ is located outside the ‘Thread Group’. This means that it will be applied for all thread groups under the current ‘Test Plan’.
Timers Scoping Rules
Timers have the same scoping rule as assertions. But it is still worth mentioning, since this rule is one of the main ones that causes issues for test engineers at the beginning of their JMeter knowledge road.
At first glance, it might not be very obvious that a top-level element like an assertion or timer should be applied to all samplers on lower levels. But if you accidentally specify an assertion in a way that makes it applicable for a sampler that you do not want to verify, you will probably notice it right away. This is because assertions are used mostly to verify a specific response, and in most cases, the assertion will fail if you use the same one for another endpoint. This will help you the find a root cause. But this is not how it happens with timers.
I have seen many situations when a test engineer specifies a random time out on a high-level and is not aware that it is applicable for all lower samplers. When you use different listeners to monitor your test, they do not show you the information about which timeout was triggered and when. That’s why, if you are not running your tests setting with a stopwatch in your hand, you can easily miss the moment when you introduced a timer that has a scope that includes a sampler which you weren’t supposed to include.
As for the rest, scoping rules are the same for assertions and timeouts, except for one more difference: in execution order. Assertions are always executed after each sampler, while timers are executed before.
Timer “F” is applicable for the entire thread group as it stays on the same level with it, while Timer “A” is located inside the thread group and is applicable for all the elements inside this thread group => we can say that Sampler №1 and Sampler №2 will be impacted by Timer “F” and Timer “A”.
Sampler №3 and Sampler №4 (in addition to Timer “F” and Timer “A”, which are still valid from the higher level scope), also have Timer “B” and Timer “D” on the same level which are applicable for these samplers too => Sampler №3 and Sampler №4 will be impacted by Timer “F”, Timer “A”, Timer “B” and Timer “D”.
As for Sampler №7, it has even one more timer on its level => Sampler №7 is impacted by all these timers together.
Scoping Rule Exceptions
As you might notice, scoping rules are pretty straightforward, as soon as you get the main idea. But are there any exceptions to that rule? Of course there are!
The first scoping rule that might be considered as an exception is the CSV Data Set Config scoping rule, which enables using CSV files as an external data source in JMeter scripts. The scoping rule of this element is configurable and can be specified by the configuration controller itself:
Another exception is when you are using the “HTTP Header”, “HTTP Cookie” and “HTTP Authorization Manager” configuration elements. While other configuration elements are merged and applied altogether based on the same scoping rules we discussed above, these elements are not merged into one configuration file, but rather each new instance of one of these configuration elements fully overrides the previous instance without any config values merge:
In this example you can see that for “Sampler №1” there will be only one valid “HTTP Header”, “HTTP Cookie” and “HTTP Authorization Manager” elements, accordingly. All previous config managers will not be valid for this sampler.
That’s it! That it is everything you need to know to be comfortable for understanding scoping rules into JMeter. These rules are extremely simple as soon as you get the main idea. But keep in mind all mentioned exceptions. This might save your time in the future!
Now that you’ve conquered scoping, you can learn more JMeter for free from our JMeter academy.