Mockery (Mockery v2.5.0)

View Source

Provides core mocking functionality for Elixir tests.

This module offers tools to create and manage mocks within the context of individual test processes. Mocks created here are isolated and will not affect other processes, making them safe for concurrent and asynchronous testing.

Using Mockery in your tests

By adding use Mockery in your test modules, you automatically import several useful modules and functions:

Example usage:

defmodule MyApp.User do
  def greet, do: "Hello, User!"
end

defmodule MyApp.Greeter do
  use Mockery.Macro

  def greet_user do
    mockable(MyApp.User).greet()
  end
end

defmodule MyApp.GreeterTest do
  use ExUnit.Case, async: true
  use Mockery

  test "mock greet/0 from MyApp.User" do
    mock(MyApp.User, [greet: 0], "Hello, Mocked User!")

    assert MyApp.Greeter.greet_user() == "Hello, Mocked User!"
    assert_called! MyApp.User, :greet, args: [], times: 1
  end
end

Summary

Types

A dynamic mock function.

Function name (an atom identifying the function).

A static mock return value

Functions

Function used to create mock in context of single test process.

Types

dynamic_mock()

@type dynamic_mock() :: fun()

A dynamic mock function.

This is a function invoked when the mocked function is called. The dynamic mock must accept the same arity as the original function being mocked and its return value is used as the mock result.

function_name()

@type function_name() :: atom()

Function name (an atom identifying the function).

static_mock_value()

@type static_mock_value() :: term()

A static mock return value

Any Elixir term except functions.

Functions

mock(mod, fun, value \\ :mocked)

@spec mock(module(), function_name(), static_mock_value()) :: module()
@spec mock(module(), [{function_name(), arity()}], static_mock_value()) :: module()
@spec mock(module(), [{function_name(), arity()}], dynamic_mock()) :: module()

Function used to create mock in context of single test process.

Mock created in test won't leak to another process (other test, spawned Task, GenServer...). It can be used safely in asynchronous tests.

Mocks can be created with static value:

mock Mod, [fun: 2], "mocked value"

or function:

mock Mod, [fun: 2], fn(_, arg2) -> arg2 end

Keep in mind that function inside mock must have same arity as original one.

This:

mock Mod, [fun: 2], &to_string/1

will raise an error.

It is also possible to mock function with given name and any arity

mock Mod, :fun, "mocked value"

but this version doesn't support function as value.

Also, multiple mocks for same module are chainable

Mod
|> mock(:fun1, "value")
|> mock([fun2: 1], &string/1)

Deprecated

new(mod, opts \\ [])

This function is deprecated. Mockery was not designed as solution for other libraries. It was a bad decision to try to workaround this. This approach was also extremely ugly and lacking all the advantages of Mockery .

of(mod, opts \\ [])

This function is deprecated. Tuple calls won't be officially supported in Mockery v3. Please migrate to the new macro-based alternative available in `Mockery.Macro` .