Controllers: Simple, Loop, Transaction, If, While, Switch, and Throughput: Configuration, Design Patterns, and Trade-Offs

1. Mandatory executable path remains local

2. Flat tree versus nested controllers

Use the shallowest tree that still exposes the scenario's real control semantics. Nesting for aesthetics alone adds maintenance cost.

3. Thread Group loop versus Loop Controller

Use Thread Group loop count for whole-journey repetition. Use Loop Controller when only a subsection repeats.

Example: “browse once, perform three searches, checkout once” belongs naturally to one outer iteration containing SearchLoop ×3. Setting Thread Group loops=3 would repeat browse and checkout three times too.

4. If Controller condition style

Preferred choices:

• direct boolean variable: ${DO_CHECKOUT};
• JEXL3: ${__jexl3(${CART_TOTAL} > 0)};
• Groovy function for conditions not cleanly expressible otherwise.

Keep Interpret Condition as Variable Expression? enabled. Avoid JavaScript mode for load tests because current documentation warns it can have a very large performance penalty.

Unless the business rule can change between child elements, leave Evaluate for all children off; reevaluating before every child adds complexity and can make a branch partially execute when its condition mutates mid-controller.

5. While condition style and hard bounds

Use a variable whose producer is clear: response extraction, explicit counter state, or a stable property. Because the While condition is evaluated twice per cycle, avoid side-effecting functions in the condition itself.

For production-like polling, pair the business stop condition with a safety bound: target-side timeout, max attempts encoded by a separate counter/controller, and/or Thread Group duration. Infinite polling is never an acceptable “wait until ready” strategy.

6. Switch numeric index versus named branches

Numeric indexes are concise but brittle to reordering. Named children such as standard, express, and default preserve intent. Name matching is case-sensitive except the special default fallback.

Use a variable such as ${CHECKOUT_MODE} supplied by test data/configuration rather than embedding multiple environment-specific conditions into the tree.

7. Additional transaction sample versus parent sample

Choose based on your reporting pipeline. Never switch modes between baselines without documenting that result schema changed.

8. Transaction timing: endpoint sum versus business wall time

By default Transaction Controller excludes timers and pre/post-processor processing from generated transaction time. Enable “Include duration of timer and pre-post processors” only when the metric explicitly intends that broader generator-side journey duration.

That option changes measurement semantics, not target behavior. Record it with the result artifact.

9. Throughput Controller percentage versus total executions

10. Per User changes the counting domain

With Total Executions=2:

• Per User off + 5 threads → at most 2 executions total in that JMeter instance.
• Per User on + 5 threads → up to 10 executions (2 per thread).

In distributed mode each remote engine has its own JMeter process/controller state, so a “global” count across all remote engines requires explicit architecture/aggregation; do not assume controller counters synchronize across machines.

11. Explicit branch data versus control logic

Store population attributes such as DO_CHECKOUT, CHECKOUT_MODE, or user cohort in Chapter 11 data/configuration. Controllers should implement the branch, not invent the population.

This separation improves reviewability: changing the business mix can often mean changing data/property inputs rather than restructuring the JMX.

12. Nested scope versus accidental inheritance

A Timer or Assertion attached above a controller applies to descendant samplers in its scope. Deep nesting can make inheritance hard to see. Use Simple Controller to establish explicit business boundaries when a scoped assertion/timer should affect a subset of samples.

13. Controller design affects measurement validity

Wrong loop multiplication changes offered load. Expensive If scripts reduce generator headroom. Transaction parent mode changes JTL schema. Throughput Controller percentages change business mix. While loops can create excess traffic. Every controller change therefore belongs in the run manifest and baseline comparison.

For every meaningful comparison, preserve the raw JTL together with its matching jmeter.log, the exact JMX/controller settings, and independent target request counts. The JTL proves which labels/results were emitted; jmeter.log preserves engine/runtime and condition-evaluation diagnostics; target counts prove which controller decisions became real protocol traffic.

14. Keep controller logic separate from surrounding layers

15. Decision table

Knowledge check

Official references and version notes

• Component Reference — Logic Controllers — Simple, Loop, Throughput, If, While, Switch, and Transaction Controller semantics.
• Elements of a Test Plan — scope and execution-order rules for samplers, controllers, timers, processors, and assertions.
• Functions and Variables — current JEXL3/Groovy/function/variable behavior used in conditions.
• Best Practices — GUI authoring versus CLI load execution and generator-validity guidance.
• Apache JMeter downloads — current production release and Java requirement.