| 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 |
|