Scenario Lifecycle & Orchestration

Budment separates test definitions into deterministic execution phases. This design guarantees that administrative initialization, resource distribution, and graceful cleanup remain strictly isolated from high-throughput concurrent loops throughout test execution.

1. Scenario Declaration Paradigms

Budment supports two primary authoring styles. Both compile directly into identical Directed Acyclic Graph (DAG) structures inside the Go runtime.

Paradigm A: Declarative ES Module Exports (Recommended)

Ideal for standard load test scripts and CI/CD pipelines. Uses native JavaScript/TypeScript module exports.

import { http, sleep, metrics } from "@budment/sdk";

// 1. Scenario configuration
export const config = {
  vus: 10,
  duration: "30s",
};

// 2. Setup Phase: Executed strictly once before any concurrent workers spawn
export const setup = [
  http.get("https://api.example.com/health").after({ expect: { status: 200 } }),
];

// 3. Execution Phase: Traversed concurrently by active Virtual Users (VUs)
export default [
  http.get("https://api.example.com/items"),
  sleep(0.5),
  metrics.counter("completed_passes", 1),
];

// 4. Teardown Phase: Executed strictly once after execution finishes or is aborted
export const teardown = [http.delete("https://api.example.com/test-data")];

Paradigm B: Fluent Builder Pattern

Ideal for complex scenarios requiring strict TypeScript type-checking, dynamic programmatic generation, or reusable modular test components.

import { scenario, http, sleep } from "@budment/sdk";

export const checkoutScenario = scenario("Checkout Flow")
  .config({
    vus: 20,
    duration: "1m",
    order: 1,
  })
  .setup(
    http
      .post("https://api.example.com/auth/admin-token")
      .after({ extract: { token: "admin_jwt" } }),
  )
  .execution(http.get("https://api.example.com/cart"), sleep(1))
  .teardown(http.post("https://api.example.com/auth/logout"));

2. Phase Execution Lifecycle

Every Budment execution flows through a deterministic sequence:

Phase 1: Setup Pipeline

• Execution Boundary: Executed strictly once using a dedicated setup worker (VU 0, Iteration 0) prior to spawning the load generator worker pool.
• Failure Guard: If any assertion fails or an unhandled exception (abort()) occurs during setup, the engine immediately halts the run and exits with code 1, preventing unverified load against target environments.
• State Seeding: Data initialized via local.set(), global.set(), or distribute() is guaranteed to be fully synchronized and available to all workers before Phase 2 begins.

Phase 2: Execution Pipeline

• Worker Traversal: Concurrency scales according to the scenario's configured Virtual Users (vus) or dynamic ramping profile (stages).
• Iteration Isolation: Each worker iterates through the configured pipeline steps. Once an iteration finishes, worker-scoped memory is cleaned to prevent state leakage between cycles.
• Native Yield: When timers (sleep) or synchronization primitives (barrier) are encountered, execution yields control back to the Go concurrency scheduler without blocking operating system threads.

Phase 3: Teardown Pipeline

• Execution Boundary: Executed strictly once using a dedicated teardown worker (VU 0, Iteration 0) after the Execution phase completes natively, exhausts its duration, or is interrupted (e.g., via SIGINT / Ctrl+C).
• Graceful Cleanup: The teardown phase operates within a highly isolated background context with its own dedicated timeout. This guarantees that critical cleanup tasks—such as wiping ephemeral test records, revoking authentication tokens, or flushing final webhooks—are reliably executed even if the primary load test is forcefully canceled by the user.

3. Multi-Scenario Orchestration

Budment supports running multiple independent scenarios within a single script. Scenarios can run sequentially via execution tiers (order), simultaneously, or with scheduled start times (startAt).

Declarative Multi-Scenario Script

import { http, sleep } from "@budment/sdk";

// Global options applied to all scenarios unless overridden locally
export const options = {
  duration: "30s",
};

// Scenario 1: Cache Warming (Runs first in Order 1)
export const warmUpPhase = {
  config: {
    vus: 2,
    duration: "15s",
    order: 1,
  },
  setup: [http.get("https://api.example.com/health")],
  execution: [http.get("https://api.example.com/cache/warm"), sleep(1)],
};

// Scenario 2: Main Traffic (Runs in Order 2 after Order 1 completely finishes)
export const peakTraffic = {
  config: {
    vus: 50,
    duration: "2m",
    order: 2,
  },
  execution: [http.get("https://api.example.com/search?q=budment"), sleep(0.2)],
  teardown: [http.delete("https://api.example.com/cache/warm")],
};

4. Scenario Configuration & Precedence

Scenario Configuration Schema

Configurations declared in config or options accept the following fields:

Configuration Hierarchy & Override Order

Budment resolves configuration conflicts using a strict precedence order. Higher levels always override lower levels:

• Any configuration declared in export const config or export const options overrides defaults set in budment.yaml.
• Environment variables (e.g., BUDMENT_VUS, BUDMENT_DURATION) and CLI parameters override both file configurations at runtime.

5. Reserved Export Keywords

To ensure your scenarios compile as intended, avoid using the following reserved export identifiers as scenario names: