Scripting with JSR223 and Groovy for Advanced Test Logic: Configuration, Design Patterns, and Trade-Offs

1. Mandatory examples remain local/free

2. Built-in component/function versus JSR223

Do not replace a JSON JMESPath Extractor with JsonSlurper just because Groovy can parse JSON. The built-in component already models that state transition.

3. JMeter function versus JSR223 element

__groovy can be useful for a tiny expression embedded in a field. It has cache-safe bindings such as vars and props. However, once the expression becomes multi-line, reusable, needs unit tests, or has exception branches, prefer a named JSR223 element/script file.

Functions can also obscure execution timing because they are evaluated when the containing field is resolved. A visible PreProcessor/PostProcessor often makes lifecycle clearer.

4. Inline script versus script file

5. vars versus props

Rule: if you find yourself using props.put('CURRENT_USER_TOKEN', ...), stop and re-evaluate ownership.

6. Immutable local data versus shared state

Local variables inside one script invocation are cheapest to reason about. Thread-local vars are the next boundary. Immutable objects referenced safely can be shared when justified. Mutable shared maps/lists/counters require concurrency-safe types and a clear reason.

Do not use props.put('LIST', new ArrayList()) and let all threads append. Even if it “works” at low load, the object itself is not made thread-safe by living in Properties.

7. Cached Groovy versus slower scripting engines

JMeter best practices recommend a JSR223 language implementing Compilable for intensive load; Groovy does. BeanShell and JavaScript are not recommended for intensive JSR223 paths in current JMeter guidance.

Do not assume a JavaScript engine is present on every modern JDK/JMeter runtime. If your existing plan relies on one, pin/provision the engine explicitly and benchmark it—or migrate small hot-path logic to cached Groovy/built-ins.

8. Groovy helper versus custom Java library/plugin

A 10–50 line helper can stay Groovy. When scripts grow into a shared domain library with many classes, complex parsing, large data structures, frequent allocation, concurrency primitives, or public APIs across dozens of plans, consider moving logic into a separately tested/versioned Java library. A real custom JMeter TestElement/plugin is justified only when new component behavior/UI/lifecycle integration is needed.

That choice adds build/release/classpath/plugin compatibility work. Do not create a plugin merely to avoid learning built-in JMeter components.

9. Cache-size trade-off

The default compiled script cache holds 100 compiled scripts. A normal plan should not need hundreds of dynamically different script bodies. If cache pressure appears because code embeds changing data into script source, fix the source/binding design first rather than increasing the cache.

Only tune jsr223.compiled_scripts_cache_size when evidence shows a legitimate large number of stable scripts and generator memory/cache behavior has been measured.

10. Logging design

Use INFO for setup/version/run summaries and rare lifecycle events, DEBUG for targeted temporary investigation, ERROR with contextual identifiers for genuine failures. Avoid logging full response bodies, tokens, passwords, environment variables, or one INFO line per sample in a hot loop.

Per-sample logs add formatting, locking/appender/file I/O and can enlarge jmeter.log enough to affect the generator.

11. Exception strategy

Pure helper functions should reject invalid inputs explicitly. Do not catch Exception and continue with stale variables. If a script cannot produce valid state, surface the exception/failure and let the plan's defined error policy act.

Catch only when you can add useful context or transform the error into a deliberate domain assertion without losing the original cause.

12. Configuration-layer boundaries

13. Worked scenario

Requirement: “A response has five JSON fields and one proprietary checksum transformation.”

• JSON JMESPath Extractors/Assertion handle the five fields/status.
• One cached Groovy helper computes only the proprietary checksum from thread-local inputs.
• The checksum helper has separate unit tests.
• The plan records generator CPU/throughput before/after introducing it.
• If the checksum library grows or becomes shared across many plans, move it to a tested Java library rather than growing ad-hoc Groovy indefinitely.

14. Decision table

15. Configured versus achieved load and evidence

Configured load is thread count, loops, timers, target endpoint and intended sample count. Achieved load is completed valid samples/second after Groovy compilation/execution, generator CPU/GC, result/logging overhead, and target service time. Preserve script source/hash, cache/config note, vars/props ownership table, unit-test output, JTL + matching jmeter.log, generator CPU/heap, target event counts/service time, and experimental limitations.

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.