Yuri Bushnev is a Head of System Quality at AlphaSense, with more than 5 years of experience in Quality Assurance, DevOps and Development.

Become a JMeter and Continuous Testing Pro

Start Learning

Test Your Website Performance NOW! |

arrowPlease enter a URL with http(s)
Oct 26 2017

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.


jmeter scoping rules


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.


how does scoping work in jmeter?


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.


scoping, jmeter, timers


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


jmeter, assertions, scoping


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


scoping on jmeter an explanation


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:


scoping rules - a guide


There is a great article which explains all sharing modes for CSV Data Set Config in action


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:


explaining jmeter scoping rules


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.


Click here to subscribe to our newsletter.


To try out BlazeMeter, which enhances JMeter abilities, put your URL or JMX file in the box below, and your test will start in minutes. You can also request a demo.

arrowPlease enter a URL with http(s)

Interested in writing for our Blog?Send us a pitch!