Suites

What a suite declares

Each step picks a flow by name and configures its workload. Per-step settings mirror the engine workload — repetitions, rate, duration, timeout, params, trace, gen_subscriber. Six more fields are suite-only:

• stop_on_failure and always_run govern step ordering (covered below).
• checks assert aggregate-metric thresholds against the step's metrics after it runs — for example p99_latency_ms < 100. A failed check marks the step as not passed.
• success_when overrides per-UE pass/fail with a final-state criterion — at_least_one_final_state, exactly_n_final_state, or all_final_state. Use it for rate-limit and lockout tests where "at least one UE hit the locked state" is the success condition.
• background_flows names server-mode flows to start in parallel with the step's main flow, sharing the suite's event bus.

The last field, carry_params, passes state between steps — see Carrying state across steps.

For the full field list and types, see the suite schema reference.

Cycles

The suite runner repeats the full step list N times — each repetition is a cycle. The CLI exposes the outer-loop knobs:

-rate is rejected at the suite level — suites are strictly serial in v1. Per-step rate lives in the suite YAML.

Each cycle produces:

• A cycle-level report summarizing the whole step list.
• One per-step report for each executed step — the same shape as a standalone run-flow report.

One cycle of a typical register/load/cleanup suite, end to end:

stop_on_failure

Default true. If a step does not pass, the cycle aborts before the next non-always_run step. The aborted cycle is marked aborted in its report, and CI gets a non-zero exit.

Override with stop_on_failure: false for steps that are expected to fail intermittently:

always_run

A step marked always_run: true executes even after the cycle aborted earlier. This is the try/finally pattern: register UEs, run load, then deregister — and the deregistration runs even if the load step failed.

always_run still respects context cancellation (Ctrl+C, deadline) — if you really need to abort, the cleanup step is skipped.

Subscribers across steps

Each step independently acquires its own subscribers from the pool. repetitions: 5 on step 1 takes 5 subscribers, releases them at the end of the step, then step 2 takes 5 fresh ones. There is no subscriber sharing across steps in v1.

Implication: provision enough subscribers for the largest step's repetitions (or use gen_subscriber: true to synthesize per-UE in memory).

When to use a suite vs multiple flows

Use a suite when:

• The composition is meaningful — provision/load/cleanup, register-then-deregister, attach-then-handover-then-detach.
• You want one report per cycle covering all the steps.
• You need cleanup steps that run even on upstream failure.

Use multiple back-to-back run-flow calls when:

• The composition is just "run these in any order, gate on each independently".
• The steps don't share a meaningful cycle.

Carrying state across steps

Set carry_params: true on a step to export its UE's final params map to the next step. The downstream step layers its own params over the carried values, so an explicit YAML key always wins over a stale carried one. Use this when one step produces a value the next step needs — for example, step 1 extracts a version_id and step 2 issues a request against it.

carry_params is valid only when the exporting step runs a single UE (repetitions of 1 or less) — with more, the engine has no way to choose which UE's params to keep.

For procedures that need richer cross-step coupling, you can still write one larger flow that drives the whole sequence as a single state machine.

Where to go next

• Suite schema reference — every field, with types and defaults
• Flow and suite catalog — what ships
• Writing flows guide — author the flows a suite composes
• Running flows guide — invocation and exit codes