Hammox Documentation

Instead of manually calling Hammox.protect/3 to generate protected anonymous functions, you can use the Hammox.Protect module within your test modules. This macro-based approach automatically defines functions in your test module that correspond to the functions in the target module, but with the added benefit of being protected by Hammox.

This is similar to import-ing the module you are testing, but the resulting functions are protected versions that enforce contract testing.

Configuration Options

When calling use Hammox.Protect, you can provide the following options:

• :module (required): The module you want to protect (typically the module under test).
• :behaviour: The behaviour module you want to protect the implementation module with. If :module and :behaviour are the same, this can be omitted.
• :funs: An optional list of specific functions to protect for the preceding :behaviour.

Handling Multiple Behaviours

You can provide multiple :behaviour and :funs options to protect modules that implement multiple behaviours. Note that :funs is specific to the :behaviour that immediately precedes it.

• If you provide a :behaviour without a following :funs option, all callbacks defined in that behaviour will be protected.
• If you provide only the :module option, all callbacks from the module's own behaviour (if any) will be protected.

use Hammox.Protect,
  module: Hammox.Test.MultiBehaviourImplementation,
  behaviour: Hammox.Test.SmallBehaviour,
  # the `funs` opt below effects the funs protected from `SmallBehaviour`
  funs: [foo: 0, other_foo: 1],
  behaviour: Hammox.Test.AdditionalBehaviour
  # with no `funs` pt provided after `AdditionalBehaviour`, all callbacks
  # will be protected

To use Hammox telemetry for performance tracing (e.g., with Spandex), implement a handle_event/4 function. You can capture start events to begin a span, stop events to finish it, and exception events to record errors in the trace.

Note that [:hammox, :expect, :start] provides metadata like :mock and :function_name, while measurements typically contains timing information like :system_time or :duration.

defmodule HammoxTelemetryHandler do
  alias Spandex.Tracer

  def handle_event([:hammox, :expect, :start], measurements, metadata, _config) do
    when is_map(measurements)
    mock_name = Map.get(metadata, :mock)
    func_name = Map.get(metadata, :name)
    expect_count = Map.get(metadata, :count) |> to_string()

    tags = 
      []
      |> tags_put(:mock, mock_name)
      |> tags_put(:func_name, func_name)
      |> tags_put(:expect_count, expect_count)

    system_time = get_time(measurements, :system_time)

    if Tracer.current_trace_id() do
      span_string = "#{mock_name}.#{func_name}" |> String.trim_leading("Elixir.")
      span_string = "expect #{span_string}"
      _span_context = Tracer.start_span(span_string, service: :hammox, tags: tags)
      Tracer.update_span(start: system_time)
    end
  end

  def handle_event([:hammox, :expect, :stop], measurements, _metadata, _config) do
    handle_exception(measurements)
  end

  def handle_event([:hammox, :expect, :exception], measurements, _metadata, _config) do
    handle_exception(measurements)
  end

  defp handle_exception(measurements) do
    error_message = "Exception occurred during hammox execution"
    Logger.error(error_message)

    if Tracer.current_trace_id() do
      current_span = Tracer.current_span([])
      Tracer.update_span_with_error(error_message, current_span)
    end

    handle_stop(measurements)
  end

  defp handle_stop(measurements, tags \ []) do
    duration_time = get_time(measurements, :duration)

    case Tracer.current_span([]) do
      %{start: start_time} ->
        completion_time = start_time + duration_time
        Tracer.update_span(tags: tags, completion_time: completion_time)
        Tracer.finish_span()

      _no_current_span ->
        :ok
    end
  end

  defp get_time(log_entry, key) do
    Map.get(log_entry, key)
  end
end

You can attach handlers for all supported Hammox events using :telemetry.attach_many/4. The following pattern demonstrates how to generate event lists for start, stop, and exception phases and attach them to a handler function.

def build_events(event_atom) do
  event_list = [
    :expect,
    :allow,
    :run_expect,
    :check_call,
    :match_args,
    :match_return_value,
    :fetch_typespecs,
    :cache_put,
    :stub,
    :verify_on_exit!,
    :deny
  ]

  Enum.map(event_list, fn event ->
    [:hammox, event, event_atom]
  end)
end

# In your application startup:
start_events = build_events(:start)
:ok = :telemetry.attach_many("hammox-start", start_events, &handle_event/4, nil)

stop_events = build_events(:stop)
:ok = :telemetry.attach_many("hammox-stop", stop_events, &handle_event/4, nil)

exception_events = build_events(:exception)
:ok = :telemetry.attach_many("hammox-exception", exception_events, &handle_event/4, nil)