Scenarios & Feeders¶
A Scenario defines the step-by-step workflow executed by virtual users, while Feeders supply realistic, distinct test data to each virtual user so your simulation exercises real database records, cache distributions, and partition keys.
1. Anatomy of a Gatling Java Scenario¶
All blocks in Gatling's Java DSL use fluent method chaining (.on(...), .then(...)) rather than Scala curly braces:
ScenarioBuilder orderJourney = scenario("Order Workflow")
.feed(userFeeder) // 1. Inject CSV row into Session
.group("Browse Phase").on( // 2. Logical group for report Rollup
exec(http("Search Catalog")
.get("/products?category=#{category}")
.check(status().is(200), jsonPath("$[0].id").saveAs("productId")))
.pause(Duration.ofSeconds(2), Duration.ofSeconds(5))
)
.doIf(session -> "VIP".equals(session.getString("tier"))).then( // 3. Conditional branch
exec(http("Apply VIP Discount").post("/cart/vip-coupon"))
)
.repeat(2, "itemIndex").on( // 4. Loop 2 times
exec(http("Add Item")
.post("/cart/items")
.body(StringBody("{\"productId\": \"#{productId}\", \"qty\": 1}")))
.pause(1)
);
2. Built-In Feeder Types & Strategies¶
Without feeders, every virtual user requests the exact same hardcoded ID—turning a database load test into an unrealistic in-memory cache hit test.
Iterator<Map<String, Object>> uuidFeeder =
Stream.generate((Supplier<Map<String, Object>>) () -> Map.of(
"requestId", UUID.randomUUID().toString(),
"amount", ThreadLocalRandom.current().nextInt(10, 500),
"timestamp", Instant.now().toString()
)).iterator();
// Feed unlimited unique records:
scenario("Event Stream").feed(uuidFeeder);
Choosing the Right Feeder Strategy¶
| Strategy | Method | Behavior When Data Runs Out | Best Used For |
|---|---|---|---|
| Queue (default) | .queue() |
Aborts test immediately (Feeder is now empty) |
One-time unique tokens (e.g., single-use registration codes, DELETE IDs) |
| Circular | .circular() |
Wraps seamlessly back to row #1 | General read/update load tests where rows can be reused across time |
| Random | .random() |
Picks any row at random with replacement | Avoiding sequential table/cache scan patterns |
| Shuffle | .shuffle() |
Randomizes row order once, then consumes sequentially (combine with .circular()) |
Unique non-repeating random order per cycle |
Memory Tip for Huge CSV Files
By default, csv("huge.csv") loads the entire file eagerly into JVM heap for zero-I/O runtime speed. If your CSV has millions of rows (> 200 MB), chain .batch(2000) (e.g., csv("huge.csv").batch(2000).circular()) so Gatling streams records in bounded chunks!
3. Gatling Expression Language (#{...}) vs. Lambdas¶
Gatling provides Expression Language (EL) strings ("#{varName}") for fast, clean variable interpolation inside URLs, headers, and ElFileBody templates:
| Built-In EL Expression | Output Example |
|---|---|
#{userId} |
Substitutes userId from Session |
#{productIds(0)} |
Indexes element 0 of a List stored in Session |
#{productIds.random()} |
Picks a random item from a Session list |
#{randomUuid()} |
Generates a fresh UUIDv4 without needing a feeder |
#{randomInt(1, 100)} |
Random integer in [1, 100] |
#{currentTimeMillis()} |
Epoch timestamp in ms |
Important Limitation of Gatling EL
Gatling EL (#{...}) is not a general-purpose scripting language—you cannot write math expressions like #{price * 1.08} inside an EL string! Compute derived values in a session -> ... function and store the result in Session first.
Knowledge Check¶
Your users.csv file has 10 rows, and your simulation injects 500 virtual users. If you define csv("data/users.csv") without specifying a strategy, what happens at user #11?
Next Steps¶
- Read next: Checks & Assertions — Validate HTTP responses, extract dynamic correlation fields, and enforce build-breaking SLO gates.