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
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
|
<html>
<head>
<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>SimpleTest for PHP mock objects documentation</title>
<link rel="stylesheet" type="text/css" href="docs.css" title="Styles">
</head>
<body>
<div class="menu_back">
<div class="menu">
<h2>
<a href="index.html">SimpleTest</a>
</h2>
<ul>
<li>
<a href="overview.html">Overview</a>
</li>
<li>
<a href="unit_test_documentation.html">Unit tester</a>
</li>
<li>
<a href="group_test_documentation.html">Group tests</a>
</li>
<li>
<span class="chosen">Mock objects</span>
</li>
<li>
<a href="partial_mocks_documentation.html">Partial mocks</a>
</li>
<li>
<a href="reporter_documentation.html">Reporting</a>
</li>
<li>
<a href="expectation_documentation.html">Expectations</a>
</li>
<li>
<a href="web_tester_documentation.html">Web tester</a>
</li>
<li>
<a href="form_testing_documentation.html">Testing forms</a>
</li>
<li>
<a href="authentication_documentation.html">Authentication</a>
</li>
<li>
<a href="browser_documentation.html">Scriptable browser</a>
</li>
</ul>
</div>
</div>
<h1>Mock objects documentation</h1>
<div class="content">
<p>
<a class="target" name="what">
<h2>What are mock objects?</h2>
</a>
</p>
<p>
Mock objects have two roles during a test case: actor and critic.
</p>
<p>
The actor behaviour is to simulate objects that are difficult to
set up or time consuming to set up for a test.
The classic example is a database connection.
Setting up a test database at the start of each test would slow
testing to a crawl and would require the installation of the
database engine and test data on the test machine.
If we can simulate the connection and return data of our
choosing we not only win on the pragmatics of testing, but can
also feed our code spurious data to see how it responds.
We can simulate databases being down or other extremes
without having to create a broken database for real.
In other words, we get greater control of the test environment.
</p>
<p>
If mock objects only behaved as actors they would simply be
known as server stubs.
This was originally a pattern named by Robert Binder (Testing
object-oriented systems: models, patterns, and tools,
Addison-Wesley) in 1999.
</p>
<p>
A server stub is a simulation of an object or component.
It should exactly replace a component in a system for test
or prototyping purposes, but remain lightweight.
This allows tests to run more quickly, or if the simulated
class has not been written, to run at all.
</p>
<p>
However, the mock objects not only play a part (by supplying chosen
return values on demand) they are also sensitive to the
messages sent to them (via expectations).
By setting expected parameters for a method call they act
as a guard that the calls upon them are made correctly.
If expectations are not met they save us the effort of
writing a failed test assertion by performing that duty on our
behalf.
</p>
<p>
In the case of an imaginary database connection they can
test that the query, say SQL, was correctly formed by
the object that is using the connection.
Set them up with fairly tight expectations and you will
hardly need manual assertions at all.
</p>
<p>
<a class="target" name="creation">
<h2>Creating mock objects</h2>
</a>
</p>
<p>
In the same way that we create server stubs, all we need is an
existing class, say a database connection that looks like this...
<pre>
<strong>class DatabaseConnection {
function DatabaseConnection() {
}
function query() {
}
function selectQuery() {
}
}</strong>
</pre>
The class does not need to have been implemented yet.
To create a mock version of the class we need to include the
mock object library and run the generator...
<pre>
<strong>require_once('simpletest/unit_tester.php');
require_once('simpletest/mock_objects.php');
require_once('database_connection.php');
Mock::generate('DatabaseConnection');</strong>
</pre>
This generates a clone class called
<span class="new_code">MockDatabaseConnection</span>.
We can now create instances of the new class within
our test case...
<pre>
require_once('simpletest/unit_tester.php');
require_once('simpletest/mock_objects.php');
require_once('database_connection.php');
Mock::generate('DatabaseConnection');
<strong>
class MyTestCase extends UnitTestCase {
function testSomething() {
$connection = &new MockDatabaseConnection();
}
}</strong>
</pre>
Unlike the generated stubs the mock constructor needs a reference
to the test case so that it can dispatch passes and failures while
checking its expectations.
This means that mock objects can only be used within test cases.
Despite this their extra power means that stubs are hardly ever used
if mocks are available.
</p>
<p>
<a class="target" name="stub">
<h2>Mocks as actors</h2>
</a>
</p>
<p>
The mock version of a class has all the methods of the original,
so that operations like
<span class="new_code">$connection->query()</span> are still
legal.
The return value will be <span class="new_code">null</span>,
but we can change that with...
<pre>
<strong>$connection->setReturnValue('query', 37)</strong>
</pre>
Now every time we call
<span class="new_code">$connection->query()</span> we get
the result of 37.
We can set the return value to anything, say a hash of
imaginary database results or a list of persistent objects.
Parameters are irrelevant here, we always get the same
values back each time once they have been set up this way.
That may not sound like a convincing replica of a
database connection, but for the half a dozen lines of
a test method it is usually all you need.
</p>
<p>
We can also add extra methods to the mock when generating it
and choose our own class name...
<pre>
<strong>Mock::generate('DatabaseConnection', 'MyMockDatabaseConnection', array('setOptions'));</strong>
</pre>
Here the mock will behave as if the <span class="new_code">setOptions()</span>
existed in the original class.
This is handy if a class has used the PHP <span class="new_code">overload()</span>
mechanism to add dynamic methods.
You can create a special mock to simulate this situation.
</p>
<p>
Things aren't always that simple though.
One common problem is iterators, where constantly returning
the same value could cause an endless loop in the object
being tested.
For these we need to set up sequences of values.
Let's say we have a simple iterator that looks like this...
<pre>
class Iterator {
function Iterator() {
}
function next() {
}
}
</pre>
This is about the simplest iterator you could have.
Assuming that this iterator only returns text until it
reaches the end, when it returns false, we can simulate it
with...
<pre>
Mock::generate('Iterator');
class IteratorTest extends UnitTestCase() {
function testASequence() {<strong>
$iterator = &new MockIterator();
$iterator->setReturnValue('next', false);
$iterator->setReturnValueAt(0, 'next', 'First string');
$iterator->setReturnValueAt(1, 'next', 'Second string');</strong>
...
}
}
</pre>
When <span class="new_code">next()</span> is called on the
mock iterator it will first return "First string",
on the second call "Second string" will be returned
and on any other call <span class="new_code">false</span> will
be returned.
The sequenced return values take precedence over the constant
return value.
The constant one is a kind of default if you like.
</p>
<p>
Another tricky situation is an overloaded
<span class="new_code">get()</span> operation.
An example of this is an information holder with name/value pairs.
Say we have a configuration class like...
<pre>
class Configuration {
function Configuration() {
}
function getValue($key) {
}
}
</pre>
This is a classic situation for using mock objects as
actual configuration will vary from machine to machine,
hardly helping the reliability of our tests if we use it
directly.
The problem though is that all the data comes through the
<span class="new_code">getValue()</span> method and yet
we want different results for different keys.
Luckily the mocks have a filter system...
<pre>
<strong>$config = &new MockConfiguration();
$config->setReturnValue('getValue', 'primary', array('db_host'));
$config->setReturnValue('getValue', 'admin', array('db_user'));
$config->setReturnValue('getValue', 'secret', array('db_password'));</strong>
</pre>
The extra parameter is a list of arguments to attempt
to match.
In this case we are trying to match only one argument which
is the look up key.
Now when the mock object has the
<span class="new_code">getValue()</span> method invoked
like this...
<pre>
$config->getValue('db_user')
</pre>
...it will return "admin".
It finds this by attempting to match the calling arguments
to its list of returns one after another until
a complete match is found.
</p>
<p>
You can set a default argument argument like so...
<pre>
<strong>
$config->setReturnValue('getValue', false, array('*'));</strong>
</pre>
This is not the same as setting the return value without
any argument requirements like this...
<pre>
<strong>
$config->setReturnValue('getValue', false);</strong>
</pre>
In the first case it will accept any single argument,
but exactly one is required.
In the second case any number of arguments will do and
it acts as a catchall after all other matches.
Note that if we add further single parameter options after
the wildcard in the first case, they will be ignored as the wildcard
will match first.
With complex parameter lists the ordering could be important
or else desired matches could be masked by earlier wildcard
ones.
Declare the most specific matches first if you are not sure.
</p>
<p>
There are times when you want a specific object to be
dished out by the mock rather than a copy.
The PHP4 copy semantics force us to use a different method
for this.
You might be simulating a container for example...
<pre>
class Thing {
}
class Vector {
function Vector() {
}
function get($index) {
}
}
</pre>
In this case you can set a reference into the mock's
return list...
<pre>
$thing = &new Thing();<strong>
$vector = &new MockVector();
$vector->setReturnReference('get', $thing, array(12));</strong>
</pre>
With this arrangement you know that every time
<span class="new_code">$vector->get(12)</span> is
called it will return the same
<span class="new_code">$thing</span> each time.
This is compatible with PHP5 as well.
</p>
<p>
These three factors, timing, parameters and whether to copy,
can be combined orthogonally.
For example...
<pre>
$complex = &new MockComplexThing();
$stuff = &new Stuff();<strong>
$complex->setReturnReferenceAt(3, 'get', $stuff, array('*', 1));</strong>
</pre>
This will return the <span class="new_code">$stuff</span> only on the third
call and only if two parameters were set the second of
which must be the integer 1.
That should cover most simple prototyping situations.
</p>
<p>
A final tricky case is one object creating another, known
as a factory pattern.
Suppose that on a successful query to our imaginary
database, a result set is returned as an iterator with
each call to <span class="new_code">next()</span> giving
one row until false.
This sounds like a simulation nightmare, but in fact it can all
be mocked using the mechanics above.
</p>
<p>
Here's how...
<pre>
Mock::generate('DatabaseConnection');
Mock::generate('ResultIterator');
class DatabaseTest extends UnitTestCase {
function testUserFinder() {<strong>
$result = &new MockResultIterator();
$result->setReturnValue('next', false);
$result->setReturnValueAt(0, 'next', array(1, 'tom'));
$result->setReturnValueAt(1, 'next', array(3, 'dick'));
$result->setReturnValueAt(2, 'next', array(6, 'harry'));
$connection = &new MockDatabaseConnection();
$connection->setReturnValue('query', false);
$connection->setReturnReference(
'query',
$result,
array('select id, name from users'));</strong>
$finder = &new UserFinder($connection);
$this->assertIdentical(
$finder->findNames(),
array('tom', 'dick', 'harry'));
}
}
</pre>
Now only if our
<span class="new_code">$connection</span> is called with the correct
<span class="new_code">query()</span> will the
<span class="new_code">$result</span> be returned that is
itself exhausted after the third call to <span class="new_code">next()</span>.
This should be enough
information for our <span class="new_code">UserFinder</span> class,
the class actually
being tested here, to come up with goods.
A very precise test and not a real database in sight.
</p>
<p>
<a class="target" name="expectations">
<h2>Mocks as critics</h2>
</a>
</p>
<p>
Although the server stubs approach insulates your tests from
real world disruption, it is only half the benefit.
You can have the class under test receiving the required
messages, but is your new class sending correct ones?
Testing this can get messy without a mock objects library.
</p>
<p>
By way of example, suppose we have a
<span class="new_code">SessionPool</span> class that we
want to add logging to.
Rather than grow the original class into something more
complicated, we want to add this behaviour with a decorator (GOF).
The <span class="new_code">SessionPool</span> code currently looks
like this...
<pre>
<strong>class SessionPool {
function SessionPool() {
...
}
function &findSession($cookie) {
...
}
...
}
class Session {
...
}</strong>
</php>
While our logging code looks like this...
<php><strong>
class Log {
function Log() {
...
}
function message() {
...
}
}
class LoggingSessionPool {
function LoggingSessionPool(&$session_pool, &$log) {
...
}
function &findSession(\$cookie) {
...
}
...
}</strong>
</pre>
Out of all of this, the only class we want to test here
is the <span class="new_code">LoggingSessionPool</span>.
In particular we would like to check that the
<span class="new_code">findSession()</span> method is
called with the correct session ID in the cookie and that
it sent the message "Starting session $cookie"
to the logger.
</p>
<p>
Despite the fact that we are testing only a few lines of
production code, here is what we would have to do in a
conventional test case:
<ol>
<li>Create a log object.</li>
<li>Set a directory to place the log file.</li>
<li>Set the directory permissions so we can write the log.</li>
<li>Create a <span class="new_code">SessionPool</span> object.</li>
<li>Hand start a session, which probably does lot's of things.</li>
<li>Invoke <span class="new_code">findSession()</span>.</li>
<li>Read the new Session ID (hope there is an accessor!).</li>
<li>Raise a test assertion to confirm that the ID matches the cookie.</li>
<li>Read the last line of the log file.</li>
<li>Pattern match out the extra logging timestamps, etc.</li>
<li>Assert that the session message is contained in the text.</li>
</ol>
It is hardly surprising that developers hate writing tests
when they are this much drudgery.
To make things worse, every time the logging format changes or
the method of creating new sessions changes, we have to rewrite
parts of this test even though this test does not officially
test those parts of the system.
We are creating headaches for the writers of these other classes.
</p>
<p>
Instead, here is the complete test method using mock object magic...
<pre>
Mock::generate('Session');
Mock::generate('SessionPool');
Mock::generate('Log');
class LoggingSessionPoolTest extends UnitTestCase {
...
function testFindSessionLogging() {<strong>
$session = &new MockSession();
$pool = &new MockSessionPool();
$pool->setReturnReference('findSession', $session);
$pool->expectOnce('findSession', array('abc'));
$log = &new MockLog();
$log->expectOnce('message', array('Starting session abc'));
$logging_pool = &new LoggingSessionPool($pool, $log);
$this->assertReference($logging_pool->findSession('abc'), $session);</strong>
}
}
</pre>
We start by creating a dummy session.
We don't have to be too fussy about this as the check
for which session we want is done elsewhere.
We only need to check that it was the same one that came
from the session pool.
</p>
<p>
<span class="new_code">findSession()</span> is a factory
method the simulation of which is described <a href="#stub">above</a>.
The point of departure comes with the first
<span class="new_code">expectOnce()</span> call.
This line states that whenever
<span class="new_code">findSession()</span> is invoked on the
mock, it will test the incoming arguments.
If it receives the single argument of a string "abc"
then a test pass is sent to the unit tester, otherwise a fail is
generated.
This was the part where we checked that the right session was asked for.
The argument list follows the same format as the one for setting
return values.
You can have wildcards and sequences and the order of
evaluation is the same.
</p>
<p>
We use the same pattern to set up the mock logger.
We tell it that it should have
<span class="new_code">message()</span> invoked
once only with the argument "Starting session abc".
By testing the calling arguments, rather than the logger output,
we insulate the test from any display changes in the logger.
</p>
<p>
We start to run our tests when we create the new
<span class="new_code">LoggingSessionPool</span> and feed
it our preset mock objects.
Everything is now under our control.
</p>
<p>
This is still quite a bit of test code, but the code is very
strict.
If it still seems rather daunting there is a lot less of it
than if we tried this without mocks and this particular test,
interactions rather than output, is always more work to set
up.
More often you will be testing more complex situations without
needing this level or precision.
Also some of this can be refactored into a test case
<span class="new_code">setUp()</span> method.
</p>
<p>
Here is the full list of expectations you can set on a mock object
in <a href="http://www.lastcraft.com/simple_test.php">SimpleTest</a>...
<table>
<thead>
<tr>
<th>Expectation</th><th>Needs <span class="new_code">tally()</span></th>
</tr>
</thead>
<tbody>
<tr>
<td><span class="new_code">expect($method, $args)</span></td>
<td style="text-align: center">No</td>
</tr>
<tr>
<td><span class="new_code">expectAt($timing, $method, $args)</span></td>
<td style="text-align: center">No</td>
</tr>
<tr>
<td><span class="new_code">expectCallCount($method, $count)</span></td>
<td style="text-align: center">Yes</td>
</tr>
<tr>
<td><span class="new_code">expectMaximumCallCount($method, $count)</span></td>
<td style="text-align: center">No</td>
</tr>
<tr>
<td><span class="new_code">expectMinimumCallCount($method, $count)</span></td>
<td style="text-align: center">Yes</td>
</tr>
<tr>
<td><span class="new_code">expectNever($method)</span></td>
<td style="text-align: center">No</td>
</tr>
<tr>
<td><span class="new_code">expectOnce($method, $args)</span></td>
<td style="text-align: center">Yes</td>
</tr>
<tr>
<td><span class="new_code">expectAtLeastOnce($method, $args)</span></td>
<td style="text-align: center">Yes</td>
</tr>
</tbody>
</table>
Where the parameters are...
<dl>
<dt class="new_code">$method</dt>
<dd>The method name, as a string, to apply the condition to.</dd>
<dt class="new_code">$args</dt>
<dd>
The arguments as a list. Wildcards can be included in the same
manner as for <span class="new_code">setReturn()</span>.
This argument is optional for <span class="new_code">expectOnce()</span>
and <span class="new_code">expectAtLeastOnce()</span>.
</dd>
<dt class="new_code">$timing</dt>
<dd>
The only point in time to test the condition.
The first call starts at zero.
</dd>
<dt class="new_code">$count</dt>
<dd>The number of calls expected.</dd>
</dl>
The method <span class="new_code">expectMaximumCallCount()</span>
is slightly different in that it will only ever generate a failure.
It is silent if the limit is never reached.
</p>
<p>
Like the assertions within test cases, all of the expectations
can take a message override as an extra parameter.
Also the original failure message can be embedded in the output
as "%s".
</p>
<p>
<a class="target" name="approaches">
<h2>Other approaches</h2>
</a>
</p>
<p>
There are three approaches to creating mocks including the one
that SimpleTest employs.
Coding them by hand using a base class, generating them to
a file and dynamically generating them on the fly.
</p>
<p>
Mock objects generated with <a href="simple_test.html">SimpleTest</a>
are dynamic.
They are created at run time in memory, using
<span class="new_code">eval()</span>, rather than written
out to a file.
This makes the mocks easy to create, a one liner,
especially compared with hand
crafting them in a parallel class hierarchy.
The problem is that the behaviour is usually set up in the tests
themselves.
If the original objects change the mock versions
that the tests rely on can get out of sync.
This can happen with the parallel hierarchy approach as well,
but is far more quickly detected.
</p>
<p>
The solution, of course, is to add some real integration
tests.
You don't need very many and the convenience gained
from the mocks more than outweighs the small amount of
extra testing.
You cannot trust code that was only tested with mocks.
</p>
<p>
If you are still determined to build static libraries of mocks
because you want to simulate very specific behaviour, you can
achieve the same effect using the SimpleTest class generator.
In your library file, say <em>mocks/connection.php</em> for a
database connection, create a mock and inherit to override
special methods or add presets...
<pre>
<?php
require_once('simpletest/mock_objects.php');
require_once('../classes/connection.php');
<strong>
Mock::generate('Connection', 'BasicMockConnection');
class MockConnection extends BasicMockConnection {
function MockConnection() {
$this->BasicMockConnection();
$this->setReturn('query', false);
}
}</strong>
?>
</pre>
The generate call tells the class generator to create
a class called <span class="new_code">BasicMockConnection</span>
rather than the usual <span class="new_code">MockConnection</span>.
We then inherit from this to get our version of
<span class="new_code">MockConnection</span>.
By intercepting in this way we can add behaviour, here setting
the default value of <span class="new_code">query()</span> to be false.
By using the default name we make sure that the mock class
generator will not recreate a different one when invoked elsewhere in the
tests.
It never creates a class if it already exists.
As long as the above file is included first then all tests
that generated <span class="new_code">MockConnection</span> should
now be using our one instead.
If we don't get the order right and the mock library
creates one first then the class creation will simply fail.
</p>
<p>
Use this trick if you find you have a lot of common mock behaviour
or you are getting frequent integration problems at later
stages of testing.
</p>
</div>
<div class="copyright">
Copyright<br>Marcus Baker, Jason Sweat, Perrick Penet 2004
</div>
</body>
</html>
|
