In a k6 scenarios map, what is `startTime` measured from, and how do you make two scenarios run back to back?

## `startTime` is an absolute offset `startTime` is one of the keys every k6 scenario entry accepts. It is a duration string, it defaults to `"0s"`, and a negative value is rejected at config time with *the startTime can't be negative*. The crucial property is what it is relative to: **the start of the test run**, not the end of any other scenario. There is no dependency between entries in the map — no `after`, no `dependsOn`, no ordering by position in the object. Mechanically, k6 launches one goroutine per scenario as soon as the run starts. A scenario whose `startTime` is greater than zero sits in a waiting state — its progress bar reads `waiting` with a countdown — and only then hands control to its executor. This is why scenarios are described as running in parallel and only *appear* sequential when you arrange the offsets so their windows do not overlap. ## Staggering two scenarios The worked shape is two named scenarios, the second offset past the first: ```javascript export const options = { scenarios: { warm_up: { executor: 'constant-vus', exec: 'browse', vus: 5, duration: '30s', gracefulStop: '5s', }, peak: { executor: 'constant-vus', exec: 'browse', vus: 50, duration: '2m', startTime: '35s', }, }, }; ``` `warm_up` starts at zero and stops handing out iterations at 30 seconds, but its graceful window keeps it alive until 35 seconds. `peak` is offset to exactly that point, so the two never overlap. ## Doing the arithmetic The offset you need for a genuinely sequential run is not the previous scenario's `duration`: 1. take the earlier scenario's own length — its `duration`, the sum of its stages, or its iteration ceiling; 2. add that scenario's `gracefulStop`, which defaults to `30s` and extends its slot in k6's execution plan; 3. add the earlier scenario's own `startTime`, because every offset is measured from the same origin; 4. use the total as the later scenario's `startTime`. Step 2 is the one people miss. A `duration: '30s'` scenario left on the default graceful stop occupies the plan until second 60, so a second scenario at `startTime: '30s'` overlaps it for half a minute. ## Executors you cannot time exactly Sequencing is only reliable when the earlier scenario has a length k6 knows in advance. Executors configured by a duration or by stages do; iteration-based ones finish whenever their iterations are done and carry only a ceiling, so a scenario built on them may end long before the offset you computed. In practice that is fine — you get a gap rather than an overlap — but it means "back to back" is a floor, not a guarantee. ## What overlap actually costs Overlapping scenarios are a normal thing to want, and k6 supports them directly. The cost is in VU allocation. Before the run k6 merges every scenario's VU requirements into a single execution plan, adding the requirements of any scenarios whose windows coincide, and initialises one pool sized to the peak of that merged curve. All scenarios then draw from that one pool. - Two 10-VU scenarios that overlap need 20 initialised VUs; the run header prints `2 scenarios, 20 max VUs`. - The same two scenarios offset so they never overlap need only 10. - The header's *max duration (incl. graceful stop)* is the end of the last scenario's window, so it includes both the largest `startTime` and that scenario's graceful stop. - k6 lists the scenarios in the header sorted by `(startTime, name)`, so the printed order is the schedule, not the order you wrote them. Because every VU is initialised before the run starts, VU initialisation cost is paid for the peak even if the peak lasts one second. Staggering scenarios so their peaks do not coincide is therefore also a way of keeping the initialised VU count down. | two 10-VU scenarios, each `duration: '1m'` | offsets | initialised VUs | wall clock | |---|---|---|---| | both left at the default offset | `0s` and `0s` | 20 | about 1m30s | | second offset past the first's duration only | `0s` and `60s` | 20 | about 2m30s | | second offset past duration plus graceful stop | `0s` and `90s` | 10 | about 3m | The middle row is the trap: it looks sequential, costs the VUs of a parallel run, and nothing in the script says so — only the header's max VUs figure does. ## Common mistakes - Treating `startTime` as a delay after the previous scenario, then wondering why three 1-minute scenarios all finish within a minute of each other. - Forgetting `gracefulStop` in the arithmetic and getting a silent overlap. - Assuming the map's property order controls execution order; it does not, and object key order is not part of the contract. - Expecting `startTime` to delay `setup()` — it does not. `setup()` runs once, before any scenario's clock starts, and the offsets are measured from after it.