Step Constructs

Gatling simulations are not scripts that run top to bottom. A simulation is **assembled** from builder values, and only the tree of builders that ultimately reaches `setUp` is executed by the engine. Knowing which value each DSL call hands back is most of what scenario authoring is. ## Two builder types, one shared API | call | returns | can it be injected? | |---|---|---| | `scenario("Shopper")` | a `ScenarioBuilder` — a **named** chain of actions | yes | | `exec(http("Home").get("/"))` | a `ChainBuilder` — a **detached**, unnamed fragment | no | | `scenario("Shopper").exec(...)` | a new `ScenarioBuilder` | yes | | `browse.exec(...)` | a new `ChainBuilder` | no | Both types extend the same internal `StructureBuilder`, which is why they expose exactly the same vocabulary — `exec`, `group`, the loop constructs, the conditional constructs. The only substantive differences are that a `ScenarioBuilder` carries a name and offers the entry point that turns it into a population, while a `ChainBuilder` is a fragment you keep in a variable. That symmetry is the point. A chain is a **value**, not a statement. You can declare it as a constant, return it from a method, put it in a list, and reuse the same instance from several scenarios in the same simulation. ## Building browse-then-checkout ```java public class BrowseThenCheckoutSimulation extends Simulation { private static final ChainBuilder BROWSE = exec(http("Home").get("/")) .exec(http("Category").get("/books")); private static final ChainBuilder CHECKOUT = exec(http("Cart").get("/cart")) .exec(http("Place order").post("/orders")); { setUp(scenario("Shopper").exec(BROWSE, CHECKOUT).injectOpen(atOnceUsers(1))); } } ``` Three things are worth noticing: 1. `BROWSE` and `CHECKOUT` are plain constants. They are built once, when the class is initialised, and nothing about them is specific to the scenario that later uses them. 2. `exec(BROWSE, CHECKOUT)` attaches the two chains **sequentially** — a virtual user runs everything in `BROWSE`, then everything in `CHECKOUT`. 3. No HTTP traffic happens where those lines are written. `http("Home").get("/")` is a definition; if you build one and never attach it to anything that reaches `setUp`, it is a dangling definition with no effect at all. ## The shapes of `exec` In the Java API, `exec` comes in three forms, and the same three exist on `ScenarioBuilder` and on `ChainBuilder`: - `exec(Function<Session, Session>)` — attach a step that manipulates the virtual user's session. - `exec(head, tail...)` — attach one or more executables. Both `ChainBuilder` and every action builder (an HTTP request builder, for example) implement the same `Executable` interface, so you can freely mix them: `exec(BROWSE, http("Ping").get("/ping"), CHECKOUT)`. - `exec(List<ChainBuilder>)` — attach a whole list at once, which is handy when the set of chains is computed rather than written out. There is also a bare, static `exec(...)` — the one that bootstraps a fresh `ChainBuilder` from nothing. That static form is what you call when you write `ChainBuilder browse = exec(...)`, and the instance form is what you call when you write `browse.exec(...)`. ## The same shape in the other SDKs The `scenario` and `exec` spellings are identical in Java, Kotlin, JavaScript, TypeScript and Scala; only the surrounding syntax differs (`val` versus `ChainBuilder`, semicolons or not). Scala uses the same names: ```scala private val browse = exec(http("Home").get("/")).exec(http("Category").get("/books")) private val checkout = exec(http("Cart").get("/cart")).exec(http("Place order").post("/orders")) private val shopper = scenario("Shopper").exec(browse, checkout) ``` The SDKs do diverge at the point where a scenario becomes a population — Scala has a single `inject`, while the Java API (which Kotlin and the JavaScript/TypeScript package sit on) has `injectOpen` and `injectClosed` — but that is registration, not composition. ## What the scenario name is for The string you pass to `scenario` identifies the population in the run's output. Gatling normalises it on the way in: carriage returns, newlines and tabs are each replaced by a space and the result is trimmed, so a name containing whitespace oddities is silently rewritten rather than rejected. ## One chain, several scenarios Because a chain is an immutable value, the same `BROWSE` constant can be attached to a shopper scenario, an admin scenario and a smoke scenario in the same simulation, and none of them affects the others. That is what makes a small library of named flows worth having: each flow is written once and reviewed once, and the scenarios that use it read as a list of business steps rather than as a wall of requests. It also means a chain can be produced by a method. A helper with the signature `static ChainBuilder search(String term)` is a perfectly ordinary way to parameterise a flow, because there is nothing stateful about the value it hands back — the helper builds a fresh chain per call and the caller owns it. ## Common mistakes - Writing `exec(...)` on its own line and expecting a request to be sent there. - Assuming a chain belongs to the first scenario that used it and cannot be shared. - Trying to inject a `ChainBuilder`: only a named `ScenarioBuilder` becomes a population. - Inlining every action into one enormous `scenario(...)` call instead of naming the flows — which costs readability long before it costs anything else.