Edit: Part of this tutorial made it to the Mox project part of this tutorial made it to the Mox project as an example of basic usage. Great stuff!

Let's take a look at setting up Mox to help defining contracts within an Elixir application. Below are simplified `git diff`s from an example application I created to demonstrate Mox from first principles. You can find the link to it below. Each of the diffs is a commit in the repo.

# mix.exs
   defp deps do
     [
+      {:mox, "~> 1.0", only: :test}
     ]
   end

# lib/weather_behaviour.ex
defmodule WeatherBehaviour do
  @callback get_weather(binary()) :: {:ok, map()} | {:error, binary()}
end

# lib/weather_impl.ex
defmodule WeatherImpl do
  @moduledoc """
  An implementation of a WeatherBehaviour
  """

  @behaviour WeatherBehaviour

  @impl WeatherBehaviour
  def get_weather(city) when is_binary(city) do
    # Here you could call an external api directly with an HTTP client or use
    # a third party library that does that work for you. In this example we send a
    # request using a `httpc` to get back some html, which we can process later.

    :inets.start()
    :ssl.start()

    case :httpc.request(:get, {"https://www.google.com/search?q=weather+#{city}", []}, [], []) do
      {:ok, {_, _, html_content}} -> {:ok, %{body: html_content}}
      error -> {:error, "Error getting weather: #{inspect(error)}"}
    end
  end
end
```

# bound.ex, the main context we chose to call this function from
defmodule Bound do
  def get_weather(city) do
    weather_impl().get_weather(city)
  end

  defp weather_impl() do
    Application.get_env(:bound, :weather, WeatherImpl)
  end
end

# in test/test_helper.exs
+Mox.defmock(WeatherBehaviourMock, for: WeatherBehaviour)
+Application.put_env(:bound, :weather, WeatherBehaviourMock)
 ExUnit.start()

# test/bound_test.exs
defmodule BoundTest do
  use ExUnit.Case

  import Mox

  setup :verify_on_exit!

  describe "get_weather/1" do
    test "fetches weather based on a location" do
      expect(WeatherBehaviourMock, :get_weather, fn args ->
        # here we can assert on the arguments that get passed to the function
        assert args == "Chicago"

        # here we decide what the mock returns
        {:ok, %{body: "Some html with weather data"}}
      end)

      assert {:ok, _} = Bound.get_weather("Chicago")
    end
  end
end

And there we go, we have implemented Mox in an Elixir project!

Mox helps setting clear boundaries and contracts not only with third party apis/libraries/resources but also code from other teams or contexts in a large application. It has been extremely useful in my career while working with Elixir. I highly suggest using it above other alternatives.

Usually, we call to third party APIs (or anything that crosses a boundary/contract) to get some data so we can then do something else with it. In this simple example, we added a function to a higher level abstraction to interact with the implementation. It's pretty silly, but it demonstrates how Mox can verify the arguments that are passed to that function and assert that the mock is called in the execution. Let's explore something that would resemble a feature we would see in a production application:

# Example A
defmodule DailyUserEmail do
  require Logger

  def send_emails(users) do
    Logger.info("Started to send daily emails")

    result = Enum.reduce(users, %{success_count: 0, error_count: 0}, fn user ->
      with {:ok, %{city: city}} <- Accounts.get_user_city(user),
           {:ok, weather_details} <- weather_impl().get_weather(city),
           {:ok, _} <- email_client_impl().send_email(%{user: user, template: :daily, weather_details: weather_details}) do
        Logger.info("Successfully sent daily email to user_id #{user.id}")
        %{acc | success_count: acc.success_count + 1}
      else
        error ->
          Logger.error("Unable to send email to user_id #{user.id}, error: #{inspect(error)}")
          %{acc | error_count: acc.error_count + 1}
      end
    end)

    Logger.info("Finished sending daily emails, result: #{inspect(result)}")
    result
  end

  defp weather_impl() do
    Application.get_env(:bound, :weather, WeatherImpl)
  end

  defp email_client_impl() do
    Application.get_env(:bound, :email, MailGunImpl)
  end
end

Both the implementations above could be mocked in our unit tests.

Here is the code for the example app I created, feel free to look at the commits. Here is the Mox documentation and a Mox lesson in Elixir School.