1Test::Tester(3) User Contributed Perl Documentation Test::Tester(3)
2
6 Test::Tester - Ease testing test modules built with Test::Builder
7
9 use Test::Tester tests => 6;
10 use Test::MyStyle;
12 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 or
25 use Test::Tester tests => 6;
27 use Test::MyStyle;
29 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 or
42 use Test::Tester;
44 use Test::More tests => 3;
46 use Test::MyStyle;
47 my ($premature, @results) = run_tests(
49 sub {
50 is_database_alive("dbname");
51 }
52 );
53 # now use Test::More::like to check the diagnostic output
55 like($results[0]->{diag}, "/^Database ping took \\d+ seconds$"/, "diag");
57
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
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 use Test::Tester;
67 in your test script before any other Test::Builder based modules and
69 away you go.
70 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 The easiest way to test is to do something like
78 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 this will execute the is_mystyle_eq test, capturing its results and
89 checking that they are what was expected.
90 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 my ($premature, @results) = run_tests(
97 sub {
98 is_database_alive("dbname");
99 }
100 );
101 like($result[0]->{diag}, "/^Database ping took \\d+ seconds$"/, "diag");
103 or
105 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 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
120 This is here for backwards compatibility only
121 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 sub set_builder
129 {
130 $Test = shift;
131 }
132 should allow your test scripts to do
134 Test::YourModule::set_builder(Test::Tester->capture);
136 and after that any tests inside your module will captured.
138
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 These fields are documented in Test::Builder in the details() function
145 ok
147 Did the test pass?
148 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 name
154 The name supplied for the test.
155 type
157 What kind of test? Possibilities include, skip, todo etc. See
158 Test::Builder for more details.
159 reason
161 The reason for the skip, todo etc. See Test::Builder for more
162 details.
163 These fields are exclusive to Test::Tester.
165 diag
167 Any diagnostics that were output for the test. This only includes
168 diagnostics output after the test result is declared.
169 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 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 run_tests( sub { my_test_function("a", "b") } );
186 the depth should be 1 and in
188 sub deeper { my_test_function("a", "b") }
190 run_tests(sub { deeper() });
192 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 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 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 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
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 # Got diag (5 bytes):
223 # 'abcd '
224 # Expected diag (4 bytes):
225 # 'abcd'
226 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 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 # Got diag (5 bytes):
243 # abcd\x{20}
244 # Expected diag (4 bytes):
245 # abcd
246
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 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
261 ($premature, @results) = run_tests(\&test_sub)
262 \&test_sub is a reference to a subroutine.
264 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 $premature is a string containing any diagnostic output from before the
270 first test.
271 @results is an array of test result hashes.
273 cmp_result(\%result, \%expect, $name)
275 \%result is a ref to a test result hash.
277 \%expect is a ref to a hash of expected values for the test result.
279 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 cmp_results(\@results, \@expects, $name)
286 \@results is a ref to an array of test results.
288 \@expects is a ref to an array of hash refs.
290 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 ($premature, @results) = check_tests(\&test_sub, \@expects, $name)
298 \&test_sub is a reference to a subroutine.
300 \@expect is a ref to an array of hash refs which are expected test
302 results.
303 check_tests combines run_tests and cmp_tests into a single call. It
305 also checks if the tests died at any stage.
306 It returns the same values as run_tests, so you can further examine the
308 test results if you need to.
309 ($premature, @results) = check_test(\&test_sub, \%expect, $name)
311 \&test_sub is a reference to a subroutine.
313 \%expect is a ref to an hash of expected values for the test result.
315 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 It returns the same values as run_tests, so you can further examine the
322 test results if you need to.
323 show_space()
325 Turn on the escaping of characters as described in the SPACES AND TABS
327 section.
328
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
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
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
357 This module is copyright 2005 Fergal Daly <fergal@esatclear.ie>, some
358 parts are based on other people's work.
359 Plan handling lifted from Test::More. written by Michael G Schwern
361 <schwern@pobox.com>.
362 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
368 Under the same license as Perl itself
369 See http://www.perl.com/perl/misc/Artistic.html
371perl v5.36.0 2023-03-15 Test::Tester(3)