Debian Codegraph @

README

raw
1 NAME
2
3 Test::ExpectAndCheck - expect/check-style unit testing with object
4 methods
5
6 SYNOPSIS
7
8 use Test::More;
9 use Test::ExpectAndCheck;
10
11 my ( $controller, $mock ) = Test::ExpectAndCheck->create;
12
13 {
14 $controller->expect( act => 123, 45 )
15 ->will_return( 678 );
16
17 is( $mock->act( 123, 45 ), 678, '$mock->act returns result' );
18
19 $controller->check_and_clear( '->act' );
20 }
21
22 done_testing;
23
24 DESCRIPTION
25
26 This package creates objects that assist in writing unit tests with
27 mocked object instances. Each mock instance will expect to receive a
28 given list of method calls. Each method call is checked that it
29 received the right arguments, and will return a prescribed result. At
30 the end of each test, each object is checked to ensure all the expected
31 methods were called.
32
33 Verbose Mode
34
35 Sometimes when debugging a failing test it can be useful to see a log
36 of which expectations have been called. By setting the $VERBOSE package
37 variable to a true value, extra printing will happen during the test.
38
39 {
40 local $Test::ExpectAndCheck::VERBOSE = 1;
41
42 $controller->expect( ... );
43
44 ...
45 }
46
47 This is printed directly to STDERR and is intended for temporary
48 debugging during development.
49
50 METHODS
51
52 create
53
54 ( $controller, $mock ) = Test::ExpectAndCheck->create( %params );
55
56 Objects are created in "entangled pairs" by the create method. The
57 first object is called the "controller", and is used by the unit
58 testing script to set up what method calls are to be expected, and what
59 their results shall be. The second object is the "mock", the object to
60 be passed to the code being tested, on which the expected method calls
61 are (hopefully) invoked. It will have whatever interface is implied by
62 the method call expectations.
63
64 Takes the following optional named parameters:
65
66 isa
67
68 isa => [qw( Some Class Names )],
69
70 Since version 0.08.
71
72 Specifies a list of class names that the mock object will claim to be
73 if interrogated by its isa method. This is useful if the code under
74 test will use an ->isa check on the passed-in mocking object and
75 therefore it needs to pretend to be of some particular class.
76
77 Note though that no actual method inheritence will take place here.
78 This simply provides the isa method. Any actual required behaviour
79 will still have to be created using the "expect" or "whenever"
80 methods as usual.
81
82 expect
83
84 $exp = $controller->expect( $method, @args );
85
86 Specifies that the mock will expect to receive a method call of the
87 given name, with the given arguments.
88
89 The argument values are compared using "cmp_deeply" in Test::Deep.
90 Values can be specified literally, or using any of the "Special
91 Comparisons" defined by Test::Deep. Additionally, the "namedargs"
92 function listed below can also appear as the final argument test.
93
94 The test script can call the "will_return" or "will_throw" methods on
95 the expectation to set what the result of invoking this method will be.
96
97 whenever
98
99 $exp = $controller->whenever( $method, @args );
100
101 Since version 0.05.
102
103 Specifies that the mock might expect to receive method calls of the
104 given name with the given arguments. These expectations are not expired
105 once called, nor do they expect to be called in any particular order.
106 Furthermore it is not a test failure for one of these not to be invoked
107 at all.
108
109 These expectations do not directly form part of the test assertions
110 checked by the "check_and_clear" method, but they may be useful to
111 assist the code under test, such as providing support behaviours that
112 it may rely on but would make the test script too fragile if spelled
113 out in full using a regular expect.
114
115 These expectations are only used as a fallback mechanism, if the next
116 real expect-based expectation does not match a method call. Individual
117 special cases can still be set up using expect even though a whenever
118 exists that might also match it.
119
120 As with "expect", the argument values are compared using Test::Deep,
121 and results can be set with "will_return" or "will_throw".
122
123 check_and_clear
124
125 $controller->check_and_clear( $name );
126
127 Checks that by now, every expected method has been called, and emits a
128 new test output line via Test::Builder. Regardless, the expectations
129 are also cleared out ready for the start of the next test.
130
131 FUNCTIONS
132
133 namedargs
134
135 $cmp = namedargs(name => $val, ...)
136
137 Since version 0.07.
138
139 This exportable function may be used as the final argument to an
140 "expect" or "whenever" expectation, to indicate that all of the
141 remaining arguments passed at that position should be treated like
142 named parameters in a list of key/value pairs. This makes then
143 insensitive to the order that the values are passed by the caller.
144
145 Each value given can be a literal value or a special comparison from
146 Test::Deep.
147
148 For example, this simple expectation will fail 50% of the time due to
149 hash order randomisation:
150
151 $controller->expect( m => x => "X", y => "Y" );
152
153 my %args = ( x => "X", y => "Y" );
154 $puppet->m( %args );
155
156 This is solved by using the namedargs() function.
157
158 use Test::ExpectAndCheck 'namedargs';
159
160 $controller->expect( m => namedargs(x => "X", y => "Y") );
161
162 Additionally, positional arguments may appear before this call.
163
164 $controller->expect( n => 1, 2, namedargs(x => "X", y => "Y") );
165 $puppet->n( $one, $two, %args );
166
167 EXPECTATIONS
168
169 Each value returned by the "expect" method is an "expectation", an
170 object that represents one expected method call, the arguments it
171 should receive, and the return value it should provide.
172
173 will_return
174
175 $exp->will_return( @result );
176
177 Since version 0.04.
178
179 Sets the result that will be returned by this method call.
180
181 This method used to be named returns, which should be avoided in new
182 code. Uses of the old name will print a deprecation warning.
183
184 will_return_using
185
186 $exp->will_return_using( sub ($args) { ... } );
187
188 Since version 0.05.
189
190 Sets the result that will be returned, calculated by invoking the code.
191
192 The code block is invoked at the time that a result is needed. It is
193 invoked with an array reference containing the arguments to the
194 original method call. This is especially useful for expectations
195 created using "whenever".
196
197 Since version 0.06 the code block is passed a reference to the caller's
198 actual arguments array, and therefore can modify values in it if
199 required - e.g. when trying to mock functions such as open() or
200 sysread() which modify lvalues passed in as arguments.
201
202 There is no corresponding will_throw_using, but an exception thrown by
203 this code will be seen by the calling code.
204
205 will_throw
206
207 $exp->will_throw( $e );
208
209 Since version 0.04.
210
211 Sets the exception that will be thrown by this method call.
212
213 This method used to be named throws, which should be avoided in new
214 code.
215
216 will_also
217
218 $exp->will_also( sub { ... } );
219
220 Since version 0.04.
221
222 Adds extra code which is run when the expected method is called, in
223 addition to generating the result value or exception.
224
225 When invoked, the code body is invoked in void context with no
226 additional arguments.
227
228 indefinitely
229
230 $exp->indefinitely;
231
232 Since version 0.05.
233
234 On an expectation created using "whenever", this expectation will not
235 be cleared by "check_and_clear", effectively establishing its effects
236 for the entire lifetime of the test script.
237
238 On an expectation created using "expect" this has no effect; such an
239 expectation will still be cleared as usual.
240
241 AUTHOR
242
243 Paul Evans <[email protected]>
244