1Test::Tester(3)       User Contributed Perl Documentation      Test::Tester(3)
2
3
4

NAME

6       Test::Tester - Ease testing test modules built with Test::Builder
7

SYNOPSIS

9         use Test::Tester tests => 6;
10
11         use Test::MyStyle;
12
13         check_test(
14           sub {
15             is_mystyle_eq("this", "that", "not eq");
16           },
17           {
18             ok => 0, # expect this to fail
19             name => "not eq",
20             diag => "Expected: 'this'\nGot: 'that'",
21           }
22         );
23
24       or
25
26         use Test::Tester;
27
28         use Test::More tests => 3;
29         use Test::MyStyle;
30
31         my ($premature, @results) = run_tests(
32           sub {
33             is_database_alive("dbname");
34           }
35         );
36
37         # now use Test::More::like to check the diagnostic output
38
39         like($results[0]->{diag}, "/^Database ping took \\d+ seconds$"/, "diag");
40

DESCRIPTION

42       If you have written a test module based on Test::Builder then
43       Test::Tester allows you to test it with the minimum of effort.
44

HOW TO USE (THE EASY WAY)

46       From version 0.08 Test::Tester no longer requires you to included
47       anything special in your test modules. All you need to do is
48
49         use Test::Tester;
50
51       in your test script before any other Test::Builder based modules and
52       away you go.
53
54       Other modules based on Test::Builder can be used to help with the
55       testing.  In fact you can even use functions from your module to test
56       other functions from the same module (while this is possible it is
57       probably not a good idea, if your module has bugs, then using it to
58       test itself may give the wrong answers).
59
60       The easiest way to test is to do something like
61
62         check_test(
63           sub { is_mystyle_eq("this", "that", "not eq") },
64           {
65             ok => 0, # we expect the test to fail
66             name => "not eq",
67             diag => "Expected: 'this'\nGot: 'that'",
68           }
69         );
70
71       this will execute the is_mystyle_eq test, capturing it's results and
72       checking that they are what was expected.
73
74       You may need to examine the test results in a more flexible way, for
75       example, the diagnostic output may be quite long or complex or it may
76       involve something that you cannot predict in advance like a timestamp.
77       In this case you can get direct access to the test results:
78
79         my ($premature, @results) = run_tests(
80           sub {
81             is_database_alive("dbname");
82           }
83         );
84
85         like($result[0]->{diag}, "/^Database ping took \\d+ seconds$"/, "diag");
86
87       We cannot predict how long the database ping will take so we use
88       Test::More's like() test to check that the diagnostic string is of the
89       right form.
90

HOW TO USE (THE HARD WAY)

92       This is here for backwards compatibility only
93
94       Make your module use the Test::Tester::Capture object instead of the
95       Test::Builder one. How to do this depends on your module but assuming
96       that your module holds the Test::Builder object in $Test and that all
97       your test routines access it through $Test then providing a function
98       something like this
99
100         sub set_builder
101         {
102           $Test = shift;
103         }
104
105       should allow your test scripts to do
106
107         Test::YourModule::set_builder(Test::Tester->capture);
108
109       and after that any tests inside your module will captured.
110

TEST RESULTS

112       The result of each test is captured in a hash. These hashes are the
113       same as the hashes returned by Test::Builder->details but with a couple
114       of extra fields.
115
116       These fields are documented in Test::Builder in the details() function
117
118       ok
119         Did the test pass?
120
121       actual_ok
122         Did the test really pass? That is, did the pass come from
123         Test::Builder->ok() or did it pass because it was a TODO test?
124
125       name
126         The name supplied for the test.
127
128       type
129         What kind of test? Possibilities include, skip, todo etc. See
130         Test::Builder for more details.
131
132       reason
133         The reason for the skip, todo etc. See Test::Builder for more
134         details.
135
136       These fields are exclusive to Test::Tester.
137
138       diag
139         Any diagnostics that were output for the test. This only includes
140         diagnostics output after the test result is declared.
141
142         Note that Test::Builder ensures that any diagnostics end in a \n and
143         it in earlier versions of Test::Tester it was essential that you have
144         the final \n in your expected diagnostics. From version 0.10 onwards,
145         Test::Tester will add the \n if you forgot it. It will not add a \n
146         if you are expecting no diagnostics. See below for help tracking down
147         hard to find space and tab related problems.
148
149       depth
150         This allows you to check that your test module is setting the correct
151         value for $Test::Builder::Level and thus giving the correct file and
152         line number when a test fails. It is calculated by looking at
153         caller() and $Test::Builder::Level. It should count how many
154         subroutines there are before jumping into the function you are
155         testing. So for example in
156
157           run_tests( sub { my_test_function("a", "b") } );
158
159         the depth should be 1 and in
160
161           sub deeper { my_test_function("a", "b") }
162
163           run_tests(sub { deeper() });
164
165         depth should be 2, that is 1 for the sub {} and one for deeper().
166         This might seem a little complex but if your tests look like the
167         simple examples in this doc then you don't need to worry as the depth
168         will always be 1 and that's what Test::Tester expects by default.
169
170         Note: if you do not specify a value for depth in check_test() then it
171         automatically compares it against 1, if you really want to skip the
172         depth test then pass in undef.
173
174         Note: depth will not be correctly calculated for tests that run from
175         a signal handler or an END block or anywhere else that hides the call
176         stack.
177
178       Some of Test::Tester's functions return arrays of these hashes, just
179       like Test::Builder->details. That is, the hash for the first test will
180       be array element 1 (not 0). Element 0 will not be a hash it will be a
181       string which contains any diagnostic output that came before the first
182       test. This should usually be empty, if it's not, it means something
183       output diagnostics before any test results showed up.
184

SPACES AND TABS

186       Appearances can be deceptive, especially when it comes to emptiness. If
187       you are scratching your head trying to work out why Test::Tester is
188       saying that your diagnostics are wrong when they look perfectly right
189       then the answer is probably whitespace. From version 0.10 on,
190       Test::Tester surrounds the expected and got diag values with single
191       quotes to make it easier to spot trailing whitesapce. So in this
192       example
193
194         # Got diag (5 bytes):
195         # 'abcd '
196         # Expected diag (4 bytes):
197         # 'abcd'
198
199       it is quite clear that there is a space at the end of the first string.
200       Another way to solve this problem is to use colour and inverse video on
201       an ANSI terminal, see below COLOUR below if you want this.
202
203       Unfortunately this is sometimes not enough, neither colour nor quotes
204       will help you with problems involving tabs, other non-printing
205       characters and certain kinds of problems inherent in Unicode. To deal
206       with this, you can switch Test::Tester into a mode whereby all "tricky"
207       characters are shown as \{xx}. Tricky characters are those with ASCII
208       code less than 33 or higher than 126. This makes the output more
209       difficult to read but much easier to find subtle differences between
210       strings. To turn on this mode either call show_space() in your test
211       script or set the TESTTESTERSPACE environment variable to be a true
212       value. The example above would then look like
213
214         # Got diag (5 bytes):
215         # abcd\x{20}
216         # Expected diag (4 bytes):
217         # abcd
218

COLOUR

220       If you prefer to use colour as a means of finding tricky whitespace
221       characters then you can set the TESTTESTCOLOUR environment variable to
222       a comma separated pair of colours, the first for the foreground, the
223       second for the background. For example "white,red" will print white
224       text on a red background. This requires the Term::ANSIColor module. You
225       can specify any colour that would be acceptable to the
226       Term::ANSIColor::color function.
227
228       If you spell colour differently, that's no problem. The TESTTESTERCOLOR
229       variable also works (if both are set then the British spelling wins
230       out).
231

EXPORTED FUNCTIONS

233       ($premature, @results) = run_tests(\&test_sub)
234
235       \&test_sub is a reference to a subroutine.
236
237       run_tests runs the subroutine in $test_sub and captures the results of
238       any tests inside it. You can run more than 1 test inside this
239       subroutine if you like.
240
241       $premature is a string containing any diagnostic output from before the
242       first test.
243
244       @results is an array of test result hashes.
245
246       cmp_result(\%result, \%expect, $name)
247
248       \%result is a ref to a test result hash.
249
250       \%expect is a ref to a hash of expected values for the test result.
251
252       cmp_result compares the result with the expected values. If any
253       differences are found it outputs diagnostics. You may leave out any
254       field from the expected result and cmp_result will not do the
255       comparison of that field.
256
257       cmp_results(\@results, \@expects, $name)
258
259       \@results is a ref to an array of test results.
260
261       \@expects is a ref to an array of hash refs.
262
263       cmp_results checks that the results match the expected results and if
264       any differences are found it outputs diagnostics. It first checks that
265       the number of elements in \@results and \@expects is the same. Then it
266       goes through each result checking it against the expected result as in
267       cmp_result() above.
268
269       ($premature, @results) = check_tests(\&test_sub, \@expects, $name)
270
271       \&test_sub is a reference to a subroutine.
272
273       \@expect is a ref to an array of hash refs which are expected test
274       results.
275
276       check_tests combines run_tests and cmp_tests into a single call. It
277       also checks if the tests died at any stage.
278
279       It returns the same values as run_tests, so you can further examine the
280       test results if you need to.
281
282       ($premature, @results) = check_test(\&test_sub, \%expect, $name)
283
284       \&test_sub is a reference to a subroutine.
285
286       \%expect is a ref to an hash of expected values for the test result.
287
288       check_test is a wrapper around check_tests. It combines run_tests and
289       cmp_tests into a single call, checking if the test died. It assumes
290       that only a single test is run inside \&test_sub and include a test to
291       make sure this is true.
292
293       It returns the same values as run_tests, so you can further examine the
294       test results if you need to.
295
296       show_space()
297
298       Turn on the escaping of characters as described in the SPACES AND TABS
299       section.
300

HOW IT WORKS

302       Normally, a test module (let's call it Test:MyStyle) calls
303       Test::Builder->new to get the Test::Builder object. Test::MyStyle calls
304       methods on this object to record information about test results. When
305       Test::Tester is loaded, it replaces Test::Builder's new() method with
306       one which returns a Test::Tester::Delegate object. Most of the time
307       this object behaves as the real Test::Builder object. Any methods that
308       are called are delegated to the real Test::Builder object so everything
309       works perfectly.  However once we go into test mode, the method calls
310       are no longer passed to the real Test::Builder object, instead they go
311       to the Test::Tester::Capture object. This object seems exactly like the
312       real Test::Builder object, except, instead of outputting test results
313       and diagnostics, it just records all the information for later
314       analysis.
315

SEE ALSO

317       Test::Builder the source of testing goodness. Test::Builder::Tester for
318       an alternative approach to the problem tackled by Test::Tester -
319       captures the strings output by Test::Builder. This means you cannot get
320       separate access to the individual pieces of information and you must
321       predict exactly what your test will output.
322

AUTHOR

324       This module is copyright 2005 Fergal Daly <fergal@esatclear.ie>, some
325       parts are based on other people's work.
326
327       Plan handling lifted from Test::More. written by Michael G Schwern
328       <schwern@pobox.com>.
329
330       Test::Tester::Capture is a cut down and hacked up version of
331       Test::Builder.  Test::Builder was written by chromatic
332       <chromatic@wgz.org> and Michael G Schwern <schwern@pobox.com>.
333

LICENSE

335       Under the same license as Perl itself
336
337       See http://www.perl.com/perl/misc/Artistic.html
338
339
340
341perl v5.10.1                      2008-03-01                   Test::Tester(3)
Impressum