1 |
-----BEGIN PGP SIGNED MESSAGE----- |
2 |
Hash: SHA1 |
3 |
|
4 |
dams wrote: |
5 |
> test |
6 |
|
7 |
NAME |
8 |
Test - provides a simple framework for writing test scripts |
9 |
|
10 |
SYNOPSIS |
11 |
use strict; |
12 |
use Test; |
13 |
|
14 |
# use a BEGIN block so we print our plan before MyModule is loaded |
15 |
BEGIN { plan tests => 14, todo => [3,4] } |
16 |
|
17 |
# load your module... |
18 |
use MyModule; |
19 |
|
20 |
# Helpful notes. All note-lines must start with a "#". |
21 |
print "# I'm testing MyModule version $MyModule::VERSION\n"; |
22 |
|
23 |
ok(0); # failure |
24 |
ok(1); # success |
25 |
|
26 |
ok(0); # ok, expected failure (see todo list, above) |
27 |
ok(1); # surprise success! |
28 |
|
29 |
ok(0,1); # failure: '0' ne '1' |
30 |
ok('broke','fixed'); # failure: 'broke' ne 'fixed' |
31 |
ok('fixed','fixed'); # success: 'fixed' eq 'fixed' |
32 |
ok('fixed',qr/x/); # success: 'fixed' =~ qr/x/ |
33 |
|
34 |
ok(sub { 1+1 }, 2); # success: '2' eq '2' |
35 |
ok(sub { 1+1 }, 3); # failure: '2' ne '3' |
36 |
|
37 |
my @list = (0,0); |
38 |
ok @list, 3, "\@list=".join(',',@list); #extra notes |
39 |
ok 'segmentation fault', '/(?i)success/'; #regex match |
40 |
|
41 |
skip( |
42 |
$^O =~ m/MSWin/ ? "Skip if MSWin" : 0, # whether to skip |
43 |
$foo, $bar # arguments just like for ok(...) |
44 |
); |
45 |
skip( |
46 |
$^O =~ m/MSWin/ ? 0 : "Skip unless MSWin", # whether to skip |
47 |
$foo, $bar # arguments just like for ok(...) |
48 |
); |
49 |
|
50 |
DESCRIPTION |
51 |
This module simplifies the task of writing test files for Perl modules, |
52 |
such that their output is in the format that Test::Harness expects to |
53 |
see. |
54 |
|
55 |
QUICK START GUIDE |
56 |
To write a test for your new (and probably not even done) module, create |
57 |
a new file called t/test.t (in a new t directory). If you have multiple |
58 |
test files, to test the "foo", "bar", and "baz" feature sets, then feel |
59 |
free to call your files t/foo.t, t/bar.t, and t/baz.t |
60 |
|
61 |
Functions |
62 |
This module defines three public functions, "plan(...)", "ok(...)", and |
63 |
"skip(...)". By default, all three are exported by the "use Test;" |
64 |
statement. |
65 |
|
66 |
"plan(...)" |
67 |
BEGIN { plan %theplan; } |
68 |
|
69 |
This should be the first thing you call in your test script. It |
70 |
declares your testing plan, how many there will be, if any of them |
71 |
should be allowed to fail, and so on. |
72 |
|
73 |
Typical usage is just: |
74 |
|
75 |
use Test; |
76 |
BEGIN { plan tests => 23 } |
77 |
|
78 |
These are the things that you can put in the parameters to plan: |
79 |
|
80 |
"tests => *number*" |
81 |
The number of tests in your script. This means all ok() and |
82 |
skip() calls. |
83 |
|
84 |
"todo => [*1,5,14*]" |
85 |
A reference to a list of tests which are allowed to fail. See |
86 |
"TODO TESTS". |
87 |
|
88 |
"onfail => sub { ... }" |
89 |
"onfail => \&some_sub" |
90 |
A subroutine reference to be run at the end of the test script, |
91 |
if any of the tests fail. See "ONFAIL". |
92 |
|
93 |
You must call "plan(...)" once and only once. You should call it in |
94 |
a "BEGIN {...}" block, like so: |
95 |
|
96 |
BEGIN { plan tests => 23 } |
97 |
|
98 |
"ok(...)" |
99 |
ok(1 + 1 == 2); |
100 |
ok($have, $expect); |
101 |
ok($have, $expect, $diagnostics); |
102 |
|
103 |
This function is the reason for "Test"'s existence. It's the basic |
104 |
function that handles printing ""ok"" or ""not ok"", along with the |
105 |
current test number. (That's what "Test::Harness" wants to see.) |
106 |
|
107 |
In its most basic usage, "ok(...)" simply takes a single scalar |
108 |
expression. If its value is true, the test passes; if false, the |
109 |
test fails. Examples: |
110 |
|
111 |
# Examples of ok(scalar) |
112 |
|
113 |
ok( 1 + 1 == 2 ); # ok if 1 + 1 == 2 |
114 |
ok( $foo =~ /bar/ ); # ok if $foo contains 'bar' |
115 |
ok( baz($x + $y) eq 'Armondo' ); # ok if baz($x + $y) returns |
116 |
# 'Armondo' |
117 |
ok( @a == @b ); # ok if @a and @b are the same |
118 |
length |
119 |
|
120 |
The expression is evaluated in scalar context. So the following will |
121 |
work: |
122 |
|
123 |
ok( @stuff ); # ok if @stuff has any |
124 |
elements |
125 |
ok( !grep !defined $_, @stuff ); # ok if everything in |
126 |
@stuff is |
127 |
# defined. |
128 |
|
129 |
A special case is if the expression is a subroutine reference (in |
130 |
either "sub {...}" syntax or "\&foo" syntax). In that case, it is |
131 |
executed and its value (true or false) determines if the test passes |
132 |
or fails. For example, |
133 |
|
134 |
ok( sub { # See whether sleep works at least passably |
135 |
my $start_time = time; |
136 |
sleep 5; |
137 |
time() - $start_time >= 4 |
138 |
}); |
139 |
|
140 |
In its two-argument form, "ok(*arg1*, *arg2*)" compares the two |
141 |
scalar values to see if they match. They match if both are |
142 |
undefined, or if *arg2* is a regex that matches *arg1*, or if they |
143 |
compare equal with "eq". |
144 |
|
145 |
# Example of ok(scalar, scalar) |
146 |
|
147 |
ok( "this", "that" ); # not ok, 'this' ne 'that' |
148 |
ok( "", undef ); # not ok, "" is defined |
149 |
|
150 |
The second argument is considered a regex if it is either a regex |
151 |
object or a string that looks like a regex. Regex objects are |
152 |
constructed with the qr// operator in recent versions of perl. A |
153 |
string is considered to look like a regex if its first and last |
154 |
characters are "/", or if the first character is "m" and its second |
155 |
and last characters are both the same non-alphanumeric |
156 |
non-whitespace character. These regexp |
157 |
|
158 |
Regex examples: |
159 |
|
160 |
ok( 'JaffO', '/Jaff/' ); # ok, 'JaffO' =~ /Jaff/ |
161 |
ok( 'JaffO', 'm|Jaff|' ); # ok, 'JaffO' =~ m|Jaff| |
162 |
ok( 'JaffO', qr/Jaff/ ); # ok, 'JaffO' =~ qr/Jaff/; |
163 |
ok( 'JaffO', '/(?i)jaff/ ); # ok, 'JaffO' =~ /jaff/i; |
164 |
|
165 |
If either (or both!) is a subroutine reference, it is run and used |
166 |
as the value for comparing. For example: |
167 |
|
168 |
ok sub { |
169 |
open(OUT, ">x.dat") || die $!; |
170 |
print OUT "\x{e000}"; |
171 |
close OUT; |
172 |
my $bytecount = -s 'x.dat'; |
173 |
unlink 'x.dat' or warn "Can't unlink : $!"; |
174 |
return $bytecount; |
175 |
}, |
176 |
4 |
177 |
; |
178 |
|
179 |
The above test passes two values to "ok(arg1, arg2)" -- the first a |
180 |
coderef, and the second is the number 4. Before "ok" compares them, |
181 |
it calls the coderef, and uses its return value as the real value of |
182 |
this parameter. Assuming that $bytecount returns 4, "ok" ends up |
183 |
testing "4 eq 4". Since that's true, this test passes. |
184 |
|
185 |
Finally, you can append an optional third argument, in |
186 |
"ok(*arg1*,*arg2*, *note*)", where *note* is a string value that |
187 |
will be printed if the test fails. This should be some useful |
188 |
information about the test, pertaining to why it failed, and/or a |
189 |
description of the test. For example: |
190 |
|
191 |
ok( grep($_ eq 'something unique', @stuff), 1, |
192 |
"Something that should be unique isn't!\n". |
193 |
'@stuff = '.join ', ', @stuff |
194 |
); |
195 |
|
196 |
Unfortunately, a note cannot be used with the single argument style |
197 |
of "ok()". That is, if you try "ok(*arg1*, *note*)", then "Test" |
198 |
will interpret this as "ok(*arg1*, *arg2*)", and probably end up |
199 |
testing "*arg1* eq *arg2*" -- and that's not what you want! |
200 |
|
201 |
All of the above special cases can occasionally cause some problems. |
202 |
See "BUGS and CAVEATS". |
203 |
|
204 |
"skip(*skip_if_true*, *args...*)" |
205 |
This is used for tests that under some conditions can be skipped. |
206 |
It's basically equivalent to: |
207 |
|
208 |
if( $skip_if_true ) { |
209 |
ok(1); |
210 |
} else { |
211 |
ok( args... ); |
212 |
} |
213 |
|
214 |
...except that the ok(1) emits not just ""ok *testnum*"" but |
215 |
actually ""ok *testnum* # *skip_if_true_value*"". |
216 |
|
217 |
The arguments after the *skip_if_true* are what is fed to "ok(...)" |
218 |
if this test isn't skipped. |
219 |
|
220 |
Example usage: |
221 |
|
222 |
my $if_MSWin = |
223 |
$^O =~ m/MSWin/ ? 'Skip if under MSWin' : ''; |
224 |
|
225 |
# A test to be skipped if under MSWin (i.e., run except under |
226 |
MSWin) |
227 |
skip($if_MSWin, thing($foo), thing($bar) ); |
228 |
|
229 |
Or, going the other way: |
230 |
|
231 |
my $unless_MSWin = |
232 |
$^O =~ m/MSWin/ ? '' : 'Skip unless under MSWin'; |
233 |
|
234 |
# A test to be skipped unless under MSWin (i.e., run only |
235 |
under MSWin) |
236 |
skip($unless_MSWin, thing($foo), thing($bar) ); |
237 |
|
238 |
The tricky thing to remember is that the first parameter is true if |
239 |
you want to *skip* the test, not *run* it; and it also doubles as a |
240 |
note about why it's being skipped. So in the first codeblock above, |
241 |
read the code as "skip if MSWin -- (otherwise) test whether |
242 |
"thing($foo)" is "thing($bar)"" or for the second case, "skip unless |
243 |
MSWin...". |
244 |
|
245 |
Also, when your *skip_if_reason* string is true, it really should |
246 |
(for backwards compatibility with older Test.pm versions) start with |
247 |
the string "Skip", as shown in the above examples. |
248 |
|
249 |
Note that in the above cases, "thing($foo)" and "thing($bar)" *are* |
250 |
evaluated -- but as long as the "skip_if_true" is true, then we |
251 |
"skip(...)" just tosses out their value (i.e., not bothering to |
252 |
treat them like values to "ok(...)". But if you need to *not* eval |
253 |
the arguments when skipping the test, use this format: |
254 |
|
255 |
skip( $unless_MSWin, |
256 |
sub { |
257 |
# This code returns true if the test passes. |
258 |
# (But it doesn't even get called if the test is skipped.) |
259 |
thing($foo) eq thing($bar) |
260 |
} |
261 |
); |
262 |
|
263 |
or even this, which is basically equivalent: |
264 |
|
265 |
skip( $unless_MSWin, |
266 |
sub { thing($foo) }, sub { thing($bar) } |
267 |
); |
268 |
|
269 |
That is, both are like this: |
270 |
|
271 |
if( $unless_MSWin ) { |
272 |
ok(1); # but it actually appends "# $unless_MSWin" |
273 |
# so that Test::Harness can tell it's a skip |
274 |
} else { |
275 |
# Not skipping, so actually call and evaluate... |
276 |
ok( sub { thing($foo) }, sub { thing($bar) } ); |
277 |
} |
278 |
|
279 |
TEST TYPES |
280 |
* NORMAL TESTS |
281 |
These tests are expected to succeed. Usually, most or all of your |
282 |
tests are in this category. If a normal test doesn't succeed, then |
283 |
that means that something is *wrong*. |
284 |
|
285 |
* SKIPPED TESTS |
286 |
The "skip(...)" function is for tests that might or might not be |
287 |
possible to run, depending on the availability of platform-specific |
288 |
features. The first argument should evaluate to true (think "yes, |
289 |
please skip") if the required feature is *not* available. After the |
290 |
first argument, "skip(...)" works exactly the same way as "ok(...)" |
291 |
does. |
292 |
|
293 |
* TODO TESTS |
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 soon |
300 |
as a TODO test starts working, it should be promoted to a normal |
301 |
test, and the newly working feature should be documented in the |
302 |
release notes or in the change log. |
303 |
|
304 |
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". (You |
311 |
shouldn't rely on any other fields being present.) If the test had an |
312 |
expected value or a diagnostic (or "note") string, these will also be |
313 |
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 be |
317 |
used to generate extremely sophisticated diagnostics for a particularly |
318 |
bizarre test failure. However it's not a panacea. Core dumps or other |
319 |
unrecoverable errors prevent the "onfail" hook from running. (It is run |
320 |
inside an "END" block.) Besides, "onfail" is probably over-kill in most |
321 |
cases. (Your test code should be simpler than the code it is testing, |
322 |
yes?) |
323 |
|
324 |
BUGS and CAVEATS |
325 |
* "ok(...)"'s special handing of strings which look like they might be |
326 |
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 when |
336 |
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, @bar" |
349 |
to compare the *size* of the two arrays. But don't be fooled into |
350 |
thinking that "ok @foo, @bar" means a comparison of the contents of |
351 |
two arrays -- you're comparing *just* the number of elements of |
352 |
each. It's so easy to make that mistake in reading "ok @foo, @bar" |
353 |
that you might want to be very explicit about it, and instead write |
354 |
"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 you'll |
378 |
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 |
|
409 |
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 diff |
412 |
installed, you might want to set "PERL_TEST_DIFF" to "diff -u". If you |
413 |
don't have a suitable program, you might install the "Text::Diff" module |
414 |
and then set "PERL_TEST_DIFF" to be "perl -MText::Diff -e 'print |
415 |
diff(@ARGV)'". If "PERL_TEST_DIFF" isn't set but the "Algorithm::Diff" |
416 |
module is available, then it will be used to show the differences in |
417 |
multiline results. |
418 |
|
419 |
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 that |
425 |
there are already more ambitious modules out there, such as Test::More |
426 |
and Test::Unit. |
427 |
|
428 |
Some earlier versions of this module had docs with some confusing typoes |
429 |
in the description of "skip(...)". |
430 |
|
431 |
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 and SelfTest let you embed tests in code. |
441 |
|
442 |
AUTHOR |
443 |
Copyright (c) 1998-2000 Joshua Nathaniel Pritikin. All rights reserved. |
444 |
|
445 |
Copyright (c) 2001-2002 Michael G. Schwern. |
446 |
|
447 |
Copyright (c) 2002-2004 and counting Sean M. Burke. |
448 |
|
449 |
Current maintainer: Sean M. Burke. <sburke@××××.org> |
450 |
|
451 |
This package is free software and is provided "as is" without express or |
452 |
implied warranty. It may be used, redistributed and/or modified under |
453 |
the same terms as Perl itself. |
454 |
|
455 |
|
456 |
|
457 |
- -- |
458 |
|
459 |
- -----o()o---------------------------------------------- |
460 |
Michael Cummings | #gentoo-dev, #gentoo-perl |
461 |
Gentoo Perl Dev | on irc.freenode.net |
462 |
Gentoo/SPARC |
463 |
Gentoo/AMD64 |
464 |
GPG: 0543 6FA3 5F82 3A76 3BF7 8323 AB5C ED4E 9E7F 4E2E |
465 |
- -----o()o---------------------------------------------- |
466 |
-----BEGIN PGP SIGNATURE----- |
467 |
Version: GnuPG v1.4.4 (GNU/Linux) |
468 |
|
469 |
iD8DBQFFAFbxq1ztTp5/Ti4RAh0uAJ4wfp+RbyUs7gMYhrbJ/itksNUi9ACgjlS+ |
470 |
Hl84SvH4qv+SttwgC87Bn9k= |
471 |
=XSnj |
472 |
-----END PGP SIGNATURE----- |
473 |
-- |
474 |
gentoo-perl@g.o mailing list |