Commit | Line | Data |
---|---|---|
920dae64 AT |
1 | .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 |
2 | .\" | |
3 | .\" Standard preamble: | |
4 | .\" ======================================================================== | |
5 | .de Sh \" Subsection heading | |
6 | .br | |
7 | .if t .Sp | |
8 | .ne 5 | |
9 | .PP | |
10 | \fB\\$1\fR | |
11 | .PP | |
12 | .. | |
13 | .de Sp \" Vertical space (when we can't use .PP) | |
14 | .if t .sp .5v | |
15 | .if n .sp | |
16 | .. | |
17 | .de Vb \" Begin verbatim text | |
18 | .ft CW | |
19 | .nf | |
20 | .ne \\$1 | |
21 | .. | |
22 | .de Ve \" End verbatim text | |
23 | .ft R | |
24 | .fi | |
25 | .. | |
26 | .\" Set up some character translations and predefined strings. \*(-- will | |
27 | .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left | |
28 | .\" double quote, and \*(R" will give a right double quote. | will give a | |
29 | .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to | |
30 | .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' | |
31 | .\" expand to `' in nroff, nothing in troff, for use with C<>. | |
32 | .tr \(*W-|\(bv\*(Tr | |
33 | .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' | |
34 | .ie n \{\ | |
35 | . ds -- \(*W- | |
36 | . ds PI pi | |
37 | . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch | |
38 | . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch | |
39 | . ds L" "" | |
40 | . ds R" "" | |
41 | . ds C` "" | |
42 | . ds C' "" | |
43 | 'br\} | |
44 | .el\{\ | |
45 | . ds -- \|\(em\| | |
46 | . ds PI \(*p | |
47 | . ds L" `` | |
48 | . ds R" '' | |
49 | 'br\} | |
50 | .\" | |
51 | .\" If the F register is turned on, we'll generate index entries on stderr for | |
52 | .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index | |
53 | .\" entries marked with X<> in POD. Of course, you'll have to process the | |
54 | .\" output yourself in some meaningful fashion. | |
55 | .if \nF \{\ | |
56 | . de IX | |
57 | . tm Index:\\$1\t\\n%\t"\\$2" | |
58 | .. | |
59 | . nr % 0 | |
60 | . rr F | |
61 | .\} | |
62 | .\" | |
63 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes | |
64 | .\" way too many mistakes in technical documents. | |
65 | .hy 0 | |
66 | .if n .na | |
67 | .\" | |
68 | .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). | |
69 | .\" Fear. Run. Save yourself. No user-serviceable parts. | |
70 | . \" fudge factors for nroff and troff | |
71 | .if n \{\ | |
72 | . ds #H 0 | |
73 | . ds #V .8m | |
74 | . ds #F .3m | |
75 | . ds #[ \f1 | |
76 | . ds #] \fP | |
77 | .\} | |
78 | .if t \{\ | |
79 | . ds #H ((1u-(\\\\n(.fu%2u))*.13m) | |
80 | . ds #V .6m | |
81 | . ds #F 0 | |
82 | . ds #[ \& | |
83 | . ds #] \& | |
84 | .\} | |
85 | . \" simple accents for nroff and troff | |
86 | .if n \{\ | |
87 | . ds ' \& | |
88 | . ds ` \& | |
89 | . ds ^ \& | |
90 | . ds , \& | |
91 | . ds ~ ~ | |
92 | . ds / | |
93 | .\} | |
94 | .if t \{\ | |
95 | . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" | |
96 | . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' | |
97 | . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' | |
98 | . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' | |
99 | . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' | |
100 | . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' | |
101 | .\} | |
102 | . \" troff and (daisy-wheel) nroff accents | |
103 | .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' | |
104 | .ds 8 \h'\*(#H'\(*b\h'-\*(#H' | |
105 | .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] | |
106 | .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' | |
107 | .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' | |
108 | .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] | |
109 | .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] | |
110 | .ds ae a\h'-(\w'a'u*4/10)'e | |
111 | .ds Ae A\h'-(\w'A'u*4/10)'E | |
112 | . \" corrections for vroff | |
113 | .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' | |
114 | .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' | |
115 | . \" for low resolution devices (crt and lpr) | |
116 | .if \n(.H>23 .if \n(.V>19 \ | |
117 | \{\ | |
118 | . ds : e | |
119 | . ds 8 ss | |
120 | . ds o a | |
121 | . ds d- d\h'-1'\(ga | |
122 | . ds D- D\h'-1'\(hy | |
123 | . ds th \o'bp' | |
124 | . ds Th \o'LP' | |
125 | . ds ae ae | |
126 | . ds Ae AE | |
127 | .\} | |
128 | .rm #[ #] #H #V #F C | |
129 | .\" ======================================================================== | |
130 | .\" | |
131 | .IX Title "Test 3" | |
132 | .TH Test 3 "2001-09-21" "perl v5.8.8" "Perl Programmers Reference Guide" | |
133 | .SH "NAME" | |
134 | Test \- provides a simple framework for writing test scripts | |
135 | .SH "SYNOPSIS" | |
136 | .IX Header "SYNOPSIS" | |
137 | .Vb 2 | |
138 | \& use strict; | |
139 | \& use Test; | |
140 | .Ve | |
141 | .PP | |
142 | .Vb 2 | |
143 | \& # use a BEGIN block so we print our plan before MyModule is loaded | |
144 | \& BEGIN { plan tests => 14, todo => [3,4] } | |
145 | .Ve | |
146 | .PP | |
147 | .Vb 2 | |
148 | \& # load your module... | |
149 | \& use MyModule; | |
150 | .Ve | |
151 | .PP | |
152 | .Vb 2 | |
153 | \& # Helpful notes. All note-lines must start with a "#". | |
154 | \& print "# I'm testing MyModule version $MyModule::VERSION\en"; | |
155 | .Ve | |
156 | .PP | |
157 | .Vb 2 | |
158 | \& ok(0); # failure | |
159 | \& ok(1); # success | |
160 | .Ve | |
161 | .PP | |
162 | .Vb 2 | |
163 | \& ok(0); # ok, expected failure (see todo list, above) | |
164 | \& ok(1); # surprise success! | |
165 | .Ve | |
166 | .PP | |
167 | .Vb 4 | |
168 | \& ok(0,1); # failure: '0' ne '1' | |
169 | \& ok('broke','fixed'); # failure: 'broke' ne 'fixed' | |
170 | \& ok('fixed','fixed'); # success: 'fixed' eq 'fixed' | |
171 | \& ok('fixed',qr/x/); # success: 'fixed' =~ qr/x/ | |
172 | .Ve | |
173 | .PP | |
174 | .Vb 2 | |
175 | \& ok(sub { 1+1 }, 2); # success: '2' eq '2' | |
176 | \& ok(sub { 1+1 }, 3); # failure: '2' ne '3' | |
177 | .Ve | |
178 | .PP | |
179 | .Vb 3 | |
180 | \& my @list = (0,0); | |
181 | \& ok @list, 3, "\e@list=".join(',',@list); #extra notes | |
182 | \& ok 'segmentation fault', '/(?i)success/'; #regex match | |
183 | .Ve | |
184 | .PP | |
185 | .Vb 8 | |
186 | \& skip( | |
187 | \& $^O =~ m/MSWin/ ? "Skip if MSWin" : 0, # whether to skip | |
188 | \& $foo, $bar # arguments just like for ok(...) | |
189 | \& ); | |
190 | \& skip( | |
191 | \& $^O =~ m/MSWin/ ? 0 : "Skip unless MSWin", # whether to skip | |
192 | \& $foo, $bar # arguments just like for ok(...) | |
193 | \& ); | |
194 | .Ve | |
195 | .SH "DESCRIPTION" | |
196 | .IX Header "DESCRIPTION" | |
197 | This module simplifies the task of writing test files for Perl modules, | |
198 | such that their output is in the format that | |
199 | Test::Harness expects to see. | |
200 | .SH "QUICK START GUIDE" | |
201 | .IX Header "QUICK START GUIDE" | |
202 | To write a test for your new (and probably not even done) module, create | |
203 | a new file called \fIt/test.t\fR (in a new \fIt\fR directory). If you have | |
204 | multiple test files, to test the \*(L"foo\*(R", \*(L"bar\*(R", and \*(L"baz\*(R" feature sets, | |
205 | then feel free to call your files \fIt/foo.t\fR, \fIt/bar.t\fR, and | |
206 | \&\fIt/baz.t\fR | |
207 | .Sh "Functions" | |
208 | .IX Subsection "Functions" | |
209 | This module defines three public functions, \f(CW\*(C`plan(...)\*(C'\fR, \f(CW\*(C`ok(...)\*(C'\fR, | |
210 | and \f(CW\*(C`skip(...)\*(C'\fR. By default, all three are exported by | |
211 | the \f(CW\*(C`use Test;\*(C'\fR statement. | |
212 | .ie n .IP """plan(...)""" 4 | |
213 | .el .IP "\f(CWplan(...)\fR" 4 | |
214 | .IX Item "plan(...)" | |
215 | .Vb 1 | |
216 | \& BEGIN { plan %theplan; } | |
217 | .Ve | |
218 | .Sp | |
219 | This should be the first thing you call in your test script. It | |
220 | declares your testing plan, how many there will be, if any of them | |
221 | should be allowed to fail, and so on. | |
222 | .Sp | |
223 | Typical usage is just: | |
224 | .Sp | |
225 | .Vb 2 | |
226 | \& use Test; | |
227 | \& BEGIN { plan tests => 23 } | |
228 | .Ve | |
229 | .Sp | |
230 | These are the things that you can put in the parameters to plan: | |
231 | .RS 4 | |
232 | .ie n .IP """tests => \f(CInumber\f(CW""" 4 | |
233 | .el .IP "\f(CWtests => \f(CInumber\f(CW\fR" 4 | |
234 | .IX Item "tests => number" | |
235 | The number of tests in your script. | |
236 | This means all \fIok()\fR and \fIskip()\fR calls. | |
237 | .ie n .IP """todo => [\f(CI1,5,14\f(CW]""" 4 | |
238 | .el .IP "\f(CWtodo => [\f(CI1,5,14\f(CW]\fR" 4 | |
239 | .IX Item "todo => [1,5,14]" | |
240 | A reference to a list of tests which are allowed to fail. | |
241 | See \*(L"\s-1TODO\s0 \s-1TESTS\s0\*(R". | |
242 | .ie n .IP """onfail => sub { ... }""" 4 | |
243 | .el .IP "\f(CWonfail => sub { ... }\fR" 4 | |
244 | .IX Item "onfail => sub { ... }" | |
245 | .PD 0 | |
246 | .ie n .IP """onfail => \e&some_sub""" 4 | |
247 | .el .IP "\f(CWonfail => \e&some_sub\fR" 4 | |
248 | .IX Item "onfail => &some_sub" | |
249 | .PD | |
250 | A subroutine reference to be run at the end of the test script, if | |
251 | any of the tests fail. See \*(L"\s-1ONFAIL\s0\*(R". | |
252 | .RE | |
253 | .RS 4 | |
254 | .Sp | |
255 | You must call \f(CW\*(C`plan(...)\*(C'\fR once and only once. You should call it | |
256 | in a \f(CW\*(C`BEGIN {...}\*(C'\fR block, like so: | |
257 | .Sp | |
258 | .Vb 1 | |
259 | \& BEGIN { plan tests => 23 } | |
260 | .Ve | |
261 | .RE | |
262 | .ie n .IP """ok(...)""" 4 | |
263 | .el .IP "\f(CWok(...)\fR" 4 | |
264 | .IX Item "ok(...)" | |
265 | .Vb 3 | |
266 | \& ok(1 + 1 == 2); | |
267 | \& ok($have, $expect); | |
268 | \& ok($have, $expect, $diagnostics); | |
269 | .Ve | |
270 | .Sp | |
271 | This function is the reason for \f(CW\*(C`Test\*(C'\fR's existence. It's | |
272 | the basic function that | |
273 | handles printing "\f(CW\*(C`ok\*(C'\fR\*(L" or \*(R"\f(CW\*(C`not ok\*(C'\fR", along with the | |
274 | current test number. (That's what \f(CW\*(C`Test::Harness\*(C'\fR wants to see.) | |
275 | .Sp | |
276 | In its most basic usage, \f(CW\*(C`ok(...)\*(C'\fR simply takes a single scalar | |
277 | expression. If its value is true, the test passes; if false, | |
278 | the test fails. Examples: | |
279 | .Sp | |
280 | .Vb 1 | |
281 | \& # Examples of ok(scalar) | |
282 | .Ve | |
283 | .Sp | |
284 | .Vb 5 | |
285 | \& ok( 1 + 1 == 2 ); # ok if 1 + 1 == 2 | |
286 | \& ok( $foo =~ /bar/ ); # ok if $foo contains 'bar' | |
287 | \& ok( baz($x + $y) eq 'Armondo' ); # ok if baz($x + $y) returns | |
288 | \& # 'Armondo' | |
289 | \& ok( @a == @b ); # ok if @a and @b are the same length | |
290 | .Ve | |
291 | .Sp | |
292 | The expression is evaluated in scalar context. So the following will | |
293 | work: | |
294 | .Sp | |
295 | .Vb 3 | |
296 | \& ok( @stuff ); # ok if @stuff has any elements | |
297 | \& ok( !grep !defined $_, @stuff ); # ok if everything in @stuff is | |
298 | \& # defined. | |
299 | .Ve | |
300 | .Sp | |
301 | A special case is if the expression is a subroutine reference (in either | |
302 | \&\f(CW\*(C`sub {...}\*(C'\fR syntax or \f(CW\*(C`\e&foo\*(C'\fR syntax). In | |
303 | that case, it is executed and its value (true or false) determines if | |
304 | the test passes or fails. For example, | |
305 | .Sp | |
306 | .Vb 5 | |
307 | \& ok( sub { # See whether sleep works at least passably | |
308 | \& my $start_time = time; | |
309 | \& sleep 5; | |
310 | \& time() - $start_time >= 4 | |
311 | \& }); | |
312 | .Ve | |
313 | .Sp | |
314 | In its two-argument form, \f(CW\*(C`ok(\f(CIarg1\f(CW, \f(CIarg2\f(CW)\*(C'\fR compares the two | |
315 | scalar values to see if they match. They match if both are undefined, | |
316 | or if \fIarg2\fR is a regex that matches \fIarg1\fR, or if they compare equal | |
317 | with \f(CW\*(C`eq\*(C'\fR. | |
318 | .Sp | |
319 | .Vb 1 | |
320 | \& # Example of ok(scalar, scalar) | |
321 | .Ve | |
322 | .Sp | |
323 | .Vb 2 | |
324 | \& ok( "this", "that" ); # not ok, 'this' ne 'that' | |
325 | \& ok( "", undef ); # not ok, "" is defined | |
326 | .Ve | |
327 | .Sp | |
328 | The second argument is considered a regex if it is either a regex | |
329 | object or a string that looks like a regex. Regex objects are | |
330 | constructed with the qr// operator in recent versions of perl. A | |
331 | string is considered to look like a regex if its first and last | |
332 | characters are \*(L"/\*(R", or if the first character is \*(L"m\*(R" | |
333 | and its second and last characters are both the | |
334 | same non-alphanumeric non-whitespace character. These regexp | |
335 | .Sp | |
336 | Regex examples: | |
337 | .Sp | |
338 | .Vb 4 | |
339 | \& ok( 'JaffO', '/Jaff/' ); # ok, 'JaffO' =~ /Jaff/ | |
340 | \& ok( 'JaffO', 'm|Jaff|' ); # ok, 'JaffO' =~ m|Jaff| | |
341 | \& ok( 'JaffO', qr/Jaff/ ); # ok, 'JaffO' =~ qr/Jaff/; | |
342 | \& ok( 'JaffO', '/(?i)jaff/ ); # ok, 'JaffO' =~ /jaff/i; | |
343 | .Ve | |
344 | .Sp | |
345 | If either (or both!) is a subroutine reference, it is run and used | |
346 | as the value for comparing. For example: | |
347 | .Sp | |
348 | .Vb 10 | |
349 | \& ok sub { | |
350 | \& open(OUT, ">x.dat") || die $!; | |
351 | \& print OUT "\ex{e000}"; | |
352 | \& close OUT; | |
353 | \& my $bytecount = -s 'x.dat'; | |
354 | \& unlink 'x.dat' or warn "Can't unlink : $!"; | |
355 | \& return $bytecount; | |
356 | \& }, | |
357 | \& 4 | |
358 | \& ; | |
359 | .Ve | |
360 | .Sp | |
361 | The above test passes two values to \f(CW\*(C`ok(arg1, arg2)\*(C'\fR \*(-- the first | |
362 | a coderef, and the second is the number 4. Before \f(CW\*(C`ok\*(C'\fR compares them, | |
363 | it calls the coderef, and uses its return value as the real value of | |
364 | this parameter. Assuming that \f(CW$bytecount\fR returns 4, \f(CW\*(C`ok\*(C'\fR ends up | |
365 | testing \f(CW\*(C`4 eq 4\*(C'\fR. Since that's true, this test passes. | |
366 | .Sp | |
367 | Finally, you can append an optional third argument, in | |
368 | \&\f(CW\*(C`ok(\f(CIarg1\f(CW,\f(CIarg2\f(CW, \f(CInote\f(CW)\*(C'\fR, where \fInote\fR is a string value that | |
369 | will be printed if the test fails. This should be some useful | |
370 | information about the test, pertaining to why it failed, and/or | |
371 | a description of the test. For example: | |
372 | .Sp | |
373 | .Vb 4 | |
374 | \& ok( grep($_ eq 'something unique', @stuff), 1, | |
375 | \& "Something that should be unique isn't!\en". | |
376 | \& '@stuff = '.join ', ', @stuff | |
377 | \& ); | |
378 | .Ve | |
379 | .Sp | |
380 | Unfortunately, a note cannot be used with the single argument | |
381 | style of \f(CW\*(C`ok()\*(C'\fR. That is, if you try \f(CW\*(C`ok(\f(CIarg1\f(CW, \f(CInote\f(CW)\*(C'\fR, then | |
382 | \&\f(CW\*(C`Test\*(C'\fR will interpret this as \f(CW\*(C`ok(\f(CIarg1\f(CW, \f(CIarg2\f(CW)\*(C'\fR, and probably | |
383 | end up testing \f(CW\*(C`\f(CIarg1\f(CW eq \f(CIarg2\f(CW\*(C'\fR \*(-- and that's not what you want! | |
384 | .Sp | |
385 | All of the above special cases can occasionally cause some | |
386 | problems. See \*(L"\s-1BUGS\s0 and \s-1CAVEATS\s0\*(R". | |
387 | .ie n .IP """skip(\f(CIskip_if_true\f(CW, \f(CIargs...\f(CW)""" 4 | |
388 | .el .IP "\f(CWskip(\f(CIskip_if_true\f(CW, \f(CIargs...\f(CW)\fR" 4 | |
389 | .IX Item "skip(skip_if_true, args...)" | |
390 | This is used for tests that under some conditions can be skipped. It's | |
391 | basically equivalent to: | |
392 | .Sp | |
393 | .Vb 5 | |
394 | \& if( $skip_if_true ) { | |
395 | \& ok(1); | |
396 | \& } else { | |
397 | \& ok( args... ); | |
398 | \& } | |
399 | .Ve | |
400 | .Sp | |
401 | \&...except that the \f(CWok(1)\fR emits not just "\f(CW\*(C`ok \f(CItestnum\f(CW\*(C'\fR\*(L" but | |
402 | actually \*(R"\f(CW\*(C`ok \f(CItestnum\f(CW # \f(CIskip_if_true_value\f(CW\*(C'\fR". | |
403 | .Sp | |
404 | The arguments after the \fIskip_if_true\fR are what is fed to \f(CW\*(C`ok(...)\*(C'\fR if | |
405 | this test isn't skipped. | |
406 | .Sp | |
407 | Example usage: | |
408 | .Sp | |
409 | .Vb 2 | |
410 | \& my $if_MSWin = | |
411 | \& $^O =~ m/MSWin/ ? 'Skip if under MSWin' : ''; | |
412 | .Ve | |
413 | .Sp | |
414 | .Vb 2 | |
415 | \& # A test to be skipped if under MSWin (i.e., run except under MSWin) | |
416 | \& skip($if_MSWin, thing($foo), thing($bar) ); | |
417 | .Ve | |
418 | .Sp | |
419 | Or, going the other way: | |
420 | .Sp | |
421 | .Vb 2 | |
422 | \& my $unless_MSWin = | |
423 | \& $^O =~ m/MSWin/ ? '' : 'Skip unless under MSWin'; | |
424 | .Ve | |
425 | .Sp | |
426 | .Vb 2 | |
427 | \& # A test to be skipped unless under MSWin (i.e., run only under MSWin) | |
428 | \& skip($unless_MSWin, thing($foo), thing($bar) ); | |
429 | .Ve | |
430 | .Sp | |
431 | The tricky thing to remember is that the first parameter is true if | |
432 | you want to \fIskip\fR the test, not \fIrun\fR it; and it also doubles as a | |
433 | note about why it's being skipped. So in the first codeblock above, read | |
434 | the code as "skip if MSWin \*(-- (otherwise) test whether \f(CW\*(C`thing($foo)\*(C'\fR is | |
435 | \&\f(CW\*(C`thing($bar)\*(C'\fR\*(L" or for the second case, \*(R"skip unless MSWin...". | |
436 | .Sp | |
437 | Also, when your \fIskip_if_reason\fR string is true, it really should (for | |
438 | backwards compatibility with older Test.pm versions) start with the | |
439 | string \*(L"Skip\*(R", as shown in the above examples. | |
440 | .Sp | |
441 | Note that in the above cases, \f(CW\*(C`thing($foo)\*(C'\fR and \f(CW\*(C`thing($bar)\*(C'\fR | |
442 | \&\fIare\fR evaluated \*(-- but as long as the \f(CW\*(C`skip_if_true\*(C'\fR is true, | |
443 | then we \f(CW\*(C`skip(...)\*(C'\fR just tosses out their value (i.e., not | |
444 | bothering to treat them like values to \f(CW\*(C`ok(...)\*(C'\fR. But if | |
445 | you need to \fInot\fR eval the arguments when skipping the | |
446 | test, use | |
447 | this format: | |
448 | .Sp | |
449 | .Vb 7 | |
450 | \& skip( $unless_MSWin, | |
451 | \& sub { | |
452 | \& # This code returns true if the test passes. | |
453 | \& # (But it doesn't even get called if the test is skipped.) | |
454 | \& thing($foo) eq thing($bar) | |
455 | \& } | |
456 | \& ); | |
457 | .Ve | |
458 | .Sp | |
459 | or even this, which is basically equivalent: | |
460 | .Sp | |
461 | .Vb 3 | |
462 | \& skip( $unless_MSWin, | |
463 | \& sub { thing($foo) }, sub { thing($bar) } | |
464 | \& ); | |
465 | .Ve | |
466 | .Sp | |
467 | That is, both are like this: | |
468 | .Sp | |
469 | .Vb 7 | |
470 | \& if( $unless_MSWin ) { | |
471 | \& ok(1); # but it actually appends "# $unless_MSWin" | |
472 | \& # so that Test::Harness can tell it's a skip | |
473 | \& } else { | |
474 | \& # Not skipping, so actually call and evaluate... | |
475 | \& ok( sub { thing($foo) }, sub { thing($bar) } ); | |
476 | \& } | |
477 | .Ve | |
478 | .SH "TEST TYPES" | |
479 | .IX Header "TEST TYPES" | |
480 | .IP "* \s-1NORMAL\s0 \s-1TESTS\s0" 4 | |
481 | .IX Item "NORMAL TESTS" | |
482 | These tests are expected to succeed. Usually, most or all of your tests | |
483 | are in this category. If a normal test doesn't succeed, then that | |
484 | means that something is \fIwrong\fR. | |
485 | .IP "* \s-1SKIPPED\s0 \s-1TESTS\s0" 4 | |
486 | .IX Item "SKIPPED TESTS" | |
487 | The \f(CW\*(C`skip(...)\*(C'\fR function is for tests that might or might not be | |
488 | possible to run, depending | |
489 | on the availability of platform-specific features. The first argument | |
490 | should evaluate to true (think \*(L"yes, please skip\*(R") if the required | |
491 | feature is \fInot\fR available. After the first argument, \f(CW\*(C`skip(...)\*(C'\fR works | |
492 | exactly the same way as \f(CW\*(C`ok(...)\*(C'\fR does. | |
493 | .IP "* \s-1TODO\s0 \s-1TESTS\s0" 4 | |
494 | .IX Item "TODO TESTS" | |
495 | \&\s-1TODO\s0 tests are designed for maintaining an \fBexecutable \s-1TODO\s0 list\fR. | |
496 | These tests are \fIexpected to fail.\fR If a \s-1TODO\s0 test does succeed, | |
497 | then the feature in question shouldn't be on the \s-1TODO\s0 list, now | |
498 | should it? | |
499 | .Sp | |
500 | Packages should \s-1NOT\s0 be released with succeeding \s-1TODO\s0 tests. As soon | |
501 | as a \s-1TODO\s0 test starts working, it should be promoted to a normal test, | |
502 | and the newly working feature should be documented in the release | |
503 | notes or in the change log. | |
504 | .SH "ONFAIL" | |
505 | .IX Header "ONFAIL" | |
506 | .Vb 1 | |
507 | \& BEGIN { plan test => 4, onfail => sub { warn "CALL 911!" } } | |
508 | .Ve | |
509 | .PP | |
510 | Although test failures should be enough, extra diagnostics can be | |
511 | triggered at the end of a test run. \f(CW\*(C`onfail\*(C'\fR is passed an array ref | |
512 | of hash refs that describe each test failure. Each hash will contain | |
513 | at least the following fields: \f(CW\*(C`package\*(C'\fR, \f(CW\*(C`repetition\*(C'\fR, and | |
514 | \&\f(CW\*(C`result\*(C'\fR. (You shouldn't rely on any other fields being present.) If the test | |
515 | had an expected value or a diagnostic (or \*(L"note\*(R") string, these will also be | |
516 | included. | |
517 | .PP | |
518 | The \fIoptional\fR \f(CW\*(C`onfail\*(C'\fR hook might be used simply to print out the | |
519 | version of your package and/or how to report problems. It might also | |
520 | be used to generate extremely sophisticated diagnostics for a | |
521 | particularly bizarre test failure. However it's not a panacea. Core | |
522 | dumps or other unrecoverable errors prevent the \f(CW\*(C`onfail\*(C'\fR hook from | |
523 | running. (It is run inside an \f(CW\*(C`END\*(C'\fR block.) Besides, \f(CW\*(C`onfail\*(C'\fR is | |
524 | probably over-kill in most cases. (Your test code should be simpler | |
525 | than the code it is testing, yes?) | |
526 | .SH "BUGS and CAVEATS" | |
527 | .IX Header "BUGS and CAVEATS" | |
528 | .IP "\(bu" 4 | |
529 | \&\f(CW\*(C`ok(...)\*(C'\fR's special handing of strings which look like they might be | |
530 | regexes can also cause unexpected behavior. An innocent: | |
531 | .Sp | |
532 | .Vb 1 | |
533 | \& ok( $fileglob, '/path/to/some/*stuff/' ); | |
534 | .Ve | |
535 | .Sp | |
536 | will fail, since Test.pm considers the second argument to be a regex! | |
537 | The best bet is to use the one-argument form: | |
538 | .Sp | |
539 | .Vb 1 | |
540 | \& ok( $fileglob eq '/path/to/some/*stuff/' ); | |
541 | .Ve | |
542 | .IP "\(bu" 4 | |
543 | \&\f(CW\*(C`ok(...)\*(C'\fR's use of string \f(CW\*(C`eq\*(C'\fR can sometimes cause odd problems | |
544 | when comparing | |
545 | numbers, especially if you're casting a string to a number: | |
546 | .Sp | |
547 | .Vb 2 | |
548 | \& $foo = "1.0"; | |
549 | \& ok( $foo, 1 ); # not ok, "1.0" ne 1 | |
550 | .Ve | |
551 | .Sp | |
552 | Your best bet is to use the single argument form: | |
553 | .Sp | |
554 | .Vb 1 | |
555 | \& ok( $foo == 1 ); # ok "1.0" == 1 | |
556 | .Ve | |
557 | .IP "\(bu" 4 | |
558 | As you may have inferred from the above documentation and examples, | |
559 | \&\f(CW\*(C`ok\*(C'\fR's prototype is \f(CW\*(C`($;$$)\*(C'\fR (and, incidentally, \f(CW\*(C`skip\*(C'\fR's is | |
560 | \&\f(CW\*(C`($;$$$)\*(C'\fR). This means, for example, that you can do \f(CW\*(C`ok @foo, @bar\*(C'\fR | |
561 | to compare the \fIsize\fR of the two arrays. But don't be fooled into | |
562 | thinking that \f(CW\*(C`ok @foo, @bar\*(C'\fR means a comparison of the contents of two | |
563 | arrays \*(-- you're comparing \fIjust\fR the number of elements of each. It's | |
564 | so easy to make that mistake in reading \f(CW\*(C`ok @foo, @bar\*(C'\fR that you might | |
565 | want to be very explicit about it, and instead write \f(CW\*(C`ok scalar(@foo), | |
566 | scalar(@bar)\*(C'\fR. | |
567 | .IP "\(bu" 4 | |
568 | This almost definitely doesn't do what you expect: | |
569 | .Sp | |
570 | .Vb 1 | |
571 | \& ok $thingy->can('some_method'); | |
572 | .Ve | |
573 | .Sp | |
574 | Why? Because \f(CW\*(C`can\*(C'\fR returns a coderef to mean \*(L"yes it can (and the | |
575 | method is this...)\*(R", and then \f(CW\*(C`ok\*(C'\fR sees a coderef and thinks you're | |
576 | passing a function that you want it to call and consider the truth of | |
577 | the result of! I.e., just like: | |
578 | .Sp | |
579 | .Vb 1 | |
580 | \& ok $thingy->can('some_method')->(); | |
581 | .Ve | |
582 | .Sp | |
583 | What you probably want instead is this: | |
584 | .Sp | |
585 | .Vb 1 | |
586 | \& ok $thingy->can('some_method') && 1; | |
587 | .Ve | |
588 | .Sp | |
589 | If the \f(CW\*(C`can\*(C'\fR returns false, then that is passed to \f(CW\*(C`ok\*(C'\fR. If it | |
590 | returns true, then the larger expression \f(CW\*(C`$thingy\->can('some_method')\ &&\ 1\*(C'\fR returns 1, which \f(CW\*(C`ok\*(C'\fR sees as | |
591 | a simple signal of success, as you would expect. | |
592 | .IP "\(bu" 4 | |
593 | The syntax for \f(CW\*(C`skip\*(C'\fR is about the only way it can be, but it's still | |
594 | quite confusing. Just start with the above examples and you'll | |
595 | be okay. | |
596 | .Sp | |
597 | Moreover, users may expect this: | |
598 | .Sp | |
599 | .Vb 1 | |
600 | \& skip $unless_mswin, foo($bar), baz($quux); | |
601 | .Ve | |
602 | .Sp | |
603 | to not evaluate \f(CW\*(C`foo($bar)\*(C'\fR and \f(CW\*(C`baz($quux)\*(C'\fR when the test is being | |
604 | skipped. But in reality, they \fIare\fR evaluated, but \f(CW\*(C`skip\*(C'\fR just won't | |
605 | bother comparing them if \f(CW$unless_mswin\fR is true. | |
606 | .Sp | |
607 | You could do this: | |
608 | .Sp | |
609 | .Vb 1 | |
610 | \& skip $unless_mswin, sub{foo($bar)}, sub{baz($quux)}; | |
611 | .Ve | |
612 | .Sp | |
613 | But that's not terribly pretty. You may find it simpler or clearer in | |
614 | the long run to just do things like this: | |
615 | .Sp | |
616 | .Vb 10 | |
617 | \& if( $^O =~ m/MSWin/ ) { | |
618 | \& print "# Yay, we're under $^O\en"; | |
619 | \& ok foo($bar), baz($quux); | |
620 | \& ok thing($whatever), baz($stuff); | |
621 | \& ok blorp($quux, $whatever); | |
622 | \& ok foo($barzbarz), thang($quux); | |
623 | \& } else { | |
624 | \& print "# Feh, we're under $^O. Watch me skip some tests...\en"; | |
625 | \& for(1 .. 4) { skip "Skip unless under MSWin" } | |
626 | \& } | |
627 | .Ve | |
628 | .Sp | |
629 | But be quite sure that \f(CW\*(C`ok\*(C'\fR is called exactly as many times in the | |
630 | first block as \f(CW\*(C`skip\*(C'\fR is called in the second block. | |
631 | .SH "ENVIRONMENT" | |
632 | .IX Header "ENVIRONMENT" | |
633 | If \f(CW\*(C`PERL_TEST_DIFF\*(C'\fR environment variable is set, it will be used as a | |
634 | command for comparing unexpected multiline results. If you have \s-1GNU\s0 | |
635 | diff installed, you might want to set \f(CW\*(C`PERL_TEST_DIFF\*(C'\fR to \f(CW\*(C`diff \-u\*(C'\fR. | |
636 | If you don't have a suitable program, you might install the | |
637 | \&\f(CW\*(C`Text::Diff\*(C'\fR module and then set \f(CW\*(C`PERL_TEST_DIFF\*(C'\fR to be \f(CW\*(C`perl | |
638 | \&\-MText::Diff \-e 'print diff(@ARGV)'\*(C'\fR. If \f(CW\*(C`PERL_TEST_DIFF\*(C'\fR isn't set | |
639 | but the \f(CW\*(C`Algorithm::Diff\*(C'\fR module is available, then it will be used | |
640 | to show the differences in multiline results. | |
641 | .SH "NOTE" | |
642 | .IX Header "NOTE" | |
643 | A past developer of this module once said that it was no longer being | |
644 | actively developed. However, rumors of its demise were greatly | |
645 | exaggerated. Feedback and suggestions are quite welcome. | |
646 | .PP | |
647 | Be aware that the main value of this module is its simplicity. Note | |
648 | that there are already more ambitious modules out there, such as | |
649 | Test::More and Test::Unit. | |
650 | .PP | |
651 | Some earlier versions of this module had docs with some confusing | |
652 | typoes in the description of \f(CW\*(C`skip(...)\*(C'\fR. | |
653 | .SH "SEE ALSO" | |
654 | .IX Header "SEE ALSO" | |
655 | Test::Harness | |
656 | .PP | |
657 | Test::Simple, Test::More, Devel::Cover | |
658 | .PP | |
659 | Test::Builder for building your own testing library. | |
660 | .PP | |
661 | Test::Unit is an interesting XUnit-style testing library. | |
662 | .PP | |
663 | Test::Inline and SelfTest let you embed tests in code. | |
664 | .SH "AUTHOR" | |
665 | .IX Header "AUTHOR" | |
666 | Copyright (c) 1998\-2000 Joshua Nathaniel Pritikin. All rights reserved. | |
667 | .PP | |
668 | Copyright (c) 2001\-2002 Michael G. Schwern. | |
669 | .PP | |
670 | Copyright (c) 2002\-2004 and counting Sean M. Burke. | |
671 | .PP | |
672 | Current maintainer: Sean M. Burke. <sburke@cpan.org> | |
673 | .PP | |
674 | This package is free software and is provided \*(L"as is\*(R" without express | |
675 | or implied warranty. It may be used, redistributed and/or modified | |
676 | under the same terms as Perl itself. |