Behaviour for mock services that simulate third-party APIs.

MockServiceAdapters intercept calls from the SUT to external services and return controlled responses. They can also inject events into the test framework based on those interactions.

The Problem

When testing a system that depends on external services (payment gateways, email providers, etc.), you need to control what those services return. MockServiceAdapter provides this capability:

┌─────────┐       ┌─────────┐       ┌───────────────────┐
│  Test   │──────▶│   SUT   │──────▶│ MockServiceAdapter│
│Framework│◀──────│         │◀──────│  (controlled)     │
└─────────┘       └─────────┘       └───────────────────┘
     │                                      │
     │◀─────────── injected events ─────────┘

Key Concepts

Stateful Mock Behavior

Mocks maintain state that evolves with the test. Commands can configure mock behavior, and the mock can react to events:

defmodule PaymentGatewayMock do
  use PropertyDamage.MockServiceAdapter

  @impl true
  def init_state, do: %{behavior: :success}

  @impl true
  def on_command(%ConfigurePayment{behavior: b}, state) do
    %{state | behavior: b}
  end

  @impl true
  def handle_request(%{path: "/charge"}, state) do
    case state.behavior do
      :success -> {:ok, %{status: 200, body: %{id: "txn_123"}}}
      :decline -> {:ok, %{status: 402, body: %{error: "declined"}}}
    end
  end
end

Event Injection

When the SUT calls the mock, you can inject events into the test:

def handle_request(%{path: "/charge", body: body}, state) do
  response = %{status: 200, body: %{transaction_id: "txn_123"}}

  # These events are applied to projections
  events = [%PaymentProcessed{amount: body["amount"]}]

  {:ok, response, events}
end

Projection Awareness

Mock handlers receive projection state, enabling realistic responses:

def handle_request(%{path: "/balance"}, state) do
  balance = get_in(state.projections, [ModelState, :accounts, id, :balance])
  {:ok, %{status: 200, body: %{balance: balance}}}
end

Example

defmodule MyTest.PaymentMock do
  use PropertyDamage.MockServiceAdapter

  @emits [PaymentAuthorized, PaymentDeclined]

  @impl true
  def setup(config) do
    {:ok, pid} = MockServer.start_link(port: 4445, handler: __MODULE__)
    {:ok, %{server: pid}}
  end

  @impl true
  def teardown(%{server: pid}) do
    MockServer.stop(pid)
    :ok
  end

  @impl true
  def init_state do
    %{behavior: :success, decline_reason: nil}
  end

  @impl true
  def on_command(%ConfigurePayment{behavior: b, reason: r}, state) do
    %{state | behavior: b, decline_reason: r}
  end

  @impl true
  def on_command(_other, state), do: state

  @impl true
  def on_event(_event, state), do: state

  @impl true
  def handle_request(%{path: "/authorize", body: body}, state) do
    case state.behavior do
      :success ->
        resp = %{status: 200, body: %{auth_code: "AUTH123"}}
        events = [%PaymentAuthorized{amount: body["amount"]}]
        {:ok, resp, events}

      :decline ->
        resp = %{status: 402, body: %{error: state.decline_reason}}
        events = [%PaymentDeclined{reason: state.decline_reason}]
        {:ok, resp, events}
    end
  end

  @impl true
  def handle_request(_request, _state) do
    {:ok, %{status: 404, body: %{error: "not_found"}}}
  end
end

Configuration Commands

Define commands that configure mock behavior. These commands are executed against the SUT like normal commands, but the on_command/2 callback allows mock adapters to react and update their behavior:

defmodule ConfigurePayment do
  @behaviour PropertyDamage.Command

  defstruct [:behavior, :reason]

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

  @impl true
  def new!(state, overrides \\ %{}) do
    StreamData.fixed_map(%{
      behavior: StreamData.member_of([:success, :decline]),
      reason: StreamData.member_of([nil, "insufficient_funds"])
    })
    |> StreamData.map(&struct!(__MODULE__, &1))
  end
end

The mock adapter's on_command/2 callback receives all commands, allowing it to react to configuration commands and update its internal state.