Suite schema

Synopsis

Working suites live under suites/ in the public templates repo: github.com/dflux-io/d3x-templates.

Top-level fields

Per-step fields

Execution semantics

• Steps run in YAML order, strictly serial — no parallelism.
• Each step independently acquires its own subscribers from the pool; subscribers are not shared across steps.
• The runner repeats the full step list -repetitions times, or until -duration elapses.
• Suites are serial, so there is no suite-level rate. run-suite registers no -rate flag — set rate per step in YAML instead.

Default stop_on_failure: true

When a step does not pass, the cycle aborts before the next step that is not marked always_run. The aborted cycle is reported as aborted.

always_run: true

A step marked always_run: true executes even when an earlier step aborted the cycle. Use it for cleanup steps. An always_run step still respects cancellation — Ctrl+C or a deadline skips it.

Aggregate checks

Per-step checks and top-level final_checks turn a suite into a load-test or conformance gate. Each check asserts a numeric comparison against a metric from the run.

• checks run after a single step completes, against that step's metrics. A failed check flips the step to failed, which feeds stop_on_failure.
• final_checks run once per cycle against the metrics merged across every step. Counters are summed; latency and RTT percentiles are computed from the merged histograms, so p99_latency_ms means p99 across all step samples. A failed final check fails the cycle but does not abort it — every step has already run by then.

A check has three fields: metric (a key such as avg_latency_ms, p99_latency_ms, success_rate, or flows_failed), op, and value. Valid ops are numeric only: equals, greater_than, less_than, greater_or_equal, less_or_equal.

success_when

By default a step passes only when every UE passes. success_when replaces that with a count-based criterion over the per-UE final-state tally — useful for negative tests where you expect some UEs to land in a rejection state. Exactly one matcher must be set:

• at_least_one_final_state: <state> — passes when at least one UE ended in that state.
• exactly_n_final_state: { state: <state>, count: <n> } — passes when exactly N UEs ended in that state.
• all_final_state: <state> — passes when every completed UE ended in that state (and at least one completed).

carry_params

Set carry_params: true to export a step's final params so the next step can consume them — for example, step one extracts a version_id and step two issues a PUT against it. The next step layers its own authored params on top, so on a key collision the downstream value wins. Valid only when repetitions is 1 or 0; with more than one UE the engine has no defensible way to choose whose params to keep.

Validation

run-suite rejects a suite at load time when:

• kind is set to anything other than suite
• name is empty
• there are no steps
• a step name is empty or duplicated within the suite
• a step flow is empty (the name itself is not resolved at parse time)
• any of repetitions, rate, duration, timeout is negative
• a success_when sets zero or more than one matcher
• a check is missing its metric or uses a non-numeric op
• carry_params: true is set on a step with repetitions greater than 1

Examples

Single-step smoke

Provision → load → cleanup

Per-region matrix

Notes

• flow: resolves at runtime, not at parse time. A suite that names a missing flow loads cleanly and fails at the first step that can't resolve.
• params: does not propagate between steps unless you set carry_params — otherwise each step starts fresh.
• gen_subscriber: true on one step doesn't affect its siblings; the synthesized subscriber lives only for that step's UEs.

Where to go next

• Writing flows and suites — prose walkthrough of authoring.
• Metrics reference — the metric keys available to checks and final_checks.
• Flow & suite catalog — every shipped flow and suite.