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, cre‐
55 ate a new file called t/test.t (in a new t directory). If you have mul‐
56 tiple 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
62 "skip(...)". By default, all three are exported by the "use Test;"
63 statement.
64 "plan(...)"
66 BEGIN { plan %theplan; }
67 This should be the first thing you call in your test script. It
69 declares your testing plan, how many there will be, if any of them
70 should be allowed to fail, and so on.
71 Typical usage is just:
73 use Test;
75 BEGIN { plan tests => 23 }
76 These are the things that you can put in the parameters to plan:
78 "tests => number"
80 The number of tests in your script. This means all ok() and
81 skip() calls.
82 "todo => [1,5,14]"
84 A reference to a list of tests which are allowed to fail. See
85 "TODO TESTS".
86 "onfail => sub { ... }"
88 "onfail => \&some_sub"
89 A subroutine reference to be run at the end of the test script,
90 if any of the tests fail. See "ONFAIL".
91 You must call "plan(...)" once and only once. You should call it
93 in a "BEGIN {...}" block, like so:
94 BEGIN { plan tests => 23 }
96 "ok(...)"
98 ok(1 + 1 == 2);
99 ok($have, $expect);
100 ok($have, $expect, $diagnostics);
101 This function is the reason for "Test"'s existence. It's the basic
103 function that handles printing ""ok"" or ""not ok"", along with the
104 current test number. (That's what "Test::Harness" wants to see.)
105 In its most basic usage, "ok(...)" simply takes a single scalar
107 expression. If its value is true, the test passes; if false, the
108 test fails. Examples:
109 # Examples of ok(scalar)
111 ok( 1 + 1 == 2 ); # ok if 1 + 1 == 2
113 ok( $foo =~ /bar/ ); # ok if $foo contains 'bar'
114 ok( baz($x + $y) eq 'Armondo' ); # ok if baz($x + $y) returns
115 # 'Armondo'
116 ok( @a == @b ); # ok if @a and @b are the same length
117 The expression is evaluated in scalar context. So the following
119 will work:
120 ok( @stuff ); # ok if @stuff has any elements
122 ok( !grep !defined $_, @stuff ); # ok if everything in @stuff is
123 # defined.
124 A special case is if the expression is a subroutine reference (in
126 either "sub {...}" syntax or "\&foo" syntax). In that case, it is
127 executed and its value (true or false) determines if the test
128 passes or fails. For example,
129 ok( sub { # See whether sleep works at least passably
131 my $start_time = time;
132 sleep 5;
133 time() - $start_time >= 4
134 });
135 In its two-argument form, "ok(arg1, arg2)" compares the two scalar
137 values to see if they match. They match if both are undefined, or
138 if arg2 is a regex that matches arg1, or if they compare equal with
139 "eq".
140 # Example of ok(scalar, scalar)
142 ok( "this", "that" ); # not ok, 'this' ne 'that'
144 ok( "", undef ); # not ok, "" is defined
145 The second argument is considered a regex if it is either a regex
147 object or a string that looks like a regex. Regex objects are con‐
148 structed with the qr// operator in recent versions of perl. A
149 string is considered to look like a regex if its first and last
150 characters are "/", or if the first character is "m" and its second
151 and last characters are both the same non-alphanumeric non-white‐
152 space character. These regexp
153 Regex examples:
155 ok( 'JaffO', '/Jaff/' ); # ok, 'JaffO' =~ /Jaff/
157 ok( 'JaffO', 'm⎪Jaff⎪' ); # ok, 'JaffO' =~ m⎪Jaff⎪
158 ok( 'JaffO', qr/Jaff/ ); # ok, 'JaffO' =~ qr/Jaff/;
159 ok( 'JaffO', '/(?i)jaff/ ); # ok, 'JaffO' =~ /jaff/i;
160 If either (or both!) is a subroutine reference, it is run and used
162 as the value for comparing. For example:
163 ok sub {
165 open(OUT, ">x.dat") ⎪⎪ die $!;
166 print OUT "\x{e000}";
167 close OUT;
168 my $bytecount = -s 'x.dat';
169 unlink 'x.dat' or warn "Can't unlink : $!";
170 return $bytecount;
171 },
172 4
173 ;
174 The above test passes two values to "ok(arg1, arg2)" -- the first a
176 coderef, and the second is the number 4. Before "ok" compares
177 them, it calls the coderef, and uses its return value as the real
178 value of this parameter. Assuming that $bytecount returns 4, "ok"
179 ends up testing "4 eq 4". Since that's true, this test passes.
180 Finally, you can append an optional third argument, in
182 "ok(arg1,arg2, note)", where note is a string value that will be
183 printed if the test fails. This should be some useful information
184 about the test, pertaining to why it failed, and/or a description
185 of the test. For example:
186 ok( grep($_ eq 'something unique', @stuff), 1,
188 "Something that should be unique isn't!\n".
189 '@stuff = '.join ', ', @stuff
190 );
191 Unfortunately, a note cannot be used with the single argument style
193 of "ok()". That is, if you try "ok(arg1, note)", then "Test" will
194 interpret this as "ok(arg1, arg2)", and probably end up testing
195 "arg1 eq arg2" -- and that's not what you want!
196 All of the above special cases can occasionally cause some prob‐
198 lems. See "BUGS and CAVEATS".
199 "skip(skip_if_true, args...)"
201 This is used for tests that under some conditions can be skipped.
202 It's basically equivalent to:
203 if( $skip_if_true ) {
205 ok(1);
206 } else {
207 ok( args... );
208 }
209 ...except that the ok(1) emits not just ""ok testnum"" but actually
211 ""ok testnum # skip_if_true_value"".
212 The arguments after the skip_if_true are what is fed to "ok(...)"
214 if this test isn't skipped.
215 Example usage:
217 my $if_MSWin =
219 $^O =~ m/MSWin/ ? 'Skip if under MSWin' : '';
220 # A test to be skipped if under MSWin (i.e., run except under MSWin)
222 skip($if_MSWin, thing($foo), thing($bar) );
223 Or, going the other way:
225 my $unless_MSWin =
227 $^O =~ m/MSWin/ ? '' : 'Skip unless under MSWin';
228 # A test to be skipped unless under MSWin (i.e., run only under MSWin)
230 skip($unless_MSWin, thing($foo), thing($bar) );
231 The tricky thing to remember is that the first parameter is true if
233 you want to skip the test, not run it; and it also doubles as a
234 note about why it's being skipped. So in the first codeblock above,
235 read the code as "skip if MSWin -- (otherwise) test whether
236 "thing($foo)" is "thing($bar)"" or for the second case, "skip
237 unless MSWin...".
238 Also, when your skip_if_reason string is true, it really should
240 (for backwards compatibility with older Test.pm versions) start
241 with the string "Skip", as shown in the above examples.
242 Note that in the above cases, "thing($foo)" and "thing($bar)" are
244 evaluated -- but as long as the "skip_if_true" is true, then we
245 "skip(...)" just tosses out their value (i.e., not bothering to
246 treat them like values to "ok(...)". But if you need to not eval
247 the arguments when skipping the test, use this format:
248 skip( $unless_MSWin,
250 sub {
251 # This code returns true if the test passes.
252 # (But it doesn't even get called if the test is skipped.)
253 thing($foo) eq thing($bar)
254 }
255 );
256 or even this, which is basically equivalent:
258 skip( $unless_MSWin,
260 sub { thing($foo) }, sub { thing($bar) }
261 );
262 That is, both are like this:
264 if( $unless_MSWin ) {
266 ok(1); # but it actually appends "# $unless_MSWin"
267 # so that Test::Harness can tell it's a skip
268 } else {
269 # Not skipping, so actually call and evaluate...
270 ok( sub { thing($foo) }, sub { thing($bar) } );
271 }
272
274 * NORMAL TESTS
275 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
281 possible to run, depending on the availability of platform-specific
282 features. The first argument should evaluate to true (think "yes,
283 please skip") if the required feature is not available. After the
284 first argument, "skip(...)" works exactly the same way as "ok(...)"
285 does.
286 * TODO TESTS
288 TODO tests are designed for maintaining an executable TODO list.
289 These tests are expected to fail. If a TODO test does succeed,
290 then the feature in question shouldn't be on the TODO list, now
291 should it?
292 Packages should NOT be released with succeeding TODO tests. As
294 soon as a TODO test starts working, it should be promoted to a nor‐
295 mal test, and the newly working feature should be documented in the
296 release notes or in the change log.
297
299 BEGIN { plan test => 4, onfail => sub { warn "CALL 911!" } }
300 Although test failures should be enough, extra diagnostics can be trig‐
302 gered at the end of a test run. "onfail" is passed an array ref of
303 hash refs that describe each test failure. Each hash will contain at
304 least the following fields: "package", "repetition", and "result".
305 (You shouldn't rely on any other fields being present.) If the test
306 had an expected value or a diagnostic (or "note") string, these will
307 also be included.
308 The optional "onfail" hook might be used simply to print out the ver‐
310 sion of your package and/or how to report problems. It might also be
311 used to generate extremely sophisticated diagnostics for a particularly
312 bizarre test failure. However it's not a panacea. Core dumps or other
313 unrecoverable errors prevent the "onfail" hook from running. (It is
314 run inside an "END" block.) Besides, "onfail" is probably over-kill in
315 most cases. (Your test code should be simpler than the code it is
316 testing, yes?)
317
319 · "ok(...)"'s special handing of strings which look like they might
320 be regexes can also cause unexpected behavior. An innocent:
321 ok( $fileglob, '/path/to/some/*stuff/' );
323 will fail, since Test.pm considers the second argument to be a
325 regex! The best bet is to use the one-argument form:
326 ok( $fileglob eq '/path/to/some/*stuff/' );
328 · "ok(...)"'s use of string "eq" can sometimes cause odd problems
330 when comparing numbers, especially if you're casting a string to a
331 number:
332 $foo = "1.0";
334 ok( $foo, 1 ); # not ok, "1.0" ne 1
335 Your best bet is to use the single argument form:
337 ok( $foo == 1 ); # ok "1.0" == 1
339 · As you may have inferred from the above documentation and examples,
341 "ok"'s prototype is "($;$$)" (and, incidentally, "skip"'s is
342 "($;$$$)"). This means, for example, that you can do "ok @foo,
343 @bar" to compare the size of the two arrays. But don't be fooled
344 into thinking that "ok @foo, @bar" means a comparison of the con‐
345 tents of two arrays -- you're comparing just the number of elements
346 of each. It's so easy to make that mistake in reading "ok @foo,
347 @bar" that you might want to be very explicit about it, and instead
348 write "ok scalar(@foo), scalar(@bar)".
349 · This almost definitely doesn't do what you expect:
351 ok $thingy->can('some_method');
353 Why? Because "can" returns a coderef to mean "yes it can (and the
355 method is this...)", and then "ok" sees a coderef and thinks you're
356 passing a function that you want it to call and consider the truth
357 of the result of! I.e., just like:
358 ok $thingy->can('some_method')->();
360 What you probably want instead is this:
362 ok $thingy->can('some_method') && 1;
364 If the "can" returns false, then that is passed to "ok". If it
366 returns true, then the larger expression
367 "$thingy->can('some_method') && 1" returns 1, which "ok" sees as a
368 simple signal of success, as you would expect.
369 · The syntax for "skip" is about the only way it can be, but it's
371 still quite confusing. Just start with the above examples and
372 you'll be okay.
373 Moreover, users may expect this:
375 skip $unless_mswin, foo($bar), baz($quux);
377 to not evaluate "foo($bar)" and "baz($quux)" when the test is being
379 skipped. But in reality, they are evaluated, but "skip" just won't
380 bother comparing them if $unless_mswin is true.
381 You could do this:
383 skip $unless_mswin, sub{foo($bar)}, sub{baz($quux)};
385 But that's not terribly pretty. You may find it simpler or clearer
387 in the long run to just do things like this:
388 if( $^O =~ m/MSWin/ ) {
390 print "# Yay, we're under $^O\n";
391 ok foo($bar), baz($quux);
392 ok thing($whatever), baz($stuff);
393 ok blorp($quux, $whatever);
394 ok foo($barzbarz), thang($quux);
395 } else {
396 print "# Feh, we're under $^O. Watch me skip some tests...\n";
397 for(1 .. 4) { skip "Skip unless under MSWin" }
398 }
399 But be quite sure that "ok" is called exactly as many times in the
401 first block as "skip" is called in the second block.
402
404 If "PERL_TEST_DIFF" environment variable is set, it will be used as a
405 command for comparing unexpected multiline results. If you have GNU
406 diff installed, you might want to set "PERL_TEST_DIFF" to "diff -u".
407 If you don't have a suitable program, you might install the
408 "Text::Diff" module and then set "PERL_TEST_DIFF" to be "perl
409 -MText::Diff -e 'print diff(@ARGV)'". If "PERL_TEST_DIFF" isn't set
410 but the "Algorithm::Diff" module is available, then it will be used to
411 show the differences in multiline results.
412
414 A past developer of this module once said that it was no longer being
415 actively developed. However, rumors of its demise were greatly exag‐
416 gerated. Feedback and suggestions are quite welcome.
417 Be aware that the main value of this module is its simplicity. Note
419 that there are already more ambitious modules out there, such as
420 Test::More and Test::Unit.
421 Some earlier versions of this module had docs with some confusing
423 typoes in the description of "skip(...)".
424
426 Test::Harness
427 Test::Simple, Test::More, Devel::Cover
429 Test::Builder for building your own testing library.
431 Test::Unit is an interesting XUnit-style testing library.
433 Test::Inline and SelfTest let you embed tests in code.
435
437 Copyright (c) 1998-2000 Joshua Nathaniel Pritikin. All rights
438 reserved.
439 Copyright (c) 2001-2002 Michael G. Schwern.
441 Copyright (c) 2002-2004 and counting Sean M. Burke.
443 Current maintainer: Sean M. Burke. <sburke@cpan.org>
445 This package is free software and is provided "as is" without express
447 or implied warranty. It may be used, redistributed and/or modified
448 under the same terms as Perl itself.
449perl v5.8.8 2001-09-21 Test(3pm)