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;
27 use Test::More tests => 3;
29 use Test::MyStyle;
30 my ($premature, @results) = run_tests(
32 sub {
33 is_database_alive("dbname");
34 }
35 );
36 # now use Test::More::like to check the diagnostic output
38 like($results[0]->{diag}, "/^Database ping took \\d+ seconds$"/, "diag");
40
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
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 use Test::Tester;
50 in your test script before any other Test::Builder based modules and
52 away you go.
53 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 The easiest way to test is to do something like
61 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 this will execute the is_mystyle_eq test, capturing it's results and
72 checking that they are what was expected.
73 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 my ($premature, @results) = run_tests(
80 sub {
81 is_database_alive("dbname");
82 }
83 );
84 like($result[0]->{diag}, "/^Database ping took \\d+ seconds$"/, "diag");
86 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
92 This is here for backwards compatibility only
93 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 sub set_builder
101 {
102 $Test = shift;
103 }
104 should allow your test scripts to do
106 Test::YourModule::set_builder(Test::Tester->capture);
108 and after that any tests inside your module will captured.
110
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 These fields are documented in Test::Builder in the details() function
117 ok
119 Did the test pass?
120 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 name
126 The name supplied for the test.
127 type
129 What kind of test? Possibilities include, skip, todo etc. See
130 Test::Builder for more details.
131 reason
133 The reason for the skip, todo etc. See Test::Builder for more
134 details.
135 These fields are exclusive to Test::Tester.
137 diag
139 Any diagnostics that were output for the test. This only includes
140 diagnostics output after the test result is declared.
141 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 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 run_tests( sub { my_test_function("a", "b") } );
158 the depth should be 1 and in
160 sub deeper { my_test_function("a", "b") }
162 run_tests(sub { deeper() });
164 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 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 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 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
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 # Got diag (5 bytes):
195 # 'abcd '
196 # Expected diag (4 bytes):
197 # 'abcd'
198 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 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 # Got diag (5 bytes):
215 # abcd\x{20}
216 # Expected diag (4 bytes):
217 # abcd
218
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 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
233 ($premature, @results) = run_tests(\&test_sub)
234 \&test_sub is a reference to a subroutine.
236 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 $premature is a string containing any diagnostic output from before the
242 first test.
243 @results is an array of test result hashes.
245 cmp_result(\%result, \%expect, $name)
247 \%result is a ref to a test result hash.
249 \%expect is a ref to a hash of expected values for the test result.
251 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 cmp_results(\@results, \@expects, $name)
258 \@results is a ref to an array of test results.
260 \@expects is a ref to an array of hash refs.
262 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 ($premature, @results) = check_tests(\&test_sub, \@expects, $name)
270 \&test_sub is a reference to a subroutine.
272 \@expect is a ref to an array of hash refs which are expected test
274 results.
275 check_tests combines run_tests and cmp_tests into a single call. It
277 also checks if the tests died at any stage.
278 It returns the same values as run_tests, so you can further examine the
280 test results if you need to.
281 ($premature, @results) = check_test(\&test_sub, \%expect, $name)
283 \&test_sub is a reference to a subroutine.
285 \%expect is a ref to an hash of expected values for the test result.
287 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 It returns the same values as run_tests, so you can further examine the
294 test results if you need to.
295 show_space()
297 Turn on the escaping of characters as described in the SPACES AND TABS
299 section.
300
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
317 Support for calling Test::Builder->note is minimal. It's implemented as
318 an empty stub, so modules that use it will not crash but the calls are
319 not recorded for testing purposes like the others. Patches welcome.
320
322 Test::Builder the source of testing goodness. Test::Builder::Tester for
323 an alternative approach to the problem tackled by Test::Tester -
324 captures the strings output by Test::Builder. This means you cannot get
325 separate access to the individual pieces of information and you must
326 predict exactly what your test will output.
327
329 This module is copyright 2005 Fergal Daly <fergal@esatclear.ie>, some
330 parts are based on other people's work.
331 Plan handling lifted from Test::More. written by Michael G Schwern
333 <schwern@pobox.com>.
334 Test::Tester::Capture is a cut down and hacked up version of
336 Test::Builder. Test::Builder was written by chromatic
337 <chromatic@wgz.org> and Michael G Schwern <schwern@pobox.com>.
338
340 Under the same license as Perl itself
341 See http://www.perl.com/perl/misc/Artistic.html
343perl v5.16.3 2013-05-26 Test::Tester(3)