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
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
|
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>
File: README
— Mocha 2.4.2
</title>
<link rel="stylesheet" href="css/style.css" type="text/css" />
<link rel="stylesheet" href="css/common.css" type="text/css" />
<script type="text/javascript">
pathId = "README";
relpath = '';
</script>
<script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
<script type="text/javascript" charset="utf-8" src="js/app.js"></script>
</head>
<body>
<div class="nav_wrap">
<iframe id="nav" src="class_list.html?1"></iframe>
<div id="resizer"></div>
</div>
<div id="main" tabindex="-1">
<div id="header">
<div id="menu">
<a href="_index.html">Index</a> »
<span class="title">File: README</span>
</div>
<div id="search">
<a class="full_list_link" id="class_list_link"
href="class_list.html">
<svg width="24" height="24">
<rect x="0" y="4" width="24" height="4" rx="1" ry="1"></rect>
<rect x="0" y="12" width="24" height="4" rx="1" ry="1"></rect>
<rect x="0" y="20" width="24" height="4" rx="1" ry="1"></rect>
</svg>
</a>
</div>
<div class="clear"></div>
</div>
<div id="content"><div id='filecontents'><h2 id="mocha">Mocha <a href="https://app.circleci.com/pipelines/github/freerange/mocha"><img src="https://circleci.com/gh/freerange/mocha.svg?style=shield" alt="CircleCI status of freerange/mocha"></a> <a href="http://badge.fury.io/rb/mocha"><img src="https://badge.fury.io/rb/mocha.svg" alt="Gem Version"></a></h2>
<h3 id="description">Description</h3>
<ul>
<li>A Ruby library for <a href="http://xunitpatterns.com/Mock%20Object.html">mocking</a> and <a href="http://xunitpatterns.com/Test%20Stub.html">stubbing</a> - but deliberately not (yet) <a href="http://xunitpatterns.com/Fake%20Object.html">faking</a> or <a href="http://xunitpatterns.com/Test%20Spy.html">spying</a>.</li>
<li>A unified, simple and readable syntax for both full & partial mocking.</li>
<li>Built-in support for Minitest and Test::Unit.</li>
<li>Supported by many other test frameworks.</li>
</ul>
<h3 id="intended-usage">Intended Usage</h3>
<p>Mocha is intended to be used in unit tests for the <a href="http://xunitpatterns.com/Mock%20Object.html">Mock Object</a> or <a href="http://xunitpatterns.com/Test%20Stub.html">Test Stub</a> types of <a href="http://xunitpatterns.com/Test%20Double.html">Test Double</a>, not the <a href="http://xunitpatterns.com/Fake%20Object.html">Fake Object</a> or <a href="http://xunitpatterns.com/Test%20Spy.html">Test Spy</a> types. Although it would be possible to extend Mocha to allow the implementation of fakes and spies, we have chosen to keep it focused on mocks and stubs.</p>
<h3 id="installation">Installation</h3>
<h4 id="gem">Gem</h4>
<p>Install the latest version of the gem with the following command...</p>
<pre class="code ruby"><code class="ruby">$ gem install mocha
</code></pre>
<p>Note: If you are intending to use Mocha with Test::Unit or Minitest, you should only setup Mocha <em>after</em> loading the relevant test library...</p>
<h5 id="test-unit">Test::Unit</h5>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_require'>require</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>rubygems</span><span class='tstring_end'>'</span></span>
<span class='id identifier rubyid_gem'>gem</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>mocha</span><span class='tstring_end'>'</span></span>
<span class='id identifier rubyid_require'>require</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>test/unit</span><span class='tstring_end'>'</span></span>
<span class='id identifier rubyid_require'>require</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>mocha/test_unit</span><span class='tstring_end'>'</span></span>
</code></pre>
<h5 id="minitest">Minitest</h5>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_require'>require</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>rubygems</span><span class='tstring_end'>'</span></span>
<span class='id identifier rubyid_gem'>gem</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>mocha</span><span class='tstring_end'>'</span></span>
<span class='id identifier rubyid_require'>require</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>minitest/autorun</span><span class='tstring_end'>'</span></span>
<span class='id identifier rubyid_require'>require</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>mocha/minitest</span><span class='tstring_end'>'</span></span>
</code></pre>
<h4 id="bundler">Bundler</h4>
<p>If you're using Bundler, include Mocha in the <code>Gemfile</code> and then setup Mocha later once you know the test library has been loaded...</p>
<h5 id="test-unit">Test::Unit</h5>
<pre class="code ruby"><code class="ruby"><span class='comment'># Gemfile
</span><span class='id identifier rubyid_gem'>gem</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>mocha</span><span class='tstring_end'>'</span></span>
<span class='comment'># Elsewhere after Bundler has loaded gems e.g. after `require 'bundler/setup'`
</span><span class='id identifier rubyid_require'>require</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>test/unit</span><span class='tstring_end'>'</span></span>
<span class='id identifier rubyid_require'>require</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>mocha/test_unit</span><span class='tstring_end'>'</span></span>
</code></pre>
<h5 id="minitest">Minitest</h5>
<pre class="code ruby"><code class="ruby"><span class='comment'># Gemfile
</span><span class='id identifier rubyid_gem'>gem</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>mocha</span><span class='tstring_end'>'</span></span>
<span class='comment'># Elsewhere after Bundler has loaded gems e.g. after `require 'bundler/setup'`
</span><span class='id identifier rubyid_require'>require</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>minitest/autorun</span><span class='tstring_end'>'</span></span>
<span class='id identifier rubyid_require'>require</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>mocha/minitest</span><span class='tstring_end'>'</span></span>
</code></pre>
<h5 id="rspec">RSpec</h5>
<p>RSpec includes a mocha adapter. Just tell RSpec you want to mock with <code>:mocha</code>:</p>
<pre class="code ruby"><code class="ruby"><span class='comment'># Gemfile in Rails app
</span><span class='id identifier rubyid_gem'>gem</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>mocha</span><span class='tstring_end'>'</span></span>
<span class='comment'># Within `spec/spec_helper.rb`
</span><span class='const'>RSpec</span><span class='period'>.</span><span class='id identifier rubyid_configure'>configure</span> <span class='kw'>do</span> <span class='op'>|</span><span class='id identifier rubyid_config'>config</span><span class='op'>|</span>
<span class='id identifier rubyid_config'>config</span><span class='period'>.</span><span class='id identifier rubyid_mock_with'>mock_with</span> <span class='symbol'>:mocha</span>
<span class='kw'>end</span>
</code></pre>
<p>Note: There is no need to use a require statement to setup Mocha; RSpec does this itself.</p>
<h5 id="cucumber">Cucumber</h5>
<pre class="code ruby"><code class="ruby"><span class='comment'># In e.g. features/support/mocha.rb
</span><span class='id identifier rubyid_require'>require</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>mocha/api</span><span class='tstring_end'>'</span></span>
<span class='const'>World</span><span class='lparen'>(</span><span class='const'><span class='object_link'><a href="Mocha.html" title="Mocha (module)">Mocha</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Mocha/API.html" title="Mocha::API (module)">API</a></span></span><span class='rparen'>)</span>
<span class='const'>Around</span> <span class='kw'>do</span> <span class='op'>|</span><span class='id identifier rubyid_scenario'>scenario</span><span class='comma'>,</span> <span class='id identifier rubyid_block'>block</span><span class='op'>|</span>
<span class='kw'>begin</span>
<span class='id identifier rubyid_mocha_setup'>mocha_setup</span>
<span class='id identifier rubyid_block'>block</span><span class='period'>.</span><span class='id identifier rubyid_call'>call</span>
<span class='id identifier rubyid_mocha_verify'>mocha_verify</span>
<span class='kw'>ensure</span>
<span class='id identifier rubyid_mocha_teardown'>mocha_teardown</span>
<span class='kw'>end</span>
<span class='kw'>end</span>
</code></pre>
<h4 id="rails">Rails</h4>
<p>If you're loading Mocha using Bundler within a Rails application, you should setup Mocha manually e.g. at the bottom of your <code>test_helper.rb</code>.</p>
<h5 id="minitest">Minitest</h5>
<p>Note that since Rails v4 (at least), <code>ActiveSupport::TestCase</code> has inherited from <code>Minitest::Test</code> or its earlier equivalents. Thus unless you are <em>explicitly</em> using Test::Unit, you are likely to be using Minitest.</p>
<pre class="code ruby"><code class="ruby"><span class='comment'># Gemfile in Rails app
</span><span class='id identifier rubyid_gem'>gem</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>mocha</span><span class='tstring_end'>'</span></span>
<span class='comment'># At bottom of test_helper.rb (or at least after `require 'rails/test_help'`)
</span><span class='id identifier rubyid_require'>require</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>mocha/minitest</span><span class='tstring_end'>'</span></span>
</code></pre>
<h5 id="other-test-framework">Other Test Framework</h5>
<p>Follow the instructions for the relevant test framework in the <a href="#bundler">Bundler</a> section, but ensure that the relevant Mocha file (<code>mocha/minitest</code>, <code>mocha/test_unit</code>, or <code>mocha/api</code>) is required <strong>after</strong> the test framework has been loaded, e.g. at the bottom of <code>test_helper.rb</code> or <code>spec_helper.rb</code>, or at least after <code>rails/test_help</code> has been required.</p>
<h4 id="known-issues">Known Issues</h4>
<ul>
<li>In Mocha v1.10.0 an undocumented feature of <code>API#mock</code>, <code>API#stub</code> & <code>API#stub_everything</code> was changed. Previously when these methods were passed a single symbol, they returned a mock object that responded to the method identified by the symbol. Now Passing a single symbol is equivalent to passing a single string, i.e. it now defines the 'name' of the mock object.</li>
<li>In Mocha v1.2.0 there is a scenario where stubbing a class method originally defined in a module hangs the Ruby interpreter due to <a href="https://bugs.ruby-lang.org/issues/12832">a bug in Ruby v2.3.1</a>. See #272. This was fixed in Mocha v1.2.1.</li>
<li>Since v1.1.0 Mocha has used prepended modules internally for stubbing methods. There is <a href="https://bugs.ruby-lang.org/issues/12876">an obscure Ruby bug</a> in many (but not all) versions of Ruby between v2.0 & v2.3 which under certain circumstances may cause your Ruby interpreter to hang. See the Ruby bug report for more details. The bug has been fixed in Ruby v2.3.3 & v2.4.0.</li>
<li>Stubbing an aliased class method, where the original method is defined in a module that's used to <code>extend</code> the class doesn't work in Ruby 1.8.x. See stub_method_defined_on_module_and_aliased_test.rb for an example of this behaviour.</li>
<li>0.13.x versions cause a harmless, but annoying, deprecation warning when used with Rails 3.2.0-3.2.12, 3.1.0-3.1.10 & 3.0.0-3.0.19.</li>
<li>0.11.x versions don't work with Rails 3.2.13 (<code>TypeError: superclass mismatch for class ExpectationError</code>). See #115.</li>
<li>Versions 0.10.2, 0.10.3 & 0.11.0 of the Mocha gem were broken. Please do not use these versions.</li>
</ul>
<h3 id="usage">Usage</h3>
<h4 id="quick-start">Quick Start</h4>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_require'>require</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>test/unit</span><span class='tstring_end'>'</span></span>
<span class='id identifier rubyid_require'>require</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>mocha/test_unit</span><span class='tstring_end'>'</span></span>
<span class='kw'>class</span> <span class='const'>MiscExampleTest</span> <span class='op'><</span> <span class='const'>Test</span><span class='op'>::</span><span class='const'>Unit</span><span class='op'>::</span><span class='const'>TestCase</span>
<span class='kw'>def</span> <span class='id identifier rubyid_test_mocking_a_class_method'>test_mocking_a_class_method</span>
<span class='id identifier rubyid_product'>product</span> <span class='op'>=</span> <span class='const'>Product</span><span class='period'>.</span><span class='id identifier rubyid_new'>new</span>
<span class='const'>Product</span><span class='period'>.</span><span class='id identifier rubyid_expects'>expects</span><span class='lparen'>(</span><span class='symbol'>:find</span><span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_with'>with</span><span class='lparen'>(</span><span class='int'>1</span><span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_returns'>returns</span><span class='lparen'>(</span><span class='id identifier rubyid_product'>product</span><span class='rparen'>)</span>
<span class='id identifier rubyid_assert_equal'>assert_equal</span> <span class='id identifier rubyid_product'>product</span><span class='comma'>,</span> <span class='const'>Product</span><span class='period'>.</span><span class='id identifier rubyid_find'>find</span><span class='lparen'>(</span><span class='int'>1</span><span class='rparen'>)</span>
<span class='kw'>end</span>
<span class='kw'>def</span> <span class='id identifier rubyid_test_mocking_an_instance_method_on_a_real_object'>test_mocking_an_instance_method_on_a_real_object</span>
<span class='id identifier rubyid_product'>product</span> <span class='op'>=</span> <span class='const'>Product</span><span class='period'>.</span><span class='id identifier rubyid_new'>new</span>
<span class='id identifier rubyid_product'>product</span><span class='period'>.</span><span class='id identifier rubyid_expects'>expects</span><span class='lparen'>(</span><span class='symbol'>:save</span><span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_returns'>returns</span><span class='lparen'>(</span><span class='kw'>true</span><span class='rparen'>)</span>
<span class='id identifier rubyid_assert'>assert</span> <span class='id identifier rubyid_product'>product</span><span class='period'>.</span><span class='id identifier rubyid_save'>save</span>
<span class='kw'>end</span>
<span class='kw'>def</span> <span class='id identifier rubyid_test_stubbing_instance_methods_on_real_objects'>test_stubbing_instance_methods_on_real_objects</span>
<span class='id identifier rubyid_prices'>prices</span> <span class='op'>=</span> <span class='lbracket'>[</span><span class='id identifier rubyid_stub'>stub</span><span class='lparen'>(</span><span class='label'>pence:</span> <span class='int'>1000</span><span class='rparen'>)</span><span class='comma'>,</span> <span class='id identifier rubyid_stub'>stub</span><span class='lparen'>(</span><span class='label'>pence:</span> <span class='int'>2000</span><span class='rparen'>)</span><span class='rbracket'>]</span>
<span class='id identifier rubyid_product'>product</span> <span class='op'>=</span> <span class='const'>Product</span><span class='period'>.</span><span class='id identifier rubyid_new'>new</span>
<span class='id identifier rubyid_product'>product</span><span class='period'>.</span><span class='id identifier rubyid_stubs'>stubs</span><span class='lparen'>(</span><span class='symbol'>:prices</span><span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_returns'>returns</span><span class='lparen'>(</span><span class='id identifier rubyid_prices'>prices</span><span class='rparen'>)</span>
<span class='id identifier rubyid_assert_equal'>assert_equal</span> <span class='lbracket'>[</span><span class='int'>1000</span><span class='comma'>,</span> <span class='int'>2000</span><span class='rbracket'>]</span><span class='comma'>,</span> <span class='id identifier rubyid_product'>product</span><span class='period'>.</span><span class='id identifier rubyid_prices'>prices</span><span class='period'>.</span><span class='id identifier rubyid_collect'>collect</span> <span class='lbrace'>{</span><span class='op'>|</span><span class='id identifier rubyid_p'>p</span><span class='op'>|</span> <span class='id identifier rubyid_p'>p</span><span class='period'>.</span><span class='id identifier rubyid_pence'>pence</span><span class='rbrace'>}</span>
<span class='kw'>end</span>
<span class='kw'>def</span> <span class='id identifier rubyid_test_stubbing_an_instance_method_on_all_instances_of_a_class'>test_stubbing_an_instance_method_on_all_instances_of_a_class</span>
<span class='const'>Product</span><span class='period'>.</span><span class='id identifier rubyid_any_instance'>any_instance</span><span class='period'>.</span><span class='id identifier rubyid_stubs'>stubs</span><span class='lparen'>(</span><span class='symbol'>:name</span><span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_returns'>returns</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>stubbed_name</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span>
<span class='id identifier rubyid_product'>product</span> <span class='op'>=</span> <span class='const'>Product</span><span class='period'>.</span><span class='id identifier rubyid_new'>new</span>
<span class='id identifier rubyid_assert_equal'>assert_equal</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>stubbed_name</span><span class='tstring_end'>'</span></span><span class='comma'>,</span> <span class='id identifier rubyid_product'>product</span><span class='period'>.</span><span class='id identifier rubyid_name'>name</span>
<span class='kw'>end</span>
<span class='kw'>def</span> <span class='id identifier rubyid_test_traditional_mocking'>test_traditional_mocking</span>
<span class='id identifier rubyid_object'>object</span> <span class='op'>=</span> <span class='id identifier rubyid_mock'>mock</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>object</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span>
<span class='id identifier rubyid_object'>object</span><span class='period'>.</span><span class='id identifier rubyid_expects'>expects</span><span class='lparen'>(</span><span class='symbol'>:expected_method</span><span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_with'>with</span><span class='lparen'>(</span><span class='symbol'>:p1</span><span class='comma'>,</span> <span class='symbol'>:p2</span><span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_returns'>returns</span><span class='lparen'>(</span><span class='symbol'>:result</span><span class='rparen'>)</span>
<span class='id identifier rubyid_assert_equal'>assert_equal</span> <span class='symbol'>:result</span><span class='comma'>,</span> <span class='id identifier rubyid_object'>object</span><span class='period'>.</span><span class='id identifier rubyid_expected_method'>expected_method</span><span class='lparen'>(</span><span class='symbol'>:p1</span><span class='comma'>,</span> <span class='symbol'>:p2</span><span class='rparen'>)</span>
<span class='kw'>end</span>
<span class='kw'>def</span> <span class='id identifier rubyid_test_shortcuts'>test_shortcuts</span>
<span class='id identifier rubyid_object'>object</span> <span class='op'>=</span> <span class='id identifier rubyid_stub'>stub</span><span class='lparen'>(</span><span class='label'>method1:</span> <span class='symbol'>:result1</span><span class='comma'>,</span> <span class='label'>method2:</span> <span class='symbol'>:result2</span><span class='rparen'>)</span>
<span class='id identifier rubyid_assert_equal'>assert_equal</span> <span class='symbol'>:result1</span><span class='comma'>,</span> <span class='id identifier rubyid_object'>object</span><span class='period'>.</span><span class='id identifier rubyid_method1'>method1</span>
<span class='id identifier rubyid_assert_equal'>assert_equal</span> <span class='symbol'>:result2</span><span class='comma'>,</span> <span class='id identifier rubyid_object'>object</span><span class='period'>.</span><span class='id identifier rubyid_method2'>method2</span>
<span class='kw'>end</span>
<span class='kw'>end</span>
</code></pre>
<h4 id="mock-objects">Mock Objects</h4>
<pre class="code ruby"><code class="ruby"><span class='kw'>class</span> <span class='const'>Enterprise</span>
<span class='kw'>def</span> <span class='id identifier rubyid_initialize'>initialize</span><span class='lparen'>(</span><span class='id identifier rubyid_dilithium'>dilithium</span><span class='rparen'>)</span>
<span class='ivar'>@dilithium</span> <span class='op'>=</span> <span class='id identifier rubyid_dilithium'>dilithium</span>
<span class='kw'>end</span>
<span class='kw'>def</span> <span class='id identifier rubyid_go'>go</span><span class='lparen'>(</span><span class='id identifier rubyid_warp_factor'>warp_factor</span><span class='rparen'>)</span>
<span class='id identifier rubyid_warp_factor'>warp_factor</span><span class='period'>.</span><span class='id identifier rubyid_times'>times</span> <span class='lbrace'>{</span> <span class='ivar'>@dilithium</span><span class='period'>.</span><span class='id identifier rubyid_nuke'>nuke</span><span class='lparen'>(</span><span class='symbol'>:anti_matter</span><span class='rparen'>)</span> <span class='rbrace'>}</span>
<span class='kw'>end</span>
<span class='kw'>end</span>
<span class='id identifier rubyid_require'>require</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>test/unit</span><span class='tstring_end'>'</span></span>
<span class='id identifier rubyid_require'>require</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>mocha/test_unit</span><span class='tstring_end'>'</span></span>
<span class='kw'>class</span> <span class='const'>EnterpriseTest</span> <span class='op'><</span> <span class='const'>Test</span><span class='op'>::</span><span class='const'>Unit</span><span class='op'>::</span><span class='const'>TestCase</span>
<span class='kw'>def</span> <span class='id identifier rubyid_test_should_boldly_go'>test_should_boldly_go</span>
<span class='id identifier rubyid_dilithium'>dilithium</span> <span class='op'>=</span> <span class='id identifier rubyid_mock'>mock</span><span class='lparen'>(</span><span class='rparen'>)</span>
<span class='id identifier rubyid_dilithium'>dilithium</span><span class='period'>.</span><span class='id identifier rubyid_expects'>expects</span><span class='lparen'>(</span><span class='symbol'>:nuke</span><span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_with'>with</span><span class='lparen'>(</span><span class='symbol'>:anti_matter</span><span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_at_least_once'>at_least_once</span> <span class='comment'># auto-verified at end of test
</span> <span class='id identifier rubyid_enterprise'>enterprise</span> <span class='op'>=</span> <span class='const'>Enterprise</span><span class='period'>.</span><span class='id identifier rubyid_new'>new</span><span class='lparen'>(</span><span class='id identifier rubyid_dilithium'>dilithium</span><span class='rparen'>)</span>
<span class='id identifier rubyid_enterprise'>enterprise</span><span class='period'>.</span><span class='id identifier rubyid_go'>go</span><span class='lparen'>(</span><span class='int'>2</span><span class='rparen'>)</span>
<span class='kw'>end</span>
<span class='kw'>end</span>
</code></pre>
<h4 id="partial-mocking">Partial Mocking</h4>
<pre class="code ruby"><code class="ruby"><span class='kw'>class</span> <span class='const'>Order</span>
<span class='id identifier rubyid_attr_accessor'>attr_accessor</span> <span class='symbol'>:shipped_on</span>
<span class='kw'>def</span> <span class='id identifier rubyid_total_cost'>total_cost</span>
<span class='id identifier rubyid_line_items'>line_items</span><span class='period'>.</span><span class='id identifier rubyid_inject'>inject</span><span class='lparen'>(</span><span class='int'>0</span><span class='rparen'>)</span> <span class='lbrace'>{</span> <span class='op'>|</span><span class='id identifier rubyid_total'>total</span><span class='comma'>,</span> <span class='id identifier rubyid_line_item'>line_item</span><span class='op'>|</span> <span class='id identifier rubyid_total'>total</span> <span class='op'>+</span> <span class='id identifier rubyid_line_item'>line_item</span><span class='period'>.</span><span class='id identifier rubyid_price'>price</span> <span class='rbrace'>}</span> <span class='op'>+</span> <span class='id identifier rubyid_shipping_cost'>shipping_cost</span>
<span class='kw'>end</span>
<span class='kw'>def</span> <span class='id identifier rubyid_total_weight'>total_weight</span>
<span class='id identifier rubyid_line_items'>line_items</span><span class='period'>.</span><span class='id identifier rubyid_inject'>inject</span><span class='lparen'>(</span><span class='int'>0</span><span class='rparen'>)</span> <span class='lbrace'>{</span> <span class='op'>|</span><span class='id identifier rubyid_total'>total</span><span class='comma'>,</span> <span class='id identifier rubyid_line_item'>line_item</span><span class='op'>|</span> <span class='id identifier rubyid_total'>total</span> <span class='op'>+</span> <span class='id identifier rubyid_line_item'>line_item</span><span class='period'>.</span><span class='id identifier rubyid_weight'>weight</span> <span class='rbrace'>}</span>
<span class='kw'>end</span>
<span class='kw'>def</span> <span class='id identifier rubyid_shipping_cost'>shipping_cost</span>
<span class='id identifier rubyid_total_weight'>total_weight</span> <span class='op'>*</span> <span class='int'>5</span> <span class='op'>+</span> <span class='int'>10</span>
<span class='kw'>end</span>
<span class='kw'>class</span> <span class='op'><<</span> <span class='kw'>self</span>
<span class='kw'>def</span> <span class='id identifier rubyid_find_all'>find_all</span>
<span class='comment'># Database.connection.execute('select * from orders...
</span> <span class='kw'>end</span>
<span class='kw'>def</span> <span class='id identifier rubyid_number_shipped_since'>number_shipped_since</span><span class='lparen'>(</span><span class='id identifier rubyid_date'>date</span><span class='rparen'>)</span>
<span class='id identifier rubyid_find_all'>find_all</span><span class='period'>.</span><span class='id identifier rubyid_select'>select</span> <span class='lbrace'>{</span> <span class='op'>|</span><span class='id identifier rubyid_order'>order</span><span class='op'>|</span> <span class='id identifier rubyid_order'>order</span><span class='period'>.</span><span class='id identifier rubyid_shipped_on'>shipped_on</span> <span class='op'>></span> <span class='id identifier rubyid_date'>date</span> <span class='rbrace'>}</span><span class='period'>.</span><span class='id identifier rubyid_length'>length</span>
<span class='kw'>end</span>
<span class='kw'>def</span> <span class='id identifier rubyid_unshipped_value'>unshipped_value</span>
<span class='id identifier rubyid_find_all'>find_all</span><span class='period'>.</span><span class='id identifier rubyid_inject'>inject</span><span class='lparen'>(</span><span class='int'>0</span><span class='rparen'>)</span> <span class='lbrace'>{</span> <span class='op'>|</span><span class='id identifier rubyid_total'>total</span><span class='comma'>,</span> <span class='id identifier rubyid_order'>order</span><span class='op'>|</span> <span class='id identifier rubyid_order'>order</span><span class='period'>.</span><span class='id identifier rubyid_shipped_on'>shipped_on</span> <span class='op'>?</span> <span class='id identifier rubyid_total'>total</span> <span class='op'>:</span> <span class='id identifier rubyid_total'>total</span> <span class='op'>+</span> <span class='id identifier rubyid_order'>order</span><span class='period'>.</span><span class='id identifier rubyid_total_cost'>total_cost</span> <span class='rbrace'>}</span>
<span class='kw'>end</span>
<span class='kw'>end</span>
<span class='kw'>end</span>
<span class='id identifier rubyid_require'>require</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>test/unit</span><span class='tstring_end'>'</span></span>
<span class='id identifier rubyid_require'>require</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>mocha/test_unit</span><span class='tstring_end'>'</span></span>
<span class='kw'>class</span> <span class='const'>OrderTest</span> <span class='op'><</span> <span class='const'>Test</span><span class='op'>::</span><span class='const'>Unit</span><span class='op'>::</span><span class='const'>TestCase</span>
<span class='comment'># illustrates stubbing instance method
</span> <span class='kw'>def</span> <span class='id identifier rubyid_test_should_calculate_shipping_cost_based_on_total_weight'>test_should_calculate_shipping_cost_based_on_total_weight</span>
<span class='id identifier rubyid_order'>order</span> <span class='op'>=</span> <span class='const'>Order</span><span class='period'>.</span><span class='id identifier rubyid_new'>new</span>
<span class='id identifier rubyid_order'>order</span><span class='period'>.</span><span class='id identifier rubyid_stubs'>stubs</span><span class='lparen'>(</span><span class='symbol'>:total_weight</span><span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_returns'>returns</span><span class='lparen'>(</span><span class='int'>10</span><span class='rparen'>)</span>
<span class='id identifier rubyid_assert_equal'>assert_equal</span> <span class='int'>60</span><span class='comma'>,</span> <span class='id identifier rubyid_order'>order</span><span class='period'>.</span><span class='id identifier rubyid_shipping_cost'>shipping_cost</span>
<span class='kw'>end</span>
<span class='comment'># illustrates stubbing class method
</span> <span class='kw'>def</span> <span class='id identifier rubyid_test_should_count_number_of_orders_shipped_after_specified_date'>test_should_count_number_of_orders_shipped_after_specified_date</span>
<span class='id identifier rubyid_now'>now</span> <span class='op'>=</span> <span class='const'>Time</span><span class='period'>.</span><span class='id identifier rubyid_now'>now</span><span class='semicolon'>;</span> <span class='id identifier rubyid_week_in_secs'>week_in_secs</span> <span class='op'>=</span> <span class='int'>7</span> <span class='op'>*</span> <span class='int'>24</span> <span class='op'>*</span> <span class='int'>60</span> <span class='op'>*</span> <span class='int'>60</span>
<span class='id identifier rubyid_order_1'>order_1</span> <span class='op'>=</span> <span class='const'>Order</span><span class='period'>.</span><span class='id identifier rubyid_new'>new</span><span class='semicolon'>;</span> <span class='id identifier rubyid_order_1'>order_1</span><span class='period'>.</span><span class='id identifier rubyid_shipped_on'>shipped_on</span> <span class='op'>=</span> <span class='id identifier rubyid_now'>now</span> <span class='op'>-</span> <span class='int'>1</span> <span class='op'>*</span> <span class='id identifier rubyid_week_in_secs'>week_in_secs</span>
<span class='id identifier rubyid_order_2'>order_2</span> <span class='op'>=</span> <span class='const'>Order</span><span class='period'>.</span><span class='id identifier rubyid_new'>new</span><span class='semicolon'>;</span> <span class='id identifier rubyid_order_2'>order_2</span><span class='period'>.</span><span class='id identifier rubyid_shipped_on'>shipped_on</span> <span class='op'>=</span> <span class='id identifier rubyid_now'>now</span> <span class='op'>-</span> <span class='int'>3</span> <span class='op'>*</span> <span class='id identifier rubyid_week_in_secs'>week_in_secs</span>
<span class='const'>Order</span><span class='period'>.</span><span class='id identifier rubyid_stubs'>stubs</span><span class='lparen'>(</span><span class='symbol'>:find_all</span><span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_returns'>returns</span><span class='lparen'>(</span><span class='lbracket'>[</span><span class='id identifier rubyid_order_1'>order_1</span><span class='comma'>,</span> <span class='id identifier rubyid_order_2'>order_2</span><span class='rbracket'>]</span><span class='rparen'>)</span>
<span class='id identifier rubyid_assert_equal'>assert_equal</span> <span class='int'>1</span><span class='comma'>,</span> <span class='const'>Order</span><span class='period'>.</span><span class='id identifier rubyid_number_shipped_since'>number_shipped_since</span><span class='lparen'>(</span><span class='id identifier rubyid_now'>now</span> <span class='op'>-</span> <span class='int'>2</span> <span class='op'>*</span> <span class='id identifier rubyid_week_in_secs'>week_in_secs</span><span class='rparen'>)</span>
<span class='kw'>end</span>
<span class='comment'># illustrates stubbing instance method for all instances of a class
</span> <span class='kw'>def</span> <span class='id identifier rubyid_test_should_calculate_value_of_unshipped_orders'>test_should_calculate_value_of_unshipped_orders</span>
<span class='const'>Order</span><span class='period'>.</span><span class='id identifier rubyid_stubs'>stubs</span><span class='lparen'>(</span><span class='symbol'>:find_all</span><span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_returns'>returns</span><span class='lparen'>(</span><span class='lbracket'>[</span><span class='const'>Order</span><span class='period'>.</span><span class='id identifier rubyid_new'>new</span><span class='comma'>,</span> <span class='const'>Order</span><span class='period'>.</span><span class='id identifier rubyid_new'>new</span><span class='comma'>,</span> <span class='const'>Order</span><span class='period'>.</span><span class='id identifier rubyid_new'>new</span><span class='rbracket'>]</span><span class='rparen'>)</span>
<span class='const'>Order</span><span class='period'>.</span><span class='id identifier rubyid_any_instance'>any_instance</span><span class='period'>.</span><span class='id identifier rubyid_stubs'>stubs</span><span class='lparen'>(</span><span class='symbol'>:shipped_on</span><span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_returns'>returns</span><span class='lparen'>(</span><span class='kw'>nil</span><span class='rparen'>)</span>
<span class='const'>Order</span><span class='period'>.</span><span class='id identifier rubyid_any_instance'>any_instance</span><span class='period'>.</span><span class='id identifier rubyid_stubs'>stubs</span><span class='lparen'>(</span><span class='symbol'>:total_cost</span><span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_returns'>returns</span><span class='lparen'>(</span><span class='int'>10</span><span class='rparen'>)</span>
<span class='id identifier rubyid_assert_equal'>assert_equal</span> <span class='int'>30</span><span class='comma'>,</span> <span class='const'>Order</span><span class='period'>.</span><span class='id identifier rubyid_unshipped_value'>unshipped_value</span>
<span class='kw'>end</span>
<span class='kw'>end</span>
</code></pre>
<h3 id="thread-safety">Thread safety</h3>
<p>Mocha currently <em>does not</em> attempt to be thread-safe.</p>
<h4 id="can-i-test-multi-threaded-code-with-mocha">Can I test multi-threaded code with Mocha?</h4>
<p>The short answer is no. In multi-threaded code Mocha exceptions may be raised in a thread other than the one which is running the test and thus a Mocha exception may not be correctly intercepted by Mocha exception handling code.</p>
<h4 id="can-i-run-my-tests-across-multiple-threads">Can I run my tests across multiple threads?</h4>
<p>Maybe, but probably not. Partial mocking changes the state of objects in the <code>ObjectSpace</code> which is shared across all threads in the Ruby process and this access to what is effectively global state is not synchronized. So, for example, if two tests are running concurrently and one uses <code>#any_instance</code> to modify a class, both tests will see those changes immediately.</p>
<h3 id="expectation-matching-invocation-order">Expectation matching / invocation order</h3>
<p>Stubs and expectations are basically the same thing. A stub is just an expectation of zero or more invocations. The <code>Expectation#stubs</code> method is syntactic sugar to make the intent of the test more explicit.</p>
<p>When a method is invoked on a mock object, the mock object searches through its expectations from newest to oldest to find one that matches the invocation. After the invocation, the matching expectation might stop matching further invocations.</p>
<p>See the <a href="https://mocha.jamesmead.org/Mocha/Mock.html">documentation</a> for <code>Mocha::Mock</code> for further details.</p>
<h3 id="configuration">Configuration</h3>
<p>If you want, Mocha can generate a warning or raise an exception when:</p>
<ul>
<li>stubbing a method unnecessarily</li>
<li>stubbing method on a non-mock object</li>
<li>stubbing a non-existent method</li>
<li>stubbing a non-public method</li>
</ul>
<p>See the <a href="https://mocha.jamesmead.org/Mocha/Configuration.html">documentation</a> for <code>Mocha::Configuration</code> for further details.</p>
<h5 id="mocha_options">MOCHA_OPTIONS</h5>
<p><code>MOCHA_OPTIONS</code> is an environment variable whose value can be set to a comma-separated list, so that we can specify multiple options e.g. <code>MOCHA_OPTIONS=debug,use_test_unit_gem</code>.
Only the following values are currently recognized and have an effect:</p>
<ul>
<li><code>debug</code>: Enables a debug mode which will output backtraces for each deprecation warning. This is useful for finding where in the test suite the deprecated calls are.</li>
</ul>
<h3 id="semantic-versioning">Semantic versioning</h3>
<ul>
<li>Every effort is made to comply with <a href="https://semver.org/">semantic versioning</a>.</li>
<li>However, this only applies to the behaviour documented in the public API.</li>
<li>The documented public API does <em>not</em> include the content or format of messsages displayed to the user, e.g. assertion failure messages.</li>
</ul>
<h3 id="useful-links">Useful Links</h3>
<ul>
<li><a href="https://mocha.jamesmead.org">Official Documentation</a></li>
<li><a href="http://github.com/freerange/mocha">Source Code</a></li>
<li><a href="http://groups.google.com/group/mocha-developer">Mailing List</a></li>
<li><a href="http://jamesmead.org/blog/">James Mead's Blog</a></li>
<li><a href="http://jamesmead.org/talks/2007-07-09-introduction-to-mock-objects-in-ruby-at-lrug/">An Introduction To Mock Objects In Ruby</a></li>
<li><a href="http://martinfowler.com/articles/mocksArentStubs.html">Mocks Aren't Stubs</a></li>
<li><a href="http://www.growing-object-oriented-software.com/">Growing Object-Oriented Software Guided By Tests</a></li>
<li><a href="http://www.jmock.org/oopsla2004.pdf">Mock Roles Not Objects</a></li>
<li><a href="http://www.jmock.org/">jMock</a></li>
</ul>
<h3 id="contributors">Contributors</h3>
<p>See this <a href="https://github.com/freerange/mocha/graphs/contributors">list of contributors</a>.</p>
<h3 id="releasing-a-new-version">Releasing a new version</h3>
<ul>
<li>Update the RELEASE.md file with a summary of changes</li>
<li>Bump the version in <code>lib/mocha/version.rb</code></li>
<li>Commit & push to GitHub</li>
<li><p>Check CircleCI build is passing - <a href="https://app.circleci.com/pipelines/github/freerange/mocha">https://app.circleci.com/pipelines/github/freerange/mocha</a></p></li>
<li><p>Generate documentation:</p></li>
</ul>
<pre class="code bash"><code class="bash">$ MOCHA_GENERATE_DOCS=true bundle install
$ MOCHA_GENERATE_DOCS=true rake generate_docs
</code></pre>
<ul>
<li>Commit documentation & push to GitHub</li>
<li>Sign in to rubygems.org and find API key - <a href="https://rubygems.org/profile/edit">https://rubygems.org/profile/edit</a></li>
</ul>
<pre class="code bash"><code class="bash">$ curl -u <email-address> -H 'OTP:<one-time-password>' https://rubygems.org/api/v1/api_key.yaml > ~/.gem/credentials; chmod 0600 ~/.gem/credentials
</code></pre>
<ul>
<li>Release gem to Rubygems:</li>
</ul>
<pre class="code bash"><code class="bash">$ rake release
[runs tests]
mocha 1.2.0 built to pkg/mocha-1.2.0.gem.
Tagged v1.2.0.
Pushed git commits and tags.
Pushed mocha 1.2.0 to rubygems.org.
</code></pre>
<h3 id="history">History</h3>
<p>Mocha was initially harvested from projects at <a href="http://www.reevoo.com/">Reevoo</a>. It's syntax is heavily based on that of <a href="http://www.jmock.org">jMock</a>.</p>
<h3 id="license">License</h3>
<p>© Copyright James Mead 2006</p>
<p>You may use, copy and redistribute this library under the same terms as <a href="https://www.ruby-lang.org/en/about/license.txt">Ruby itself</a> or under the <a href="https://mit-license.org/">MIT license</a>.</p>
</div></div>
<div id="footer">
Generated on Thu Jul 18 09:24:57 2024 by
<a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
0.9.36 (ruby-3.2.0).
</div>
</div>
</body>
</html>
|
