Copyright © 2010-2017 Adam Lindberg, 2010-2011 Erlang Solutions Ltd
Authors: Adam Lindberg (eproxus@gmail.com).
args_spec() = [any() | '_' | matcher()] | non_neg_integer()
Argument specification is used to specify argument patterns throughout Meck.
In particular it is used in definition of expectation clauses by
expect/3
, expect/4
, and by history digging functions
num_called/3
, called/3
to specify what arguments of a
function call of interest should look like.
An argument specification can be given as a argument pattern list or as a non-negative integer that represents function clause/call arity.
If an argument specification is given as an argument pattern, then every
pattern element corresponds to a function argument at the respective
position. '_' is a wildcard that matches any value. In fact you can specify
atom wildcard '_' at any level in the value structure.
(E.g.: {1, [blah, {'_', "bar", 2} | '_'], 3}). It is also possible to use a
matcher()
created by is/1
in-place of a value pattern.
func_clause_spec() = {args_spec(), ret_spec()}
It is used in expect/3
and expect/4
to define a function
clause of complex multi-clause expectations.
history() = [{CallerPid::pid(), meck_mfa(), Result::any()} | {CallerPid::pid(), meck_mfa(), Class::throw | error | exit, Reason::any(), stack_trace()}]
Represents a list of either successful function calls with a returned result or function calls that resulted in an exception with a type, reason and a stack trace. Each tuple begins with the pid of the process that made the call to the function.
abstract datatype: matcher()
Matcher is an entity that is used to check that a particular value meets
some criteria. They are used in defining expectation where Erlang patterns
are not enough. E.g. to check that a numeric value is within bounds.
Instances of matcher
can be created by is/1
function from either a
predicate function or a hamcrest matcher. (see is/1
for details).
An instance of this type may be specified in any or even all positions of an
arg_spec()
.
meck_mfa() = {Mod::atom(), Func::atom(), Args::[any()]}
Module, function and arguments that the mock module got called with.
ret_spec() = meck_ret_spec:ret_spec()
Opaque data structure that specifies a value or a set of values to be returned
by a mock stub function defined by either expect/3
and expect/4
.
Values of ret_spec()
are constructed by seq/1
, loop/1
,
val/1
, exec/1
, and raise/2
functions. They are used
to specify return values in expect/3
and expect/4
functions,
and also as a parameter of the stub_all
option of new/2
function.
X
is a valid ret_spec()
equivalent to
meck:val(X)
.
stack_trace() = [{Mod::atom(), Func::atom(), AriOrArgs::byte() | [any()]} | {Mod::atom(), Func::atom(), AriOrArgs::byte() | [any()], Location::[{atom(), any()}]}]
Erlang stack trace.
called/3 | Returns whether Mod:Func has been called with Args . |
called/4 | Returns whether Pid has called Mod:Func with Args . |
capture/5 | Returns the value of an argument as it was passed to a particular
function call, It fails with not_found error if a function call of
interest has never been made. |
capture/6 | Returns the value of an argument as it was passed to a particular function call made by a particular process. |
delete/3 | Deletes an expectation. |
delete/4 | Deletes an expectation. |
exception/2 | Throws an expected exception inside an expect fun. |
exec/1 | Creates a ret_spec() from a function. |
expect/3 | Add expectation for a function Func to the mocked modules Mod . |
expect/4 | Adds an expectation with the supplied arity and return value. |
expects/1 | Returns the list of expectations. |
expects/2 | Returns the list of expectations. |
history/1 | Return the call history of the mocked module for all processes. |
history/2 | Return the call history of the mocked module for the specified process. |
is/1 | creates a matcher/0 instance from either Predicate or
HamcrestMatcher . |
loop/1 | Converts a list of terms into ret_spec() defining a loop of
values. |
loop/4 | (Deprecated.) Equivalent to expect(Mod, Func, Ari, loop(Loop)). |
mocked/0 | Returns the currently mocked modules. |
new/1 | Equivalent to new(Mod, []). |
new/2 | Creates new mocked module(s). |
num_calls/3 | Returns the number of times Mod:Func has been called with Args . |
num_calls/4 | Returns the number of times process Pid has called Mod:Func
with Args . |
passthrough/0 | Creates a ret_spec() that makes the original module function be
called. |
passthrough/1 | Calls the original function (if existing) inside an expectation fun. |
raise/2 | Creates a ret_spec() that defines an exception. |
reset/1 | Erases the call history for a mocked module or a list of mocked modules. |
seq/1 | Converts a list of terms into ret_spec() defining a sequence of
values. |
sequence/4 | (Deprecated.) Equivalent to expect(Mod, Func, Ari, seq(Sequence)). |
unload/0 | Unloads all mocked modules from memory. |
unload/1 | Unload a mocked module or a list of mocked modules. |
val/1 | Converts a term into ret_spec() defining an individual value. |
validate/1 | Validate the state of the mock module(s). |
wait/4 | Blocks until either function Mod:Func is called at least once with
arguments matching OptArgsSpec , or Timeout has elapsed. |
wait/5 | Blocks until either function Mod:Func is called at least Times with
arguments matching OptArgsSpec , or Timeout has elapsed. |
wait/6 | Blocks until either function Mod:Func is called at least Times with
arguments matching OptArgsSpec by process OptCallerPid , or Timeout has
elapsed. |
called(Mod, OptFun, OptArgsSpec) -> boolean()
Equivalent to called(Mod, Fun, Args, '_').
Returns whether Mod:Func
has been called with Args
.
called(Mod, OptFun, OptArgsSpec, OptCallerPid) -> boolean()
Returns whether Pid
has called Mod:Func
with Args
.
This will check the history for the module, Mod
, to determine
whether process Pid
call the function, Fun
, with arguments, Args
. If
so, this function returns true, otherwise false.
'_'
See also: called/3.
capture(Occur, Mod, Func, OptArgsSpec, ArgNum) -> ArgValue
Equivalent to capture(Occur, Mod, Func, OptArgsSpec, ArgNum, '_').
Returns the value of an argument as it was passed to a particular
function call, It fails with not_found
error if a function call of
interest has never been made.
It retrieves the value of argument at ArgNum
position as it was passed
to function call Mod:Func
with arguments that match OptArgsSpec
that
occurred Occur
'th according to the call history.
first
and last
can be used in place of the occurrence number to
retrieve the argument value passed when the function was called the first
or the last time respectively.
capture(Occur, Mod, Func, OptArgsSpec, ArgNum, OptCallerPid) -> ArgValue
Returns the value of an argument as it was passed to a particular
function call made by a particular process. It fails with not_found
error
if a function call of interest has never been made.
It retrieves the value of argument at ArgNum
position as it was passed
to function call Mod:Func
with arguments that match OptArgsSpec
made by
process CallerPid
that occurred Occur
'th according to the call history.
Atoms first
and last
can be used in place of the occurrence number to
retrieve the argument value passed when the function was called the first
or the last time respectively.
_
might be passed as OptCallerPid
, but it is better
to use capture/5
instead.
delete(Mods, Func, Ari) -> ok
Deletes an expectation.
Deletes the expectation for the functionFunc
with the matching
arity Arity
.
If the mock has passthrough enabled, this function restores the
expectation to the original function. See delete/4
.
delete(Mods, Func, Ari, Force) -> ok
Deletes an expectation.
Deletes the expectation for the functionFunc
with the matching
arity Arity
.
Force
is a flag to delete the function even if it is passthrough.
exception(Class, Reason) -> no_return()
Throws an expected exception inside an expect fun.
This exception will get thrown without invalidating the mocked module. That is, the code using the mocked module is expected to handle this exception.
Note: this code should only be used inside an expect fun.exec(Fun::function()) -> ret_spec()
Creates a ret_spec()
from a function. Calls to an expect,
created with ret_spec()
returned by this function, will be forwarded
to the specified function.
expect(Mods, Func, Expectation) -> ok
Add expectation for a function Func
to the mocked modules Mod
.
function()
Func
is called. The arity of function()
identifies for which
particular Func
variant an expectation is created for (that is, a function
with arity 2 will generate an expectation for Func/2
).[
func_clause_spec()
]
arg_spec()
/ret_spec()
pairs. Whenever the function Func
is called
the arguments are matched against the arg_spec()
in the list. As
soon as the first match is found then a value defined by the corresponding
ret_spec()
is returned.expect(Mods, Func, ArgsSpec, RetSpec) -> ok
Equivalent to expect(Mod, Func, [{ArgsSpec, RetSpec}]).
Adds an expectation with the supplied arity and return value.
This creates an expectation that has the only clause {ArgsSpec
, RetSpec
}.
expects(Mods) -> [{Mod, Func, Ari}]
Returns the list of expectations.
Returns the list of MFAs that were replaced by expectationsexpects(Mods, ExcludePassthrough) -> [{Mod, Func, Ari}]
Returns the list of expectations.
Returns the list of MFAs that were replaced by expectations IfExcludePassthrough
is on, only expectations that are not
direct passthroughs are returned
Equivalent to history(Mod, '_').
Return the call history of the mocked module for all processes.
Return the call history of the mocked module for the specified process.
Returns a list of calls to the mocked module and their results for the specifiedPid
. Results can be either normal Erlang terms or
exceptions that occurred.
See also: called/3, called/4, history/1, num_calls/3, num_calls/4.
is(MatcherImpl) -> matcher()
creates a matcher/0
instance from either Predicate
or
HamcrestMatcher
.
Predicate
- is a single parameter function. If it returns true
then
the argument passed to it is considered as meeting the matcher criteria,
otherwise as not.HamcrestMatcher
- is a matcher created by
Hamcrest-Erlang
libraryConverts a list of terms into ret_spec()
defining a loop of
values. It is intended to be in construction of clause specs for the
expect/3
function.
ret_spec()
returned by this function,
will return one element at a time from the Loop
list and will restart at
the first element when the end is reached.
loop(Mods, Func, Ari, Loop) -> ok
Equivalent to expect(Mod, Func, Ari, loop(Loop)).
This function is deprecated: Please use expect/3
or expect/4
along with
ret_spec()
generated by loop/1
.
mocked() -> [atom()]
Returns the currently mocked modules.
new(Mods) -> ok
Equivalent to new(Mod, []).
Creates new mocked module(s).
This replaces the current version (if any) of the modules in Mod
with an empty module.
Since this library is intended to use from test code, this function links a process for each mock to the calling process.
The valid options are:passthrough
stub_all
then stub_all
is ignored.no_link
unstick
no_passthrough_cover
{spawn_opt, list()}
no_history
non_strict
{stub_all,
ret_spec()
}
ret_spec()
regardless of arguments
passed in. It is possible to specify this option as just stub_all
then stubs will return atom ok
. If used along with passthrough
then stub_all
is ignored. merge_expects
error:{undefined_module, Mod}
non_strict
.error:{module_is_sticky, Mod}
unstick
.error:{abstract_code_not_found, Mod}
passthrough
was used but the original module has no
abstract code which can be called. Make sure the module is compiled
with the compiler option debug_info
.num_calls(Mod, OptFun, OptArgsSpec) -> non_neg_integer()
Equivalent to num_calls(Mod, Fun, Args, '_').
Returns the number of times Mod:Func
has been called with Args
.
num_calls(Mod, OptFun, OptArgsSpec, OptCallerPid) -> non_neg_integer()
Returns the number of times process Pid
has called Mod:Func
with Args
.
Mod
, to determine how
many times process Pid
has called the function, Fun
, with
arguments, Args
and returns the result.
See also: num_calls/3.
passthrough() -> ret_spec()
Creates a ret_spec()
that makes the original module function be
called.
ret_spec()
returned by this function,
will be forwarded to the original function.
passthrough(Args) -> Result
Calls the original function (if existing) inside an expectation fun.
Note: this code should only be used inside an expect fun.Creates a ret_spec()
that defines an exception.
ret_spec()
returned by this function,
will raise the specified exception.
reset(Mods) -> ok
Erases the call history for a mocked module or a list of mocked modules.
This function will erase all calls made heretofore from the history of the specified modules. It is intended to prevent cluttering of test results with calls to mocked modules made during the test setup phase.Converts a list of terms into ret_spec()
defining a sequence of
values. It is intended to be in construction of clause specs for the
expect/3
function.
ret_spec
returned by this function,
will exhaust the Sequence
list of return values in order until the last
value is reached. That value is then returned for all subsequent calls.
sequence(Mods, Func, Ari, Sequence) -> ok
Equivalent to expect(Mod, Func, Ari, seq(Sequence)).
This function is deprecated: Please use expect/3
or expect/4
along with
ret_spec()
generated by seq/1
.
unload() -> Unloaded
Unloads all mocked modules from memory.
The function returns the list of mocked modules that were unloaded in the process.unload(Mods) -> ok
Unload a mocked module or a list of mocked modules.
This will purge and delete the module(s) from the Erlang virtual machine. If the mocked module(s) replaced an existing module, this module will still be in the Erlang load path and can be loaded manually or when called.Converts a term into ret_spec()
defining an individual value.
It is intended to be in construction of clause specs for the
expect/3
function.
validate(Mods) -> boolean()
Validate the state of the mock module(s).
The function returns true
if the mocked module(s) has been used
according to its expectations. It returns false
if a call has
failed in some way. Reasons for failure are wrong number of
arguments or non-existing function (undef), wrong arguments
(function clause) or unexpected exceptions.
Validation can detect:
function_clause
)true
being returnedValidation cannot detect:
undef
)undef
)The reason Meck cannot detect these cases is because of how it is implemented. Meck replaces the module with a mock and a process that maintains the mock. Everything Meck get goes through that mock module. Meck does not insert itself at the caller level (i.e. in your module or in your test case), so it cannot know that you failed to call a module.
Use thehistory/1
or history/2
function to analyze errors.
wait(Mod, OptFunc, OptArgsSpec, Timeout) -> ok
Equivalent to wait(1, Mod, OptFunc, OptArgsSpec, '_', Timeout).
Blocks until either function Mod:Func
is called at least once with
arguments matching OptArgsSpec
, or Timeout
has elapsed. In the latter
case the call fails with error:timeout
.
reset/1
on the mock or from the mock creation, whichever occurred
latter. If a matching call has already occurred, then the function returns
ok
immediately.
wait(Times, Mod, OptFunc, OptArgsSpec, Timeout) -> ok
Equivalent to wait(Times, Mod, OptFunc, OptArgsSpec, '_', Timeout).
Blocks until either function Mod:Func
is called at least Times
with
arguments matching OptArgsSpec
, or Timeout
has elapsed. In the latter
case the call fails with error:timeout
.
reset/1
on the mock or from the mock creation, whichever occurred
latter. If Times
number of matching calls has already occurred, then the
function returns ok
immediately.
wait(Times, Mod, OptFunc, OptArgsSpec, OptCallerPid, Timeout) -> ok
Blocks until either function Mod:Func
is called at least Times
with
arguments matching OptArgsSpec
by process OptCallerPid
, or Timeout
has
elapsed. In the latter case the call fails with error:timeout
.
reset/1
on the mock or from the mock creation, whichever occurred
latter. If Times
number of matching call has already occurred, then the
function returns ok
immediately.
Generated by EDoc