Scripting with JSR223 and Groovy for Advanced Test Logic: Core Concepts and Mental Model

1. The practical problem: scripting can hide both logic and cost

A 15-line JSR223 helper may be the clearest way to canonicalize an unusual identifier. A 400-line script that performs HTTP calls, parses JSON, implements retries, global counters, pacing, assertions, data allocation, and reporting has effectively hidden the test plan inside code. Reviewers can no longer see scope, execution order, or workload semantics from the tree, and generator CPU becomes difficult to attribute.

2. Mental model: JMeter lifecycle → JSR223 engine → controlled state change → downstream element

flowchart TD
T[Test Plan tree + thread lifecycle] --> E[JSR223 element at scoped execution point]
E --> G[Groovy JSR223 engine]
G --> B[Bindings: ctx / vars / props / prev or SampleResult / sampler / log / args]
B --> C[Small deterministic calculation or validation]
C --> M[Controlled mutation: usually vars or assertion/sample metadata]
M --> N[Downstream built-in sampler/assertion/controller]
N --> J[JTL + jmeter.log]
N --> S[Target evidence]
G --> P[Generator CPU / heap / compiled-script cache]
P --> V[Validity review]
J --> V
S --> V

The JMeter tree still decides when code runs: a PreProcessor runs before its sampler, a PostProcessor after it, an Assertion checks a sample in its scope, and a JSR223 Sampler is itself a sample/computation. The JSR223 element asks the Groovy engine to execute source. JMeter supplies bindings such as per-thread variables and global properties. Good script code makes one controlled change—for example, canonicalizing one thread-local value—and returns to built-in JMeter components. JTL and target evidence validate behavior; generator CPU/heap/cache evidence validates that scripting has not become the bottleneck.

3. Core bindings: what each object means

4. vars versus props is a concurrency decision

vars belongs to one JMeter thread. If two users both write vars.put('TOKEN', ...), their values remain independent. props belongs to the JMeter process; every thread can see the same property. That makes props appropriate for immutable run identity such as RUN_ID or VARIANT, but a dangerous place for a mutable per-user token, sequence, or ordinary ArrayList.

Distributed mode adds another boundary: each remote engine is a separate JVM with its own properties and memory. A property is “global” only inside one JMeter process, not magically shared across engines.

5. Compiled-script caching

Groovy implements JSR223 Compilable. Current JMeter recommends either a Script File (compiled/cached when the engine supports it) or inline script text with Cache compiled script if available enabled. The compiled-script cache defaults to 100 entries.

Caching removes repeated compilation from the hot path. It does not make your mutable objects thread-safe, and it does not make expensive Groovy logic free.

6. Why ${VAR} inside cached source is a correctness bug

JMeter performs variable/function replacement in inline script text before it is passed to the interpreter. If the script is then cached, the compiled source can represent the first expanded value rather than the new value from later iterations.

Broken cached source:

// BROKEN ON PURPOSE when cache is enabled:
def raw = '${RAW_NAME}'
vars.put('REQUEST_NAME', raw.trim().toLowerCase(java.util.Locale.ROOT))

Correct cache-safe source:

// Cache-safe: script text stays constant; runtime value is read from JMeterVariables.
def raw = vars.get('RAW_NAME')
vars.put('REQUEST_NAME', raw.trim().toLowerCase(java.util.Locale.ROOT))

The script text now remains constant, and vars.get reads current thread state every invocation.

7. SampleResult power requires restraint

JSR223 Sampler can set response data/status/code/message through SampleResult. That is legitimate when the script itself is the synthetic sampler. It is dangerous when used in a PostProcessor to turn a genuine HTTP 500 into a fake success.

Do not mutate prev.setSuccessful(true) merely to make dashboards green. Fix the assertion/target or classify an expected error explicitly without hiding it.

8. Non-destructive inspection before scripting

• Confirm JMeter 5.6.3, Java 17, and Groovy engine version.
• Search the tree for existing JSR223/BeanShell/JavaScript elements before adding another.
• Check whether a built-in extractor/assertion/controller/function already expresses the requirement.
• Inspect jsr223.compiled_scripts_cache_size overrides; default is 100.
• Classify each value as thread-local vars, immutable process-wide props, external data, or target/session state.
• Inspect jmeter.log for script compile/runtime exceptions.
• Record baseline generator CPU/heap/GC before placing Groovy in a hot path.

9. Version/cache preflight inside JMeter

A one-time JSR223 Sampler (Groovy, cache enabled) can return/log non-secret engine metadata:

def cacheSetting = props.getProperty('jsr223.compiled_scripts_cache_size', '100(default)')
def text = "groovy=${GroovySystem.version}; java=${System.getProperty('java.version')}; cache=${cacheSetting}"
log.info("PROMPT19 preflight " + text)
SampleResult.setResponseCode("200")
SampleResult.setResponseMessage("JSR223 preflight")
SampleResult.setSuccessful(true)
return text

Run this once during authoring/preflight, not inside the benchmark loop. On the course baseline it should identify Groovy 3.0.20 and Java 17.

10. State checklist before changing the plan

11. DevOps connection

Minimal scripts are easier to code-review, unit-test, version, benchmark, and reproduce in CI. They preserve a declarative JMeter tree while leaving one escape hatch for genuinely custom logic. The operating rule is simple: prefer JMeter components first; script the irreducible transformation; measure the generator cost.

Knowledge check

Official references and version notes

• JMeter Component Reference — JSR223 Sampler — compilation caching, bindings, script-file paths, SampleResult behavior, and Groovy guidance.
• JMeter Component Reference — JSR223 PreProcessor — scoped pre-sample scripting and bindings.
• JMeter Component Reference — JSR223 PostProcessor — post-sample scripting and previous-sample access.
• JMeter Component Reference — JSR223 Assertion — scripted assertion scope and bindings.
• JMeter Functions — __groovy — Groovy function bindings and cache-safe variable access.
• JMeter Properties Reference — jsr223.compiled_scripts_cache_size and advanced Groovy/JSR223 configuration.
• JMeter Best Practices — JSR223/Groovy recommendations, compiled scripting, lean results, and non-GUI load execution.
• Apache JMeter downloads — current stable release and Java requirement.
• Apache JMeter issue #6402 — JMeter 5.6.3 stack traces identify bundled Groovy 3.0.20 and document newer-JDK compatibility context.