1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
|
[](http://travis-ci.org/eproxus/meck)
* [Introduction](#introduction)
* [Features](#features)
* [Examples](#examples)
* [Build](#build)
* [Install](#install)
* [Contribute](#contribute)
meck
====
A mocking library for Erlang.
<a name='introduction'>
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.
<a name='features'>
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
<a name='examples'>
Examples
--------
Here's an example of using meck in the Erlang shell:
```erl
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:
```erl
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):
```erl
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:
```erlang
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`.
```erl
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):
```erl
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"
```
<a name='build'>
Build
-----
meck requires [rebar][1] to build. To build meck, go to the meck
directory and simply type:
```sh
rebar compile
```
To make sure meck works on your platform, run the tests:
```sh
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.
<a name='install'>
Install
-------
To install meck permanently, use of [Agner][2] is recommended:
```sh
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.
<a name='contribute'>
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]
[1]: https://github.com/basho/rebar "Rebar - A build tool for Erlang"
[2]: http://erlagner.org/ "Agner - Erlang Package Index & Package Manager"
[3]: http://github.com/eproxus/meck/issues "meck issues"
|
