Behaviour for adapters that execute commands against the System Under Test.

Adapters are the bridge between the test framework and the actual SUT. They translate command structs into real operations (HTTP calls, function calls, message sends, etc.) and return the resulting events.

Lifecycle

During each test run (including shrink attempts), the adapter lifecycle is:

1. setup/1 - Establish connections, create clients
2. execute/2 × N - Execute each command in the sequence
3. teardown/1 - Cleanup connections

The full lifecycle with model hooks:

Property test run
├── Model.setup_once()           # Once at start
│
├── Run 1
│   ├── Model.setup_each()       # Reset SUT state
│   ├── Adapter.setup()          # Establish connections
│   ├── Adapter.execute() × N    # Execute each command
│   └── Adapter.teardown()       # Cleanup connections
│
├── Run 2 ... Run N              # Same as above
│
├── [On failure] Shrinking
│   ├── Shrink attempt 1
│   │   ├── Model.setup_each()
│   │   ├── Adapter.setup()
│   │   ├── Adapter.execute() × M
│   │   └── Adapter.teardown()
│   └── ...
│
└── Model.teardown_once()        # Once at end

Example

defmodule MyTest.APIAdapter do
  use PropertyDamage.Adapter

  @impl true
  def setup(config) do
    {:ok, client} = HTTPClient.start(base_url: config[:api_url])
    {:ok, %{client: client}}
  end

  @impl true
  def teardown(%{client: client}) do
    HTTPClient.stop(client)
    :ok
  end

  @impl true
  def execute(%CreateOrder{amount: amt}, %{client: client}) do
    case HTTPClient.post(client, "/orders", %{amount: amt}) do
      {:ok, %{status: 201, body: body}} ->
        {:ok, [%OrderCreated{order_id: body["id"], amount: amt}]}
      {:ok, %{status: 400}} ->
        {:ok, [%OrderRejected{reason: :invalid}]}
      {:error, reason} ->
        {:error, reason}
    end
  end
end

Delegation

For complex adapters, use delegate_execution/1 to route commands to sub-adapter modules:

defmodule MyTest.MainAdapter do
  use PropertyDamage.Adapter

  delegate_execution for: [CreateOrder, ViewOrder], to: OrdersSubAdapter
  delegate_execution for: [CreatePayment], to: PaymentsSubAdapter

  @impl true
  def setup(config), do: {:ok, config}

  @impl true
  def teardown(_context), do: :ok
end

Stutter/Idempotency Testing

When stutter testing is enabled, the framework may execute commands multiple times to verify idempotent behavior. During retry executions, the adapter context includes a :stutter key with information the adapter can use:

%{
  stutter: %{
    attempt: 2,           # Current attempt (2, 3, etc. for retries)
    is_retry: true,       # Always true for retry executions
    idempotency_key: "abc123"  # From Command.idempotency_key/1, or nil
  }
}

Adapters can use this to include idempotency keys in HTTP headers:

def execute(%CreateOrder{} = cmd, context) do
  headers = build_headers(context)
  # headers will include "Idempotency-Key" if stutter context present
  HTTPClient.post(context.client, "/orders", body, headers)
end

defp build_headers(%{stutter: %{idempotency_key: key}}) when is_binary(key) do
  [{"Idempotency-Key", key}]
end
defp build_headers(_context), do: []

The first execution (attempt 1) does NOT include stutter context, only retries do. This allows the adapter to behave normally for the initial execution.

Mid-Execution Event Injection

For commands with :async semantics that poll for completion, you may want to emit events as they happen rather than batching all events at the end. The adapter context includes an :inject function for this purpose:

%{
  inject: #Function<...>  # Call with event to inject it immediately
}

Use this to emit events at the correct time in the execution timeline:

def execute(%CreateAuthorization{} = cmd, ctx) do
  # Step 1: Create the authorization (T=0)
  {:ok, %{body: %{"id" => id, "status" => "processing"}}} =
    Req.post(ctx.client, url: "/authorizations", json: payload)

  # Inject immediately - projections update NOW at T=0
  ctx.inject.(%AuthorizationCreated{authorization_id: id})

  # Step 2: Poll until settled (T=5000)
  case poll_until_settled(ctx.client, id) do
    :approved ->
      # Return settlement event - recorded at T=5000
      {:ok, [%AuthorizationApproved{authorization_id: id}]}

    :declined ->
      {:ok, [%AuthorizationDeclined{authorization_id: id}]}
  end
end

Key behaviors:

• Injected events update projections immediately
• Injected events are recorded in the event log with source :injected
• For events with external() fields, values are captured from the first injected event
• Adapters that don't use inject continue to work unchanged

This is particularly useful when your model needs to track intermediate states, or when assertions depend on events appearing at the correct point in time.

Execute Context

The context map passed to execute/2 contains:

The :stutter map (when present) contains: