The If Controller is a gate. Everything behind it runs only when its condition says yes.

JMeter is a free, open-source tool from the Apache Software Foundation. It pretends to be many users at the same time and measures how a system behaves. A JMeter test is described by a test plan, which is a tree of small elements. Some elements send requests, and these are called samplers. Some elements decide the order and the conditions under which samplers run, and these are called logic controllers. The If Controller is one of the logic controllers.

The simple definition

An If Controller holds a condition, which is a short expression that is either true or false. It also holds a group of child elements, such as samplers and other controllers. When a virtual user reaches the If Controller, JMeter checks the condition. If the condition is true, the children run in their normal order. If it is false, the children are skipped, and the virtual user moves on to whatever comes next in the tree.

What it does not do

Beginners sometimes expect more from the If Controller than it gives. It does not have an “else” branch, so you cannot tell it “do this when true and do that when false”. It does not repeat anything, so it is not a loop. It also does not send a request or create a measurement of its own. It is purely a gatekeeper. If you need an else, a loop, or a random choice, other controllers or simple patterns are used, and we cover them in later chapters.

A test that never decides is a test that never matches real behaviour.

When we say a load test should be realistic, we usually think about the number of users and the amount of think time. But realism also means variety of paths. Real users do not all do the same thing. Some browse and leave. Some search and buy. Some are already signed in, and some are new. Some meet an error and retry. A test that sends every virtual user down the same single path will produce numbers that look tidy but may not match what the server really faces.

Four common reasons to make a test decide

What goes wrong without decisions

Imagine a search step that sometimes returns no results. If the next step always tries to open “the first result”, then every empty search triggers an error in the next step. Your error rate climbs, but the cause is not the server. It is your script. In the same way, a test that logs in for every round creates far more login traffic than real life, and then reports that the login system is slow when it is only being abused by an unrealistic script.

Position decides what is gated and how often the gate is checked.

A test plan is a tree. At the top sits the Test Plan, below it one or more thread groups, which are the crowds of virtual users, and below those the controllers and samplers. You add an If Controller by right-clicking a thread group or another controller and choosing to add a logic controller. Then you drag samplers into it, or add them as its children.

flowchart TD
    TP["Test Plan"] --> TG["Thread Group: virtual users"]
    TG --> S1["Sampler: Open Home Page"]
    TG --> IF["If Controller: user is not signed in"]
    IF --> S2["Sampler: Login Page"]
    IF --> S3["Sampler: Submit Credentials"]
    TG --> S4["Sampler: View Basket"]
    TG --> IF2["If Controller: basket is not empty"]
    IF2 --> S5["Sampler: Checkout"]

How often is the gate checked?

Every time a virtual user’s thread reaches the If Controller while walking down the tree, the condition is evaluated again. If the controller sits directly under a thread group that loops one hundred times, the condition is checked one hundred times for each thread, once per round. If it sits inside a Loop Controller, it is checked on each pass of that loop. This is important because conditions often depend on values that change over time, such as a counter, or a token that was extracted a moment ago.

Who is inside the gate?

Everything placed below an If Controller is governed by it. This includes not only samplers, but also timers, assertions, extractors, and other controllers that are its children. If the condition is false, none of these run. A timer placed inside, for example, adds no think time when the gate is closed, which is usually exactly what you want, but can surprise you if you expected a pause to happen anyway.

The panel is small. Three items on it decide almost everything.

When you select an If Controller in the tree, the right-hand panel shows only a few fields. Understanding each one removes most of the mystery.

The condition field

The condition field is a single line of text. JMeter replaces any variable references in it with their current values before it decides what to do. So if the field contains a reference to a variable called count, JMeter looks up the value of that variable at the moment the thread reaches the controller. Because the lookup happens each time, the same controller can give different answers in different rounds and for different threads.

Two checkboxes, two big questions

The first checkbox answers the question: how should this text be understood? The second answers the question: how often should it be checked? Each of these gets its own chapter, because getting them wrong is the most common cause of If Controllers that “do nothing” or “run when they should not”. For now, keep a simple rule: use the variable expression mode, and leave the all-children option off unless you have a clear reason.

Follow a single thread as it reaches the gate, from first glance to final decision.

Understanding what JMeter does behind the scenes helps you predict how a condition will behave and why it sometimes does not. The process is short and the same every time.

flowchart TD
    A["Thread reaches the If Controller"] --> B["Replace variables and functions in the condition text"]
    B --> C{"Variable expression mode?"}
    C -- "Yes" --> D["Compare the resulting text with the word true"]
    C -- "No" --> E["Run the text as a script and read its result"]
    D --> F{"Is it true?"}
    E --> F
    F -- "Yes" --> G["Run the children in order"]
    F -- "No" --> H["Skip the children"]
    G --> I["Continue with the next element"]
    H --> I

Each thread decides on its own

The condition is evaluated separately for each virtual user. Variables in JMeter belong to a single thread, so one user’s token does not affect another user’s decision. This is why you can have a thousand threads, each with a different answer at the same moment: some are skipping the login while others are running it.

The importance of timing

Because the condition is evaluated at the moment the thread reaches the controller, the order of elements matters. An extractor that stores a value must come before the If Controller that reads it, otherwise the condition sees the old value, or no value at all. In the same way, a counter used in the condition must already have been updated. When a condition seems to use “yesterday’s information”, the cause is almost always an element placed in the wrong order.

The single most misunderstood checkbox in the controller. Learn it once and save hours.

The checkbox called “Interpret Condition as Variable Expression” decides how the condition text is understood. It has two settings, and each calls for a different way of writing the same idea.

What “must produce true” means

In variable expression mode, JMeter does all its variable and function replacement, then looks at the final text. If that text is exactly the word true, the gate opens. Anything else, including the word false, an empty string, or an error message, keeps the gate closed. This has a useful consequence: if you have a variable that already holds the word true or false, you can place it alone in the condition field and it will work.

For real comparisons, you use a function that performs the comparison and returns true or false. Two commonly used functions are the JEXL function, which is good for simple comparisons of numbers and text, and the Groovy function, which is more powerful and can read JMeter variables directly. For example, a condition that opens the gate when a counter is above five can be written as ${__jexl3(${count} > 5)}. A condition that opens it when a token variable exists can be written as ${__groovy(vars.get("token") != null)}.

Script mode and why it is fading

In the older script mode, the condition is run by a built-in script engine and written like a statement, for example comparing a quoted variable with a quoted word. This was the original default. It has two problems. First, starting and using a script engine for every check is much slower than variable expression mode, which hurts when thousands of threads check the gate thousands of times. Second, the script engine available inside Java has changed across Java versions, so a plan that worked on one machine may fail on another with a different Java.

The second checkbox decides whether the gate is checked once, or before every single child.

By default, the If Controller evaluates its condition once, when the thread first reaches it. If the answer is true, all the children run, one after another, without the condition being checked again. This is usually what you want, and it is also the fastest approach.

The checkbox “Evaluate for all children” changes this. When it is ticked, the condition is checked again before each child element. If the condition becomes false in the middle, the remaining children are skipped, even though the first ones ran.

When checking for every child helps

The ticked mode is useful when a step inside the group may change the answer. Imagine a group of five steps that depend on a session that could expire. The condition is “the session is valid”. If the second step fails and marks the session as invalid, you may want steps three to five to be skipped immediately, since they would only produce errors. With the default mode, all five run regardless. With the ticked mode, the gate closes right after the failure.

Do not use it by habit

Ticking the box “just in case” is a poor habit. It adds cost to every child, and it changes the meaning of the group. If your condition is simple and stable, leave the box off. If you notice that you need it, consider whether splitting the group into smaller If Controllers, each with its own condition, would be clearer.

A good condition is short, clear, and written so that it can only mean one thing.

Most conditions are built from the same small set of ideas: compare a value with another value, check whether something exists, or combine several checks. Learning a few patterns covers the vast majority of needs.

Comparing numbers

Numbers are compared with the usual signs: greater than, less than, equal, and not equal. A condition such as “the match count is greater than zero” tells you that an extractor found at least one result. Be careful that variables hold text in JMeter. The JEXL function usually converts text that looks like a number into a number for you, but if the variable holds something else, such as an empty string or a literal variable name when the variable does not exist, the comparison may fail or give a surprising answer.

Comparing text

For text, put quote marks around values. The condition “the status equals ok” is written with the word in quotes and compared with a double equals sign. Text comparison is case-sensitive, so “OK” and “ok” are different. If the server may return either, convert both to the same case first, or compare with a function that ignores case.

Checking that something exists

Often the question is not “what is the value” but “is there a value at all”. An extractor that finds nothing leaves its variable unset, or filled with the default you gave it. A reliable habit is to give every extractor a clear default such as NOT_FOUND, and then write the condition as “the variable does not equal NOT_FOUND”. That is far easier to understand than testing for an unset variable.

Combining conditions

You can combine checks using “and” and “or” signs. A condition that must satisfy two things at once uses the double ampersand, and a condition that needs either of two uses the double vertical bar. Parentheses make the order clear. When a combined condition becomes long, consider calculating the answer earlier, in a small helper, and storing it in a single variable named for its meaning, such as needs_login. The condition then reads as plainly as a sentence.

In variable expression mode, a function does the real work. Two functions cover almost every need.

In variable expression mode, the condition field contains a function call, and the function returns the word true or false. JMeter ships with several functions, but two of them are used far more than the rest. Understanding the difference between them helps you pick the right one each time.

The JEXL function

JEXL is a small expression language. The JEXL function evaluates an expression made of values, comparison signs, and simple logic. It is ideal for questions such as “is this number bigger than that one”, “does this text equal that text”, and “are both of these true”. Its great advantage is simplicity: an expression is short, readable, and cannot do very much, which makes it safe and fast. Use the version called jexl3 in new plans, since the older version is kept only for compatibility.

The Groovy function

Groovy is a full programming language that runs on Java. The Groovy function evaluates a short Groovy statement. It has direct access to JMeter’s variables and properties, through names that JMeter provides, so it can read a variable by name without pasting its text into the expression. This makes it the best choice for checks that JEXL handles awkwardly, such as testing whether a variable exists at all, working with lists, or calling a small helper method. Groovy functions are generally compiled and cached after their first use, so repeated evaluation stays fast.

A simple guideline

Start with JEXL for comparisons and combinations. Move to Groovy only when you need to ask about existence, lists, or something JEXL cannot express cleanly. Avoid the older functions that evaluate other script languages inside the condition. They are slower and several of them are kept only for old plans.

Most “impossible” condition bugs are really small mismatches between what a value looks like and what it is.

JMeter variables are stored as text. When you write a number in a condition, the function may treat it as a number, as text, or as something else, depending on how you wrote it. A handful of traps appear again and again, and knowing them in advance saves hours.

Trap one: numbers that are really text

A variable that holds the characters five and zero looks like the number fifty. If you compare it with another number, a good function will convert it for you. But if the variable also contains a space, a comma, or a currency sign, the conversion fails, and the comparison can silently give the wrong answer. Clean values at the source, by choosing an extractor pattern that captures only the digits.

Trap two: the empty value

An empty variable is different from a missing variable, and both are different from the word NOT_FOUND. A condition written to catch one of these will not catch the others. Decide which of these states your plan can produce, and make the condition cover each of them, or arrange for the plan to produce only one of them by always giving extractors a default.

Trap three: spaces and line breaks

Values extracted from web pages often carry invisible spaces or line breaks at the ends. A value that looks like ok may actually be ok followed by a space, and a comparison with the word ok will fail. Trim the value in the extractor pattern, or compare with a function that ignores surrounding spaces.

Trap four: true and false are just words

In variable expression mode, the gate opens only for the text true. The text True, the number one, the word yes, and the word on do not open it. If a data file or property supplies a switch, make the value exactly true or false, and decide whether the comparison should ignore case.

Trap five: quotes and special characters

A value that contains a quote mark, a bracket, or a comma can break the function around it. This happens when the variable’s text is pasted into the expression. To reduce the risk, read variables through the function’s own lookup rather than pasting them in, and avoid conditions that include free-form text from users or servers.

Common questions a test plan needs to ask, with a condition for each, written for variable expression mode.

Most real conditions come from a short list of recurring situations. The table below gives a recipe for each. Treat the expressions as starting points and adjust names to match your own variables.

Reading a condition aloud

A good test of a condition is to read it aloud as a sentence. “If the last sample was ok.” “If the number of results is greater than zero.” “If the role equals admin.” If a condition cannot be said in plain language without stumbling, it is probably too clever, and a future reader will struggle with it. Prefer the clearer form, even if it takes one more line of setup.

A note on the first-round idea

Running something only on the first round of a thread is a popular need. The Once Only Controller is built exactly for this and is clearer than writing a condition for it. Use an If Controller for the first-round idea only when you need to combine it with other conditions.

The If Controller and extractors are close partners. One finds the facts and the other acts on them.

An extractor is a helper that reads a response and stores a value from it into a variable. Examples include the JSON Extractor, the Regular Expression Extractor, and the CSS Selector Extractor. The If Controller is the natural next step: once a value is stored, the controller decides what to do with it.

The matchNr trick

Most extractors also store the number of matches they found, in a variable named after your variable with a suffix. If your variable is called results, the count is stored in results_matchNr. This count is perfect for an If Controller. A condition that says “the match count is greater than zero” guards any step that needs at least one result. If the search found nothing, the step is skipped instead of failing with an error.

Defaults make decisions visible

An extractor that finds nothing normally leaves its variable unchanged or unset, depending on its settings. To make the failure explicit, give the extractor a default value, for example NOT_FOUND. Then the condition can ask directly whether the value is something other than NOT_FOUND. A default also keeps the rest of the plan from sending literal variable names to the server when something goes missing.

Choosing an extractor mode that supports your decision

Some extractors can pick the first match, a random match, or all matches. If you plan to loop over all matches with a ForEach Controller, the count is the thing to check first. If you need only one match, ask for the first. An If Controller in front of either one keeps empty results from causing trouble.

One variable lets a test notice failure and react to it.

After each sampler finishes, JMeter stores whether it succeeded in a special variable named JMeterThread.last_sample_ok. It holds the word true when the previous sample passed and false when it failed, including failures caused by assertions. This is a simple way to make an If Controller respond to the immediate past.

What you can do with it

A pattern: guard what follows a risky step

Place an If Controller directly after a risky sampler, with the condition set to the last-sample variable, and put the dependent steps inside it. If the risky step succeeded, the dependent steps run. If not, they are skipped, and the failure is counted once, in the risky sampler, not many times down the chain.

flowchart LR
    L["Sampler: Login"] --> G{"If Controller: last sample ok"}
    G -- "true" --> A["Sampler: Browse Account"]
    A --> B["Sampler: Update Profile"]
    G -- "false" --> N["Skip dependent steps"]
    B --> NX["Next part of the journey"]
    N --> NX

The thread group has an error action too

Do not forget that the thread group has its own setting for what to do after a sampler error: continue, start the next loop, stop the thread, or stop the test. Often that setting is the cleaner way to handle a failed login, because it needs no condition at all. Use an If Controller when you need finer control, such as skipping only part of a journey while still running the rest.

Let the data file decide who does what, so one plan serves many kinds of users.

A CSV Data Set Config element reads a plain text file of rows and hands each virtual user one row. The columns become variables. An If Controller can then branch on the value of any column, which makes the data file a very flexible control panel.

One plan, several kinds of user

Suppose your data file has a column called role, with values such as customer, admin, and guest. A single test plan can contain three If Controllers, one for each role, each holding that role’s journey. A thread that receives a customer row follows the customer path. A thread with an admin row follows the admin path. You can adjust the mix of users in a test simply by editing the data file, with no change to the plan itself.

Benefits and limits

• Easy mix control. Changing the share of each role means changing the number of matching rows.
• Repeatable. The same file gives the same mix on every run, which makes comparisons fair.
• Visible. People can read the data file and see the planned mix without opening the plan.
• Order matters. If rows are handed out in file order, a file sorted by role will give each role in a block rather than evenly mixed. Shuffle the rows if you want a smooth mixture.
• Sharing mode matters. Whether the file is shared across all threads or per thread changes which thread gets which row. Check the sharing setting to be sure the mix is what you expect.

Passing the data into the condition

The condition simply reads the column variable. For the role example, the condition says that the role equals admin. Because the variable comes from the data file, there is no extra setup. Keep the values in the data file simple and consistent. A role typed once as admin and once as Admin will be treated as two different roles by a case-sensitive comparison.

A property turns a branch into a switch you can flip without editing the plan.

JMeter properties are named settings that you supply when the test starts, usually on the command line. They are shared by the whole test, unlike variables, which belong to one thread. Properties make excellent feature switches for an If Controller, because a person starting the test can turn a branch on or off without opening the plan.

What a switch can control

A safe way to write the switch

The property function reads a property and lets you give a default. A condition that tests whether the property called withGift equals true, with a default of false, is written in the same style as the cookbook. Because the default is false, a person who forgets to set the property gets the safer behaviour. Choose defaults that make the plan run in its simplest and least risky form.

Document your switches

A plan with five switches has thirty-two possible combinations. Without documentation, nobody knows which combinations were ever tried. Write the list of switches, their defaults, and their meaning at the top of the plan in a comment, and record the values used with each set of results.

Put the pieces together in one small plan, from first request to final report.

Let us build a plan for an imaginary online shop, step by step, using only ideas from this guide. The goal is a journey in which users sign in only when needed, search for a product, open one if results exist, and optionally add gift wrap.

flowchart TD
    A["Sampler: Open Home Page"] --> B{"If Controller A: no session token"}
    B -- "open" --> C["Sampler: Login"]
    B -- "closed" --> D["Sampler: Search"]
    C --> D
    D --> E{"If Controller B: results found"}
    E -- "open" --> F["Sampler: Open Product"]
    F --> G{"If Controller C: gift switch on"}
    G -- "open" --> H["Sampler: Add Gift Wrap"]
    G -- "closed" --> I["Sampler: Add to Basket"]
    H --> I

Checks that make it trustworthy

• Each sampler has a response assertion that checks real content, not only the status code.
• Think time is added by timers placed inside each gate, so skipped steps add no pause.
• Names describe the rule, such as “If no session token” and “If results found”.
• After the run, the counts for login, open product, and gift wrap are compared with the planned shares.

JMeter has no else. These patterns give you one anyway.

Many programming languages let you write “if this, do that, otherwise do something else”. The JMeter If Controller has no else branch. Experienced testers use a few reliable patterns to get the same effect.

flowchart TD
    S["Compute a flag variable: is_member"] --> I1{"If Controller A: flag is true"}
    S --> I2{"If Controller B: flag is not true"}
    I1 -- "true" --> M["Sampler: Member Journey"]
    I2 -- "true" --> G["Sampler: Guest Journey"]

Pattern one: twin controllers with opposite conditions

Create two If Controllers one after the other. The first has a condition and the second has the exact opposite. Exactly one of them opens. This is the closest equivalent to an else and is easy for any reader to understand.

Pattern two: compute the answer first

The twin pattern has a risk. If the steps inside the first controller change something that the second condition reads, the second condition may be evaluated against changed information, and both gates could open, or neither. To avoid this, compute the answer once into a flag variable before either controller, and have both controllers read the flag. The flag does not change while the branches run, so the answers stay consistent.

Pattern three: a Switch Controller

When there are more than two possible paths, such as customer, admin, and guest, a Switch Controller is often a better fit. It reads a value, such as a number or a name, and runs only the child that matches. This gives you “one of many” in a single element rather than several If Controllers, each with an opposite condition that grows more complicated as you add choices.

An If Controller can sit inside another. Use this power sparingly.

Because an If Controller can have other controllers as children, you can place one inside another. The inner controller is only reached when the outer condition is true, and then its own condition is checked. The effect is an “and” between the two conditions.

Nesting versus combining

Two conditions can be joined in a single controller with an “and” sign or placed in two nested controllers. Both give the same result in the simple case. The difference is readability and reuse. Nesting is clearer when the outer condition guards a large group and the inner condition guards only a small part of it. A single combined condition is clearer when both rules apply to the same small group of steps.

Keep the depth small

As a rule of thumb, two levels of nesting are acceptable and three are a warning sign. If you find a third level, step back and ask whether the logic belongs in a flag variable, a Switch Controller, or a separate thread group for that kind of user.

Several controllers make decisions. Picking the right one keeps a plan simple.

JMeter offers a family of logic controllers. Some are close relatives of the If Controller, and mixing them up leads to plans that work but are awkward. A quick comparison clarifies when each is the best fit.

If versus While

The If Controller checks once and runs its children once. The While Controller checks, runs its children, checks again, and repeats until the condition is false. A common mistake is using an If Controller to wait for something. An If Controller that finds the job not ready will simply skip and move on, rather than waiting. For waiting and polling, use a While Controller with a timer to pause between checks, and protect it with a limit so it cannot spin forever.

If versus Throughput

If you want “twenty percent of users do this”, do not invent a random condition. The Throughput Controller is built for ratios and keeps the percentage correct in a way that random conditions often do not. The If Controller is best at answering questions about state, such as whether a value exists, not questions about proportion.

Helpers placed inside an If Controller follow the same rules as the samplers they belong to.

A JMeter test plan has several kinds of helper elements. Timers add pauses to imitate thinking. Assertions check whether responses are acceptable. Pre-processors and post-processors prepare requests and read responses. Config elements supply settings. Each of them has a scope, which means the set of samplers it affects, decided by its position in the tree.

What happens when the gate is closed

Elements inside an If Controller only act when the controller’s children run. If the condition is false, the children are skipped, and the helpers inside them are skipped too. This is a very useful feature, because it lets you attach exactly the right helper to exactly the right branch. It also has consequences you should plan for.

A hidden effect on think time

Consider a journey in which each step is followed by a short pause. If the pause lives inside the gate and the gate closes, the thread skips the step and its pause. The overall journey becomes shorter than one with the gate open, and the thread returns to the top of the loop sooner. When many threads skip a step, the whole crowd cycles faster and sends more requests per second to the other steps. This is not wrong, but it can change the load on the rest of the system, so keep it in mind when you compare runs with different branch mixes.

Stale variables

If an extractor lives inside the gate and the gate closes, the variable it would have set keeps whatever value it held before, which may be from a previous round. A later step that reads the variable may use old information without any warning. A careful plan resets such variables at the start of each round, or gives them a default before the gate, so that “not set this time” is clearly visible.

Business timings and branches need to be arranged with care so that numbers stay meaningful.

A Transaction Controller groups several samplers and reports their combined time as one business step, such as “Checkout”. It is a favourite of reports, because business readers understand it far better than a list of technical requests. Combining it with an If Controller needs a little thought, because the two controllers answer different questions.

Where to place each one

Why Option A is usually better

Imagine a step called “Apply voucher” that only twenty percent of users perform. With the gate outside, the report shows a count equal to the number of vouchers actually applied and an honest response time for them. With the transaction outside, the report may show a count for every user, with eighty percent of them showing almost no time. The average looks wonderful, and it means nothing.

flowchart TD
    G["Thread Group"] --> I["If Controller: user has a voucher"]
    I --> T["Transaction Controller: Apply Voucher"]
    T --> S1["Sampler: Enter Code"]
    T --> S2["Sampler: Confirm Discount"]

Naming for clarity

Because the If Controller does not produce a row in the report, the names of the transaction and its samplers are the only trace of the branch. Choose names that contain the reason, for example “Apply Voucher” rather than “Step 7”. A reader looking at the final report then understands which branch each number belongs to.

The If Controller answers questions about state. Questions about proportion belong to other tools.

A very common request is “make twenty percent of users do the purchase step”. Many beginners try to build this with an If Controller and a random number, for example a condition that is true when a random number between one and one hundred is less than twenty-one. It works roughly, but it is not the best tool for the job.

Why random conditions are a weak fit

A random condition gives about twenty percent over a long run, but not exactly. In a short test, the real share can drift well away from the target by pure chance. Also, each thread draws its own random number, so the split is not controlled across the whole test. And the intent is hidden inside a clever expression that a reader must decode, instead of being stated plainly.

The better tools

When many machines run the same plan, conditions that use thread numbers or machine details behave in surprising ways.

In distributed testing, one machine called the controller sends the plan to several remote machines called engines. Each engine runs the whole plan on its own. Variables and thread numbers are local to each engine, so conditions that depend on them may not mean what you expect.

“Only thread one” runs once per engine

A condition that says the thread number equals one is true for the first thread of the group on each engine. With five engines, that is five threads, not one. If your goal is “exactly one setup action in the whole test”, this pattern is not enough. Use a setUp thread group, which runs once per engine, together with a design that tolerates repeats, or make the action safe to run more than once.

Properties must reach the engines

A property that you set on the controller may not be known to the engines unless it is sent to them in the way JMeter provides for this. If the engines do not receive a property, they use the default written in your condition. A branch you meant to switch on may then stay off on every engine, even though it appears to work when you test on a single machine.

Data files and branches

If branches depend on columns in a data file, each engine needs its own copy of the file. If the files differ between engines, the mix of branches will differ too. Keep files identical, or deliberately split them, and write down which choice you made.

A branch changes how many times a request runs, so your report must be read with the branch mix in mind.

In a plain test, every sampler runs the same number of times as the others. With If Controllers, counts differ. A sampler behind a gate runs only as often as the gate opens. This changes how you read throughput, error rates, and averages.

Counts first

Look at the number of samples for each label before looking at response times. If a sampler behind a gate shows a count far from what you planned, either the gate opened too rarely or too often. For example, if you expected twenty percent of users to apply a voucher and the report shows two percent, the condition or the data is off. Fix the plan before drawing any conclusion from the timings.

Error rate depends on the denominator

The error rate of a sampler is the number of its failures divided by the number of times it ran. When a gate closes more often during a struggling period, perhaps because a login failed and later steps were skipped, the denominator shrinks, and the reported error rate may look better than the real experience of users. To avoid this, compare the number of attempted journeys with the number of completed journeys, as well as the per-sampler error rate.

Small branches and small samples

A branch that runs for only a few users gives few samples. Percentiles from a handful of values are shaky, so treat them as hints, not facts. If a rare branch is important, run the test long enough, or increase the share of that branch in a dedicated test, so that you collect enough measurements.

If a gate leaves no trace in the results, you must create one on purpose.

Because the If Controller produces no sample of its own, a silently closed gate leaves no mark. You can finish a test, see healthy numbers, and never learn that an important step was skipped for most users. Good monitoring makes decisions visible.

flowchart LR
    G["If Controller decisions"] --> C["Counter variables or labelled samplers"]
    C --> R["Results file and Backend Listener"]
    R --> D["Dashboard: branch counts over time"]
    L["JMeter log"] --> D
    SYS["System under test metrics"] --> D
    D --> H["Review: did the mix match the plan?"]

Ways to make branches visible

• Use clear labels. Each sampler inside a gate should have a name that includes its branch, so that counts per label reveal how often the branch ran.
• Count skips on purpose. Place a lightweight counter or a log message in a second, opposite gate to count how often the gate stayed closed.
• Compare against the plan. After a run, compare the counts of each branch with the expected ratio, and write the comparison into the report.
• Watch throughput per label over time. A branch whose throughput suddenly drops during the test often points to a condition that started to fail, such as an expired token.
• Use the log while building. JMeter can be asked to log more detail about its controllers for a short test, which helps you see why a gate opened or stayed shut. Turn the extra detail off for real runs, because heavy logging slows the test machine.

Watch the system under test too

Branches change the mix of requests the server receives. A sudden jump in database load might come from a branch opening more often, not from the server weakening. Put server metrics on the same timeline as the branch counts, so a change in one can be matched with a change in the other.

A condition is tiny, but a tiny cost repeated millions of times is no longer tiny.

When your test runs thousands of threads for hours, a condition may be evaluated millions of times. Most conditions are cheap, but a few choices make a real difference, and you should know them before the first large run.

Keep the heavy work elsewhere

If a decision needs real calculation, do the calculation once, in a script element with compiled-script caching, and store the answer in a variable. The If Controller then just reads that variable. This keeps the controller light, makes the logic testable, and avoids repeating the same work in many places.

Think about the whole chain

The cost of an If Controller is almost always smaller than the cost of what it skips. A well-placed gate that avoids a heavy request saves far more resources than it spends. The real danger is not the condition itself, but tests so large that even tiny overheads add up on the test machine. Always watch the processor and memory of the load generator during your first large run.

A condition is a small piece of code. Treat it with the care you give any code.

Conditions look like harmless one-liners, but in variable expression mode they can call functions, and in script mode they run as scripts. Because JMeter replaces variables with their values before evaluating the text, the content of those variables becomes part of the expression. When a variable holds data that comes from outside, such as a server response, that data can change what the expression does.

The injection risk

Suppose a condition inserts a variable into a script, and the variable holds text taken from a web page. If that text contains script commands, the script engine may run them. This is called injection, and it is one of the oldest security problems in software. In a load-testing tool it is less dramatic than on a public website, but it is still real: your test machines often hold credentials and sit inside private networks.

Safer habits

• Read variables inside the function, not by text substitution. A Groovy function that reads a variable with its own lookup is safer than one in which the variable’s content is pasted into the script text.
• Do not build conditions from untrusted text. Avoid inserting raw server responses or data file contents directly into an expression. Compare them as values instead.
• Prefer simple comparisons. The less a condition can do, the less it can be made to do by surprise.
• Review plans from outside sources. A test plan is a program. Opening one from an unknown source is like running an unknown file.
• Restrict who can edit shared plans. Conditions in plans that run on shared infrastructure should go through review like any other code.

Secrets and switches

If you switch branches by properties, do not put secrets, such as passwords, into properties that are echoed in logs. Use protected files or a secrets service, and have conditions check only harmless flags. Keep switches that unlock risky actions off by default, and require a deliberate choice to turn them on, ideally with a note in the test record about who did it and why.

Be careful with what the branch does

A branch that is rarely taken is easy to forget during a safety review. A branch that sends emails, writes data, or calls a payment service is just as dangerous as a main path, perhaps more so, because nobody is watching it. Make sure every branch uses test data and test endpoints, and that you have approval to run it.

The If Controller is simple and powerful. Like every tool, it brings costs you should know before you rely on it.

Flexibility versus clarity

The more branches a plan has, the more realistic it can be, and the harder it becomes to understand. A plan with no branches is easy to read and easy to reason about, but it may not resemble real traffic. A plan with dozens of nested conditions can imitate real behaviour well, but nobody dares to touch it. Most teams find a sweet spot with a handful of well-named gates that reflect the few differences that really matter.

Control versus risk of silent failure

A skipped step is a silent event. If a bug in a condition keeps a gate closed for everyone, the test still finishes, the error rate may look excellent, and the report may be wrong in a way nobody notices. The price of control is the extra work of checking that each branch ran as intended. This is why the chapters on results and monitoring matter as much as the chapters on writing conditions.

One plan versus many plans

Switches let one plan serve many situations, but they also hide differences between runs. The alternative, keeping separate plans for separate scenarios, is simpler to read but costly to maintain, since every shared change must be made several times. Many teams use a middle path: one plan for the shared core with a small number of documented switches.

Patterns are habits that keep branching plans healthy. Anti-patterns are habits that quietly spoil results.

Helpful patterns

Anti-patterns to avoid

When a gate opens at the wrong time, or never, work through the usual suspects in order.

Most If Controller problems come from a small set of causes. Match your symptom to the table and check the likely cause first.

A method for any puzzle

A short, cheap rehearsal catches nearly every branching bug before it can waste a real test.

The bugs that hurt most in branching plans are silent ones: a gate that never opens, or always opens, while the test still finishes and the report still looks healthy. A rehearsal, run at tiny scale, shows these bugs before they spoil a large run. The method has four stages.

A table makes it concrete

Repeat after every change

The rehearsal is not a one-time task. Whenever you change a condition, reorder elements, or edit the data file, run the four rows again. It takes minutes, and it turns branching from a source of doubt into something you can state with confidence: every path was seen to behave as designed.

A short checklist to carry into your next test.

Common mistakes in one list

• Pasting a condition written for script mode into variable expression mode, or the other way around
• Forgetting quotes around text values, or ignoring case differences
• Placing the extractor after the gate that reads its value
• Expecting an else branch that does not exist
• Using an If Controller to wait, loop, or split by exact percentages
• Leaving a debugging sampler or a heavy results viewer switched on during a real run
• Putting a transaction outside a rarely taken branch and averaging empty results
• Never checking whether a branch ran as often as planned

Five typical situations, described in general terms so you can adapt them.

One idea, many uses

All five scenarios use the same small element with different conditions. That is the quiet strength of the If Controller: it takes almost no effort to add, and it lets a single test plan behave as many different kinds of users and many different environments.

A one-page summary you can keep next to your test plan.

Five questions before pressing start

• Is each condition written for the mode that is currently selected?
• Does every variable used in a condition have a value or a default at that moment?
• Can I say each gate’s rule aloud in a plain sentence?
• Do I know how often each gate should open, and where I will check it?
• Are all debugging helpers switched off for the real run?

Quick answers to the questions beginners ask most often.

The If Controller is a small gate with a large effect. It lets a test plan skip steps that do not apply, react to what just happened, and follow different paths for different users, which is how real traffic behaves. Used well, it makes results more realistic and more trustworthy. Used carelessly, it hides problems behind silent skipping. If you remember one idea, let it be that every gate needs a reason you can say aloud, and a way to prove after the run that it opened as often as you planned.