Validation Proposal

An API is needed to verify number of calls, arguments used and order of calls (among other things). This page lists the various proposals for how such an API could look like.

Proposal #1 - Verification Matchers

Detailed here: https://github.com/eproxus/meck/pull/68

The proposal is centered around the verify/3,4,5 functions where the first argument is a matcher that is applied on the history. Several matchers have been implemented.

`Count`	Is a shortcut for `{times, Count}` see below.
`never`	Checks that the function has never been called. Equivalent to: `?assertEquals(0, num_calls(Mod, Fun, Args, Pid))`
`at_least_once`	Checks that the function has been called at least once. Equivalent to: `?assert(called(Mod, Fun, Args, Pid))`
`{times, Count}`	Checks that the function has been called exactly `Count` times. Equivalent to `?assertEquals(Count, num_calls(Mod, Fun, Args, Pid))`
`{at_least, Count}`	Checks that the function has been called at least `Count` times.
`{at_most, Count}`	Checks that the function has been called at most `Count` times.
`{MatcherFun, Params}`	The following call is made `MatcherFun(Actual, Params)` where `Actual` is the actual number of calls that has been made. If it returns `true` then the verification is considered as passed, otherwise a runtime error is raised.

Proposal #2 - Hamcrest Matchers

Inspired by Hamcrest for Erlang: https://github.com/hyperthunk/hamcrest-erlang

Either Meck will supply it's own Hamcrest implementation (stand-alone) or depend on Hamcrest for Erlang.

Examples:

assert_that(meck:history(Mod), contains(call_to(Mod, test, ['_', 1]))).
assert_that(meck:history(Mod), starts_with(call_to(Mod, test, ['_', 1]))).
assert_that(meck:history(Mod), isempty()).
assert_that(meck:history(Mod), contains(exactly(5, calls_to(Mod, test, ['_', 1])))).
assert_that(meck:history(Mod), contains(more_than(5, calls_to(Mod, test, '_'))).

Perhaps a more Meck-orient approach could be:

meck:assert_that(history_for(Mod), contains(less_than(5, calls_to(test, '_'))).