1 |
On Thursday 07 September 2006 10:29, Michael Cummings wrote: |
2 |
> dams wrote: |
3 |
> > test |
4 |
> |
5 |
> NAME |
6 |
> Test - provides a simple framework for writing test scripts |
7 |
> |
8 |
> 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 |
> |
48 |
> 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 |
> |
53 |
> 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, then |
57 |
> 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 in |
92 |
> 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) |
114 |
> returns # '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 |
124 |
> @stuff is |
125 |
> # defined. |
126 |
> |
127 |
> A special case is if the expression is a subroutine reference (in |
128 |
> either "sub {...}" syntax or "\&foo" syntax). In that case, it is |
129 |
> executed and its value (true or false) determines if the test |
130 |
> passes or fails. For example, |
131 |
> |
132 |
> ok( sub { # See whether sleep works at least passably |
133 |
> my $start_time = time; |
134 |
> sleep 5; |
135 |
> time() - $start_time >= 4 |
136 |
> }); |
137 |
> |
138 |
> In its two-argument form, "ok(*arg1*, *arg2*)" compares the two |
139 |
> scalar values to see if they match. They match if both are |
140 |
> undefined, or if *arg2* is a regex that matches *arg1*, or if they |
141 |
> compare equal with "eq". |
142 |
> |
143 |
> # Example of ok(scalar, scalar) |
144 |
> |
145 |
> ok( "this", "that" ); # not ok, 'this' ne 'that' |
146 |
> ok( "", undef ); # not ok, "" is defined |
147 |
> |
148 |
> The second argument is considered a regex if it is either a regex |
149 |
> object or a string that looks like a regex. Regex objects are |
150 |
> constructed with the qr// operator in recent versions of perl. A |
151 |
> string is considered to look like a regex if its first and last |
152 |
> characters are "/", or if the first character is "m" and its second |
153 |
> and last characters are both the same non-alphanumeric |
154 |
> non-whitespace character. These regexp |
155 |
> |
156 |
> Regex examples: |
157 |
> |
158 |
> ok( 'JaffO', '/Jaff/' ); # ok, 'JaffO' =~ /Jaff/ |
159 |
> ok( 'JaffO', 'm|Jaff|' ); # ok, 'JaffO' =~ m|Jaff| |
160 |
> ok( 'JaffO', qr/Jaff/ ); # ok, 'JaffO' =~ qr/Jaff/; |
161 |
> ok( 'JaffO', '/(?i)jaff/ ); # ok, 'JaffO' =~ /jaff/i; |
162 |
> |
163 |
> If either (or both!) is a subroutine reference, it is run and used |
164 |
> as the value for comparing. For example: |
165 |
> |
166 |
> ok sub { |
167 |
> open(OUT, ">x.dat") || die $!; |
168 |
> print OUT "\x{e000}"; |
169 |
> close OUT; |
170 |
> my $bytecount = -s 'x.dat'; |
171 |
> unlink 'x.dat' or warn "Can't unlink : $!"; |
172 |
> return $bytecount; |
173 |
> }, |
174 |
> 4 |
175 |
> ; |
176 |
> |
177 |
> The above test passes two values to "ok(arg1, arg2)" -- the first a |
178 |
> coderef, and the second is the number 4. Before "ok" compares them, |
179 |
> it calls the coderef, and uses its return value as the real value |
180 |
> of this parameter. Assuming that $bytecount returns 4, "ok" ends up testing |
181 |
> "4 eq 4". Since that's true, this test passes. |
182 |
> |
183 |
> Finally, you can append an optional third argument, in |
184 |
> "ok(*arg1*,*arg2*, *note*)", where *note* is a string value that |
185 |
> will be printed if the test fails. This should be some useful |
186 |
> information about the test, pertaining to why it failed, and/or a |
187 |
> description of the test. For example: |
188 |
> |
189 |
> ok( grep($_ eq 'something unique', @stuff), 1, |
190 |
> "Something that should be unique isn't!\n". |
191 |
> '@stuff = '.join ', ', @stuff |
192 |
> ); |
193 |
> |
194 |
> Unfortunately, a note cannot be used with the single argument style |
195 |
> of "ok()". That is, if you try "ok(*arg1*, *note*)", then "Test" |
196 |
> will interpret this as "ok(*arg1*, *arg2*)", and probably end up |
197 |
> testing "*arg1* eq *arg2*" -- and that's not what you want! |
198 |
> |
199 |
> All of the above special cases can occasionally cause some |
200 |
> problems. See "BUGS and CAVEATS". |
201 |
> |
202 |
> "skip(*skip_if_true*, *args...*)" |
203 |
> This is used for tests that under some conditions can be skipped. |
204 |
> It's basically equivalent to: |
205 |
> |
206 |
> if( $skip_if_true ) { |
207 |
> ok(1); |
208 |
> } else { |
209 |
> ok( args... ); |
210 |
> } |
211 |
> |
212 |
> ...except that the ok(1) emits not just ""ok *testnum*"" but |
213 |
> actually ""ok *testnum* # *skip_if_true_value*"". |
214 |
> |
215 |
> The arguments after the *skip_if_true* are what is fed to "ok(...)" |
216 |
> if this test isn't skipped. |
217 |
> |
218 |
> Example usage: |
219 |
> |
220 |
> my $if_MSWin = |
221 |
> $^O =~ m/MSWin/ ? 'Skip if under MSWin' : ''; |
222 |
> |
223 |
> # A test to be skipped if under MSWin (i.e., run except under |
224 |
> MSWin) |
225 |
> skip($if_MSWin, thing($foo), thing($bar) ); |
226 |
> |
227 |
> Or, going the other way: |
228 |
> |
229 |
> my $unless_MSWin = |
230 |
> $^O =~ m/MSWin/ ? '' : 'Skip unless under MSWin'; |
231 |
> |
232 |
> # A test to be skipped unless under MSWin (i.e., run only |
233 |
> under MSWin) |
234 |
> skip($unless_MSWin, thing($foo), thing($bar) ); |
235 |
> |
236 |
> The tricky thing to remember is that the first parameter is true if |
237 |
> you want to *skip* the test, not *run* it; and it also doubles as a |
238 |
> note about why it's being skipped. So in the first codeblock above, |
239 |
> read the code as "skip if MSWin -- (otherwise) test whether |
240 |
> "thing($foo)" is "thing($bar)"" or for the second case, "skip |
241 |
> unless MSWin...". |
242 |
> |
243 |
> Also, when your *skip_if_reason* string is true, it really should |
244 |
> (for backwards compatibility with older Test.pm versions) start |
245 |
> with the string "Skip", as shown in the above examples. |
246 |
> |
247 |
> Note that in the above cases, "thing($foo)" and "thing($bar)" *are* |
248 |
> evaluated -- but as long as the "skip_if_true" is true, then we |
249 |
> "skip(...)" just tosses out their value (i.e., not bothering to |
250 |
> treat them like values to "ok(...)". But if you need to *not* eval |
251 |
> the arguments when skipping the test, use this format: |
252 |
> |
253 |
> skip( $unless_MSWin, |
254 |
> sub { |
255 |
> # This code returns true if the test passes. |
256 |
> # (But it doesn't even get called if the test is skipped.) |
257 |
> thing($foo) eq thing($bar) |
258 |
> } |
259 |
> ); |
260 |
> |
261 |
> or even this, which is basically equivalent: |
262 |
> |
263 |
> skip( $unless_MSWin, |
264 |
> sub { thing($foo) }, sub { thing($bar) } |
265 |
> ); |
266 |
> |
267 |
> That is, both are like this: |
268 |
> |
269 |
> if( $unless_MSWin ) { |
270 |
> ok(1); # but it actually appends "# $unless_MSWin" |
271 |
> # so that Test::Harness can tell it's a skip |
272 |
> } else { |
273 |
> # Not skipping, so actually call and evaluate... |
274 |
> ok( sub { thing($foo) }, sub { thing($bar) } ); |
275 |
> } |
276 |
> |
277 |
> TEST TYPES |
278 |
> * NORMAL TESTS |
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 |
> The "skip(...)" function is for tests that might or might not be |
285 |
> possible to run, depending on the availability of platform-specific |
286 |
> features. The first argument should evaluate to true (think "yes, |
287 |
> please skip") if the required feature is *not* available. After the |
288 |
> first argument, "skip(...)" works exactly the same way as "ok(...)" |
289 |
> does. |
290 |
> |
291 |
> * TODO TESTS |
292 |
> TODO tests are designed for maintaining an executable TODO list. |
293 |
> These tests are *expected to fail.* If a TODO test does succeed, |
294 |
> then the feature in question shouldn't be on the TODO list, now |
295 |
> should it? |
296 |
> |
297 |
> Packages should NOT be released with succeeding TODO tests. As soon |
298 |
> as a TODO test starts working, it should be promoted to a normal |
299 |
> test, and the newly working feature should be documented in the |
300 |
> release notes or in the change log. |
301 |
> |
302 |
> ONFAIL |
303 |
> BEGIN { plan test => 4, onfail => sub { warn "CALL 911!" } } |
304 |
> |
305 |
> Although test failures should be enough, extra diagnostics can be |
306 |
> triggered at the end of a test run. "onfail" is passed an array ref of |
307 |
> hash refs that describe each test failure. Each hash will contain at |
308 |
> least the following fields: "package", "repetition", and "result". (You |
309 |
> shouldn't rely on any other fields being present.) If the test had an |
310 |
> expected value or a diagnostic (or "note") string, these will also be |
311 |
> included. |
312 |
> |
313 |
> The *optional* "onfail" hook might be used simply to print out the |
314 |
> version of your package and/or how to report problems. It might also be |
315 |
> used to generate extremely sophisticated diagnostics for a particularly |
316 |
> bizarre test failure. However it's not a panacea. Core dumps or other |
317 |
> unrecoverable errors prevent the "onfail" hook from running. (It is run |
318 |
> inside an "END" block.) Besides, "onfail" is probably over-kill in most |
319 |
> cases. (Your test code should be simpler than the code it is testing, |
320 |
> yes?) |
321 |
> |
322 |
> BUGS and CAVEATS |
323 |
> * "ok(...)"'s special handing of strings which look like they might |
324 |
> be regexes can also cause unexpected behavior. An innocent: |
325 |
> |
326 |
> ok( $fileglob, '/path/to/some/*stuff/' ); |
327 |
> |
328 |
> will fail, since Test.pm considers the second argument to be a |
329 |
> regex! The best bet is to use the one-argument form: |
330 |
> |
331 |
> ok( $fileglob eq '/path/to/some/*stuff/' ); |
332 |
> |
333 |
> * "ok(...)"'s use of string "eq" can sometimes cause odd problems |
334 |
> when comparing numbers, especially if you're casting a string to a number: |
335 |
> |
336 |
> $foo = "1.0"; |
337 |
> ok( $foo, 1 ); # not ok, "1.0" ne 1 |
338 |
> |
339 |
> Your best bet is to use the single argument form: |
340 |
> |
341 |
> ok( $foo == 1 ); # ok "1.0" == 1 |
342 |
> |
343 |
> * As you may have inferred from the above documentation and examples, |
344 |
> "ok"'s prototype is "($;$$)" (and, incidentally, "skip"'s is |
345 |
> "($;$$$)"). This means, for example, that you can do "ok @foo, |
346 |
> @bar" to compare the *size* of the two arrays. But don't be fooled into |
347 |
> thinking that "ok @foo, @bar" means a comparison of the contents of two |
348 |
> arrays -- you're comparing *just* the number of elements of each. It's so |
349 |
> easy to make that mistake in reading "ok @foo, @bar" that you might want to |
350 |
> be very explicit about it, and instead write "ok scalar(@foo), |
351 |
> scalar(@bar)". |
352 |
> |
353 |
> * This almost definitely doesn't do what you expect: |
354 |
> |
355 |
> ok $thingy->can('some_method'); |
356 |
> |
357 |
> Why? Because "can" returns a coderef to mean "yes it can (and the |
358 |
> method is this...)", and then "ok" sees a coderef and thinks you're |
359 |
> passing a function that you want it to call and consider the truth |
360 |
> of the result of! I.e., just like: |
361 |
> |
362 |
> ok $thingy->can('some_method')->(); |
363 |
> |
364 |
> What you probably want instead is this: |
365 |
> |
366 |
> ok $thingy->can('some_method') && 1; |
367 |
> |
368 |
> If the "can" returns false, then that is passed to "ok". If it |
369 |
> returns true, then the larger expression |
370 |
> "$thingy->can('some_method') && 1" returns 1, which "ok" sees as a |
371 |
> simple signal of success, as you would expect. |
372 |
> |
373 |
> * The syntax for "skip" is about the only way it can be, but it's |
374 |
> still quite confusing. Just start with the above examples and |
375 |
> you'll be okay. |
376 |
> |
377 |
> Moreover, users may expect this: |
378 |
> |
379 |
> skip $unless_mswin, foo($bar), baz($quux); |
380 |
> |
381 |
> to not evaluate "foo($bar)" and "baz($quux)" when the test is being |
382 |
> skipped. But in reality, they *are* evaluated, but "skip" just |
383 |
> won't bother comparing them if $unless_mswin is true. |
384 |
> |
385 |
> You could do this: |
386 |
> |
387 |
> skip $unless_mswin, sub{foo($bar)}, sub{baz($quux)}; |
388 |
> |
389 |
> But that's not terribly pretty. You may find it simpler or clearer |
390 |
> in the long run to just do things like this: |
391 |
> |
392 |
> if( $^O =~ m/MSWin/ ) { |
393 |
> print "# Yay, we're under $^O\n"; |
394 |
> ok foo($bar), baz($quux); |
395 |
> ok thing($whatever), baz($stuff); |
396 |
> ok blorp($quux, $whatever); |
397 |
> ok foo($barzbarz), thang($quux); |
398 |
> } else { |
399 |
> print "# Feh, we're under $^O. Watch me skip some tests...\n"; |
400 |
> for(1 .. 4) { skip "Skip unless under MSWin" } |
401 |
> } |
402 |
> |
403 |
> But be quite sure that "ok" is called exactly as many times in the |
404 |
> first block as "skip" is called in the second block. |
405 |
> |
406 |
> ENVIRONMENT |
407 |
> If "PERL_TEST_DIFF" environment variable is set, it will be used as a |
408 |
> command for comparing unexpected multiline results. If you have GNU |
409 |
> diff installed, you might want to set "PERL_TEST_DIFF" to "diff -u". If you |
410 |
> don't have a suitable program, you might install the "Text::Diff" module |
411 |
> and then set "PERL_TEST_DIFF" to be "perl -MText::Diff -e 'print |
412 |
> diff(@ARGV)'". If "PERL_TEST_DIFF" isn't set but the "Algorithm::Diff" |
413 |
> module is available, then it will be used to show the differences in |
414 |
> multiline results. |
415 |
> |
416 |
> NOTE |
417 |
> A past developer of this module once said that it was no longer being |
418 |
> actively developed. However, rumors of its demise were greatly |
419 |
> exaggerated. Feedback and suggestions are quite welcome. |
420 |
> |
421 |
> Be aware that the main value of this module is its simplicity. Note |
422 |
> that there are already more ambitious modules out there, such as Test::More |
423 |
> and Test::Unit. |
424 |
> |
425 |
> Some earlier versions of this module had docs with some confusing |
426 |
> typoes in the description of "skip(...)". |
427 |
> |
428 |
> SEE ALSO |
429 |
> Test::Harness |
430 |
> |
431 |
> Test::Simple, Test::More, Devel::Cover |
432 |
> |
433 |
> Test::Builder for building your own testing library. |
434 |
> |
435 |
> Test::Unit is an interesting XUnit-style testing library. |
436 |
> |
437 |
> Test::Inline and SelfTest let you embed tests in code. |
438 |
> |
439 |
> AUTHOR |
440 |
> Copyright (c) 1998-2000 Joshua Nathaniel Pritikin. All rights reserved. |
441 |
> |
442 |
> Copyright (c) 2001-2002 Michael G. Schwern. |
443 |
> |
444 |
> Copyright (c) 2002-2004 and counting Sean M. Burke. |
445 |
> |
446 |
> Current maintainer: Sean M. Burke. <sburke@××××.org> |
447 |
> |
448 |
> This package is free software and is provided "as is" without express |
449 |
> or implied warranty. It may be used, redistributed and/or modified under |
450 |
> the same terms as Perl itself. |
451 |
> |
452 |
> |
453 |
> |
454 |
> -- |
455 |
> |
456 |
> -----o()o---------------------------------------------- |
457 |
> Michael Cummings | #gentoo-dev, #gentoo-perl |
458 |
> Gentoo Perl Dev | on irc.freenode.net |
459 |
> Gentoo/SPARC |
460 |
> Gentoo/AMD64 |
461 |
> GPG: 0543 6FA3 5F82 3A76 3BF7 8323 AB5C ED4E 9E7F 4E2E |
462 |
> -----o()o---------------------------------------------- |
463 |
|
464 |
I agree. (sorry couldn't help it ;p) |
465 |
|
466 |
-- |
467 |
Chris White |
468 |
Gentoo Developer aka: |
469 |
ChrisWhite cpw |
470 |
ChrisWhite|Work WhiteChocolate |
471 |
VanillaWhite Whitey |
472 |
WhiteLight WhiteCheese |
473 |
WhiteSugar WhiteButter |
474 |
WhiteWall WhiteLemon |
475 |
WhiteApple WhiteBlanket |
476 |
WhiteEnergy WhiteWhite |