Behaviour for fault injection commands.

Nemesis commands represent faults that can be injected into the test environment to verify system resilience. Unlike regular commands that interact with the SUT, Nemesis commands modify the test environment itself (network conditions, proxies, resource limits, etc.).

Why Nemesis Commands?

Testing resilience requires injecting faults (network partitions, latency spikes, node crashes). These shouldn't "just happen" randomly - they should be:

1. Tracked in the event log - For reproducibility and debugging
2. Shrinkable - So we can find minimal fault scenarios
3. Composable - Multiple faults can be active simultaneously
4. Time-bounded - Faults should be restorable

Lifecycle

1. Injection: The Nemesis command is generated and executed
2. Active Period: The fault is active for some duration
3. Restoration: The fault is removed (automatically or explicitly)

Example: Network Partition

defmodule MyTest.Nemesis.PartitionNetwork do
  @behaviour PropertyDamage.Nemesis

  defstruct [:partition_type, :duration_ms]

  @impl true
  def inject(%__MODULE__{partition_type: type, duration_ms: duration}, ctx) do
    :ok = Toxiproxy.partition(ctx.proxy, type)

    # Return events describing what happened
    {:ok, [%NetworkPartitioned{type: type, started_at: System.monotonic_time()}]}
  end

  @impl true
  def restore(%__MODULE__{partition_type: type}, ctx) do
    Toxiproxy.restore(ctx.proxy, type)
    {:ok, [%NetworkRestored{type: type, ended_at: System.monotonic_time()}]}
  end

  @impl true
  def precondition(_state), do: true
end

Events in Log

Nemesis events are recorded with source: :nemesis:

%PropertyDamage.EventLog.Entry{
  timestamp: 12345,
  command_index: 5,
  event: %NetworkPartitioned{type: :full, started_at: 12345},
  source: :nemesis,
  nemesis_module: MyTest.Nemesis.PartitionNetwork
}

Model Integration

Nemesis commands can be included in the model's command weights:

def commands do
  [
    {CreateOrder, weight: 5},       # Normal commands
    {ViewOrder, weight: 3},
    {PartitionNetwork, weight: 1},  # Nemesis commands (lower weight)
    {InjectLatency, weight: 1}
  ]
end

Real vs simulated faults (no silent no-ops)

Some nemeses can only inject a real fault when their backing mechanism is available. The network nemeses (NetworkLatency, NetworkPartition, PacketLoss) need Toxiproxy configured in the adapter context (%{toxiproxy: %{proxy_name: ..., api_url: ...}}); without it they cannot touch the network. Rather than silently no-op while reporting success (the former "chaos theater" behavior), they now tag their events with simulated: true, so a fault that did nothing can never be mistaken for one that did. Use simulated_event?/1 to detect it, or assert against the :simulated field directly.

The host-effect nemeses (CPUStress, MemoryPressure, ResourceExhaustion, ProcessKill) always inject real effects in the BEAM. The cooperative ones (ClockSkew, SlowIO, CertificateExpiry) install real state but only change behavior if your adapter consults their public API (e.g. ClockSkew.now/0); they are real, not simulated, but require adapter cooperation to observe.

Assertion projections can adjust invariants during active faults:

def check(:latency_within_sla, state, ctx) do
  if Map.get(state.active_faults, :network_partition) do
    :ok  # Skip SLA check during partition
  else
    if state.last_latency_ms < 100, do: :ok, else: {:error, "SLA violation"}
  end
end