Pausing and Pacing

Gatling's `pause` is the step a virtual user uses to do nothing for a while. It sits in a chain exactly like a request does — an `exec(...)` before it, an `exec(...)` after it — and its whole job is to make that one user wait a declared amount of time before moving on. ## The single-argument form `pause(10)` waits ten seconds. The rule that catches people is the unit: **a bare number is a count of seconds**, not milliseconds, in every Gatling SDK. In the Java API the overload is `pause(long duration)`, documented as "the pause duration in seconds"; in Scala the same bare number works because `io.gatling.core.Predef` declares `implicit def intToFiniteDuration(i: Int): FiniteDuration = i.seconds`. So `pause(100)` parks the user for a minute and forty seconds, which is almost never what someone who meant a tenth of a second intended. When you want a different unit, hand the step a typed duration instead. Each SDK spells that in its own type, and this is one of the places where the SDKs genuinely diverge: | SDK | how you write 100 ms | |---|---| | Java, Kotlin | `pause(Duration.ofMillis(100))` — a `java.time.Duration` | | Scala | `pause(100.millis)` — a `scala.concurrent.duration.FiniteDuration` | | JavaScript, TypeScript | `pause({ amount: 100, unit: "milliseconds" })` — an object literal | | all of them | `pause(100)` — a bare number, meaning **seconds** | ## The two-argument form `pause(1, 4)` is a *uniform random* wait between one and four seconds. It is not four one-second pauses, and it is not a fixed wait with a fixed jitter. What Gatling does is convert both bounds to milliseconds and call `ThreadLocalRandom.current.nextLong(minMillis, maxMillis)`, whose upper bound is exclusive; when the two bounds are equal it short-circuits and returns the bound itself. Two properties follow from that, and both matter when you read a report: * **The draw is per virtual user.** Two users arriving at the same `pause(1, 4)` at the same instant get independent values. * **The draw is per visit.** A user that loops back to the same step gets a new value each lap; nothing is cached in the session. That is precisely why the two-argument form de-synchronises a population that would otherwise march in lockstep, and it is the reason a scenario built from fixed pauses can produce a lumpy request pattern that a random range smooths out. ## The other two ways to say how long Both forms also accept a Gatling Expression Language string and a function of the session, so the duration can come from data rather than from a literal: * `pause("#{thinkTime}")` resolves the session attribute `thinkTime`. One `FiniteDuration` caster does that job for every SDK, and it accepts five shapes: an `Int` or a `Long` (read as seconds), a `String` that parses as a whole number (also read as seconds — which is what makes a CSV-fed attribute work, since CSV feeders yield nothing but `String`s), a `scala.concurrent.duration.FiniteDuration`, or a `java.time.Duration`. So the duration type here is *not* SDK-specific the way the literal argument in the table above is: a `java.time.Duration` resolves in a Scala simulation and a `FiniteDuration` resolves under the Java API. Anything outside those five shapes fails the virtual user at run time, not at compile time. Gatling's EL has used `#{...}` exclusively since 3.11.0, which removed the older `${...}` form, so `"${thinkTime}"` is no longer an expression at all. * `pause(session -> Duration.ofMillis(100))` in Java, or `pause(session => 100.millis)` in Scala, computes the wait from whatever the session holds. The same four shapes — bare number, typed duration, EL string, function — are available for the minimum and the maximum of the two-argument form. ## What a pause is not 1. **It is not a request.** The pause action only schedules the continuation; it never calls the stats engine, so a pause produces no row in the statistics table and no point on any response-time chart. Time spent pausing is invisible in the per-request numbers. 2. **It does not hold a thread.** `Pause` calls `session.eventLoop.schedule(...)` and returns. A paused virtual user costs a scheduled task and its session, which is why a single load generator can hold a very large number of users in think time at once. 3. **It is not `pace`.** `pause` is unconditional: it adds its duration on top of whatever the preceding steps took. The step that measures elapsed time and waits only the remainder is `pace`. 4. **Its duration is not necessarily what you wrote.** The number you pass is the input to a run-wide pause *type*, and the built-in default — constant, meaning "exactly this" — is only the default. Change the type on `setUp` and the same `pause(2)` becomes the mean of a distribution instead of a fixed wait. ## Naming the step in each SDK `pause` is spelled identically in all five authoring languages, so nothing about the name changes between Java, Kotlin, Scala, JavaScript and TypeScript. What changes is the duration argument in the table above, and — in Scala only — the fact that `pause(10)` is reaching an implicit conversion rather than a dedicated overload.