1Test(3pm) Perl Programmers Reference Guide Test(3pm)
2
3
4
6 Test - provides a simple framework for writing test scripts
7
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
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
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
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
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
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
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
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
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
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.30.1 2019-11-29 Test(3pm)