Mox Documentation

Mox follows a specific pattern to enable concurrent, behaviour-based mocking:

1. Define a Behaviour: Create a module that defines the contract (the functions and their signatures) using @callback.
2. Provide an Implementation: Create a real module that implements that behaviour for production use.
3. Implement a Switch: In your application code, do not call the implementation directly. Instead, fetch the implementation module from an application configuration (e.g., Application.get_env/2). This allows you to swap the real implementation for a mock during tests.
4. Define the Mock: In your test_helper.exs, use Mox.defmock/2 to create a mock module based on your behaviour, and then update your application configuration to point to this new mock module.
5. Use expect/3 in Tests: In your test files, use expect/3 to define how the mock should respond to specific arguments and to assert that the correct arguments were received.

Mox is designed for concurrent testing. It uses a concept of ownership to manage expectations.

Private Mode & Async Tests

In private mode, expectations are owned by the process that defines them. Because of this, you can run many tests in parallel using the same mock module without interference. If a child process needs to call the mock, you must use Mox.allow/3 to grant it access to the owner's expectations.

Global Mode

In global mode, the mock is shared across all processes. This simplifies testing when many different processes need to interact with the same mock, but it forces you to run tests sequentially (no async: true).

Avoiding Race Conditions

When calling a mock from a different process (e.g., via spawn), the test process might call verify!/1 before the spawned process actually executes the mock call. To prevent this, "sync up" with the process by sending a message from the mock's expectation back to the test process:

# Syncing with a spawned process
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)

  # Wait for the mock to actually be called before verifying
  assert_receive {^ref, :temp}

  verify!()
end

Use Mox.expect/4 to define how many times a specific function in a mock should be called and what it should return.

Behavior:

• If you call expect/4 multiple times for the same function/arity, you can define different behaviors for each successive call (e.g., failing twice then succeeding once).
• Calling expect/4 for a function/arity will remove any previously defined stub/3 for that same function/arity.
• If n is 0, it acts as a denial (ensuring the function is not called).

# Expect :get_temp/1 to be called once
expect(MockWeatherAPI, :get_temp, fn _ -> {:ok, 30} end)

# Expect :get_temp/1 to be called exactly five times
expect(MockWeatherAPI, :get_temp, 5, fn _ -> {:ok, 30} end)

# Expect :get_temp/1 to be called zero times
expect(MockWeatherAPI, :get_temp, 0, fn _ -> {:ok, 30} end)

# Sequence of calls: fail twice, then succeed once
MockWeatherAPI
  |> expect(:get_temp, 2, fn _loc -> {:error, :unreachable} end)
  |> expect(:get_temp, 1, fn _loc -> {:ok, 30} end)