Ersatz is a library for defining mocks in Elixir.

• Mocks are generated based on behaviours during configuration and injected using env variables.
• Add the mock behaviour by specifying functions to be used during tests with Ersatz.set_mock_implementation/3 or Ersatz.set_mock_return_value/3.
• Test your code's actions on the mock dependency using Ersatz.get_mock_calls/1 or the Espec custom matchers.

Example

As an example, imagine that your library defines a calculator behaviour:

defmodule MyApp.Calculator do
  @callback add(integer(), integer()) :: integer()
  @callback mult(integer(), integer()) :: integer()
end

If you want to mock the calculator behaviour during tests, the first step is to define the mock, usually in your test_helper.exs:

Ersatz.defmock(MyApp.CalcMock, for: MyApp.Calculator)

Now in your tests, you can define mock implementations and verify that they were called the right number of times and with the right parameters:

use ExUnit.Case, async: true

import Ersatz

test "invokes add and mult" do
  # Arrange
  Ersatz.set_mock_implementation(&MyApp.CalcMock.add/2, fn x, y -> x + y end)
  Ersatz.set_mock_return_value(&MyApp.CalcMock.mult/2, 42)

  # Act
  add_result = MyApp.CalcMock.add(2, 3)
  mult_result = MyApp.CalcMock.mult(4, 1)

  # Assert
  assert add_result == 5 # assert the result is the one we expected
  assert mult_result == 42 # assert the result is the one we expected

  add_mock_calls = Ersatz.get_mock_calls(&MyApp.CalcMock.add/2) # get the calls our mock implementation received
  assert add_mock_calls == [[2, 3]] # assert the call args are the ones we expected
  mult_mock_calls = Ersatz.get_mock_calls(&MyApp.CalcMock.mult/2) # get the calls our mock implementation received
  assert mult_mock_calls == [[4, 1]] # assert the call args are the ones we expected
end

In practice, you will have to pass the mock to the system under the test. If the system under test relies on application configuration, you should also set it before the tests starts to keep the async property. Usually in your config files:

config :my_app, :calculator, MyApp.CalcMock

Or in your test_helper.exs:

Application.put_env(:my_app, :calculator, MyApp.CalcMock)

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

Multiple behaviours

Ersatz supports defining mocks for multiple behaviours.

Suppose your library also defines a scientific calculator behaviour:

defmodule MyApp.ScientificCalculator do
  @callback exponent(integer(), integer()) :: integer()
end

You can mock both the calculator and scientific calculator behaviour:

Ersatz.defmock(MyApp.SciCalcMock, for: [MyApp.Calculator, MyApp.ScientificCalculator])

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:

Ersatz.defmock(MyApp.CalcMock, for: MyApp.Calculator)

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

Ersatz 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
  Ersatz.set_mock_implementation(&MyApp.CalcMock.add/2, fn x, y -> x + y end)
  Ersatz.set_mock_return_value(&MyApp.CalcMock.mult/2, 42)

  parent_pid = self()

  Task.async(fn ->
    MyApp.CalcMock |> allow(parent_pid, self())
    assert MyApp.CalcMock.add(2, 3) == 5
    assert MyApp.CalcMock.mult(2, 3) == 6
  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.

Global mode

Ersatz supports global mode, where any process can consume mocks and stubs defined in your tests. To manually switch to global mode use:

set_ersatz_global()

test "invokes add and mult from a task" do
  Ersatz.set_mock_implementation(&MyApp.CalcMock.add/2, fn x, y -> x + y end)
  Ersatz.set_mock_return_value(&MyApp.CalcMock.mult/2, 42)

  Task.async(fn ->
    assert MyApp.CalcMock.add(2, 3) == 5
    assert MyApp.CalcMock.mult(2, 3) == 42
  end)
  |> Task.await
end

The global mode must always be explicitly set per test. By default mocks run on private mode.

You can also automatically choose global or private mode depending on if your tests run in async mode or not. In such case Ersatz will use private mode when async: true, global mode otherwise:

setup :set_ersatz_from_context