Mockery.Assertions (Mockery v2.5.0)
View SourceAdditional assertion helpers for verifying calls made to mocked modules and functions in tests.
This module provides macros and functions to assert whether certain functions have been called, how many times they have been called, and with what arguments.
Important Notes
Mockery only tracks calls to modules prepared by
Mockery.Macro.mockable/2.Tracking only works when the configuration
config :mockery, enable: trueis set.Calls made outside the test process (such as those in spawned Tasks, GenServers, etc.) are not tracked.
Summary
Types
Option value for the :args key in opts.
Option value for the :arity key in opts.
Function name (an atom identifying the function).
Keyword options accepted by assert_called!/3.
Option value for the :times key in opts.
Functions
Asserts that a function on the given mod with the given fun name was called.
Negated version of assert_called!/3. Asserts that the given function on the
provided mod with name fun was NOT called according to the provided options.
Deprecated
Types
@type args_opt() :: [term()]
Option value for the :args key in opts.
A list of terms representing the argument pattern to match recorded calls.
@type arity_opt() :: non_neg_integer()
Option value for the :arity key in opts.
A non-negative integer narrowing the match to a specific function arity.
@type function_name() :: atom()
Function name (an atom identifying the function).
Keyword options accepted by assert_called!/3.
Supported keys: :arity, :args, and :times.
@type times_opt() :: non_neg_integer() | {:in, [non_neg_integer()]} | {:in, Range.t()} | {:at_least, non_neg_integer()} | {:at_most, non_neg_integer()}
Option value for the :times key in opts.
How many times the function is expected to be called.
Accepts:
- a non-negative integer for exact count
{:in, [integers]}for specific allowed counts{:in, Range.t()}for a range of allowed counts{:at_least, non_neg_integer()}for a lower bound{:at_most, non_neg_integer()}for an upper bound
Functions
@spec assert_called!(module(), function_name(), opts()) :: true | no_return()
Asserts that a function on the given mod with the given fun name was called.
This macro is a convenience wrapper that allows you to assert calls with additional filtering via options.
Accepted options:
:arity- a non-negative integer narrowing the check to calls with the given arity.:args- a list representing the argument pattern to match recorded calls. Use unbound variables (e.g._,var) to create flexible patterns.:times- how many times the function is expected to be called. Supports an integer,{:in, [integers]},{:in, Range.t()},{:at_least, n}and{:at_most, n}.
Notes:
:arityand:argsare mutually exclusive. If both are provided,:aritywill be ignored and a warning will be emitted.- If provided,
:argsmust be a list — otherwise aMockery.Errorwill be raised. - If provided,
:aritymust be a non-negative integer — otherwise aMockery.Errorwill be raised. - If
:timeshas an invalid format aMockery.Errorwill be raised.
Returns true when the assertion passes. On failure it raises an error
with a descriptive message and (when history is enabled) a snippet of the recorded calls.
Examples
# Assert any function named :fun on Mod was called at least once
assert_called! Mod, :fun
# Assert Mod.fun/2 was called
assert_called! Mod, :fun, arity: 2
# Assert Mod.fun/2 was called with specific args (supports patterns)
assert_called! Mod, :fun, args: ["a", _]
# Assert Mod.fun/2 was called exactly 3 times
assert_called! Mod, :fun, times: 3
# Assert Mod.fun/1 was called at least twice
assert_called! Mod, :fun, arity: 1, times: {:at_least, 2}@spec refute_called!(module(), function_name(), opts()) :: true | no_return()
Negated version of assert_called!/3. Asserts that the given function on the
provided mod with name fun was NOT called according to the provided options.
Supported options are the same as assert_called!/3 (:arity, :args, :times).