Scripting with JSR223 & Groovy

All six elements share the same five fields. They are TestBean elements, so the .jmx file stores them under the generic TestBeanGUI and plain property names:

A complete JSR223 PreProcessor in a .jmx file:

The other elements differ only in the tag and testclass: JSR223Sampler, JSR223PostProcessor, JSR223Timer, JSR223Assertion and JSR223Listener.

Source: JSR223 PreProcessor (Component Reference)

The six elements wrap the same script runner but treat the result and errors differently. The following is taken from the component reference and, where it is silent, from the 5.6.3 source of each element class:

In every element, an org.apache.jorphan.util.JMeterStopThreadException, JMeterStopTestException or JMeterStopTestNowException thrown by the script is not swallowed: since 3.2 it stops the thread, the test or the test immediately, like the corresponding sampler-error actions.

Source: JSR223 Sampler, JSR223 Timer, JSR223 Assertion and Changes history (bug 60813)

The JSR223 elements accept any engine, but the best-practices chapter is explicit: for intensive load testing use a language whose engine implements the Compilable interface, and of the engines usually available only Groovy does. BeanShell declares Compilable but its implementation throws an exception, so JMeter has an explicit workaround that treats it as non-compilable. JavaScript is also not compilable through these elements, and on Java 15 and later there is no JavaScript engine in the JDK at all (Nashorn was removed): JMeter 5.6.3 documents copying a Rhino engine jar into lib/ext or adding OpenJDK Nashorn as a module to get one back. Velocity and other languages work if their engine jar is in lib, with their own syntax for bindings (for Velocity, $vars.get("a")).

A non-compilable script is parsed and interpreted on every call, by every thread. A compiled Groovy script is turned into a JVM class once and then executed like Java bytecode.

Source: JSR223 Elements (Best Practices) and Changes (known problems: Nashorn)

The details, from the component reference and the 5.6.3 source:

Source: Advanced JSR-223 Scripting configuration (Properties Reference)

JMeter processes variable and function references in the Script field before the text reaches the engine. With caching on, that has two consequences, which the component reference summarises as "caching would only cache first replacement":

With caching off the values are right, but every call is a new text, so every call compiles a new class.

The fix is the same in both cases: keep the script text constant and read changing values at run time with vars.get("bookId"), or pass them through the Parameters field and read args.

A related trap is Groovy’s own string interpolation. A double-quoted Groovy string such as "Loan ${loanId} created" is also a JMeter reference as far as JMeter is concerned: if a JMeter variable loanId exists it is substituted into the text, with the effects above. In inline scripts use concatenation, single-quoted strings, or the brace-less Groovy form "Loan $id created" with a local variable; in a script file JMeter performs no substitution at all, and references are passed verbatim to the engine.

Source: JSR223 Sampler (Component Reference) and JSR223 Elements (Best Practices)

Take the canonical load profile of this section: 50 threads, a 60 s ramp-up and a 660 s scheduler duration (a 10-minute hold). Suppose one Bookshelf journey takes about 8.5 s including think time (the mean iteration of the Bookshelf mix with Z = 3 s, worked out on the logic controllers page), and contains three JSR223 elements (the body builder, the request signer and an assertion).

The component reference adds one more JVM detail: if Groovy is used without caching, set the system property -Dgroovy.use.classvalue=true (for example in JVM_ARGS or bin/setenv.sh) because of a Groovy memory leak present since 2.4.6.

Tools → Compile JSR223 Test Elements (since 5.1) compiles every JSR223 element of the open plan and reports syntax errors in the log, without running the test. Combined with a smoke run of one user, it catches typos before they turn into 50 threads writing stack traces to jmeter.log.

Source: Changes history (Version 5.1)

A reasonable rule: one-liners and short glue code inline, anything longer than a screen or shared by several elements in a file next to the plan, with JMeter started from the plan’s directory.

The __groovy function evaluates a Groovy expression wherever a field accepts a function, for example ${__groovy(vars.get("loanStatus") != "ACTIVE")} in an If or While Controller, or a schedule string in an Open Model Thread Group. It returns the script’s result as a string and can store it in a variable given as the second argument.

The best-practices chapter suggests developing a function script in a JSR223 Sampler first, then storing it in a Test Plan variable and calling it as ${__groovy(${RANDOM_NAME})}; commas inside the variable’s value then need no escaping because the call is parsed before the value is interpolated.

Source: __groovy (Functions), Advanced Groovy Scripting configuration (Properties Reference) and Developing script functions (Best Practices)

The use of __groovy in controller conditions is shown in Logic Controllers & Transactions, and in schedule strings in Open Model & Throughput Control.

POST /api/loans needs a JSON body built from several variables. Writing it by hand in the Body Data field breaks as soon as a value contains a quote; groovy.json.JsonOutput (part of the groovy-json module bundled with JMeter) escapes correctly.

The PreProcessor sits under the sampler, so it runs only for that sampler. The ${loanBody} reference in the body is fine: it is a sampler field, not script text. The other HTTP fields are described in HTTP Requests and JSON APIs in REST, JSON, GraphQL & SOAP APIs.

Source: JSR223 PreProcessor (Component Reference) and Groovy documentation (groovy.json.JsonOutput)

Suppose a gateway in front of the Bookshelf API requires each write request to carry an HMAC-SHA256 signature of the method, path, a timestamp and the body. JMeter has no signing element, but the JDK’s javax.crypto.Mac does it in a few lines. The secret is a run property with a placeholder value, never written in the plan.

Add a second JSR223 PreProcessor named Sign request after Build loan body under the same sampler (pre-processors run in tree order):

Then add the headers to the sampler’s HTTP Header Manager: X-Timestamp with value ${sigTs} and X-Signature with value ${signature}. Run it with a placeholder secret:

Mac objects are not thread-safe, which is why the script creates one per call instead of storing it in props; creating it costs microseconds. Throwing JMeterStopTestException stops the whole test at the first call, which is the right reaction to a missing property.

Source: JSR223 PreProcessor (Component Reference) and HTTP Header Manager (Component Reference)

SampleResult.setIgnore() drops a result from reporting. For a JSR223 Sampler the component reference lists the effects: the result is not delivered to listeners such as View Results Tree or the summariser, and it is not evaluated by assertions or post-processors, but it still counts for ${JMeterThread.last_sample_ok} and, since 5.4, for the Thread Group’s Action to be taken after a Sampler error. Since 4.0 the method can also be called on prev from JSR223 post-processors and assertions.

A data-only sampler. A JSR223 Sampler that only picks a book id should not appear in the report as a sample with a near-zero response time that drags every average down:

A polling request. The View loan request may be repeated by a While Controller until the loan becomes ACTIVE. Reporting every intermediate PENDING poll would inflate the request count; a JSR223 PostProcessor under it keeps only the final one:

Use this sparingly: an ignored sample also disappears from the error rate, so ignore only samples that are not part of what the test measures. The usual alternative for "do not report this" is the Flow Control Action sampler, which produces no result at all.

Source: JSR223 Sampler (Component Reference) and Changes history (bug 61806)

Variables never cross thread boundaries; properties do. The pattern: a setUp Thread Group fetches the catalogue once and publishes the ids as a property; every thread of the main Thread Group reads them.

The main Thread Group then uses the Pick a book sampler of the previous recipe, or ${__groovy(props.get('bookIds').size())} wherever a field needs the count.

Rules for shared data:

Source: Sharing variables between threads and thread groups (Best Practices) and JSON Extractor (Component Reference)

A built-in assertion says "Assertion failed"; a script can say why. The JSR223 Assertion under View loan parses the loan and checks two business rules:

The message appears in the failureMessage column of a CSV results file and in the assertion results of View Results Tree while scripting. The same can be done without an assertion element:

Prefer the JSR223 Assertion, because assertion failures are counted and reported as such, and because the JSON Assertion or JSON Extractor can usually do half of the job more cheaply. Assertions in general are covered in Assertions.

Source: JSR223 Assertion (Component Reference)

The JSR223 Timer returns a delay in milliseconds and must return an integral value:

Returning 500 + Math.random() * 1000 would produce a Double, which the timer cannot parse as a long, so the delay would silently be zero and an error would be logged on every call. Timers and their distributions are covered in Timers & Think Time.

A JSR223 Listener runs for every sample in its scope, in the sampling thread. This one counts failed loan creations per JVM, cheaply:

A JSR223 Sampler in the tearDown Thread Group can then log props.get('failedLoans').

Source: JSR223 Timer and JSR223 Listener (Component Reference)