Documentation Index
Fetch the complete documentation index at: https://mintlify.com/gatling/gatling.io-doc/llms.txt
Use this file to discover all available pages before exploring further.
Gatling’s Expression Language (EL) covers most templating needs, but sometimes you need to compute a parameter that goes beyond simple attribute lookup—parsing a value, combining multiple attributes, performing arithmetic, or applying conditional logic. For those cases, Gatling SDK methods that accept a String or value argument also accept a function that receives the virtual user’s current Session and returns the desired value. The function is evaluated freshly for each virtual user every time the action is executed, making it fully dynamic.
Functions run on Gatling’s shared threads. Never perform blocking I/O (network calls, file reads, database queries) inside a function—doing so will stall all virtual users sharing that thread and severely degrade test accuracy.
Gatling SDK components are definitions, not imperative instructions. They have no effect when called inside functions. For example, calling exec(http(...)) inside a lambda does nothing—SDK calls must be chained at the scenario-definition level and passed to setUp.
Function Signatures
The exact signature of a function parameter depends on which SDK language you use.
Java
Kotlin
Scala
JavaScript / TypeScript
In Java, functions take a Session and return a value of the expected type T:import io.gatling.javaapi.core.Session;
http("dynamic request")
.get(session -> "/users/" + session.getString("userId"))
.queryParam("locale", session -> session.getString("language").toLowerCase())
.body(StringBody(session ->
"{\"age\": " + session.getInt("age") + ", " +
"\"name\": \"" + session.getString("name") + "\"}"
));
Kotlin uses trailing lambda syntax for the same Session -> T contract:http("dynamic request")
.get { session -> "/users/${session.getString("userId")}" }
.queryParam("locale") { session -> session.getString("language").lowercase() }
.body(StringBody { session ->
"""{"age": ${session.getInt("age")}, "name": "${session.getString("name")}"}"""
})
In Scala, the type alias Expression[T] represents Session => Validation[T]. Gatling provides implicit conversions so you can return plain values without wrapping them explicitly:// Expression[String] — the String is implicitly lifted into Validation
http("dynamic request")
.get(session => s"/users/${session("userId").as[String]}")
.queryParam("locale", session => session("language").as[String].toLowerCase)
.body(StringBody(session =>
s"""{"age": ${session("age").as[Int]}, "name": "${session("name").as[String]}"}"""
))
Validation explicitly:import io.gatling.commons.validation._
http("safe parse")
.get(session =>
session("rawId").validate[String].map(id => s"/items/$id")
)
In JavaScript and TypeScript, pass a standard arrow function:http("dynamic request")
.get(session => `/users/${session.get("userId")}`)
.queryParam("locale", session => session.get("language").toLowerCase())
Session API
The Session object provides typed accessors for reading attributes that were previously stored by feeders, checks, or exec blocks.
session.getString("key") // returns String or null
session.getInt("key") // returns int (auto-unboxed)
session.getLong("key") // returns long
session.getDouble("key") // returns double
session.getBoolean("key") // returns boolean
session.getList("key") // returns List<Object>
session.getMap("key") // returns Map<String, Object>
session.contains("key") // returns boolean
Practical Examples
Constructing a URL from Session Data
http("get user orders")
.get(session ->
"/users/" + session.getString("userId") + "/orders?page=" + session.getInt("page"))
Combining Multiple Attributes in a Body
http("place order")
.post("/orders")
.body(StringBody(session ->
String.format(
"{\"product\": \"%s\", \"quantity\": %d, \"price\": %.2f}",
session.getString("productId"),
session.getInt("qty"),
session.getDouble("unitPrice") * session.getInt("qty")
)
));
Conditional Logic
http("request with optional header")
.get("/resource")
.header("X-Admin", session ->
"admin".equals(session.getString("role")) ? "true" : "false"
)
Scala for-comprehension with Validation
http("safe combined param")
.get(session =>
for {
userId <- session("userId").validate[String]
groupId <- session("groupId").validate[String]
} yield s"/groups/$groupId/users/$userId"
)
When to Use Functions vs. EL
| Situation | Best Approach |
|---|
| Simple attribute substitution | EL expression: "#{username}" |
| Nested or indexed attribute access | EL: "#{items(0)}", "#{user.email}" |
| Arithmetic or string operations | Function |
| Combining multiple attributes | Function |
| Conditional/branching logic | Function |
| Type coercion (e.g., String → Int) | Function |
In Scala, you can also write a helper method that returns Expression[T] and compose it using map/flatMap on Validation. See the Validation reference for details. 