1NAME
2 Test::Tester - Ease testing test modules built with Test::Builder
3
4SYNOPSIS
5 use Test::Tester tests => 6;
6
7 use Test::MyStyle;
8
9 check_test(
10 sub {
11 is_mystyle_eq("this", "that", "not eq");
12 },
13 {
14 ok => 0, # expect this to fail
15 name => "not eq",
16 diag => "Expected: 'this'\nGot: 'that'",
17 }
18 );
19
20 or
21
22 use Test::Tester;
23
24 use Test::More tests => 3;
25 use Test::MyStyle;
26
27 my ($premature, @results) = run_tests(
28 sub {
29 is_database_alive("dbname");
30 }
31 );
32
33 # now use Test::More::like to check the diagnostic output
34
35 like($results[0]->{diag}, "/^Database ping took \\d+ seconds$"/, "diag");
36
37DESCRIPTION
38 If you have written a test module based on Test::Builder then Test::Tester
39 allows you to test it with the minimum of effort.
40
41HOW TO USE (THE EASY WAY)
42 From version 0.08 Test::Tester no longer requires you to included anything
43 special in your test modules. All you need to do is
44
45 use Test::Tester;
46
47 in your test script before any other Test::Builder based modules and away
48 you go.
49
50 Other modules based on Test::Builder can be used to help with the testing.
51 In fact you can even use functions from your module to test other functions
52 from the same module (while this is possible it is probably not a good idea,
53 if your module has bugs, then using it to test itself may give the wrong
54 answers).
55
56 The easiest way to test is to do something like
57
58 check_test(
59 sub { is_mystyle_eq("this", "that", "not eq") },
60 {
61 ok => 0, # we expect the test to fail
62 name => "not eq",
63 diag => "Expected: 'this'\nGot: 'that'",
64 }
65 );
66
67 this will execute the is_mystyle_eq test, capturing it's results and
68 checking that they are what was expected.
69
70 You may need to examine the test results in a more flexible way, for
71 example, the diagnostic output may be quite long or complex or it may
72 involve something that you cannot predict in advance like a timestamp. In
73 this case you can get direct access to the test results:
74
75 my ($premature, @results) = run_tests(
76 sub {
77 is_database_alive("dbname");
78 }
79 );
80
81 like($result[0]->{diag}, "/^Database ping took \\d+ seconds$"/, "diag");
82
83 We cannot predict how long the database ping will take so we use
84 Test::More's like() test to check that the diagnostic string is of the right
85 form.
86
87HOW TO USE (THE HARD WAY)
88 *This is here for backwards compatibility only*
89
90 Make your module use the Test::Tester::Capture object instead of the
91 Test::Builder one. How to do this depends on your module but assuming that
92 your module holds the Test::Builder object in $Test and that all your test
93 routines access it through $Test then providing a function something like
94 this
95
96 sub set_builder
97 {
98 $Test = shift;
99 }
100
101 should allow your test scripts to do
102
103 Test::YourModule::set_builder(Test::Tester->capture);
104
105 and after that any tests inside your module will captured.
106
107TEST RESULTS
108 The result of each test is captured in a hash. These hashes are the same as
109 the hashes returned by Test::Builder->details but with a couple of extra
110 fields.
111
112 These fields are documented in Test::Builder in the details() function
113
114 ok
115 Did the test pass?
116
117 actual_ok
118 Did the test really pass? That is, did the pass come from
119 Test::Builder->ok() or did it pass because it was a TODO test?
120
121 name
122 The name supplied for the test.
123
124 type
125 What kind of test? Possibilities include, skip, todo etc. See
126 Test::Builder for more details.
127
128 reason
129 The reason for the skip, todo etc. See Test::Builder for more details.
130
131 These fields are exclusive to Test::Tester.
132
133 diag
134 Any diagnostics that were output for the test. This only includes
135 diagnostics output after the test result is declared.
136
137 Note that Test::Builder ensures that any diagnostics end in a \n and it in
138 earlier versions of Test::Tester it was essential that you have the final
139 \n in your expected diagnostics. From version 0.10 onwards, Test::Tester
140 will add the \n if you forgot it. It will not add a \n if you are
141 expecting no diagnostics. See below for help tracking down hard to find
142 space and tab related problems.
143
144 depth
145 This allows you to check that your test module is setting the correct
146 value for $Test::Builder::Level and thus giving the correct file and line
147 number when a test fails. It is calculated by looking at caller() and
148 $Test::Builder::Level. It should count how many subroutines there are
149 before jumping into the function you are testing. So for example in
150
151 run_tests( sub { my_test_function("a", "b") } );
152
153 the depth should be 1 and in
154
155 sub deeper { my_test_function("a", "b") }
156
157 run_tests(sub { deeper() });
158
159 depth should be 2, that is 1 for the sub {} and one for deeper(). This
160 might seem a little complex but if your tests look like the simple
161 examples in this doc then you don't need to worry as the depth will always
162 be 1 and that's what Test::Tester expects by default.
163
164 Note: if you do not specify a value for depth in check_test() then it
165 automatically compares it against 1, if you really want to skip the depth
166 test then pass in undef.
167
168 Note: depth will not be correctly calculated for tests that run from a
169 signal handler or an END block or anywhere else that hides the call stack.
170
171 Some of Test::Tester's functions return arrays of these hashes, just like
172 Test::Builder->details. That is, the hash for the first test will be array
173 element 1 (not 0). Element 0 will not be a hash it will be a string which
174 contains any diagnostic output that came before the first test. This should
175 usually be empty, if it's not, it means something output diagnostics before
176 any test results showed up.
177
178SPACES AND TABS
179 Appearances can be deceptive, especially when it comes to emptiness. If you
180 are scratching your head trying to work out why Test::Tester is saying that
181 your diagnostics are wrong when they look perfectly right then the answer is
182 probably whitespace. From version 0.10 on, Test::Tester surrounds the
183 expected and got diag values with single quotes to make it easier to spot
184 trailing whitesapce. So in this example
185
186 # Got diag (5 bytes):
187 # 'abcd '
188 # Expected diag (4 bytes):
189 # 'abcd'
190
191 it is quite clear that there is a space at the end of the first string.
192 Another way to solve this problem is to use colour and inverse video on an
193 ANSI terminal, see below COLOUR below if you want this.
194
195 Unfortunately this is sometimes not enough, neither colour nor quotes will
196 help you with problems involving tabs, other non-printing characters and
197 certain kinds of problems inherent in Unicode. To deal with this, you can
198 switch Test::Tester into a mode whereby all "tricky" characters are shown as
199 \{xx}. Tricky characters are those with ASCII code less than 33 or higher
200 than 126. This makes the output more difficult to read but much easier to
201 find subtle differences between strings. To turn on this mode either call
202 show_space() in your test script or set the TESTTESTERSPACE environment
203 variable to be a true value. The example above would then look like
204
205 # Got diag (5 bytes):
206 # abcd\x{20}
207 # Expected diag (4 bytes):
208 # abcd
209
210COLOUR
211 If you prefer to use colour as a means of finding tricky whitespace
212 characters then you can set the TESTTESTCOLOUR environment variable to a
213 comma separated pair of colours, the first for the foreground, the second
214 for the background. For example "white,red" will print white text on a red
215 background. This requires the Term::ANSIColor module. You can specify any
216 colour that would be acceptable to the Term::ANSIColor::color function.
217
218 If you spell colour differently, that's no problem. The TESTTESTERCOLOR
219 variable also works (if both are set then the British spelling wins out).
220
221EXPORTED FUNCTIONS
222 ($premature, @results) = run_tests(\&test_sub)
223 \&test_sub is a reference to a subroutine.
224
225 run_tests runs the subroutine in $test_sub and captures the results of any
226 tests inside it. You can run more than 1 test inside this subroutine if you
227 like.
228
229 $premature is a string containing any diagnostic output from before the
230 first test.
231
232 @results is an array of test result hashes.
233
234 cmp_result(\%result, \%expect, $name)
235 \%result is a ref to a test result hash.
236
237 \%expect is a ref to a hash of expected values for the test result.
238
239 cmp_result compares the result with the expected values. If any differences
240 are found it outputs diagnostics. You may leave out any field from the
241 expected result and cmp_result will not do the comparison of that field.
242
243 cmp_results(\@results, \@expects, $name)
244 \@results is a ref to an array of test results.
245
246 \@expects is a ref to an array of hash refs.
247
248 cmp_results checks that the results match the expected results and if any
249 differences are found it outputs diagnostics. It first checks that the
250 number of elements in \@results and \@expects is the same. Then it goes
251 through each result checking it against the expected result as in
252 cmp_result() above.
253
254 ($premature, @results) = check_tests(\&test_sub, \@expects, $name)
255 \&test_sub is a reference to a subroutine.
256
257 \@expect is a ref to an array of hash refs which are expected test results.
258
259 check_tests combines run_tests and cmp_tests into a single call. It also
260 checks if the tests died at any stage.
261
262 It returns the same values as run_tests, so you can further examine the test
263 results if you need to.
264
265 ($premature, @results) = check_test(\&test_sub, \%expect, $name)
266 \&test_sub is a reference to a subroutine.
267
268 \%expect is a ref to an hash of expected values for the test result.
269
270 check_test is a wrapper around check_tests. It combines run_tests and
271 cmp_tests into a single call, checking if the test died. It assumes that
272 only a single test is run inside \&test_sub and include a test to make sure
273 this is true.
274
275 It returns the same values as run_tests, so you can further examine the test
276 results if you need to.
277
278 show_space()
279 Turn on the escaping of characters as described in the SPACES AND TABS
280 section.
281
282HOW IT WORKS
283 Normally, a test module (let's call it Test:MyStyle) calls
284 Test::Builder->new to get the Test::Builder object. Test::MyStyle calls
285 methods on this object to record information about test results. When
286 Test::Tester is loaded, it replaces Test::Builder's new() method with one
287 which returns a Test::Tester::Delegate object. Most of the time this object
288 behaves as the real Test::Builder object. Any methods that are called are
289 delegated to the real Test::Builder object so everything works perfectly.
290 However once we go into test mode, the method calls are no longer passed to
291 the real Test::Builder object, instead they go to the Test::Tester::Capture
292 object. This object seems exactly like the real Test::Builder object,
293 except, instead of outputting test results and diagnostics, it just records
294 all the information for later analysis.
295
296SEE ALSO
297 Test::Builder the source of testing goodness. Test::Builder::Tester for an
298 alternative approach to the problem tackled by Test::Tester - captures the
299 strings output by Test::Builder. This means you cannot get separate access
300 to the individual pieces of information and you must predict exactly what
301 your test will output.
302
303AUTHOR
304 This module is copyright 2005 Fergal Daly <fergal@esatclear.ie>, some parts
305 are based on other people's work.
306
307 Plan handling lifted from Test::More. written by Michael G Schwern
308 <schwern@pobox.com>.
309
310 Test::Tester::Capture is a cut down and hacked up version of Test::Builder.
311 Test::Builder was written by chromatic <chromatic@wgz.org> and Michael G
312 Schwern <schwern@pobox.com>.
313
314LICENSE
315 Under the same license as Perl itself
316
317 See http://www.perl.com/perl/misc/Artistic.html
318
319