Behaviour for commands in stateful property-based testing.

Commands are semantic operations that can be executed against the System Under Test (SUT). They are represented as structs containing their arguments, and define how to generate valid field values.

Command Specification

Commands define a command_spec/1 function that returns a complete specification map describing execution semantics, shrinking hints, and generation options. This follows the proven child_spec/1 pattern from Elixir's standard library.

The spec map structure:

%{
  command: module(),                    # The command module
  execution: :sync | :probe | :async,   # Execution mode
  settle: %{                            # Settle config (for probe/async)
    timeout_ms: pos_integer(),
    interval_ms: pos_integer(),
    backoff: :linear | :exponential
  },
  shrink: :prefer_remove | :neutral | :prefer_keep,  # Shrinking priority
  when: (state -> boolean),             # Precondition
  with: (state -> map) | map,           # Generator overrides
  weight: pos_integer()                 # Generation weight
}

Using PropertyDamage.Command

The use macro provides a default command_spec/1 implementation:

defmodule MyTest.Commands.CreateOrder do
  use PropertyDamage.Command

  defstruct [:amount, :currency]

  @impl true
  def generator(overrides \\ %{}) do
    %{amount: StreamData.positive_integer(), currency: StreamData.constant("USD")}
    |> PropertyDamage.Generator.merge_overrides(overrides)
    |> StreamData.fixed_map()
  end
end

Commands can customize defaults via use options:

defmodule MyTest.Commands.GetOrder do
  use PropertyDamage.Command,
    execution: :probe,
    shrink: :prefer_remove,
    settle: %{timeout_ms: 5_000, interval_ms: 200, backoff: :exponential}

  defstruct [:order_ref]

  @impl true
  def generator(overrides \\ %{}), do: # ...
end

Or override command_spec/1 entirely for dynamic specs:

def command_spec(overrides \\ []) do
  defaults = PropertyDamage.Command.framework_defaults()
  Map.merge(defaults, %{command: __MODULE__, execution: :probe})
  |> Map.merge(Map.new(overrides))
end

Pure Generator Architecture

Commands define a pure generator/1 function that produces field maps. The generator takes an overrides map and returns a StreamData generator of maps. The framework wraps the result in the command struct automatically.

State-dependent concerns (preconditions, ref selection, expected events) are defined in the Model, not the Command. This separation enables command reuse across different Models with different state shapes.

Example

defmodule MyTest.Commands.CreateOrder do
  @behaviour PropertyDamage.Command
  import PropertyDamage.Generator, only: [merge_overrides: 2]

  defstruct [:amount, :currency]

  @impl true
  def generator(overrides \\ %{}) do
    %{
      amount: StreamData.positive_integer(),
      currency: StreamData.member_of(["USD", "EUR"])
    }
    |> merge_overrides(overrides)
    |> StreamData.fixed_map()
  end
end

The Model then wires this command with state-dependent configuration:

defmodule MyTest.OrderModel do
  def commands do
    [
      CreateOrder,  # Always enabled, weight 1
      {ViewOrder,
        when: fn s -> map_size(s.orders) > 0 end,
        with: fn s -> %{order_ref: StreamData.member_of(Map.keys(s.orders))} end}
    ]
  end

  def simulate(%CreateOrder{amount: amount}, _state) do
    [%OrderCreated{amount: amount, order_ref: nil}]
  end

  def simulate(%ViewOrder{order_ref: ref}, state) do
    if Map.has_key?(state.orders, ref) do
      [%OrderViewed{order_ref: ref}]
    else
      [%OrderNotFound{order_ref: ref}]
    end
  end
end

Model Integration

Models can specify commands in three forms, all of which result in a command spec:

def commands do
  [
    # Module only - uses command's command_spec/1 with empty overrides
    CreateOrder,

    # {Module, opts} - opts passed to command_spec/1
    {ViewOrder, weight: 2, shrink: :prefer_keep},

    # Map form - merged with resolved spec
    %{command: CancelOrder, weight: 1, when: &has_orders?/1}
  ]
end

Migration from Legacy Callbacks

The command_spec/1 pattern consolidates multiple callbacks:

Legacy callbacks continue to work - the framework falls back to them when command_spec/1 is not implemented.

Design Principles

• Reusability: Commands are pure semantic definitions, decoupled from state shape. Model-specific configuration (weights, preconditions, overrides) is declared in the Model, not the Command.

• Composability: The generator/1 function enables composition. A specialized command can call another command's generator and extend it.

• Separation of Concerns: Commands define WHAT operations exist and their fields. Models define WHEN to use them and HOW to parameterize them. Adapters define HOW to execute them against the SUT.

Optional Metadata Callbacks

Commands can implement optional callbacks to provide metadata used by the framework for shrinking, validation, and debugging:

• downstream_observables/0 - Event modules this command can produce
• read_only?/0 - Whether command only reads state (prioritized for removal during shrinking)
• label/2 - Human-readable label for debugging

The framework reads these via function_exported?/3, using sensible defaults when not implemented.