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 @results = run_tests(
32 sub {
33 is_database_alive("dbname");
34 },
35 {
36 ok => 1, # expect the test to pass
37 }
38 );
39 # now use Test::More::like to check the diagnostic output
41 like($result[1]->{diag}, "/^Database ping took \\d+ seconds$"/, "diag");
43
45 If you have written a test module based on Test::Builder then
46 Test::Tester allows you to test it with the minimum of effort.
47
49 From version 0.08 Test::Tester no longer requires you to included any‐
50 thing special in your test modules. All you need to do is
51 use Test::Tester;
53 in your test script before any other Test::Builder based modules and
55 away you go.
56 Other modules based on Test::Builder can be used to help with the test‐
58 ing. In fact you can even use functions from your test module to test
59 other functions from the same module - although that may not be a very
60 wise thing to do!
61 The easiest way to test is to do something like
63 check_test(
65 sub { is_mystyle_eq("this", "that", "not eq") },
66 {
67 ok => 0, # we expect the test to fail
68 name => "not eq",
69 diag => "Expected: 'this'\nGot: 'that'",
70 }
71 );
72 this will execute the is_mystyle_eq test, capturing it's results and
74 checking that they are what was expected.
75 You may need to examine the test results in a more flexible way, for
77 example, if the diagnostic output may be quite complex or it may
78 involve something that you cannot predict in advance like a timestamp.
79 In this case you can get direct access to the test results:
80 my @results = run_tests(
82 sub {
83 is_database_alive("dbname");
84 },
85 {
86 ok => 1, # expect the test to pass
87 }
88 );
89 like($result[1]->{diag}, "/^Database ping took \\d+ seconds$"/, "diag");
91 We cannot predict how long the database ping will take so we use
93 Test::More's like() test to check that the diagnostic string is of the
94 right form.
95
97 This is here for backwards compatibility only
98 Make your module use the Test::Tester::Capture object instead of the
100 Test::Builder one. How to do this depends on your module but assuming
101 that your module holds the Test::Builder object in $Test and that all
102 your test routines access it through $Test then providing a function
103 something like this
104 sub set_builder
106 {
107 $Test = shift;
108 }
109 should allow your test scripts to do
111 Test::YourModule::set_builder(Test::Tester->capture);
113 and after that any tests inside your module will captured.
115
117 The result of each test is captured in a hash. These hashes are the
118 same as the hashes returned by Test::Builder->details but with a couple
119 of extra fields.
120 These fields are documented in Test::Builder in the details() function
122 ok
124 Did the test pass?
125 actual_ok
127 Did the test really pass? That is, did the pass come from
128 Test::Builder->ok() or did it pass because it was a TODO test?
129 name
131 The name supplied for the test.
132 type
134 What kind of test? Possibilities include, skip, todo etc. See
135 Test::Builder for more details.
136 reason
138 The reason for the skip, todo etc. See Test::Builder for more
139 details.
140 These fields are exclusive to Test::Tester.
142 diag
144 Any diagnostics that were output for the test. This only includes
145 diagnostics output after the test result is declared.
146 Note that Test::Builder ensures that any diagnostics end in a \n and
148 so it was essential that you have the final \n in your expected diag‐
149 nostics. From version 0.10 onwards, Test::Tester will add the \n if
150 you forgot it. Of course it will not add a \n if you are expecting no
151 diagnostics. See below for help tracking down hard to find space and
152 tab related problems.
153 depth
155 This allows you to check that your test module is setting the correct
156 value for $Test::Builder::Level and thus giving the correct file and
157 line number when a test fails. It is calculated by looking at call‐
158 er() and $Test::Builder::Level. It should count how many subroutines
159 there are before jumping into the function you are testing so for
160 example in
161 run_tests( sub { my_test_function("a", "b") } );
163 the depth should be 1 and in
165 sub deeper { my_test_function("a", "b") }
167 run_tests(sub { deeper() });
169 depth should be 2, that is 1 for the sub {} and one for deeper().
171 This might seem a little complex but unless you are calling your test
172 functions inside subroutines or evals then depth will always be 1.
173 Note: if you do not specify a value for depth in check_test() then it
175 automatically compares it against 1, if you really want to skip the
176 depth test then pass in undef.
177 Note: depth will not be correctly calculated for tests that run from
179 a signal handler or an END block or anywhere else that hides the call
180 stack.
181 Some of the Test::Testers functions return arrays of these hashes, just
183 like Test::Builder->details. That is, the hash for the first test will
184 be array element 1 (not 0). Element 0 will not be a hash it will be a
185 string which contains any diagnostic output that came before the first
186 test. This should usually be empty.
187
189 Appearances can be deceptive, especially when it comes to emptiness. If
190 you are scratching your head trying to work out why Test::Tester is
191 saying that your diagnostics are wrong when they look perfectly right
192 then the answer is probably whitespace. From version 0.10 on,
193 Test::Tester surrounds the expected and got diag values with single
194 quotes to make it easier to spot trailing whitesapce. So in this exam‐
195 ple
196 # Got diag (5 bytes):
198 # 'abcd '
199 # Expected diag (4 bytes):
200 # 'abcd'
201 it is quite clear that there is a space at the end of the first string.
203 Another way to solve this problem is to use colour and inverse video on
204 an ANSI terminal, see below COLOUR below if you want this.
205 Unfortunately this is sometimes not enough, neither colour nor quotes
207 will help you with problems involving tabs, other non-printing charac‐
208 ters and certain kinds of problems inherent in Unicode. To deal with
209 this, you can switch Test::Tester into a mode whereby all "tricky"
210 characters are shown as \{xx}. Tricky characters are those with ASCII
211 code less than 33 or higher than 126. This makes the output more diffi‐
212 cult to read but much easier to find subtle differences between
213 strings. To turn on this mode either call show_space() in your test
214 script or set the TESTTESTERSPACE environment variable to be a true
215 value. The example above would then look like
216 # Got diag (5 bytes):
218 # abcd\x{20}
219 # Expected diag (4 bytes):
220 # abcd
221
223 If you prefer to use colour as a means of finding tricky whitespace
224 characters then you can set the TESTTESTCOLOUR environment variable to
225 a comma separated pair of colours, the first for the foreground, the
226 second for the background. For example "white,red" will print white
227 text on a red background. This requires the Term::ANSIColor module. You
228 can specify any colour that would be acceptable to the Term::ANSI‐
229 Color::color function.
230 If you spell colour differently, that's no problem. The TESTTESTERCOLOR
232 variable also works (if both are set then the British spelling wins
233 out).
234
236 ($prem, @results) = run_tests(\&test_sub, $name)
237 \&test_sub is a reference to a subroutine.
239 $name is a string.
241 run_tests runs the subroutine in $test_sub and captures the results of
243 any tests inside it. You can run more than 1 test inside this subrou‐
244 tine if you like.
245 $prem is a string containing any diagnostic output from before the
247 first test.
248 @results is an array of test result hashes.
250 cmp_result(\%result, \%expect, $name)
252 \%result is a ref to a test result hash.
254 \%expect is a ref to a hash of expected values for the test result.
256 cmp_result compares the result with the expected values. If any differ‐
258 ences are found it outputs diagnostics. You may leave out any field
259 from the expected result and cmp_result will not do the comparison of
260 that field.
261 cmp_results(\@results, \@expects, $name)
263 \@results is a ref to an array of test results.
265 \@expects is a ref to an array of hash refs.
267 cmp_results checks that the results match the expected results and if
269 any differences are found it outputs diagnostics. It first checks that
270 the number of elements in \@results and \@expects is the same. Then it
271 goes through each result checking it against the expected result as in
272 cmp_result() above.
273 ($prem, @results) = check_tests(\&test_sub, \@expects, $name)
275 \&test_sub is a reference to a subroutine.
277 \@expect is a ref to an array of hash refs which are expected test
279 results.
280 check_tests combines run_tests and cmp_tests into a single call. It
282 also checks if the tests died at any stage.
283 It returns the same values as run_tests, so you can further examine the
285 test results if you need to.
286 ($prem, @results) = check_test(\&test_sub, \%expect, $name)
288 \&test_sub is a reference to a subroutine.
290 \%expect is a ref to an hash of expected values for the test result.
292 check_test is a wrapper around check_tests. It combines run_tests and
294 cmp_tests into a single call, checking if the test died. It assumes
295 that only a single test is run inside \&test_sub and test to make this
296 is true.
297 It returns the same values as run_tests, so you can further examine the
299 test results if you need to.
300 show_space()
302 Turn on the escaping of characters as described in the SPACES AND TABS
304 section.
305
307 Normally, a test module (let's call it Test:MyStyle) calls
308 Test::Builder->new to get the Test::Builder object. Test::MyStyle calls
309 methods on this object to record information about test results. When
310 Test::Tester is loaded, it replaces Test::Builder's new() method with
311 one which returns a Test::Tester::Delegate object. Most of the time
312 this object appears to be the real Test::Builder object. Any methods
313 that are called are delegated to the real Test::Builder object so
314 everything works perfectly. However once we go into test mode, the
315 method calls are no longer passed to the real Test::Builder object,
316 instead they go to the Test::Tester::Capture object. This object seems
317 exactly like the real Test::Builder object, except, instead of out‐
318 putting test results and diagnostics, it just records all the informa‐
319 tion for later analysis.
320
322 Test::Builder the source of testing goodness. Test::Builder::Tester for
323 an alternative approach to the problem tackled by Test::Tester - cap‐
324 tures 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 <chro‐
337 matic@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.8.8 2006-12-15 Test::Tester(3)