Behaviour for adapters that receive and inject external events.

Adapter.Injector modules handle asynchronous event sources like webhooks, callbacks, message queues, or any external system that pushes events into the test. They transform incoming payloads into domain events and push them to the shared EventQueue for processing.

Direction of Event Flow

Unlike Adapter (which executes commands → produces events), Adapter.Injector receives external events → transforms → pushes to EventQueue:

External System → Adapter.Injector.to_event/1 → EventQueue → Executor

Lifecycle

Adapter.Injector modules follow a similar lifecycle to Adapters:

1. setup/1 - Start listening (webhooks, subscriptions, etc.)
2. External events arrive → to_event/1 → EventQueue.push/3
3. teardown/1 - Stop listening, cleanup

The @emits Attribute

Declare which events this adapter can emit for validation:

@emits [PaymentConfirmed, PaymentDeclined]

The framework uses this for:

• Validating that Model.injectable_events/0 covers all possible injected events
• Detecting orphan events that no assertion projection handles

Example

defmodule MyTest.PaymentWebhookAdapter do
  use PropertyDamage.Adapter.Injector

  @emits [PaymentConfirmed, PaymentDeclined]

  @impl true
  def setup(config) do
    {:ok, server} = MockWebhookServer.start_link(
      port: config[:port],
      handler: &handle_webhook(&1, config.event_queue)
    )
    {:ok, %{server: server}}
  end

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

  @impl true
  def to_event(%{"type" => "payment.success", "order_id" => id}) do
    {:ok, %PaymentConfirmed{order_id: id}}
  end

  def to_event(%{"type" => "payment.failed", "order_id" => id, "reason" => r}) do
    {:ok, %PaymentDeclined{order_id: id, reason: r}}
  end

  def to_event(_unknown), do: :skip

  defp handle_webhook(payload, queue) do
    case to_event(payload) do
      {:ok, event} -> EventQueue.push(queue, __MODULE__, event)
      :skip -> :ok
    end
  end
end

Optional Responses

Some systems expect responses to webhooks. Implement respond/2 to generate:

@impl true
def respond(%PaymentConfirmed{}, _context) do
  {:ok, %{status: 200, body: ~s({"ack": true})}}
end