1Test(3pm) Perl Programmers Reference Guide Test(3pm)
2
6 Test - provides a simple framework for writing test scripts
7
9 use strict;
10 use Test;
11 # use a BEGIN block so we print our plan before MyModule is loaded
13 BEGIN { plan tests => 14, todo => [3,4] }
14 # load your module...
16 use MyModule;
17 # Helpful notes. All note-lines must start with a "#".
19 print "# I'm testing MyModule version $MyModule::VERSION\n";
20 ok(0); # failure
22 ok(1); # success
23 ok(0); # ok, expected failure (see todo list, above)
25 ok(1); # surprise success!
26 ok(0,1); # failure: '0' ne '1'
28 ok('broke','fixed'); # failure: 'broke' ne 'fixed'
29 ok('fixed','fixed'); # success: 'fixed' eq 'fixed'
30 ok('fixed',qr/x/); # success: 'fixed' =~ qr/x/
31 ok(sub { 1+1 }, 2); # success: '2' eq '2'
33 ok(sub { 1+1 }, 3); # failure: '2' ne '3'
34 my @list = (0,0);
36 ok @list, 3, "\@list=".join(',',@list); #extra notes
37 ok 'segmentation fault', '/(?i)success/'; #regex match
38 skip(
40 $^O =~ m/MSWin/ ? "Skip if MSWin" : 0, # whether to skip
41 $foo, $bar # arguments just like for ok(...)
42 );
43 skip(
44 $^O =~ m/MSWin/ ? 0 : "Skip unless MSWin", # whether to skip
45 $foo, $bar # arguments just like for ok(...)
46 );
47
49 This module simplifies the task of writing test files for Perl modules,
50 such that their output is in the format that Test::Harness expects to
51 see.
52
54 To write a test for your new (and probably not even done) module,
55 create a new file called t/test.t (in a new t directory). If you have
56 multiple test files, to test the "foo", "bar", and "baz" feature sets,
57 then feel free to call your files t/foo.t, t/bar.t, and t/baz.t
58 Functions
60 This module defines three public functions, "plan(...)", "ok(...)", and
61 "skip(...)". By default, all three are exported by the "use Test;"
62 statement.
63 "plan(...)"
65 BEGIN { plan %theplan; }
66 This should be the first thing you call in your test script. It
68 declares your testing plan, how many there will be, if any of them
69 should be allowed to fail, and so on.
70 Typical usage is just:
72 use Test;
74 BEGIN { plan tests => 23 }
75 These are the things that you can put in the parameters to plan:
77 "tests => number"
79 The number of tests in your script. This means all ok() and
80 skip() calls.
81 "todo => [1,5,14]"
83 A reference to a list of tests which are allowed to fail. See
84 "TODO TESTS".
85 "onfail => sub { ... }"
87 "onfail => \&some_sub"
88 A subroutine reference to be run at the end of the test script,
89 if any of the tests fail. See "ONFAIL".
90 You must call "plan(...)" once and only once. You should call it
92 in a "BEGIN {...}" block, like so:
93 BEGIN { plan tests => 23 }
95 "ok(...)"
97 ok(1 + 1 == 2);
98 ok($have, $expect);
99 ok($have, $expect, $diagnostics);
100 This function is the reason for "Test"'s existence. It's the basic
102 function that handles printing ""ok"" or ""not ok"", along with the
103 current test number. (That's what "Test::Harness" wants to see.)
104 In its most basic usage, "ok(...)" simply takes a single scalar
106 expression. If its value is true, the test passes; if false, the
107 test fails. Examples:
108 # Examples of ok(scalar)
110 ok( 1 + 1 == 2 ); # ok if 1 + 1 == 2
112 ok( $foo =~ /bar/ ); # ok if $foo contains 'bar'
113 ok( baz($x + $y) eq 'Armondo' ); # ok if baz($x + $y) returns
114 # 'Armondo'
115 ok( @a == @b ); # ok if @a and @b are the same length
116 The expression is evaluated in scalar context. So the following
118 will work:
119 ok( @stuff ); # ok if @stuff has any elements
121 ok( !grep !defined $_, @stuff ); # ok if everything in @stuff is
122 # defined.
123 A special case is if the expression is a subroutine reference (in
125 either "sub {...}" syntax or "\&foo" syntax). In that case, it is
126 executed and its value (true or false) determines if the test
127 passes or fails. For example,
128 ok( sub { # See whether sleep works at least passably
130 my $start_time = time;
131 sleep 5;
132 time() - $start_time >= 4
133 });
134 In its two-argument form, "ok(arg1, arg2)" compares the two scalar
136 values to see if they match. They match if both are undefined, or
137 if arg2 is a regex that matches arg1, or if they compare equal with
138 "eq".
139 # Example of ok(scalar, scalar)
141 ok( "this", "that" ); # not ok, 'this' ne 'that'
143 ok( "", undef ); # not ok, "" is defined
144 The second argument is considered a regex if it is either a regex
146 object or a string that looks like a regex. Regex objects are
147 constructed with the qr// operator in recent versions of perl. A
148 string is considered to look like a regex if its first and last
149 characters are "/", or if the first character is "m" and its second
150 and last characters are both the same non-alphanumeric non-
151 whitespace character. These regexp
152 Regex examples:
154 ok( 'JaffO', '/Jaff/' ); # ok, 'JaffO' =~ /Jaff/
156 ok( 'JaffO', 'm|Jaff|' ); # ok, 'JaffO' =~ m|Jaff|
157 ok( 'JaffO', qr/Jaff/ ); # ok, 'JaffO' =~ qr/Jaff/;
158 ok( 'JaffO', '/(?i)jaff/ ); # ok, 'JaffO' =~ /jaff/i;
159 If either (or both!) is a subroutine reference, it is run and used
161 as the value for comparing. For example:
162 ok sub {
164 open(OUT, ">x.dat") || die $!;
165 print OUT "\x{e000}";
166 close OUT;
167 my $bytecount = -s 'x.dat';
168 unlink 'x.dat' or warn "Can't unlink : $!";
169 return $bytecount;
170 },
171 4
172 ;
173 The above test passes two values to "ok(arg1, arg2)" -- the first a
175 coderef, and the second is the number 4. Before "ok" compares
176 them, it calls the coderef, and uses its return value as the real
177 value of this parameter. Assuming that $bytecount returns 4, "ok"
178 ends up testing "4 eq 4". Since that's true, this test passes.
179 Finally, you can append an optional third argument, in
181 "ok(arg1,arg2, note)", where note is a string value that will be
182 printed if the test fails. This should be some useful information
183 about the test, pertaining to why it failed, and/or a description
184 of the test. For example:
185 ok( grep($_ eq 'something unique', @stuff), 1,
187 "Something that should be unique isn't!\n".
188 '@stuff = '.join ', ', @stuff
189 );
190 Unfortunately, a note cannot be used with the single argument style
192 of "ok()". That is, if you try "ok(arg1, note)", then "Test" will
193 interpret this as "ok(arg1, arg2)", and probably end up testing
194 "arg1 eq arg2" -- and that's not what you want!
195 All of the above special cases can occasionally cause some
197 problems. See "BUGS and CAVEATS".
198 "skip(skip_if_true, args...)"
200 This is used for tests that under some conditions can be skipped.
201 It's basically equivalent to:
202 if( $skip_if_true ) {
204 ok(1);
205 } else {
206 ok( args... );
207 }
208 ...except that the ok(1) emits not just ""ok testnum"" but actually
210 ""ok testnum # skip_if_true_value"".
211 The arguments after the skip_if_true are what is fed to "ok(...)"
213 if this test isn't skipped.
214 Example usage:
216 my $if_MSWin =
218 $^O =~ m/MSWin/ ? 'Skip if under MSWin' : '';
219 # A test to be skipped if under MSWin (i.e., run except under MSWin)
221 skip($if_MSWin, thing($foo), thing($bar) );
222 Or, going the other way:
224 my $unless_MSWin =
226 $^O =~ m/MSWin/ ? '' : 'Skip unless under MSWin';
227 # A test to be skipped unless under MSWin (i.e., run only under MSWin)
229 skip($unless_MSWin, thing($foo), thing($bar) );
230 The tricky thing to remember is that the first parameter is true if
232 you want to skip the test, not run it; and it also doubles as a
233 note about why it's being skipped. So in the first codeblock above,
234 read the code as "skip if MSWin -- (otherwise) test whether
235 "thing($foo)" is "thing($bar)"" or for the second case, "skip
236 unless MSWin...".
237 Also, when your skip_if_reason string is true, it really should
239 (for backwards compatibility with older Test.pm versions) start
240 with the string "Skip", as shown in the above examples.
241 Note that in the above cases, "thing($foo)" and "thing($bar)" are
243 evaluated -- but as long as the "skip_if_true" is true, then we
244 "skip(...)" just tosses out their value (i.e., not bothering to
245 treat them like values to "ok(...)". But if you need to not eval
246 the arguments when skipping the test, use this format:
247 skip( $unless_MSWin,
249 sub {
250 # This code returns true if the test passes.
251 # (But it doesn't even get called if the test is skipped.)
252 thing($foo) eq thing($bar)
253 }
254 );
255 or even this, which is basically equivalent:
257 skip( $unless_MSWin,
259 sub { thing($foo) }, sub { thing($bar) }
260 );
261 That is, both are like this:
263 if( $unless_MSWin ) {
265 ok(1); # but it actually appends "# $unless_MSWin"
266 # so that Test::Harness can tell it's a skip
267 } else {
268 # Not skipping, so actually call and evaluate...
269 ok( sub { thing($foo) }, sub { thing($bar) } );
270 }
271
273 · NORMAL TESTS
274 These tests are expected to succeed. Usually, most or all of your
276 tests are in this category. If a normal test doesn't succeed, then
277 that means that something is wrong.
278 · SKIPPED TESTS
280 The "skip(...)" function is for tests that might or might not be
282 possible to run, depending on the availability of platform-specific
283 features. The first argument should evaluate to true (think "yes,
284 please skip") if the required feature is not available. After the
285 first argument, "skip(...)" works exactly the same way as "ok(...)"
286 does.
287 · TODO TESTS
289 TODO tests are designed for maintaining an executable TODO list.
291 These tests are expected to fail. If a TODO test does succeed,
292 then the feature in question shouldn't be on the TODO list, now
293 should it?
294 Packages should NOT be released with succeeding TODO tests. As
296 soon as a TODO test starts working, it should be promoted to a
297 normal test, and the newly working feature should be documented in
298 the release notes or in the change log.
299
301 BEGIN { plan test => 4, onfail => sub { warn "CALL 911!" } }
302 Although test failures should be enough, extra diagnostics can be
304 triggered at the end of a test run. "onfail" is passed an array ref of
305 hash refs that describe each test failure. Each hash will contain at
306 least the following fields: "package", "repetition", and "result".
307 (You shouldn't rely on any other fields being present.) If the test
308 had an expected value or a diagnostic (or "note") string, these will
309 also be included.
310 The optional "onfail" hook might be used simply to print out the
312 version of your package and/or how to report problems. It might also
313 be used to generate extremely sophisticated diagnostics for a
314 particularly bizarre test failure. However it's not a panacea. Core
315 dumps or other unrecoverable errors prevent the "onfail" hook from
316 running. (It is run inside an "END" block.) Besides, "onfail" is
317 probably over-kill in most cases. (Your test code should be simpler
318 than the code it is testing, yes?)
319
321 · "ok(...)"'s special handing of strings which look like they might
322 be regexes can also cause unexpected behavior. An innocent:
323 ok( $fileglob, '/path/to/some/*stuff/' );
325 will fail, since Test.pm considers the second argument to be a
327 regex! The best bet is to use the one-argument form:
328 ok( $fileglob eq '/path/to/some/*stuff/' );
330 · "ok(...)"'s use of string "eq" can sometimes cause odd problems
332 when comparing numbers, especially if you're casting a string to a
333 number:
334 $foo = "1.0";
336 ok( $foo, 1 ); # not ok, "1.0" ne 1
337 Your best bet is to use the single argument form:
339 ok( $foo == 1 ); # ok "1.0" == 1
341 · As you may have inferred from the above documentation and examples,
343 "ok"'s prototype is "($;$$)" (and, incidentally, "skip"'s is
344 "($;$$$)"). This means, for example, that you can do "ok @foo,
345 @bar" to compare the size of the two arrays. But don't be fooled
346 into thinking that "ok @foo, @bar" means a comparison of the
347 contents of two arrays -- you're comparing just the number of
348 elements of each. It's so easy to make that mistake in reading "ok
349 @foo, @bar" that you might want to be very explicit about it, and
350 instead write "ok scalar(@foo), scalar(@bar)".
351 · This almost definitely doesn't do what you expect:
353 ok $thingy->can('some_method');
355 Why? Because "can" returns a coderef to mean "yes it can (and the
357 method is this...)", and then "ok" sees a coderef and thinks you're
358 passing a function that you want it to call and consider the truth
359 of the result of! I.e., just like:
360 ok $thingy->can('some_method')->();
362 What you probably want instead is this:
364 ok $thingy->can('some_method') && 1;
366 If the "can" returns false, then that is passed to "ok". If it
368 returns true, then the larger expression
369 "$thingy->can('some_method') && 1" returns 1, which "ok" sees as a
370 simple signal of success, as you would expect.
371 · The syntax for "skip" is about the only way it can be, but it's
373 still quite confusing. Just start with the above examples and
374 you'll be okay.
375 Moreover, users may expect this:
377 skip $unless_mswin, foo($bar), baz($quux);
379 to not evaluate "foo($bar)" and "baz($quux)" when the test is being
381 skipped. But in reality, they are evaluated, but "skip" just won't
382 bother comparing them if $unless_mswin is true.
383 You could do this:
385 skip $unless_mswin, sub{foo($bar)}, sub{baz($quux)};
387 But that's not terribly pretty. You may find it simpler or clearer
389 in the long run to just do things like this:
390 if( $^O =~ m/MSWin/ ) {
392 print "# Yay, we're under $^O\n";
393 ok foo($bar), baz($quux);
394 ok thing($whatever), baz($stuff);
395 ok blorp($quux, $whatever);
396 ok foo($barzbarz), thang($quux);
397 } else {
398 print "# Feh, we're under $^O. Watch me skip some tests...\n";
399 for(1 .. 4) { skip "Skip unless under MSWin" }
400 }
401 But be quite sure that "ok" is called exactly as many times in the
403 first block as "skip" is called in the second block.
404
406 If "PERL_TEST_DIFF" environment variable is set, it will be used as a
407 command for comparing unexpected multiline results. If you have GNU
408 diff installed, you might want to set "PERL_TEST_DIFF" to "diff -u".
409 If you don't have a suitable program, you might install the
410 "Text::Diff" module and then set "PERL_TEST_DIFF" to be "perl
411 -MText::Diff -e 'print diff(@ARGV)'". If "PERL_TEST_DIFF" isn't set
412 but the "Algorithm::Diff" module is available, then it will be used to
413 show the differences in multiline results.
414
416 A past developer of this module once said that it was no longer being
417 actively developed. However, rumors of its demise were greatly
418 exaggerated. Feedback and suggestions are quite welcome.
419 Be aware that the main value of this module is its simplicity. Note
421 that there are already more ambitious modules out there, such as
422 Test::More and Test::Unit.
423 Some earlier versions of this module had docs with some confusing typos
425 in the description of "skip(...)".
426
428 Test::Harness
429 Test::Simple, Test::More, Devel::Cover
431 Test::Builder for building your own testing library.
433 Test::Unit is an interesting XUnit-style testing library.
435 Test::Inline and SelfTest let you embed tests in code.
437
439 Copyright (c) 1998-2000 Joshua Nathaniel Pritikin.
440 Copyright (c) 2001-2002 Michael G. Schwern.
442 Copyright (c) 2002-2004 Sean M. Burke.
444 Current maintainer: Jesse Vincent. <jesse@bestpractical.com>
446 This package is free software and is provided "as is" without express
448 or implied warranty. It may be used, redistributed and/or modified
449 under the same terms as Perl itself.
450perl v5.12.4 2011-06-01 Test(3pm)