In a Gatling stepped injection profile, what does separatedByRampsLasting add, and why does the presence of startingFrom change the resulting shape?

`separatedByRampsLasting` is the call that turns a flight of instant steps into the shape most capacity runs actually want: hold, rise smoothly, hold, rise smoothly. What is less obvious is that it does not compose independently with `startingFrom`. The two optional calls interact, and Gatling expands the staircase into two genuinely different lists of blocks depending on whether the starting level is **non-zero**. The branch is on the value, not on the call: the starting level defaults to `0`, so `.startingFrom(0)` is indistinguishable from omitting `startingFrom` altogether and gets the same ramp-first expansion. ## The two expansions Take eight levels twenty arrivals per second apart, each held two minutes, with thirty-second ramps. **With `.startingFrom(20)` — the pattern is `(level, ramp)` repeated, plus a final level:** 1. hold 20/s for 2 min 2. ramp 20/s to 40/s over 30 s 3. hold 40/s for 2 min 4. ... and so on ... 5. hold 160/s for 2 min — **no trailing ramp** That is **8 levels and 7 ramps**: 16 minutes of levels plus 3.5 minutes of ramps, 19 minutes 30 seconds in all. **With `startingFrom` omitted, or declared as `0` — the pattern is `(ramp, level)` repeated:** 1. ramp 0/s to 20/s over 30 s 2. hold 20/s for 2 min 3. ramp 20/s to 40/s over 30 s 4. hold 40/s for 2 min 5. ... ending with a ramp to 160/s and a hold at 160/s That is **8 levels and 8 ramps**: 16 minutes plus 4 minutes, exactly 20 minutes. ## Reading the differences | | starting level non-zero | starting level `0` or omitted | |---|---|---| | opens with | a flat level | a ramp out of zero | | ends with | a level, no trailing ramp | a level, preceded by a ramp | | ramps in the profile | `levels - 1` | `levels` | | total duration | `levels x level + (levels-1) x ramp` | `levels x (ramp + level)` | | peak | `(levels-1) x increment + start` | `levels x increment` | The last row is the one that catches people twice. **With ramps present and the starting level at zero, the peak is not one increment short** — unlike the no-ramp case, where an omitted start leaves a zero-rate level and costs you the top step. Here the ramp-first expansion counts levels from `1 * increment` up to `levels * increment`, so eight levels twenty apart still reach 160 arrivals per second. The same omission therefore has *opposite* effects on the peak depending on whether ramps are declared, which is exactly the kind of detail worth stating out loud in a review. ## The ramps inject users too A ramp is not dead time between levels; it injects at a rate rising linearly from the level below to the level above, which works out as the average of the two for its duration. A thirty-second ramp from 20 to 40 arrivals per second therefore contributes roughly 900 users that the unramped version of the same staircase never injects. Summed over the whole profile, the ramped eight-level staircase applies noticeably more work than the flat-jump one with the same levels, and it applies it over a longer wall-clock window. If a run is being compared against an earlier one, adding or removing `separatedByRampsLasting` changes both the duration and the injected total, so the two runs are no longer the same profile. Whether that makes them incomparable is a question about run comparability rather than about the DSL — but the change itself is a Gatling fact, and a one-word edit can cause it. ## Why the ramp matters beyond aesthetics A hard jump from one level to the next asks the system under test to absorb the entire increment in one instant. The ramp spreads that increment across its duration instead, which is the difference between a profile that exercises a system's steady behaviour at each level and one that repeatedly exercises its reaction to a step change. Which of those you want is a decision about the run's purpose, not about the DSL — but Gatling gives you exactly one knob for it, and the knob is on or off for the whole staircase. That uniformity is the builder's main constraint. One ramp duration applies to **every** gap; one level duration applies to **every** level. A profile that wants a longer dwell at the top, or a gentler ramp only at the highest transition, has outgrown the helper and needs hand-chained steps. ## Writing both forms ```java // level first, 7 ramps, 19m30s incrementUsersPerSec(20) .times(8) .eachLevelLasting(Duration.ofMinutes(2)) .separatedByRampsLasting(Duration.ofSeconds(30)) .startingFrom(20); // ramp first, 8 ramps, 20m incrementUsersPerSec(20) .times(8) .eachLevelLasting(Duration.ofMinutes(2)) .separatedByRampsLasting(Duration.ofSeconds(30)); ``` The two optional calls may be written in either order — both are declared on the same final stage of the chain and each returns that stage again — so `.startingFrom(20).separatedByRampsLasting(...)` builds the identical profile. ## The closed builder `incrementConcurrentUsers` expands by the same rule, substituting held concurrency for arrival rate: `(level, ramp)` with a non-zero starting level, `(ramp, level)` without one. Its ramps are `rampConcurrentUsers`-shaped, so the usual caution applies — a downward transition would not interrupt users already in the system — but a staircase built with a **positive** increment only ascends, so every ramp it generates is upward. The increment itself is not validated, so a negative one paired with a `startingFrom` high enough to keep every level at or above zero does build a descending staircase with downward ramps, and there the ramp-down caution genuinely applies. What a negative increment cannot do is open downward: with `startingFrom` omitted the leading ramp out of zero would need a negative endpoint, and `RampConcurrentUsersInjection` requires both ends to be `>= 0`.