Gatling Scenario Builder

Enforces a consistent, production-ready pattern for Gatling simulations across all five officially supported languages: Java, Kotlin, Scala, JavaScript, and TypeScript.

Output Format

When producing or fixing a simulation, always deliver three things:

1. A complete, runnable simulation file for the chosen language — never a partial snippet. The user should be able to copy it and run it immediately.
2. The exact run command with the environment parameters needed (baseUrl, users, etc.).
3. A one-line explanation of the injection profile chosen and why it fits the stated load goal.

Step 1 — Gather context

Ask only what is unknown. Typical questions:

• Language: Java (most common) · Kotlin · Scala · JavaScript · TypeScript
• Build tool: Maven · Gradle · npm (JS/TS only)
• Protocol: HTTP/REST · WebSocket · MQTT · JMS
• Goal: New project from scratch · Fix existing simulation · Specific DSL question

Only load references/PROTOCOLS.md when the user mentions WebSocket, MQTT, or JMS. Contains dependency declarations and DSL for those protocols — non-obvious setup steps the user will likely miss.

Only load references/DESIGN-PATTERNS.md when the user asks about folder structure, project architecture, separation of concerns, or how to scale beyond a single simulation file. Contains the modular layered pattern (Config → Requests → Scenarios → Simulations) with examples in Java, Scala, and TypeScript.

Step 2 — New project? Use the scaffold script

Direct the user to run the interactive script rather than writing the project structure by hand. The script handles all language/build-tool combinations, creates the correct directory layout, and produces a working simulation:

# macOS / Linux
bash scripts/scaffold.sh

# Windows
.\scripts\scaffold.ps1

After scaffolding — or whenever the user shares an existing Gatling project — execute the validator with the Bash tool (do not read it, only the output consumes tokens):

bash scripts/validate.sh [project-dir]

Report the results. The script catches the five most common configuration problems before the user wastes time on a broken run.

Step 3 — Apply the 5-block pattern

Every simulation must have these five blocks in this order. Generate the complete skeleton for the chosen language first, then fill in the details — starting from a partial file leads to structural errors.

Block 1 → Protocol    baseUrl, headers, connection settings
Block 2 → Feeders     test data injected per virtual user
Block 3 → Scenario    ordered chain of requests with pauses and checks
Block 4 → Injection   how many users, at what rate, for how long
Block 5 → Assertions  pass/fail thresholds (success rate, response time p95)

Common Mistakes — Check Every Simulation for These

These five errors appear in almost every first-draft Gatling simulation. Scan for them before delivering any code.

1. Missing pause() between requests

Without think time, all requests fire at the maximum possible rate, generating 10–100× more load than real users would. This makes results meaningless and can crash the system under test.

// Wrong
scenario("Flow").exec(http("A").get("/a")).exec(http("B").get("/b"))

// Correct — add realistic think time between actions
scenario("Flow").exec(http("A").get("/a")).pause(1, 3).exec(http("B").get("/b"))

2. Hardcoded dynamic tokens

Hardcoded tokens mean every virtual user sends the same session — the server sees one user repeated, not many distinct users. CSRF tokens and JWTs are server-side validated; they must come from the actual login response.

// Wrong — static token shared across all users
.header("Authorization", "Bearer eyJhbGciOiJIUzI1NiJ9.abc123")

// Correct — extract per user from the login response
.exec(http("Login").post("/auth/login")
    .check(jsonPath("$.token").saveAs("token")))
.exec(http("API Call").get("/data")
    .header("Authorization", "Bearer #{token}"))

3. atOnceUsers for load tests

atOnceUsers fires all users simultaneously. It is only appropriate for smoke tests (2–5 users). Using it for real load tests generates an unrealistic spike that tells you nothing about capacity.

// Wrong — not a load test, just a spike
setUp(scn.injectOpen(atOnceUsers(100)))

// Correct — ramp up, then hold to measure steady-state capacity
setUp(scn.injectOpen(
    rampUsers(100).during(60),
    constantUsersPerSec(10).during(120)
))

4. No assertions

Without assertions, Gatling exits with code 0 (success) even if every request returns 500. This means CI/CD pipelines never catch performance regressions. Define what “passing” looks like before the test runs.

// Wrong — always exits 0 regardless of results
setUp(scn.inject(...).protocols(httpProtocol))

// Correct — fail the build if thresholds are breached
setUp(scn.inject(...).protocols(httpProtocol))
    .assertions(
        global().successfulRequests().percent().gt(99.0),
        global().responseTime().percentile(95).lt(1000)
    )

5. .queue() feeder strategy for long tests

.queue() consumes each CSV record once, in order. When the file runs out, the test fails mid-run. Use .circular() for any test that may run longer than the number of records allows.

// Wrong — crashes when file is exhausted
FeederBuilder<String> f = csv("data/users.csv").queue()

// Correct for sustained tests — loops back to the start
FeederBuilder<String> f = csv("data/users.csv").circular()

// Use .queue() only when each record must be unique (e.g., user registration)

6. Check failure marks the request as FAILED

A .check() that doesn’t find its target fails the entire request — even if the server responded 200. This silently inflates error rates and hides the real problem: the field was absent or the path was wrong.

// Wrong — if $.token is absent (e.g., login failed), request is marked FAILED
.check(jsonPath("$.token").saveAs("token"))

// Correct — validate existence first so the error message is meaningful
.check(status().is(200))
.check(jsonPath("$.token").exists())
.check(jsonPath("$.token").saveAs("token"))

// When the field is genuinely optional — use .optional() to avoid false failures
.check(jsonPath("$.refreshToken").optional().saveAs("refreshToken"))

7. Missing Content-Type when sending a request body

Forgetting Content-Type on POST/PUT requests causes the server to reject with 415 Unsupported Media Type. Use .asJson() — it sets both Content-Type and Accept headers in one call.

// Wrong — server returns 415
.post("/api/users").body(StringBody("""{"name":"#{name}"}"""))

// Correct — use .asJson() shorthand
.post("/api/users").body(StringBody("""{"name":"#{name}"}""")).asJson()

// Equivalent explicit form
.post("/api/users")
    .header("Content-Type", "application/json")
    .body(StringBody("""{"name":"#{name}"}"""))

The 5-Block Pattern — Reference

Block 1: Protocol

// Java / Kotlin
HttpProtocolBuilder httpProtocol = http
    .baseUrl(System.getProperty("baseUrl", "https://api.example.com"))
    .acceptHeader("application/json")
    .contentTypeHeader("application/json");

// Scala
val httpProtocol = http
  .baseUrl(sys.props.getOrElse("baseUrl", "https://api.example.com"))
  .acceptHeader("application/json")

// TypeScript / JavaScript
const httpProtocol = http
  .baseUrl(process.env.BASE_URL ?? "https://api.example.com")
  .acceptHeader("application/json");

Block 2: Feeders

csv("data/users.csv").circular()  // sustained tests: loops forever (recommended)
csv("data/users.csv").random()    // picks records randomly, allows repeats
csv("data/users.csv").queue()     // each record used once — only for unique data
csv("data/users.csv").shuffle()   // random order, each used once

// Programmatic feeder — when each user needs a unique generated value
Iterator<Map<String, Object>> feeder =
    Stream.generate(() -> Map.<String, Object>of("id", UUID.randomUUID().toString()))
          .iterator();

Block 3: Scenario

// Java
ScenarioBuilder scn = scenario("My Flow")
    .feed(userFeeder)
    .exec(http("POST Login")
        .post("/auth/login")
        .body(StringBody("""{"username":"#{username}","password":"#{password}"}"""))
        .check(status().is(200))
        .check(jsonPath("$.token").saveAs("token")))   // extract token for reuse
    .pause(1, 3)                                        // think time
    .exec(http("GET Data")
        .get("/data")
        .header("Authorization", "Bearer #{token}")    // inject extracted token
        .check(status().is(200))
        .check(jsonPath("$.id").saveAs("resourceId")))
    .pause(1)
    .exec(http("POST Action")
        .post("/actions")
        .header("Authorization", "Bearer #{token}")
        .body(StringBody("""{"resourceId":"#{resourceId}"}"""))
        .check(status().is(201)));

// TypeScript
const scn = scenario("My Flow")
  .feed(userFeeder)
  .exec(http("POST Login").post("/auth/login")
    .body(`{"username":"#{username}","password":"#{password}"}`)
    .check(status().is(200))
    .check(jsonPath("$.token").saveAs("token")))
  .pause(1, 3)
  .exec(http("GET Data").get("/data")
    .header("Authorization", "Bearer #{token}")
    .check(status().is(200)));

Loops and conditionals:

repeat(3).on(exec(http("Poll").get("/status")))                    // fixed iterations
during(Duration.ofSeconds(30)).on(                                  // time-based loop
    exec(http("Ping").get("/ping")).pause(5))
doIf("#{isPremium}").then(exec(http("VIP").get("/vip")))           // conditional branch
randomSwitch().on(                                                   // weighted paths
    percent(60.0).exec(http("Browse").get("/products")),
    percent(40.0).exec(http("Search").get("/search")))
group("Checkout Flow").on(                                          // group for cleaner reports
    exec(http("Cart").get("/cart"))
        .exec(http("Pay").post("/pay")))

Block 4: Injection Profiles

Choose the profile that matches the test goal — using the wrong one produces misleading results.

injectOpen — controls arrival rate (new users/second). Default for web APIs and stateless services.

injectClosed — controls concurrent count (users active simultaneously). Use for systems with connection pools, queues, or session limits.

Scala note: use .inject(...) — Scala has no injectOpen/injectClosed distinction at the call site; the step type determines the model.

Throttling — cap RPS regardless of user count:

Use .throttle() when the goal is to test at a fixed request rate rather than a fixed user count. It overrides injection and is useful for SLA compliance tests.

setUp(scn.injectOpen(constantUsersPerSec(50).during(Duration.ofMinutes(10))))
    .throttle(
        reachRps(100).in(Duration.ofSeconds(10)),  // ramp to 100 RPS over 10s
        holdFor(Duration.ofMinutes(5))              // hold at 100 RPS for 5 min
    )
    .protocols(httpProtocol);

Pause distributions — choose based on realism needed:

.pause(1, 3)                                    // uniform: between 1-3s (default)
.pause(Duration.ofSeconds(2),
       PauseType.EXPONENTIAL)                   // exponential: closer to real user behavior
.pace(Duration.ofSeconds(5))                    // cadence: fixed cycle regardless of response time

Block 5: Assertions

Assertions turn the test into a pass/fail gate. Without them, the test is just an observation. Include at minimum the first line; add per-endpoint assertions for critical paths.

.assertions(
    global().failedRequests().count().lt(1L),           // minimum: zero errors
    global().successfulRequests().percent().gt(99.0),   // success rate
    global().responseTime().percentile(95).lt(1000),    // p95 < 1s
    global().responseTime().percentile(99).lt(2000),    // p99 < 2s
    global().requestsPerSec().gt(50.0),                 // throughput floor
    details("POST Login").responseTime().percentile(99).lt(500)  // per-endpoint
)

Use percentile(95) and percentile(99), not mean(). Mean hides the tail: a p99 of 10 seconds is invisible when mean is 200ms.

Run Commands

# Maven
mvn gatling:test -Dgatling.simulationClass=perf.MySimulation \
                 -DbaseUrl=https://staging.example.com -Dusers=50

# Gradle
gradle gatlingRun-perf.MySimulation -DbaseUrl=https://staging.example.com

# TypeScript / JavaScript  (use simulation name, not file path)
BASE_URL=https://staging.example.com USERS=50 \
  npx gatling run --simulation MySimulation

Reports open at: target/gatling/<simulation>-<timestamp>/index.html

References

• Scenario DSL
• Injection Profiles
• Checks
• Feeders
• Assertions
• WebSocket / MQTT / JMS
• Modular Design Patterns