Mox is a library for defining concurrent mocks in Elixir.

The library follows the principles outlined in "Mocks and explicit contracts", summarized below:

1. No ad-hoc mocks. You can only create mocks based on behaviours

2. No dynamic generation of modules during tests. Mocks are preferably defined in your test_helper.exs or in a setup_all block and not per test

3. Concurrency support. Tests using the same mock can still use async: true

4. Rely on pattern matching and function clauses for asserting on the input instead of complex expectation rules

Example

Imagine that you have an app that has to display the weather. At first, you use an external API to give you the data given a lat/long pair:

defmodule MyApp.HumanizedWeather do
  def display_temp({lat, long}) do
    {:ok, temp} = MyApp.WeatherAPI.temp({lat, long})
    "Current temperature is #{temp} degrees"
  end

  def display_humidity({lat, long}) do
    {:ok, humidity} = MyApp.WeatherAPI.humidity({lat, long})
    "Current humidity is #{humidity}%"
  end
end

However, you want to test the code above without performing external API calls. How to do so?

First, it is important to define the WeatherAPI behaviour that we want to mock. And we will define a proxy function that will dispatch to the desired implementation:

defmodule MyApp.WeatherAPI do
  @callback temp(MyApp.LatLong.t()) :: {:ok, integer()}
  @callback humidity(MyApp.LatLong.t()) :: {:ok, integer()}

  def temp(lat_long), do: impl().temp(lat_long)
  def humidity(lat_long), do: impl().humidity(lat_long)
  defp impl, do: Application.get_env(:my_app, :weather, MyApp.ExternalWeatherAPI)
end

By default, we will dispatch to MyApp.ExternalWeatherAPI, which now contains the external API implementation.

If you want to mock the WeatherAPI behaviour during tests, the first step is to define the mock with defmock/2, usually in your test_helper.exs, and configure your application to use it:

Mox.defmock(MyApp.MockWeatherAPI, for: MyApp.WeatherAPI)
Application.put_env(:my_app, :weather, MyApp.MockWeatherAPI)

Now in your tests, you can define expectations with expect/4 and verify them via verify_on_exit!/1:

defmodule MyApp.HumanizedWeatherTest do
  use ExUnit.Case, async: true

  import Mox

  # Make sure mocks are verified when the test exits
  setup :verify_on_exit!

  test "gets and formats temperature and humidity" do
    MyApp.MockWeatherAPI
    |> expect(:temp, fn {_lat, _long} -> {:ok, 30} end)
    |> expect(:humidity, fn {_lat, _long} -> {:ok, 60} end)

    assert MyApp.HumanizedWeather.display_temp({50.06, 19.94}) ==
             "Current temperature is 30 degrees"

    assert MyApp.HumanizedWeather.display_humidity({50.06, 19.94}) ==
             "Current humidity is 60%"
  end
end

All expectations are defined based on the current process. This means multiple tests using the same mock can still run concurrently unless the Mox is set to global mode. See the "Multi-process collaboration" section.

One last note, if the mock is used throughout the test suite, you might want the implementation to fall back to a stub (or actual) implementation when no expectations are defined. You can use stub_with/2 in a case template that is used throughout your test suite:

defmodule MyApp.Case do
  use ExUnit.CaseTemplate

  setup _ do
    Mox.stub_with(MyApp.MockWeatherAPI, MyApp.StubWeatherAPI)
    :ok
  end
end

Now, for every test case that uses ExUnit.Case, it can use MyApp.Case instead. Then, if no expectations are defined it will call the implementation in MyApp.StubWeatherAPI.

Multiple behaviours

Mox supports defining mocks for multiple behaviours.

Suppose your library also defines a behaviour for getting past weather:

defmodule MyApp.PastWeather do
  @callback past_temp(MyApp.LatLong.t(), DateTime.t()) :: {:ok, integer()}
end

You can mock both the weather and past weather behaviour:

Mox.defmock(MyApp.MockWeatherAPI, for: [MyApp.Weather, MyApp.PastWeather])

Compile-time requirements

If the mock needs to be available during the project compilation, for instance because you get undefined function warnings, then instead of defining the mock in your test_helper.exs, you should instead define it under test/support/mocks.ex:

Mox.defmock(MyApp.MockWeatherAPI, for: MyApp.WeatherAPI)

Then you need to make sure that files in test/support get compiled with the rest of the project. Edit your mix.exs file to add the test/support directory to compilation paths:

def project do
  [
    ...
    elixirc_paths: elixirc_paths(Mix.env),
    ...
  ]
end

defp elixirc_paths(:test), do: ["test/support", "lib"]
defp elixirc_paths(_),     do: ["lib"]

Multi-process collaboration

Mox supports multi-process collaboration via two mechanisms:

1. explicit allowances
2. global mode

The allowance mechanism can still run tests concurrently while the global one doesn't. We explore both next.

Explicit allowances

An allowance permits a child process to use the expectations and stubs defined in the parent process while still being safe for async tests.

test "invokes add and mult from a task" do
  MyApp.MockWeatherAPI
  |> expect(:temp, fn _loc -> {:ok, 30} end)
  |> expect(:humidity, fn _loc -> {:ok, 60} end)

  parent_pid = self()

  Task.async(fn ->
    MyApp.MockWeatherAPI |> allow(parent_pid, self())

    assert MyApp.HumanizedWeather.display_temp({50.06, 19.94}) ==
             "Current temperature is 30 degrees"

    assert MyApp.HumanizedWeather.display_humidity({50.06, 19.94}) ==
             "Current humidity is 60%"
  end)
  |> Task.await
end

Note: if you're running on Elixir 1.8.0 or greater and your concurrency comes from a Task then you don't need to add explicit allowances. Instead $callers is used to determine the process that actually defined the expectations.

Explicit allowances as lazy/deferred functions

Under some circumstances, the process might not have been already started when the allowance happens. In such a case, you might specify the allowance as a function in the form (-> pid()). This function would be resolved late, at the very moment of dispatch. If the function does not return an existing PID, Mox will raise a Mox.UnexpectedCallError exception.

Global mode

Mox supports global mode, where any process can consume mocks and stubs defined in your tests. set_mox_from_context/0 automatically calls set_mox_global/1 but only if the test context doesn't include async: true.

By default the mode is :private.

setup :set_mox_from_context
setup :verify_on_exit!

test "invokes add and mult from a task" do
  MyApp.MockWeatherAPI
  |> expect(:temp, fn _loc -> {:ok, 30} end)
  |> expect(:humidity, fn _loc -> {:ok, 60} end)

  Task.async(fn ->
    assert MyApp.HumanizedWeather.display_temp({50.06, 19.94}) ==
              "Current temperature is 30 degrees"

    assert MyApp.HumanizedWeather.display_humidity({50.06, 19.94}) ==
              "Current humidity is 60%"
  end)
  |> Task.await
end

Blocking on expectations

If your mock is called in a different process than the test process, in some cases there is a chance that the test will finish executing before it has a chance to call the mock and meet the expectations. Imagine this:

test "calling a mock from a different process" do
  expect(MyApp.MockWeatherAPI, :temp, fn _loc -> {:ok, 30} end)

  spawn(fn -> MyApp.HumanizedWeather.temp({50.06, 19.94}) end)

  verify!()
end

The test above has a race condition because there is a chance that the verify!/0 call will happen before the spawned process calls the mock. In most cases, you don't control the spawning of the process so you can't simply monitor the process to know when it dies in order to avoid this race condition. In those cases, the way to go is to "sync up" with the process that calls the mock by sending a message to the test process from the expectation and using that to know when the expectation has been called.

test "calling a mock from a different process" do
  parent = self()
  ref = make_ref()

  expect(MyApp.MockWeatherAPI, :temp, fn _loc ->
    send(parent, {ref, :temp})
    {:ok, 30}
  end)

  spawn(fn -> MyApp.HumanizedWeather.temp({50.06, 19.94}) end)

  assert_receive {^ref, :temp}

  verify!()
end

This way, we'll wait until the expectation is called before calling verify!/0.