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
116                                           # 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
122                                                   # elements
123               ok( !grep !defined $_, @stuff );    # ok if everything in @stuff
124                                                   # is defined.
125
126           A special case is if the expression is a subroutine reference (in
127           either "sub {...}" syntax or "\&foo" syntax).  In that case, it is
128           executed and its value (true or false) determines if the test
129           passes or fails.  For example,
130
131               ok( sub {   # See whether sleep works at least passably
132                 my $start_time = time;
133                 sleep 5;
134                 time() - $start_time  >= 4
135               });
136
137           In its two-argument form, "ok(arg1, arg2)" compares the two scalar
138           values to see if they match.  They match if both are undefined, or
139           if arg2 is a regex that matches arg1, or if they compare equal with
140           "eq".
141
142               # Example of ok(scalar, scalar)
143
144               ok( "this", "that" );               # not ok, 'this' ne 'that'
145               ok( "", undef );                    # not ok, "" is defined
146
147           The second argument is considered a regex if it is either a regex
148           object or a string that looks like a regex.  Regex objects are
149           constructed with the qr// operator in recent versions of perl.  A
150           string is considered to look like a regex if its first and last
151           characters are "/", or if the first character is "m" and its second
152           and last characters are both the same non-alphanumeric non-
153           whitespace character.  These regexp
154
155           Regex examples:
156
157               ok( 'JaffO', '/Jaff/' );    # ok, 'JaffO' =~ /Jaff/
158               ok( 'JaffO', 'm|Jaff|' );   # ok, 'JaffO' =~ m|Jaff|
159               ok( 'JaffO', qr/Jaff/ );    # ok, 'JaffO' =~ qr/Jaff/;
160               ok( 'JaffO', '/(?i)jaff/ ); # ok, 'JaffO' =~ /jaff/i;
161
162           If either (or both!) is a subroutine reference, it is run and used
163           as the value for comparing.  For example:
164
165               ok sub {
166                   open(OUT, '>', 'x.dat') || die $!;
167                   print OUT "\x{e000}";
168                   close OUT;
169                   my $bytecount = -s 'x.dat';
170                   unlink 'x.dat' or warn "Can't unlink : $!";
171                   return $bytecount;
172                 },
173                 4
174               ;
175
176           The above test passes two values to "ok(arg1, arg2)" -- the first a
177           coderef, and the second is the number 4.  Before "ok" compares
178           them, it calls the coderef, and uses its return value as the real
179           value of this parameter. Assuming that $bytecount returns 4, "ok"
180           ends up testing "4 eq 4".  Since that's true, this test passes.
181
182           Finally, you can append an optional third argument, in
183           "ok(arg1,arg2, note)", where note is a string value that will be
184           printed if the test fails.  This should be some useful information
185           about the test, pertaining to why it failed, and/or a description
186           of the test.  For example:
187
188               ok( grep($_ eq 'something unique', @stuff), 1,
189                   "Something that should be unique isn't!\n".
190                   '@stuff = '.join ', ', @stuff
191                 );
192
193           Unfortunately, a note cannot be used with the single argument style
194           of "ok()".  That is, if you try "ok(arg1, note)", then "Test" will
195           interpret this as "ok(arg1, arg2)", and probably end up testing
196           "arg1 eq arg2" -- and that's not what you want!
197
198           All of the above special cases can occasionally cause some
199           problems.  See "BUGS and CAVEATS".
200
201       "skip(skip_if_true, args...)"
202           This is used for tests that under some conditions can be skipped.
203           It's basically equivalent to:
204
205             if( $skip_if_true ) {
206               ok(1);
207             } else {
208               ok( args... );
209             }
210
211           ...except that the ok(1) emits not just ""ok testnum"" but actually
212           ""ok testnum # skip_if_true_value"".
213
214           The arguments after the skip_if_true are what is fed to "ok(...)"
215           if this test isn't skipped.
216
217           Example usage:
218
219             my $if_MSWin =
220               $^O =~ m/MSWin/ ? 'Skip if under MSWin' : '';
221
222             # A test to be skipped if under MSWin (i.e., run except under
223             # MSWin)
224             skip($if_MSWin, thing($foo), thing($bar) );
225
226           Or, going the other way:
227
228             my $unless_MSWin =
229               $^O =~ m/MSWin/ ? '' : 'Skip unless under MSWin';
230
231             # A test to be skipped unless under MSWin (i.e., run only under
232             # MSWin)
233             skip($unless_MSWin, thing($foo), thing($bar) );
234
235           The tricky thing to remember is that the first parameter is true if
236           you want to skip the test, not run it; and it also doubles as a
237           note about why it's being skipped. So in the first codeblock above,
238           read the code as "skip if MSWin -- (otherwise) test whether
239           "thing($foo)" is "thing($bar)"" or for the second case, "skip
240           unless MSWin...".
241
242           Also, when your skip_if_reason string is true, it really should
243           (for backwards compatibility with older Test.pm versions) start
244           with the string "Skip", as shown in the above examples.
245
246           Note that in the above cases, "thing($foo)" and "thing($bar)" are
247           evaluated -- but as long as the "skip_if_true" is true, then we
248           "skip(...)" just tosses out their value (i.e., not bothering to
249           treat them like values to "ok(...)".  But if you need to not eval
250           the arguments when skipping the test, use this format:
251
252             skip( $unless_MSWin,
253               sub {
254                 # This code returns true if the test passes.
255                 # (But it doesn't even get called if the test is skipped.)
256                 thing($foo) eq thing($bar)
257               }
258             );
259
260           or even this, which is basically equivalent:
261
262             skip( $unless_MSWin,
263               sub { thing($foo) }, sub { thing($bar) }
264             );
265
266           That is, both are like this:
267
268             if( $unless_MSWin ) {
269               ok(1);  # but it actually appends "# $unless_MSWin"
270                       #  so that Test::Harness can tell it's a skip
271             } else {
272               # Not skipping, so actually call and evaluate...
273               ok( sub { thing($foo) }, sub { thing($bar) } );
274             }
275

TEST TYPES

277       •   NORMAL TESTS
278
279           These tests are expected to succeed.  Usually, most or all of your
280           tests are in this category.  If a normal test doesn't succeed, then
281           that means that something is wrong.
282
283       •   SKIPPED TESTS
284
285           The "skip(...)" function is for tests that might or might not be
286           possible to run, depending on the availability of platform-specific
287           features.  The first argument should evaluate to true (think "yes,
288           please skip") if the required feature is not available.  After the
289           first argument, "skip(...)" works exactly the same way as "ok(...)"
290           does.
291
292       •   TODO TESTS
293
294           TODO tests are designed for maintaining an executable TODO list.
295           These tests are expected to fail.  If a TODO test does succeed,
296           then the feature in question shouldn't be on the TODO list, now
297           should it?
298
299           Packages should NOT be released with succeeding TODO tests.  As
300           soon as a TODO test starts working, it should be promoted to a
301           normal test, and the newly working feature should be documented in
302           the release notes or in the change log.
303

ONFAIL

305         BEGIN { plan test => 4, onfail => sub { warn "CALL 911!" } }
306
307       Although test failures should be enough, extra diagnostics can be
308       triggered at the end of a test run.  "onfail" is passed an array ref of
309       hash refs that describe each test failure.  Each hash will contain at
310       least the following fields: "package", "repetition", and "result".
311       (You shouldn't rely on any other fields being present.)  If the test
312       had an expected value or a diagnostic (or "note") string, these will
313       also be included.
314
315       The optional "onfail" hook might be used simply to print out the
316       version of your package and/or how to report problems.  It might also
317       be used to generate extremely sophisticated diagnostics for a
318       particularly bizarre test failure.  However it's not a panacea.  Core
319       dumps or other unrecoverable errors prevent the "onfail" hook from
320       running.  (It is run inside an "END" block.)  Besides, "onfail" is
321       probably over-kill in most cases.  (Your test code should be simpler
322       than the code it is testing, yes?)
323

BUGS and CAVEATS

325       •   "ok(...)"'s special handing of strings which look like they might
326           be regexes can also cause unexpected behavior.  An innocent:
327
328               ok( $fileglob, '/path/to/some/*stuff/' );
329
330           will fail, since Test.pm considers the second argument to be a
331           regex!  The best bet is to use the one-argument form:
332
333               ok( $fileglob eq '/path/to/some/*stuff/' );
334
335       •   "ok(...)"'s use of string "eq" can sometimes cause odd problems
336           when comparing numbers, especially if you're casting a string to a
337           number:
338
339               $foo = "1.0";
340               ok( $foo, 1 );      # not ok, "1.0" ne 1
341
342           Your best bet is to use the single argument form:
343
344               ok( $foo == 1 );    # ok "1.0" == 1
345
346       •   As you may have inferred from the above documentation and examples,
347           "ok"'s prototype is "($;$$)" (and, incidentally, "skip"'s is
348           "($;$$$)"). This means, for example, that you can do "ok @foo,
349           @bar" to compare the size of the two arrays. But don't be fooled
350           into thinking that "ok @foo, @bar" means a comparison of the
351           contents of two arrays -- you're comparing just the number of
352           elements of each. It's so easy to make that mistake in reading "ok
353           @foo, @bar" that you might want to be very explicit about it, and
354           instead write "ok scalar(@foo), scalar(@bar)".
355
356       •   This almost definitely doesn't do what you expect:
357
358                ok $thingy->can('some_method');
359
360           Why?  Because "can" returns a coderef to mean "yes it can (and the
361           method is this...)", and then "ok" sees a coderef and thinks you're
362           passing a function that you want it to call and consider the truth
363           of the result of!  I.e., just like:
364
365                ok $thingy->can('some_method')->();
366
367           What you probably want instead is this:
368
369                ok $thingy->can('some_method') && 1;
370
371           If the "can" returns false, then that is passed to "ok".  If it
372           returns true, then the larger expression
373           "$thingy->can('some_method') && 1" returns 1, which "ok" sees as a
374           simple signal of success, as you would expect.
375
376       •   The syntax for "skip" is about the only way it can be, but it's
377           still quite confusing.  Just start with the above examples and
378           you'll be okay.
379
380           Moreover, users may expect this:
381
382             skip $unless_mswin, foo($bar), baz($quux);
383
384           to not evaluate "foo($bar)" and "baz($quux)" when the test is being
385           skipped.  But in reality, they are evaluated, but "skip" just won't
386           bother comparing them if $unless_mswin is true.
387
388           You could do this:
389
390             skip $unless_mswin, sub{foo($bar)}, sub{baz($quux)};
391
392           But that's not terribly pretty.  You may find it simpler or clearer
393           in the long run to just do things like this:
394
395             if( $^O =~ m/MSWin/ ) {
396               print "# Yay, we're under $^O\n";
397               ok foo($bar), baz($quux);
398               ok thing($whatever), baz($stuff);
399               ok blorp($quux, $whatever);
400               ok foo($barzbarz), thang($quux);
401             } else {
402               print "# Feh, we're under $^O.  Watch me skip some tests...\n";
403               for(1 .. 4) { skip "Skip unless under MSWin" }
404             }
405
406           But be quite sure that "ok" is called exactly as many times in the
407           first block as "skip" is called in the second block.
408

ENVIRONMENT

410       If "PERL_TEST_DIFF" environment variable is set, it will be used as a
411       command for comparing unexpected multiline results.  If you have GNU
412       diff installed, you might want to set "PERL_TEST_DIFF" to "diff -u".
413       If you don't have a suitable program, you might install the
414       "Text::Diff" module and then set "PERL_TEST_DIFF" to be "perl
415       -MText::Diff -e 'print diff(@ARGV)'".  If "PERL_TEST_DIFF" isn't set
416       but the "Algorithm::Diff" module is available, then it will be used to
417       show the differences in multiline results.
418

NOTE

420       A past developer of this module once said that it was no longer being
421       actively developed.  However, rumors of its demise were greatly
422       exaggerated.  Feedback and suggestions are quite welcome.
423
424       Be aware that the main value of this module is its simplicity.  Note
425       that there are already more ambitious modules out there, such as
426       Test::More and Test::Unit.
427
428       Some earlier versions of this module had docs with some confusing typos
429       in the description of "skip(...)".
430

SEE ALSO

432       Test::Harness
433
434       Test::Simple, Test::More, Devel::Cover
435
436       Test::Builder for building your own testing library.
437
438       Test::Unit is an interesting XUnit-style testing library.
439
440       Test::Inline lets you embed tests in code.
441

AUTHOR

443       Copyright (c) 1998-2000 Joshua Nathaniel Pritikin.
444
445       Copyright (c) 2001-2002 Michael G. Schwern.
446
447       Copyright (c) 2002-2004 Sean M. Burke.
448
449       Current maintainer: Jesse Vincent. <jesse@bestpractical.com>
450
451       This package is free software and is provided "as is" without express
452       or implied warranty.  It may be used, redistributed and/or modified
453       under the same terms as Perl itself.
454
455
456
457perl v5.34.1                      2022-03-15                         Test(3pm)
Impressum