Skip to content

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.

// Reads src/test/resources/data/users.csv
FeederBuilder<String> userFeeder = csv("data/users.csv").circular();
userId,username,tier
101,alice,VIP
102,bob,STANDARD
103,charlie,STANDARD

// Reads src/test/resources/data/posts.json
FeederBuilder<Object> postFeeder = jsonFile("data/posts.json").random();
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.