1Test(3pm)              Perl Programmers Reference Guide              Test(3pm)
2
3
4

NAME

6       Test - provides a simple framework for writing test scripts
7

SYNOPSIS

9         use strict;
10         use Test;
11
12         # use a BEGIN block so we print our plan before MyModule is loaded
13         BEGIN { plan tests => 14, todo => [3,4] }
14
15         # load your module...
16         use MyModule;
17
18         # Helpful notes.  All note-lines must start with a "#".
19         print "# I'm testing MyModule version $MyModule::VERSION\n";
20
21         ok(0); # failure
22         ok(1); # success
23
24         ok(0); # ok, expected failure (see todo list, above)
25         ok(1); # surprise success!
26
27         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
32         ok(sub { 1+1 }, 2);  # success: '2' eq '2'
33         ok(sub { 1+1 }, 3);  # failure: '2' ne '3'
34
35         my @list = (0,0);
36         ok @list, 3, "\@list=".join(',',@list);      #extra notes
37         ok 'segmentation fault', '/(?i)success/';    #regex match
38
39         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

DESCRIPTION

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

QUICK START GUIDE

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
59       Functions
60
61       This module defines three public functions, "plan(...)", "ok(...)", and
62       "skip(...)".  By default, all three are exported by the "use Test;"
63       statement.
64
65       "plan(...)"
66                BEGIN { plan %theplan; }
67
68           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
72           Typical usage is just:
73
74                use Test;
75                BEGIN { plan tests => 23 }
76
77           These are the things that you can put in the parameters to plan:
78
79           "tests => number"
80               The number of tests in your script.  This means all ok() and
81               skip() calls.
82
83           "todo => [1,5,14]"
84               A reference to a list of tests which are allowed to fail.  See
85               "TODO TESTS".
86
87           "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
92           You must call "plan(...)" once and only once.  You should call it
93           in a "BEGIN {...}" block, like so:
94
95                BEGIN { plan tests => 23 }
96
97       "ok(...)"
98             ok(1 + 1 == 2);
99             ok($have, $expect);
100             ok($have, $expect, $diagnostics);
101
102           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
106           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
110               # Examples of ok(scalar)
111
112               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
118           The expression is evaluated in scalar context.  So the following
119           will work:
120
121               ok( @stuff );                       # ok if @stuff has any elements
122               ok( !grep !defined $_, @stuff );    # ok if everything in @stuff is
123                                                   # defined.
124
125           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
130               ok( sub {   # See whether sleep works at least passably
131                 my $start_time = time;
132                 sleep 5;
133                 time() - $start_time  >= 4
134               });
135
136           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
141               # Example of ok(scalar, scalar)
142
143               ok( "this", "that" );               # not ok, 'this' ne 'that'
144               ok( "", undef );                    # not ok, "" is defined
145
146           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
154           Regex examples:
155
156               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
161           If either (or both!) is a subroutine reference, it is run and used
162           as the value for comparing.  For example:
163
164               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
175           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
181           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
187               ok( grep($_ eq 'something unique', @stuff), 1,
188                   "Something that should be unique isn't!\n".
189                   '@stuff = '.join ', ', @stuff
190                 );
191
192           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
197           All of the above special cases can occasionally cause some prob‐
198           lems.  See "BUGS and CAVEATS".
199
200       "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
204             if( $skip_if_true ) {
205               ok(1);
206             } else {
207               ok( args... );
208             }
209
210           ...except that the ok(1) emits not just ""ok testnum"" but actually
211           ""ok testnum # skip_if_true_value"".
212
213           The arguments after the skip_if_true are what is fed to "ok(...)"
214           if this test isn't skipped.
215
216           Example usage:
217
218             my $if_MSWin =
219               $^O =~ m/MSWin/ ? 'Skip if under MSWin' : '';
220
221             # A test to be skipped if under MSWin (i.e., run except under MSWin)
222             skip($if_MSWin, thing($foo), thing($bar) );
223
224           Or, going the other way:
225
226             my $unless_MSWin =
227               $^O =~ m/MSWin/ ? '' : 'Skip unless under MSWin';
228
229             # A test to be skipped unless under MSWin (i.e., run only under MSWin)
230             skip($unless_MSWin, thing($foo), thing($bar) );
231
232           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
239           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
243           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
249             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
257           or even this, which is basically equivalent:
258
259             skip( $unless_MSWin,
260               sub { thing($foo) }, sub { thing($bar) }
261             );
262
263           That is, both are like this:
264
265             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

TEST TYPES

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
279       * 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
287       * 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
293           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

ONFAIL

299         BEGIN { plan test => 4, onfail => sub { warn "CALL 911!" } }
300
301       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
309       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

BUGS and CAVEATS

319       ·   "ok(...)"'s special handing of strings which look like they might
320           be regexes can also cause unexpected behavior.  An innocent:
321
322               ok( $fileglob, '/path/to/some/*stuff/' );
323
324           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
327               ok( $fileglob eq '/path/to/some/*stuff/' );
328
329       ·   "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
333               $foo = "1.0";
334               ok( $foo, 1 );      # not ok, "1.0" ne 1
335
336           Your best bet is to use the single argument form:
337
338               ok( $foo == 1 );    # ok "1.0" == 1
339
340       ·   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
350       ·   This almost definitely doesn't do what you expect:
351
352                ok $thingy->can('some_method');
353
354           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
359                ok $thingy->can('some_method')->();
360
361           What you probably want instead is this:
362
363                ok $thingy->can('some_method') && 1;
364
365           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
370       ·   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
374           Moreover, users may expect this:
375
376             skip $unless_mswin, foo($bar), baz($quux);
377
378           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
382           You could do this:
383
384             skip $unless_mswin, sub{foo($bar)}, sub{baz($quux)};
385
386           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
389             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
400           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

ENVIRONMENT

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

NOTE

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
418       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
422       Some earlier versions of this module had docs with some confusing
423       typoes in the description of "skip(...)".
424

SEE ALSO

426       Test::Harness
427
428       Test::Simple, Test::More, Devel::Cover
429
430       Test::Builder for building your own testing library.
431
432       Test::Unit is an interesting XUnit-style testing library.
433
434       Test::Inline and SelfTest let you embed tests in code.
435

AUTHOR

437       Copyright (c) 1998-2000 Joshua Nathaniel Pritikin.  All rights
438       reserved.
439
440       Copyright (c) 2001-2002 Michael G. Schwern.
441
442       Copyright (c) 2002-2004 and counting Sean M. Burke.
443
444       Current maintainer: Sean M. Burke. <sburke@cpan.org>
445
446       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.
449
450
451
452perl v5.8.8                       2001-09-21                         Test(3pm)
Impressum