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 tests => 6;
27
28         use Test::MyStyle;
29
30         check_test(
31           sub {
32             is_mystyle_qr("this", "that", "not matching");
33           },
34           {
35             ok => 0, # expect this to fail
36             name => "not matching",
37             diag => qr/Expected: 'this'\s+Got: 'that'/,
38           }
39         );
40
41       or
42
43         use Test::Tester;
44
45         use Test::More tests => 3;
46         use Test::MyStyle;
47
48         my ($premature, @results) = run_tests(
49           sub {
50             is_database_alive("dbname");
51           }
52         );
53
54         # now use Test::More::like to check the diagnostic output
55
56         like($results[0]->{diag}, "/^Database ping took \\d+ seconds$"/, "diag");
57

DESCRIPTION

59       If you have written a test module based on Test::Builder then
60       Test::Tester allows you to test it with the minimum of effort.
61

HOW TO USE (THE EASY WAY)

63       From version 0.08 Test::Tester no longer requires you to included
64       anything special in your test modules. All you need to do is
65
66         use Test::Tester;
67
68       in your test script before any other Test::Builder based modules and
69       away you go.
70
71       Other modules based on Test::Builder can be used to help with the
72       testing.  In fact you can even use functions from your module to test
73       other functions from the same module (while this is possible it is
74       probably not a good idea, if your module has bugs, then using it to
75       test itself may give the wrong answers).
76
77       The easiest way to test is to do something like
78
79         check_test(
80           sub { is_mystyle_eq("this", "that", "not eq") },
81           {
82             ok => 0, # we expect the test to fail
83             name => "not eq",
84             diag => "Expected: 'this'\nGot: 'that'",
85           }
86         );
87
88       this will execute the is_mystyle_eq test, capturing its results and
89       checking that they are what was expected.
90
91       You may need to examine the test results in a more flexible way, for
92       example, the diagnostic output may be quite long or complex or it may
93       involve something that you cannot predict in advance like a timestamp.
94       In this case you can get direct access to the test results:
95
96         my ($premature, @results) = run_tests(
97           sub {
98             is_database_alive("dbname");
99           }
100         );
101
102         like($result[0]->{diag}, "/^Database ping took \\d+ seconds$"/, "diag");
103
104       or
105
106         check_test(
107           sub { is_mystyle_qr("this", "that", "not matching") },
108           {
109             ok => 0, # we expect the test to fail
110             name => "not matching",
111             diag => qr/Expected: 'this'\s+Got: 'that'/,
112           }
113         );
114
115       We cannot predict how long the database ping will take so we use
116       Test::More's like() test to check that the diagnostic string is of the
117       right form.
118

HOW TO USE (THE HARD WAY)

120       This is here for backwards compatibility only
121
122       Make your module use the Test::Tester::Capture object instead of the
123       Test::Builder one. How to do this depends on your module but assuming
124       that your module holds the Test::Builder object in $Test and that all
125       your test routines access it through $Test then providing a function
126       something like this
127
128         sub set_builder
129         {
130           $Test = shift;
131         }
132
133       should allow your test scripts to do
134
135         Test::YourModule::set_builder(Test::Tester->capture);
136
137       and after that any tests inside your module will captured.
138

TEST RESULTS

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

SPACES AND TABS

214       Appearances can be deceptive, especially when it comes to emptiness. If
215       you are scratching your head trying to work out why Test::Tester is
216       saying that your diagnostics are wrong when they look perfectly right
217       then the answer is probably whitespace. From version 0.10 on,
218       Test::Tester surrounds the expected and got diag values with single
219       quotes to make it easier to spot trailing whitespace. So in this
220       example
221
222         # Got diag (5 bytes):
223         # 'abcd '
224         # Expected diag (4 bytes):
225         # 'abcd'
226
227       it is quite clear that there is a space at the end of the first string.
228       Another way to solve this problem is to use colour and inverse video on
229       an ANSI terminal, see below COLOUR below if you want this.
230
231       Unfortunately this is sometimes not enough, neither colour nor quotes
232       will help you with problems involving tabs, other non-printing
233       characters and certain kinds of problems inherent in Unicode. To deal
234       with this, you can switch Test::Tester into a mode whereby all "tricky"
235       characters are shown as \{xx}. Tricky characters are those with ASCII
236       code less than 33 or higher than 126. This makes the output more
237       difficult to read but much easier to find subtle differences between
238       strings. To turn on this mode either call "show_space()" in your test
239       script or set the "TESTTESTERSPACE" environment variable to be a true
240       value. The example above would then look like
241
242         # Got diag (5 bytes):
243         # abcd\x{20}
244         # Expected diag (4 bytes):
245         # abcd
246

COLOUR

248       If you prefer to use colour as a means of finding tricky whitespace
249       characters then you can set the "TESTTESTCOLOUR" environment variable
250       to a comma separated pair of colours, the first for the foreground, the
251       second for the background. For example "white,red" will print white
252       text on a red background. This requires the Term::ANSIColor module. You
253       can specify any colour that would be acceptable to the
254       Term::ANSIColor::color function.
255
256       If you spell colour differently, that's no problem. The
257       "TESTTESTERCOLOR" variable also works (if both are set then the British
258       spelling wins out).
259

EXPORTED FUNCTIONS

261       ($premature, @results) = run_tests(\&test_sub)
262
263       \&test_sub is a reference to a subroutine.
264
265       run_tests runs the subroutine in $test_sub and captures the results of
266       any tests inside it. You can run more than 1 test inside this
267       subroutine if you like.
268
269       $premature is a string containing any diagnostic output from before the
270       first test.
271
272       @results is an array of test result hashes.
273
274       cmp_result(\%result, \%expect, $name)
275
276       \%result is a ref to a test result hash.
277
278       \%expect is a ref to a hash of expected values for the test result.
279
280       cmp_result compares the result with the expected values. If any
281       differences are found it outputs diagnostics. You may leave out any
282       field from the expected result and cmp_result will not do the
283       comparison of that field.
284
285       cmp_results(\@results, \@expects, $name)
286
287       \@results is a ref to an array of test results.
288
289       \@expects is a ref to an array of hash refs.
290
291       cmp_results checks that the results match the expected results and if
292       any differences are found it outputs diagnostics. It first checks that
293       the number of elements in \@results and \@expects is the same. Then it
294       goes through each result checking it against the expected result as in
295       cmp_result() above.
296
297       ($premature, @results) = check_tests(\&test_sub, \@expects, $name)
298
299       \&test_sub is a reference to a subroutine.
300
301       \@expect is a ref to an array of hash refs which are expected test
302       results.
303
304       check_tests combines run_tests and cmp_tests into a single call. It
305       also checks if the tests died at any stage.
306
307       It returns the same values as run_tests, so you can further examine the
308       test results if you need to.
309
310       ($premature, @results) = check_test(\&test_sub, \%expect, $name)
311
312       \&test_sub is a reference to a subroutine.
313
314       \%expect is a ref to an hash of expected values for the test result.
315
316       check_test is a wrapper around check_tests. It combines run_tests and
317       cmp_tests into a single call, checking if the test died. It assumes
318       that only a single test is run inside \&test_sub and include a test to
319       make sure this is true.
320
321       It returns the same values as run_tests, so you can further examine the
322       test results if you need to.
323
324       show_space()
325
326       Turn on the escaping of characters as described in the SPACES AND TABS
327       section.
328

HOW IT WORKS

330       Normally, a test module (let's call it Test:MyStyle) calls
331       Test::Builder->new to get the Test::Builder object. Test::MyStyle calls
332       methods on this object to record information about test results. When
333       Test::Tester is loaded, it replaces Test::Builder's new() method with
334       one which returns a Test::Tester::Delegate object. Most of the time
335       this object behaves as the real Test::Builder object. Any methods that
336       are called are delegated to the real Test::Builder object so everything
337       works perfectly.  However once we go into test mode, the method calls
338       are no longer passed to the real Test::Builder object, instead they go
339       to the Test::Tester::Capture object. This object seems exactly like the
340       real Test::Builder object, except, instead of outputting test results
341       and diagnostics, it just records all the information for later
342       analysis.
343

CAVEATS

345       Support for calling Test::Builder->note is minimal. It's implemented as
346       an empty stub, so modules that use it will not crash but the calls are
347       not recorded for testing purposes like the others. Patches welcome.
348

SEE ALSO

350       Test::Builder the source of testing goodness. Test::Builder::Tester for
351       an alternative approach to the problem tackled by Test::Tester -
352       captures the strings output by Test::Builder. This means you cannot get
353       separate access to the individual pieces of information and you must
354       predict exactly what your test will output.
355

AUTHOR

357       This module is copyright 2005 Fergal Daly <fergal@esatclear.ie>, some
358       parts are based on other people's work.
359
360       Plan handling lifted from Test::More. written by Michael G Schwern
361       <schwern@pobox.com>.
362
363       Test::Tester::Capture is a cut down and hacked up version of
364       Test::Builder.  Test::Builder was written by chromatic
365       <chromatic@wgz.org> and Michael G Schwern <schwern@pobox.com>.
366

LICENSE

368       Under the same license as Perl itself
369
370       See http://www.perl.com/perl/misc/Artistic.html
371
372
373
374perl v5.32.0                      2020-10-15                   Test::Tester(3)
Impressum