Version 0.7.2

- Change: Allow wildcards in history functions
  (Might break backwards compatibility in rare cases where code relies on
   the '_' atom as a normal atom, it is now the wildcard pattern)
- Change: Add caller Pid to history
  *CAUTION* This will break backwards compatibility for functions that rely
  on the return value of history/1!
- New: function num_calls/3+4 that return number of calls made to a MFA spec.
- New: function called/4 that takes a caller Pid as argument
- New: function history/2 that takes a caller Pid as argument
- Change: By default, passthrough now records coverage statistics on original
  module (disable by using the 'no_passthrough_cover' option).
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.12 (Darwin)

iQIcBAABAgAGBQJPpq7qAAoJEP8OXb5aMnnsJGUP/2tsWa14/ghyi+MoM9KbqQwA
QVjTkGKJR8JEAlWk91wTR4mXl05i7wlCvSabJoaJ2j/xA5ud+dzylYlvXZzqcRmp
HlAKXjKXZULQ+csrbPzPjhSH3WYlT/YTsn1OcVoqNVQ9X+taRCbXOnJ9xcIzBm83
QbHq7d8629o+HVyJlnffQaQGelRgtz2byQuMo3b/OpIjqKcMgnhgVvuh5MBJU0cM
Em/whu+GQjfm068JieSR9x8SDi55vBql8MIGcl/bYlHUf3pTtnSmleBwXBD61qeT
NlMVGmpmPX5dkQs8TYZEjHRtZWbNg+UgkX7ZgoeQ/gMyQU8zO1HAZZ0QAgBpQPIj
V+nyUtKW3+UthJWncQ/PFqMsSzklWxxjBJMBnpCds+/uvqH4aBaC+oIfCvmazhqn
93+l8ESttNGdSBVV7A+9TkAwoXkvXhiVjgT4B7lp0X39GSxrE/IwJb3Ms3VNU4+m
5isRuAnaBWhYfwwGLpzTBUZHR2BDfm+v6XCvjuGlDEk5jFjxzREX9HepDro2mE23
Ha0wazlFPzEAyT3fEv4YKTtnBawWxbowvMVw57IU0j+6ad/+sbFF6I7nP/KSyWaB
vghEeJHVp1Vpk7K3heLsZuPHVCo2yDTW1d8qFKURBr2A6GT6xmCh7qe04+LODRsx
7BZc55YNIGi8RE/vaSxd
=fiWc
-----END PGP SIGNATURE-----
Version 0.7.2
3 files changed
tree: eb2f14b56d4b5717f9e94eaf9d5ea9f6c62a275f
  1. .gitignore
  2. .scripts/
  3. .travis.yml
  4. CHANGELOG
  5. LICENSE
  6. Makefile
  7. NOTICE
  8. README.md
  9. doc/
  10. rebar.config
  11. src/
  12. test/
README.md

Build Status

meck

A mocking library for Erlang.

Introduction

With meck you can easily mock modules in Erlang. You can also perform some basic validations on the mocked modules, such as making sure no unexpected exceptions occurred or looking at the call history.

Features

  • Automatic renaming and restoration of original modules
  • Automatic backup and restore of cover data
  • Changing return values using sequences and loops of static values
  • Pass through: use functions from the original module
  • Mock is linked to the creating process (disable with no_link)
  • Complete call history showing calls, results and exceptions
  • Mocking of sticky modules (using the option unstick)
  • Throwing of expected exceptions that keeps the module valid

Examples

Here's an example of using meck in the Erlang shell:

Eshell V5.8.4  (abort with ^G)
1> meck:new(dog).
ok
2> meck:expect(dog, bark, fun() -> "Woof!" end).
ok
3> dog:bark().
"Woof!"
4> meck:validate(dog).
true
5> meck:unload(dog).
ok
6> dog:bark().
** exception error: undefined function dog:bark/0

Exceptions can be anticipated by meck (resulting in validation still passing). This is intended to be used to test code that can and should handle certain exceptions indeed does take care of them:

5> meck:expect(dog, meow, fun() -> meck:exception(error, not_a_cat) end).
ok
6> catch dog:meow().
{'EXIT',{not_a_cat,[{meck,exception,2},
                    {meck,exec,4},
                    {dog,meow,[]},
                    {erl_eval,do_apply,5},
                    {erl_eval,expr,5},
                    {shell,exprs,6},
                    {shell,eval_exprs,6},
                    {shell,eval_loop,3}]}}
7> meck:validate(dog).
true

Normal Erlang exceptions result in a failed validation. The following example is just to demonstrate the behavior, in real test code the exception would normally come from the code under test (which should, if not expected, invalidate the mocked module):

8> meck:expect(dog, jump, fun(Height) when Height > 3 ->
                                  erlang:error(too_high);
                             (Height) ->
                                  ok
                          end).
ok
9> dog:jump(2).
ok
10> catch dog:jump(5).
{'EXIT',{too_high,[{meck,exec,4},
                   {dog,jump,[5]},
                   {erl_eval,do_apply,5},
                   {erl_eval,expr,5},
                   {shell,exprs,6},
                   {shell,eval_exprs,6},
                   {shell,eval_loop,3}]}}
11> meck:validate(dog).
false

Here's an example of using meck inside an EUnit test case:

my_test() ->
    meck:new(my_library_module),
    meck:expect(my_library_module, fib, fun(8) -> 21 end),
    ?assertEqual(21, code_under_test:run(fib, 8)), % Uses my_library_module
    ?assert(meck:validate(my_library_module)),
    meck:unload(my_library_module).

Pass-through is used when the original functionality of a module should be kept. When the option passthrough is used when calling new/2 all functions in the original module will be kept in the mock. These can later be overridden by calling expect/3 or expect/4.

Eshell V5.8.4  (abort with ^G)
1> meck:new(string, [unstick, passthrough]).
ok
2> string:strip("  test  ").
"test"

It's also possible to pass calls to the original function allowing us to override only a certain behavior of a function (this usage is compatible with the passthrough option). passthrough/1 will always call the original function with the same name as the expect is defined in):

Eshell V5.8.4  (abort with ^G)
1> meck:new(string, [unstick]).
ok
2> meck:expect(string, strip, fun(String) -> meck:passthrough([String]) end).
ok
3> string:strip("  test  ").
"test"
4> meck:unload(string).
ok
5> string:strip("  test  ").
"test"

Build

meck requires rebar to build. To build meck, go to the meck directory and simply type:

rebar compile

To make sure meck works on your platform, run the tests:

rebar eunit

Two things might seem alarming when running the tests:

  1. Warnings emitted by cover
  2. En exception printed by SASL

Both are expected due to the way Erlang currently prints errors. The important line you should look for is All XX tests passed, if that appears all is correct.

Install

To install meck permanently, use of Agner is recommended:

agner install meck

If you want to install your own built version of meck add the ebin directory to your Erlang code path or move the meck folder into your release folder and make sure that folder is in your ERL_LIBS environment variable.

Contribute

Patches are greatly appreciated!

Should you find yourself using meck and have issues, comments or feedback please [create an issue here on GitHub.] 3