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

TEST TYPES

273       ·   NORMAL TESTS
274
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
281           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
288       ·   TODO TESTS
289
290           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
295           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

ONFAIL

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

BUGS and CAVEATS

321       ·   "ok(...)"'s special handing of strings which look like they might
322           be regexes can also cause unexpected behavior.  An innocent:
323
324               ok( $fileglob, '/path/to/some/*stuff/' );
325
326           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
329               ok( $fileglob eq '/path/to/some/*stuff/' );
330
331       ·   "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
335               $foo = "1.0";
336               ok( $foo, 1 );      # not ok, "1.0" ne 1
337
338           Your best bet is to use the single argument form:
339
340               ok( $foo == 1 );    # ok "1.0" == 1
341
342       ·   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
352       ·   This almost definitely doesn't do what you expect:
353
354                ok $thingy->can('some_method');
355
356           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
361                ok $thingy->can('some_method')->();
362
363           What you probably want instead is this:
364
365                ok $thingy->can('some_method') && 1;
366
367           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
372       ·   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
376           Moreover, users may expect this:
377
378             skip $unless_mswin, foo($bar), baz($quux);
379
380           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
384           You could do this:
385
386             skip $unless_mswin, sub{foo($bar)}, sub{baz($quux)};
387
388           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
391             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
402           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

ENVIRONMENT

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

NOTE

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
420       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
424       Some earlier versions of this module had docs with some confusing typos
425       in the description of "skip(...)".
426

SEE ALSO

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

AUTHOR

439       Copyright (c) 1998-2000 Joshua Nathaniel Pritikin.
440
441       Copyright (c) 2001-2002 Michael G. Schwern.
442
443       Copyright (c) 2002-2004 Sean M. Burke.
444
445       Current maintainer: Jesse Vincent. <jesse@bestpractical.com>
446
447       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.
450
451
452
453perl v5.12.4                      2011-06-01                         Test(3pm)
Impressum