Load testing with realistic SPBT-generated traffic.

PropertyDamage.LoadTest leverages the stateful property-based testing infrastructure to generate realistic load against a system. Unlike synthetic benchmarks, each simulated user session follows valid state transitions with command weights that model real usage patterns.

Key Benefits

• Realistic Traffic: Commands respect preconditions and state
• Model-Based: Same model used for correctness testing
• Metrics Collection: Latency percentiles, throughput, errors
• Ramping Strategies: Linear, step, exponential load curves
• Live Reporting: Periodic metrics callbacks
• Dynamic Worker Pool: Workers created on demand, no sizing needed
• Command Timeouts: Prevents hung commands from causing unbounded growth

Quick Start

# Run a 2-minute load test at 100 arrivals/second
{:ok, report} = PropertyDamage.LoadTest.run(
  model: MyApp.TestModel,
  adapter: MyApp.HTTPAdapter,
  adapter_config: %{base_url: "http://localhost:4000"},
  arrival_rate: 100,
  duration: {2, :minutes}
)

# Print the report
IO.puts(PropertyDamage.LoadTest.Report.format(report, :terminal))

Advanced Usage

{:ok, report} = PropertyDamage.LoadTest.run(
  model: MyApp.TestModel,
  adapter: MyApp.HTTPAdapter,
  adapter_config: %{base_url: "http://localhost:4000"},

  # Load configuration
  arrival_rate: 100,  # 100 arrivals/second
  duration: {5, :minutes},

  # Ramp strategy - gradually increase load
  ramp_up: {:linear, {30, :seconds}},
  ramp_down: {:linear, {10, :seconds}},

  # Session behavior
  think_time: {100, 500},

  # Unified progress projection (DR-022): periodic LoadUpdate snapshots
  # and a terminal LoadResult carrying the final report.
  on_progress: fn
    %PropertyDamage.Progress{data: %PropertyDamage.Progress.LoadUpdate{snapshot: m}} ->
      IO.puts("RPS: #{m.requests_per_second}, p95: #{m.latency_p95}ms")

    %PropertyDamage.Progress{data: %PropertyDamage.Progress.LoadResult{report: report}} ->
      PropertyDamage.LoadTest.Report.save(report, "load_test.md", :markdown)
  end
)

Dynamic Worker Pool

The worker pool grows automatically to meet arrival rate demand. Workers are created on demand when no idle workers are available, eliminating the need to calculate pool sizes. The pool tracks:

• Workers Created: Total workers created during the test
• Peak Workers: Maximum concurrent workers at any point
• Utilization: How efficiently workers are being used

Command Timeouts

Adapters can specify timeouts for command execution via the timeout/1 callback. This prevents hung commands from causing unbounded pool growth:

defmodule MyAdapter do
  use PropertyDamage.Adapter, default_timeout: 30  # 30 seconds

  # Override for slow polling command
  def timeout(%CreateAuthorization{}), do: 120
end

Commands that exceed their timeout raise PropertyDamage.CommandTimeoutError.

Ramp Strategies

Control how load is applied over time:

• :immediate - Start at full rate immediately
• {:linear, duration} - Gradual linear ramp
• {:step, count, interval} - Increase rate in steps
• {:exponential, duration} - Exponential growth curve

Metrics Collected

• Throughput: Total requests, requests/second
• Latency: p50, p95, p99, min, max, mean
• Errors: Total count, error rate, by type
• Assertions: Failures count, rate, by assertion name (when enabled)
• Per-Command: Breakdown by command type
• Worker Pool: Workers created, peak workers, utilization
• History: Time series for trend analysis

Architecture

PropertyDamage.LoadTest
├── Runner         # Orchestrates arrivals and metrics
├── WorkerPool     # Dynamic pool of workers (auto-scaling)
├── Worker         # Holds adapter context, executes sequences
├── Metrics        # Collects latency, throughput, errors
├── RampStrategy   # Controls load ramping
└── Report         # Generates load test reports